opencode-starterkit 1.0.1

package/baseline/plans/1770013678126-witty-planet.md

@@ -0,0 +1,278 @@
+# Plan: Implement `/init` Command for OpenCodeKit
+
+## Summary
+
+Implement the `/init` slash command that provides one-command project onboarding. This command creates project-root `AGENTS.md` and populates memory files with detected project information. The command is defined in `.opencode/command/init.md` and executed by the `@plan` agent.
+
+## Current State
+
+- **CLI `ock init`**: Already exists in `src/commands/init.ts` - bootstraps `.opencode/` directory
+- **Slash `/init`**: Defined in `.opencode/command/init.md` - AI-assisted project analysis workflow
+- **Templates**: Exist in `.opencode/memory/_templates/` (user.md, tech-stack.md)
+- **Memory system**: SQLite-based with tools in `.opencode/tool/`
+
+## Phases
+
+### Phase 1: Verify Command Registration
+
+**Owner**: @build
+**Deliverable**: Ensure `/init` command is properly registered and accessible
+**Files**:
+
+- `.opencode/command/init.md` (exists, verify content)
+- `.opencode/opencode.json` (verify command registration)
+
+**Validation**:
+
+- [ ] Command appears in `ock command list`
+- [ ] Command has correct frontmatter (agent: plan, subtask: true)
+- [ ] Command description is accurate
+
+### Phase 2: Enhance Project Detection Logic
+
+**Owner**: @build
+**Deliverable**: Robust project detection with comprehensive tech stack identification
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 2 section)
+- Create utility functions for detection if needed
+
+**Implementation Details**:
+
+1. Detect tech stack from:
+   - `package.json` → Node.js/Bun/JavaScript projects
+   - `go.mod` → Go projects
+   - `pyproject.toml`, `requirements.txt` → Python projects
+   - `Cargo.toml` → Rust projects
+   - `composer.json` → PHP projects
+   - `Gemfile` → Ruby projects
+   - `pom.xml`, `build.gradle` → Java projects
+
+2. Extract key information:
+   - Language & version
+   - Framework & version
+   - Build tool
+   - Test command
+   - Lint command
+   - Key dependencies
+
+3. Validate commands by attempting to run them
+
+**Validation**:
+
+- [ ] Correctly detects this project's stack (Bun, TypeScript)
+- [ ] Correctly detects various project types in test scenarios
+- [ ] Command validation works (build, test, lint)
+
+### Phase 3: Implement AGENTS.md Generation
+
+**Owner**: @build
+**Deliverable**: Template-based AGENTS.md generation with project-specific content
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 3 section)
+- Potentially create template files
+
+**Implementation Details**:
+
+1. Create AGENTS.md template structure:
+   - Project name (from package.json or directory name)
+   - Tech stack section (from Phase 2 detection)
+   - File structure section
+   - Commands section (validated commands)
+   - Code examples section (extract from actual codebase)
+   - Testing section
+   - Boundaries section (Always/Ask First/Never rules)
+   - Gotchas section
+
+2. Target: <60 lines (max 150 lines)
+
+3. If AGENTS.md exists:
+   - Read existing content
+   - Merge/improve rather than overwrite
+   - Preserve user-added sections
+
+**Validation**:
+
+- [ ] Generated AGENTS.md is <60 lines
+- [ ] Contains accurate tech stack
+- [ ] Commands are validated and working
+- [ ] Includes at least one code example from codebase
+- [ ] Has proper Boundaries section with Never rules
+
+### Phase 4: Implement Memory File Population
+
+**Owner**: @build
+**Deliverable**: Populate `.opencode/memory/project/user.md` and `tech-stack.md`
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 5 section)
+- `.opencode/memory/_templates/user.md`
+- `.opencode/memory/_templates/tech-stack.md`
+
+**Implementation Details**:
+
+1. Load templates from `_templates/`
+
+2. Populate `user.md` from Phase 1 answers:
+   - Identity (name, git contributor)
+   - Communication preferences (terse/detailed)
+   - Workflow preferences (auto-commit/ask-first)
+   - Custom rules
+
+3. Populate `tech-stack.md` from Phase 2 detection:
+   - Framework & version
+   - Language & runtime
+   - Key dependencies with versions
+   - Key constraints
+   - Active integrations
+
+**Validation**:
+
+- [ ] user.md created with accurate information
+- [ ] tech-stack.md created with detected stack
+- [ ] Templates are properly used as base
+
+### Phase 5: Implement Optional Beads Initialization
+
+**Owner**: @build
+**Deliverable**: Initialize `.beads/` directory when user opts in
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 6 section)
+
+**Implementation Details**:
+
+1. If user says yes to beads:
+   - Run `br init` if available
+   - Or create basic structure manually:
+     - `.beads/config.yaml`
+     - `.beads/issues.jsonl`
+     - `.beads/metadata.json`
+
+**Validation**:
+
+- [ ] Beads initializes correctly when requested
+- [ ] No errors if beads already exists
+
+### Phase 6: Add --deep Mode Support
+
+**Owner**: @build
+**Deliverable**: Comprehensive research mode with subsystem detection
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 4 section)
+
+**Implementation Details**:
+
+1. When `--deep` flag is passed:
+   - Git history analysis (contributors, commit conventions)
+   - Branching strategy detection
+   - Source file pattern analysis
+   - Subsystem identification for nested AGENTS.md
+
+2. Suggest nested AGENTS.md for:
+   - `packages/*/` in monorepos
+   - `src/` vs `tests/` if patterns differ
+   - `frontend/` vs `backend/` directories
+
+**Validation**:
+
+- [ ] --deep flag triggers additional research
+- [ ] Subsystem detection works for monorepos
+- [ ] Suggestions are relevant and actionable
+
+### Phase 7: Testing & Validation
+
+**Owner**: @build
+**Deliverable**: End-to-end testing of the `/init` command
+**Files**:
+
+- Test in a fresh project directory
+- Test in existing project with AGENTS.md
+- Test with --deep flag
+
+**Test Scenarios**:
+
+1. Fresh project (no AGENTS.md):
+   - [ ] Asks upfront questions
+   - [ ] Detects tech stack correctly
+   - [ ] Creates AGENTS.md
+   - [ ] Populates memory files
+   - [ ] Shows completion summary
+
+2. Existing project (with AGENTS.md):
+   - [ ] Reads existing AGENTS.md
+   - [ ] Merges/improves rather than overwriting
+   - [ ] Preserves user content
+
+3. With --deep flag:
+   - [ ] Performs git analysis
+   - [ ] Detects subsystems
+   - [ ] Suggests nested AGENTS.md
+
+4. With --skip-questions:
+   - [ ] Skips upfront questions
+   - [ ] Infers identity from git config
+
+**Validation**:
+
+- [ ] All test scenarios pass
+- [ ] Generated files are valid and useful
+- [ ] Command completes without errors
+
+## Dependencies
+
+- Phase 2 depends on Phase 1 (command registration verification)
+- Phase 3 depends on Phase 2 (tech stack detection)
+- Phase 4 depends on Phase 1 (templates exist) and Phase 2 (detection data)
+- Phase 5 is independent but uses Phase 1 answers
+- Phase 6 is optional enhancement
+- Phase 7 depends on all previous phases
+
+## Risks
+
+| Risk                                              | Likelihood | Impact | Mitigation                                           |
+| ------------------------------------------------- | ---------- | ------ | ---------------------------------------------------- |
+| Command detection fails for exotic project types  | Medium     | Medium | Fallback to generic templates, allow manual override |
+| AGENTS.md generation produces stale code examples | Low        | Medium | Use pointers instead of inline code where possible   |
+| Memory file templates change structure            | Low        | Low    | Version templates, update command accordingly        |
+| User preferences not captured correctly           | Low        | Medium | Validate with user before writing files              |
+| --deep mode takes too long                        | Medium     | Low    | Add progress indicators, allow cancellation          |
+
+## Acceptance Criteria
+
+- [ ] `/init` command is accessible and runs without errors
+- [ ] Creates `./AGENTS.md` with project-specific information (<60 lines target)
+- [ ] Populates `.opencode/memory/project/user.md` with user preferences
+- [ ] Populates `.opencode/memory/project/tech-stack.md` with detected stack
+- [ ] Validates commands (build, test, lint) actually work
+- [ ] Handles existing AGENTS.md gracefully (merges/improves)
+- [ ] Supports `--deep` flag for comprehensive analysis
+- [ ] Supports `--skip-questions` flag for non-interactive use
+- [ ] Optional beads initialization works
+- [ ] Shows clear completion summary with next steps
+
+## Questions
+
+1. Should we add a `--dry-run` flag to preview what would be created without writing files?
+2. Should we support importing from existing `.cursorrules` or `.github/copilot-instructions.md` files?
+3. Should the command suggest running `/review-codebase` after initialization?
+
+## Implementation Notes
+
+The `/init` command is already defined in `.opencode/command/init.md`. The implementation involves:
+
+1. **Verifying** the command definition is complete and accurate
+2. **Enhancing** the command instructions with robust detection logic
+3. **Testing** the command end-to-end in various scenarios
+
+The command uses the `@plan` agent (subtask: true) which means it runs as a separate planning task. The instructions in the markdown file guide the AI through the 8-phase process.
+
+Key files to verify/modify:
+
+- `.opencode/command/init.md` - Main command definition
+- `.opencode/memory/_templates/user.md` - User profile template
+- `.opencode/memory/_templates/tech-stack.md` - Tech stack template
+
+No new CLI commands needed - this is a slash command enhancement.

package/baseline/plans/1770112267595-shiny-rocket.md

@@ -0,0 +1,258 @@
+# Plan: Patch-Package Style Feature for Template File Modifications
+
+## Summary
+
+Add a patch system that preserves user modifications to template files across upgrades. When users edit built-in skills, commands, agents, or tools, their changes are saved as patches and automatically reapplied after template updates.
+
+## Problem
+
+```
+User edits .opencode/skill/beads/skill.md (built-in template file)
+User runs `ock upgrade`
+→ Current behavior: Template file overwrites OR user version preserved forever (never gets template updates)
+→ User loses customizations OR misses template improvements
+```
+
+## Solution
+
+Save user modifications as unified diff patches. On upgrade:
+
+1. Apply new template files
+2. Automatically reapply user patches
+3. Handle conflicts gracefully
+
+---
+
+## File Structure
+
+```
+.opencode/
+├── patches/
+│   ├── .patches.json                 # Metadata index (hashes, versions)
+│   ├── skill-beads-skill.md.patch    # Unified diff patches
+│   ├── command-ship.md.patch
+│   └── *.patch.rej                   # Failed patches (conflicts)
+├── .version                          # Already exists
+└── ... (other template files)
+```
+
+---
+
+## New Commands
+
+### `ock patch save <file>`
+
+Save current modifications as a patch.
+
+```bash
+$ ock patch save .opencode/skill/beads/skill.md
+
+✓ Saved patch: .opencode/patches/skill-beads-skill.md.patch
+  Original: a1b2c3d4 → Current: e5f6g7h8
+```
+
+### `ock patch list`
+
+List all saved patches with status.
+
+```bash
+$ ock patch list
+
+Active Patches (3):
+  skill/beads/skill.md    ✓ Clean
+  command/ship.md         ⚠ Stale (template changed)
+  agent/build.md          ✗ Conflict
+```
+
+### `ock patch apply` (automatic during upgrade)
+
+Reapply patches after template update.
+
+### `ock patch remove <file>`
+
+Remove a saved patch.
+
+---
+
+## `.patches.json` Schema
+
+```json
+{
+  "version": "1.0.0",
+  "patches": {
+    "skill/beads/skill.md": {
+      "originalHash": "sha256:a1b2c3d4...",
+      "currentHash": "sha256:e5f6g7h8...",
+      "patchFile": "skill-beads-skill.md.patch",
+      "createdAt": "2026-02-03T10:00:00Z",
+      "templateVersion": "1.2.3"
+    }
+  }
+}
+```
+
+---
+
+## Upgrade Flow (Modified)
+
+```
+1. User runs: ock upgrade
+2. Check version (existing logic)
+3. For PRESERVE_DIRS files that exist in template:
+   - Copy template file (overwrite user's version)
+   - Check if patch exists in .patches.json
+   - If patch exists, apply it
+   - If patch fails, save conflict to .patch.rej
+4. Report: "✓ Updated X files, reapplied Y patches, Z conflicts"
+```
+
+---
+
+## Conflict Resolution
+
+| Scenario                        | Action                                    |
+| ------------------------------- | ----------------------------------------- |
+| Template unchanged              | Auto-apply patch                          |
+| Template changed, patch applies | Auto-apply with info message              |
+| Template changed, patch fails   | Save `.patch.rej`, skip file, notify user |
+
+**Conflict UI:**
+
+```
+⚠ CONFLICT: skill/beads/skill.md
+
+Template changed in v1.3.0 and your patch no longer applies.
+
+Options:
+  [1] View diff between versions
+  [2] Keep new template (discard patch)
+  [3] Keep your version (skip update)
+  [4] Manually merge (edit patch.rej)
+
+Saved: .opencode/patches/skill-beads-skill.md.patch.rej
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Core Patch Infrastructure
+
+**Files to create:**
+
+- `src/commands/patch.ts` - Patch save/list/apply/remove commands
+- `src/utils/patch.ts` - Diff generation, hash calculation, patch application
+
+**Files to modify:**
+
+- `src/index.ts` - Register `patch` command
+
+**Key functions:**
+
+```typescript
+// src/utils/patch.ts
+export function generatePatch(templatePath: string, userPath: string): string;
+export function applyPatch(filePath: string, patchContent: string): boolean;
+export function calculateHash(content: string): string;
+export function loadPatchMetadata(opencodeDir: string): PatchMetadata;
+export function savePatchMetadata(opencodeDir: string, metadata: PatchMetadata): void;
+```
+
+### Phase 2: Upgrade Integration
+
+**Files to modify:**
+
+- `src/commands/upgrade.ts` - Integrate patch apply after template copy
+
+**Changes:**
+
+1. After `copyDirWithPreserve()`, call `applyPatches()`
+2. Modify `PRESERVE_DIRS` logic: still preserve, but ALSO check for patches
+3. Add patch status to upgrade summary
+
+### Phase 3: CLI Polish
+
+- Interactive conflict resolution
+- `--dry-run` flag for patch apply
+- Pretty diff viewer for conflicts
+
+---
+
+## Dependencies
+
+Use existing Node.js capabilities:
+
+- `crypto.createHash('sha256')` - Hash calculation
+- **diff** library (`npm:diff`) - Generate unified diffs
+- **patch-package** or custom parser - Apply patches
+
+Alternative: Shell out to `git diff` and `git apply` (simpler, but requires git).
+
+---
+
+## Critical Files
+
+| File                      | Purpose                    |
+| ------------------------- | -------------------------- |
+| `src/commands/patch.ts`   | New - Patch commands       |
+| `src/utils/patch.ts`      | New - Patch utilities      |
+| `src/commands/upgrade.ts` | Modify - Integrate patches |
+| `src/index.ts`            | Modify - Register command  |
+
+---
+
+## Verification
+
+1. **Unit tests**: `src/commands/patch.test.ts`
+   - Test patch generation from diff
+   - Test patch application
+   - Test conflict detection
+
+2. **Integration test**:
+
+   ```bash
+   # Setup
+   ock init
+   echo "# Custom section" >> .opencode/skill/beads/skill.md
+   ock patch save .opencode/skill/beads/skill.md
+
+   # Simulate upgrade
+   ock upgrade --force
+
+   # Verify
+   grep "Custom section" .opencode/skill/beads/skill.md  # Should exist
+   ```
+
+3. **Conflict test**:
+   - Modify template file in dist/template
+   - Run upgrade
+   - Verify conflict detection and `.patch.rej` creation
+
+---
+
+## Complexity Estimate
+
+| Component           | Effort | Notes                          |
+| ------------------- | ------ | ------------------------------ |
+| Hash/diff utilities | 2h     | Use `diff` library             |
+| Patch save command  | 2h     | Generate + store patch         |
+| Patch list command  | 1h     | Read metadata, show status     |
+| Patch apply logic   | 3h     | Apply patches, handle failures |
+| Upgrade integration | 2h     | Hook into existing flow        |
+| Conflict UI         | 2h     | Interactive resolution         |
+| Tests               | 2h     | Unit + integration             |
+
+**Total: ~14 hours (2 days)**
+
+---
+
+## Open Questions
+
+1. **Git dependency?** Should we require git for `git diff`/`git apply` or use pure JS?
+   - Recommendation: Pure JS (`diff` library) for portability
+
+2. **Auto-save patches?** Should we auto-detect modifications on upgrade?
+   - Recommendation: Manual `ock patch save` for now (explicit is better)
+
+3. **Nested directories?** How to handle `skill/beads/skill.md` path → filename conversion?
+   - Recommendation: Replace `/` with `-` → `skill-beads-skill.md.patch`

package/baseline/plans/swarm-protocol.md

@@ -0,0 +1,123 @@
+# Swarm Protocol (Beads-as-Board)
+
+## Goal
+
+Use `.beads/` as the single source of truth for task state + dependencies, while agents coordinate through structured artifacts (not freeform chatter) and verification gates.
+
+## Roles (Strict)
+
+- Lead: Owns scope, prioritization, and all Beads state transitions.
+- Planner: Turns intent into Beads tasks + dependency DAG; no code changes.
+- Worker: Executes exactly one claimed task; posts a structured report.
+- Verifier: Independently validates acceptance checks; blocks close on missing evidence.
+
+## Board = Beads
+
+Canonical state lives in `.beads/issues.jsonl` (tasks) and `.beads/artifacts/<id>/` (task artifacts).
+
+- Create tasks: `br create "Title" -p <1-3>`
+- See unblocked work: `br ready`
+- Inspect context: `br show <id>`
+- Claim work: `br update <id> --status=in_progress`
+- Close work: `br close <id> --reason="..."` then `br sync --flush-only`
+
+## Task Artifact Contract
+
+Every task MUST have `.beads/artifacts/<id>/spec.md`.
+
+Optional supporting files:
+
+- `.beads/artifacts/<id>/plan.md`: multi-step implementation plan, files touched, and gates
+- `.beads/artifacts/<id>/review.md`: verifier notes + evidence summary
+
+### spec.md (Minimum Template)
+
+- Context: why this exists
+- Scope: in / out
+- Constraints: MUST / MUST NOT (security, deps, dist/, etc.)
+- Acceptance Criteria: checkboxes, each with a verification method
+- Evidence Required: exact commands and expected signals (e.g. "typecheck command passes")
+
+#### Verification Defaults (Language-Agnostic)
+
+Do NOT assume npm/pnpm/pytest/etc. Prefer this pattern:
+
+- `typecheck`: `<command>`
+- `lint`: `<command>`
+- `test`: `<command>`
+- `build` (optional): `<command>`
+
+If the repository has a canonical list of commands, reference it (e.g. `.opencode/memory/project/commands.md`).
+
+Common stacks (examples only):
+
+| Stack   | typecheck                                  | lint                         | test                   |
+| ------- | ------------------------------------------ | ---------------------------- | ---------------------- |
+| Node/TS | `npm run typecheck` or `npm run typecheck` | `npm run lint`               | `vitest` or `npm test` |
+| Python  | `python -m mypy .`                         | `ruff check .`               | `pytest`               |
+| Go      | `go test ./...` (compile+test)             | `golangci-lint run`          | `go test ./...`        |
+| Rust    | `cargo check`                              | `cargo fmt --check` (format) | `cargo test`           |
+
+## Delegation Packet (Worker Input)
+
+Every delegated task MUST include the following envelope:
+
+- TASK: `<id> - <title>`
+- EXPECTED OUTCOME: measurable end state
+- REQUIRED TOOLS: e.g. `read`, `grep`, `lsp`, `bash`
+- MUST DO: e.g. LSP-before-edits, run typecheck, run lint
+- MUST NOT DO: e.g. no new deps, no dist/ edits, no git push
+- ACCEPTANCE CHECKS: list of commands + pass criteria
+- CONTEXT: links to `.beads/artifacts/<id>/spec.md` + relevant files
+
+### Helper Tool
+
+If available, use the custom tool `swarm-delegate` to generate (and optionally write) a delegation packet:
+
+```ts
+swarm -
+  delegate({
+    bead_id: "opencodekit-template-xyz",
+    expected_outcome: "<measurable end state>",
+    required_tools: "read, grep, lsp, bash",
+    must_do: "LSP before edits, run project verification commands",
+    must_not_do: "no new deps, don't edit dist/",
+    acceptance_checks: "typecheck: <command>, lint: <command>, test: <command>",
+    context: "See .beads/artifacts/<id>/spec.md",
+    write: true,
+  });
+```
+
+## Worker Report (Worker Output)
+
+Workers MUST respond with a structured report:
+
+- Result: done / blocked / needs replan
+- Changes: file list + what changed (with file references)
+- Verification: commands run + pass/fail summary
+- Risks/Notes: edge cases, follow-ups
+- Confidence: high / medium / low
+
+## Gates (Non-Negotiable)
+
+- Planning gate: `.beads/artifacts/<id>/spec.md` exists with acceptance criteria BEFORE implementation starts
+- Execution gate: worker provides verification evidence BEFORE close
+- Review gate (risk-based): verifier signs off in `review.md` BEFORE close
+
+## Replan Triggers
+
+Immediately stop execution and return to planning if:
+
+- Scope expands to 4+ files unexpectedly
+- Requirement ambiguity changes implementation choice
+- Two-strike tool failures
+- New dependency or `.opencode/` structure change would be needed
+
+## Lead Checklist
+
+1. `br ready` -> pick task -> `br show <id>`
+2. Ensure `.beads/artifacts/<id>/spec.md` has acceptance checks
+3. `br update <id> --status=in_progress`
+4. Delegate with the packet format
+5. Require worker report + evidence
+6. `br close <id> --reason="..."` + `br sync --flush-only`