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

Implementation Plan: Update OpenCode Skill

Branch: 002-update-opencode | Date: 2025-11-11 | Spec: spec.md
Input: Feature specification from /specs/002-update-opencode/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

Create an AI agent skill that automates checking for and applying OpenCode version updates in Nix-based dotfiles. The skill eliminates manual Nix file editing and SHA256 hash lookups by querying GitHub releases, fetching cryptographic hashes via nix-prefetch-url, updating package definitions, and triggering system rebuilds with user confirmation.

Technical Context

Language/Version: Bash (no specific version requirement - standard POSIX + bash extensions)
Primary Dependencies: jq, curl, nix-prefetch-url, sed/awk, GitHub API
Storage: Filesystem - modifies ~/proj/dotfiles/pkgs/opencode/default.nix
Testing: Manual verification scripts, bash syntax validation (bash -n)
Target Platform: NixOS or Nix home-manager on Linux
Project Type: AI Agent Skill (Markdown documentation + Bash helper scripts)
Performance Goals: Version checks <10 seconds (network-dependent), updates <5 minutes (rebuild time)
Constraints: Requires network access to GitHub API, sudo for system rebuild, dotfiles at known path
Scale/Scope: Personal/small team use, single user per execution, ~5 helper scripts

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Skills Repository Constitution (from .specify/memory/constitution.md):

The constitution template is empty/placeholder. Based on project AGENTS.md and observed patterns:

I. Skill-First Design ✅ PASS

• Feature is designed as a standalone skill with clear scope
• SKILL.md will contain agent instructions
• Helper scripts are reusable and testable independently

II. Bash Best Practices ✅ PASS

• FR-012 mandates: shebang, set -euo pipefail, error handling
• Follows established patterns from niri-window-capture skill
• Scripts will use jq --arg for safe variable handling

III. Security Awareness ✅ PASS

• No security-sensitive operations (reading public GitHub data, modifying user's own files)
• No SECURITY.md required (unlike niri-window-capture which had invisible capture capability)
• User confirmation required before system modifications (FR-010)

IV. Fail-Safe Design ✅ PASS

• FR-009: No partial modifications - atomic operations only
• FR-008: Clear error messages, fail fast
• No sophisticated recovery - rely on git revert

V. Simplicity ✅ PASS

• Removed over-engineering (cross-validation, rate limit parsing, partial update detection)
• Focuses on core task: check, fetch, update, rebuild
• 12 focused requirements (down from 19 in initial draft)

Gate Result: ✅ PASS - No violations, no complexity justification needed

Project Structure

Documentation (this feature)

specs/002-update-opencode/
├── plan.md              # This file
├── spec.md              # Feature specification (completed)
├── research.md          # Phase 0 output (to be created)
├── data-model.md        # Phase 1 output (to be created)
├── quickstart.md        # Phase 1 output (to be created)
├── contracts/           # Phase 1 output (to be created)
│   └── script-interface.md  # Bash script contracts
├── checklists/          # Spec validation (completed)
│   └── requirements.md
└── tasks.md             # Phase 2 output (/speckit.tasks - not created yet)

Source Code (skills repository root)

skills/update-opencode/
├── SKILL.md             # Agent instructions (main skill definition)
├── README.md            # User-facing documentation
├── scripts/             # Helper bash scripts
│   ├── check-version.sh     # Compare current vs latest
│   ├── fetch-sha256.sh      # Get SHA256 for version
│   ├── update-nix-file.sh   # Modify default.nix safely
│   └── verify-update.sh     # Confirm version after rebuild
├── examples/            # Example usage and outputs
│   ├── usage-example.sh
│   └── example-output.txt
└── references/          # Supporting documentation
    └── nix-package-format.md  # Example Nix package structure

Structure Decision: AI Agent Skill structure (documentation + bash scripts). This is not a traditional software project but a skill for Claude Code/OpenCode agents. The skill lives in skills/update-opencode/ and will be deployed to dotfiles via bin/deploy-skill.sh script. Follows established pattern from worklog and niri-window-capture skills.

Complexity Tracking

Not applicable - Constitution Check passed with no violations.

---

Phase 0: Research & Design Decisions

Status: ✅ Complete

Research Tasks (Completed):

1. Nix Package File Parsing: Determine safest approach to read/update version = "X.Y.Z" and sha256 = "hash" fields

   • Options: sed with precise patterns, awk field replacement, nix-instantiate parsing
   • Need to preserve formatting, comments, surrounding code

2. GitHub API Usage: Verify API endpoints and response structure for stable releases

   • Confirm /repos/sst/opencode/releases/latest returns non-prerelease versions
   • Document response fields: tag_name, prerelease, tarball_url

3. nix-prefetch-url Invocation: Determine correct syntax for fetching SHA256

   • Command pattern for GitHub release tarballs
   • Error handling for network failures

4. Version Comparison Logic: Simple semantic version comparison in bash

   • Parse major.minor.patch format
   • Determine if update available (newer vs current)

5. System Rebuild Triggering: Verify rebuild command and error handling

   • Determine if sudo nixos-rebuild switch vs home-manager rebuild
   • Capture rebuild output for error reporting

Output: ✅ research.md completed with all decisions documented

---

Phase 1: Design & Contracts

Status: ✅ Complete

Deliverables (Completed):

1. data-model.md: Entity definitions

   • VersionInfo (current, latest, updateAvailable)
   • NixPackageFile (path, version, sha256, content)
   • GitHubRelease (tag, tarballUrl, isPrerelease)

2. contracts/script-interface.md: Bash script contracts

   • Input/output contracts for each helper script
   • Exit codes, stdout format, stderr error messages
   • Environment variables required

3. quickstart.md: Quick reference for skill usage

   • How agents invoke the skill
   • Example agent conversations
   • Manual script invocation for testing

4. Agent context update: ✅ Completed

   • Updated AGENTS.md with bash scripting context
   • Added GitHub API and Nix tooling knowledge
   • Documented dependencies: jq, curl, nix-prefetch-url, sed/awk

---

Phase 2: Task Breakdown

Status: ⏳ Not started (separate command: /speckit.tasks)

This phase is handled by the /speckit.tasks command after planning is complete.