skills/specs/002-update-opencode/quickstart.md

Quick Start: Update OpenCode Skill

Feature: 002-update-opencode
Date: 2025-11-11
For: Developers and AI agents

---

For AI Agents (Claude Code / OpenCode)

When to Use This Skill

The skill activates when users ask to:

• "Check for OpenCode updates"
• "Update OpenCode to the latest version"
• "Install OpenCode version X.Y.Z"
• "Is there a newer version of OpenCode available?"

Agent Workflow

P1: Check for Updates (Read-Only)

1. User: "Check for OpenCode updates"
2. Agent invokes: skills/update-opencode/scripts/check-version.sh
3. Agent reports:
   - Current version: 1.0.44
   - Latest version: 1.0.58
   - Update available: Yes

P2: Apply Update (Modifies System)

1. User: "Update OpenCode to latest"
2. Agent runs: ./check-version.sh to verify update needed
3. Agent asks: "Update will trigger system rebuild (~5 min). Continue? (yes/no)"
4. User confirms: "yes"
5. Agent executes:
   a. ./fetch-sha256.sh 1.0.58
   b. ./update-nix-file.sh 1.0.58 <hash>
   c. Trigger: sudo nixos-rebuild switch --flake ~/proj/dotfiles#delpad
6. Agent verifies: ./verify-update.sh 1.0.58
7. Agent reports: "✓ OpenCode updated to 1.0.58"

P3: Version Pinning

1. User: "Install OpenCode 1.0.44"
2. Agent follows same P2 workflow but with specific version
3. Agent warns if downgrading: "Current: 1.0.58 → Target: 1.0.44 (downgrade)"

Error Handling for Agents

Network failures:

Agent: "Cannot reach GitHub API. Check network connection."

Nix file not found:

Agent: "OpenCode package definition not found at ~/proj/dotfiles/pkgs/opencode/default.nix"

SHA256 fetch fails:

Agent: "Failed to fetch SHA256 for version 1.0.58. Version may not exist."

Rebuild fails:

Agent: "System rebuild failed. See error above. Revert with: cd ~/proj/dotfiles && git diff pkgs/opencode/default.nix"

---

For Manual Testing

Check Current vs Latest Version

cd skills/update-opencode/scripts
./check-version.sh

Expected output:

current=1.0.44
latest=1.0.58
update_available=yes

Fetch SHA256 for Specific Version

./fetch-sha256.sh 1.0.58

Expected output:

0f3gmj8qpjz7xpay1r9ccavcvbsz10fczqvlmkj79sgq8mxs6v2z

(Takes 1-4 seconds)

Preview Nix File Changes (Dry Run)

./update-nix-file.sh 1.0.58 0f3gmj8qpjz7xpay1r9ccavcvbsz10fczqvlmkj79sgq8mxs6v2z --dry-run

Expected output:

--- /home/user/proj/dotfiles/pkgs/opencode/default.nix
+++ /home/user/proj/dotfiles/pkgs/opencode/default.nix
@@ -2,7 +2,7 @@
-  version = "1.0.44";
+  version = "1.0.58";
-  sha256 = "oldhasholdhasholdhasholdhashol";
+  sha256 = "0f3gmj8qpjz7xpay1r9ccavcvbsz10fczqvlmkj79sgq8mxs6v2z";

Apply Update (Actual Modification)

# Update Nix file
./update-nix-file.sh 1.0.58 0f3gmj8qpjz7xpay1r9ccavcvbsz10fczqvlmkj79sgq8mxs6v2z

# Trigger rebuild
cd ~/proj/dotfiles
sudo nixos-rebuild switch --flake .#delpad

# Verify
cd ~/proj/skills/skills/update-opencode/scripts
./verify-update.sh 1.0.58

Full Workflow Test

#!/usr/bin/env bash
# Test complete update workflow (safe - uses dry-run)

set -euo pipefail

cd "$(dirname "$0")"

echo "==> Checking for updates..."
version_info=$(./check-version.sh)
eval "$version_info"

echo "Current: $current"
echo "Latest: $latest"
echo "Update available: $update_available"

if [[ "$update_available" == "yes" ]]; then
  echo ""
  echo "==> Fetching SHA256 for version $latest..."
  hash=$(./fetch-sha256.sh "$latest")
  echo "Hash: $hash"
  
  echo ""
  echo "==> Previewing Nix file changes (dry-run)..."
  ./update-nix-file.sh "$latest" "$hash" --dry-run
  
  echo ""
  echo "✓ Test complete (no actual changes made)"
else
  echo ""
  echo "✓ Already on latest version"
fi

---

Prerequisites

System requirements:

• NixOS or Nix home-manager
• Network access to api.github.com
• Sudo access for system rebuild

Tool dependencies:

# Check if required tools are available
for cmd in curl jq nix-prefetch-url grep sed; do
  command -v "$cmd" >/dev/null 2>&1 || echo "Missing: $cmd"
done

Dotfiles structure:

~/proj/dotfiles/
└── pkgs/
    └── opencode/
        └── default.nix  # Must contain version = "..." and sha256 = "..."

---

Common Issues

"opencode command not found" after rebuild

Cause: Shell hasn't reloaded environment
Fix: Restart shell or run: hash -r

"Network error" when checking versions

Cause: GitHub API unreachable or rate limited
Fix: Check network, wait if rate limited (60 req/hour for unauthenticated)

"Version pattern not found in file"

Cause: Nix file has unexpected format
Fix: Verify file contains exactly: version = "X.Y.Z"; and sha256 = "hash";

"nix-prefetch-url failed"

Cause: Version doesn't exist on GitHub or network issue
Fix: Verify version exists: curl -s https://api.github.com/repos/sst/opencode/releases | jq '.[].tag_name'

---

Skill File Structure

skills/update-opencode/
├── SKILL.md                  # Agent reads this for instructions
├── README.md                 # Humans read this for documentation
├── scripts/
│   ├── check-version.sh      # Compare current vs latest
│   ├── fetch-sha256.sh       # Get hash for version
│   ├── update-nix-file.sh    # Modify default.nix
│   └── verify-update.sh      # Confirm version after rebuild
├── examples/
│   ├── usage-example.sh      # Complete workflow example
│   └── example-output.txt    # Sample script outputs
└── references/
    └── nix-package-format.md # Example Nix package structure

---

Next Steps

After skill implementation:

1. Test each script independently with sample data
2. Test full workflow with actual OpenCode versions
3. Deploy to dotfiles using ./bin/deploy-skill.sh update-opencode
4. Configure Nix to install skill to ~/.claude/skills/ and ~/.config/opencode/skills/
5. Test with agent by asking "check for OpenCode updates"