# Implementation Plan: Update OpenCode Skill

**Branch**: `002-update-opencode` | **Date**: 2025-11-11 | **Spec**: [spec.md](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)

```text
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)

```text
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.