opencodekit 0.16.15 → 0.16.17

package/dist/template/.opencode/command/handoff.md

@@ -1,251 +1,147 @@
 ---
-description: Create handoff for next session - save progress and context
+description: Save progress and context for next session
 argument-hint: "<bead-id> [instructions]"
 agent: build
 ---
 
 # Handoff: $ARGUMENTS
 
-You're pausing work on a task. Save state so the next session can pick up cleanly.
+Save state so the next session can pick up cleanly.
+
+> **Workflow:** Run this when pausing work. Resume with `/resume $ARGUMENTS`.
+
+## Parse Arguments
+
+| Argument         | Default  | Description                        |
+| ---------------- | -------- | ---------------------------------- |
+| `<bead-id>`      | required | The bead to hand off               |
+| `[instructions]` | none     | Extra context for the next session |
 
 ## Load Skills
 
 ```typescript
 skill({ name: "beads" });
-skill({ name: "session-management" });
 skill({ name: "memory-system" });
-skill({ name: "compaction" }); // Context compaction strategies before handoff
 ```
 
-## Check Memory for Context
+---
 
-Before creating handoff, search for related work:
+## Phase 1: Gather State (Parallel)
 
-```typescript
-// Find previous handoffs and sessions for this bead
-memory_search({ query: "$ARGUMENTS handoff progress", limit: 3 });
-
-// Find related decisions and learnings
-memory_search({ query: "[bead description keywords]", limit: 3 });
+```bash
+br show $ARGUMENTS
+git status --porcelain
+git branch --show-current
+git rev-parse --short HEAD
+ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null
 ```
 
-Review findings to include relevant context in the handoff.
-
-## Why Handoff?
-
-- Context window getting full
-- Hit budget limit
-- Blocked on something external
-- End of work session
-- Switching to different task
-
-Don't grind past diminishing returns. A clean handoff beats degraded output.
+---
 
-## Context Compaction (Before Handoff)
+## Phase 2: Handle Uncommitted Changes
 
-Before creating the handoff document, compact context to preserve maximum signal:
+If `git status` shows uncommitted changes, ask the user:
 
 ```typescript
-// Assess current context health using compaction skill thresholds
-// 🟢 0-50%: No action needed
-// 🟡 50-75%: Distill completed tool outputs
-// 🟠 75-90%: Compress completed phases
-// 🔴 90-95%: Aggressive prune + compress
-// ⛔ 95%+: Emergency handoff (skip to handoff creation)
-
-// Step 1: Distill valuable tool outputs you've already processed
-distill({
-  targets: [
-    // Distill any read/grep/lsp outputs that contain findings worth preserving
-    { id: "<tool-id>", distillation: "<high-fidelity technical summary>" },
+question({
+  questions: [
+    {
+      header: "Uncommitted work",
+      question: "You have uncommitted changes. What should we do?",
+      options: [
+        { label: "Commit as WIP (Recommended)", description: "git commit -m 'WIP: $ARGUMENTS'" },
+        { label: "Leave uncommitted", description: "Skip commit, just write handoff" },
+      ],
+    },
   ],
 });
-
-// Step 2: Compress completed conversation phases
-compress({
-  topic: "<phase name>",
-  content: {
-    startString: "<unique start>",
-    endString: "<unique end>",
-    summary: "<exhaustive technical summary of what transpired>",
-  },
-});
-
-// Step 3: Prune noise (failed attempts, irrelevant outputs)
-prune({ ids: ["<noise-tool-ids>"] });
 ```
 
-This ensures the handoff document captures the distilled understanding, not raw noise.
+If user chooses commit:
 
-## Gather State
-
-Get current task status:
+```bash
+git add -A
+git commit -m "WIP: $ARGUMENTS - [brief description of where you stopped]"
+```
 
-!`br show $ARGUMENTS`
+---
 
-Get git state:
+## Phase 3: Write Handoff
 
-!`git remote get-url origin 2>/dev/null || echo "No remote"`
-!`git branch --show-current`
-!`git rev-parse --short HEAD`
-!`git status --porcelain`
+Write the handoff to the memory system:
 
-Check what artifacts exist:
+```typescript
+memory_update({
+  file: "handoffs/$ARGUMENTS",
+  content: `# Handoff: $ARGUMENTS
 
-!`ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null || echo "No artifacts yet"`
+**Date:** [timestamp]
+**Branch:** [from git branch]
+**Commit:** [from git rev-parse]
 
-## Commit Work In Progress
+## Done
+- [completed work]
 
-If you have uncommitted changes, commit them:
+## In Progress
+- [current step] — stopped because [reason]
 
-```bash
-git add -A
-git commit -m "WIP: $ARGUMENTS - [where you stopped]"
-```
+## Remaining
+- [next steps]
 
-Don't leave uncommitted work. The next session needs a clean starting point.
+## Files Touched
+- \`path/to/file.ts\` — [what changed]
 
-## Persist Swarm State (If Active)
+## Decisions
+- [decision]: [why]
 
-If a swarm is active for this task, note its state for recovery:
+## Blockers
+[any blockers, or "None"]
 
-```typescript
-const teamName = "$ARGUMENTS-swarm";
+## Resume Instructions
+1. [first thing to do]
+2. [second thing to do]
 
-// Check if swarm is active
-const status = await swarm({
-  operation: "monitor",
-  action: "status",
-  team_name: teamName,
+Resume with: \`/resume $ARGUMENTS\`
+`,
+  mode: "replace",
 });
-
-const stats = JSON.parse(status);
-if (stats.summary?.total_workers > 0) {
-  // Render current state for handoff
-  const ui = await swarm({
-    operation: "monitor",
-    action: "render_block",
-    team_name: teamName,
-  });
-  console.log(`✓ Swarm active (${stats.summary.total_workers} workers)`);
-  console.log(ui);
-
-  // Note in handoff that swarm was active
-  console.log("⚠️ Swarm is active - next session can resume with /resume");
-}
 ```
 
-````
+---
 
-## Record Key Learnings (Before Handoff)
+## Phase 4: Record Learnings (If Any)
 
-If you discovered important patterns or gotchas during this session:
+If you discovered patterns or gotchas worth remembering:
 
 ```typescript
 observation({
-  type: "learning", // or "pattern", "decision", "warning"
+  type: "learning",
   title: "[concise, searchable title]",
-  content: "[what you learned - specific and actionable]",
+  narrative: "[what you learned — specific and actionable]",
   bead_id: "$ARGUMENTS",
-  files: "[affected files]",
-  concepts: "[keywords for semantic search]",
+  concepts: "[keywords for search]",
 });
-````
-
-**This auto-embeds** into the vector store. The next `/resume` will find it.
-
-## Create The Handoff
-
-```bash
-mkdir -p .beads/artifacts/$ARGUMENTS/handoffs
 ```
 
-Write `.beads/artifacts/$ARGUMENTS/handoffs/$(date +%Y%m%d-%H%M).md`:
-
-```markdown
-# Handoff: $ARGUMENTS
-
-**Created:** [timestamp]
-**Branch:** [branch]
-**Commit:** [hash]
-
-## Progress
-
-What's done:
-
-- [completed step]
-- [completed step]
-
-What's in progress:
-
-- [current step] - stopped here because [reason]
-
-What's remaining:
-
-- [next step]
-- [future step]
-
-## Context
-
-Key files touched:
-
-- `src/foo.ts` - [what was changed]
-- `src/bar.ts` - [what was changed]
-
-Decisions made:
-
-- [decision]: [why]
-
-## Swarm State
-
-[If swarm was active: "Swarm persisted - workers and progress will be restored"]
-[Otherwise: "No active swarm"]
-
-## Blockers
-
-[If any blockers, list them. Otherwise "None"]
-
-## Resume Instructions
-
-1. [First thing to do]
-2. [Second thing to do]
-3. [Third thing to do]
-
-Start next session with: `/resume $ARGUMENTS`
-```
+---
 
-## Sync State
+## Phase 5: Sync
 
 ```bash
 br sync --flush-only
 ```
 
-This commits the handoff and pushes to remote.
+---
 
 ## Output
 
 ```
 Handoff: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━
 
 Branch: [branch]
 Commit: [hash]
-Progress: [X]% complete
-Saved: .beads/artifacts/$ARGUMENTS/handoffs/[timestamp].md
+Saved:  handoffs/$ARGUMENTS (memory system)
 
 Next session: /resume $ARGUMENTS
 ```
-
-## Record Learnings (If Any)
-
-If you discovered something worth remembering:
-
-```typescript
-observation({
-  type: "learning",
-  title: "[what you learned]",
-  content: "[details]",
-  bead_id: "$ARGUMENTS",
-});
-```
-
-Start fresh session for best performance. Context accumulation degrades output quality.

package/dist/template/.opencode/command/init.md

@@ -17,253 +17,87 @@ skill({ name: "index-knowledge" });
 
 ## Options
 
-- `--deep`: Comprehensive research (~100+ tool calls). Git history, patterns, contributors, subsystem detection.
-- `--skip-questions`: Skip upfront questions, infer from git config.
-
-Default: Standard research (~20-50 tool calls).
+| Argument           | Default | Description                               |
+| ------------------ | ------- | ----------------------------------------- |
+| `--deep`           | false   | Comprehensive research (~100+ tool calls) |
+| `--skip-questions` | false   | Infer from git config, skip prompts       |
 
 ## Phase 1: Upfront Questions
 
 Unless `--skip-questions`, ask in one message:
 
-1. **Identity**: "Which git contributor are you?" (show top 5 from !`git shortlog -sn --all | head -5`)
+1. **Identity**: "Which git contributor are you?" (show top 5 from `git shortlog -sn --all`)
 2. **Communication**: "Terse or detailed responses?"
 3. **Workflow**: "Auto-commit or ask-first?"
 4. **Rules**: "Any rules I should always follow?"
-5. **Beads**: "Use beads for task tracking? (y/n)"
+5. **Beads**: "Use beads for task tracking?"
 
 If skipped, infer identity from `git config user.name` and `git config user.email`.
 
 ## Phase 2: Detect Project
 
-### Always Check
-
-- `package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml` - tech stack WITH VERSIONS
-- `README.md` - project description
-- `.github/workflows/`, `.gitlab-ci.yml` - CI/CD
-- `Makefile`, `justfile` - build commands
-- Existing rules: `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`
-- Top-level directories - identify structure
-
-### Validate Commands
-
-!`npm run build 2>&1 | head -5` # Check for errors
-!`npm test -- --help 2>&1 | head -3` # Verify test syntax
-
-### With --deep
-
-!`git shortlog -sn --all | head -10` # contributors
-!`git log --format="%s" -50` # commit conventions
-!`git branch -a` # branching strategy
-
-- Source file analysis for patterns
-- Identify subsystems needing nested AGENTS.md
-
-## Phase 3: Create Project-Root AGENTS.md
-
-Create `./AGENTS.md` - **TARGET: <60 lines** (max 150 lines).
-
-Research shows: Frontier LLMs reliably follow ~150-200 instructions. More = degraded quality across ALL instructions.
-
-```markdown
-# [Project Name]
-
-## Tech Stack
-
-- [Language] [version] with [framework] [version]
-- [Key dependencies with versions]
-- [Build tool]: [tool name]
-
-## File Structure
-```
-
-src/ # Source code
-tests/ # Test files  
-docs/ # Documentation
-scripts/ # Build/deploy scripts
-
-````
-
-## Commands
-
-**Build**: `[detected command]`
-**Test**: `[detected command]` (single test: `[syntax]`)
-**Lint**: `[detected command]`
-**Dev**: `[detected command]`
-
-## Code Examples
-
-Good pattern (from your codebase):
+Detect and validate:
 
-```[language]
-[Actual code snippet showing preferred style - 5-10 lines]
-````
+- Package manager and dependencies (with versions)
+- Build, test, lint, dev commands — **validate each actually works**
+- CI/CD configuration
+- Existing AI rules (`.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
+- Top-level directory structure
 
-## Testing
+With `--deep`: Also analyze git history (contributors, commit conventions, branching strategy), source patterns, and subsystem candidates.
 
-- Tests live in: `[path]`
-- Run single test: `[command]`
-- Verify changes: `[command]`
+## Phase 3: Create AGENTS.md
 
-## Boundaries
+Create `./AGENTS.md` — **target <60 lines** (max 150). Follow the `index-knowledge` skill format:
 
-✅ **Always**: Run lint before commit, include tests for new features
-⚠️ **Ask first**: Schema changes, new dependencies, file deletions
-🚫 **Never**: Commit secrets, modify vendor/, force push main, skip tests
+- Tech stack with versions
+- File structure
+- Commands (validated)
+- Code example from actual codebase (5-10 lines)
+- Testing conventions
+- Boundaries (always/ask-first/never)
+- Gotchas
 
-## Gotchas
+**Principles**: Examples > explanations. Pointers > copies. If AGENTS.md already exists, improve it — don't overwrite blindly.
 
-- [Known issue or edge case]
-- [Thing that will waste 2+ hours if forgotten]
+## Phase 4: Populate Memory Files
 
-````
+Read templates from `.opencode/memory/_templates/`, then create:
 
-**Key principles:**
-- Examples > Explanations (LLMs are in-context learners)
-- Pointers > Copies ("See docs/architecture.md" not inline everything)
-- If AGENTS.md exists, improve it - don't overwrite blindly
+- `.opencode/memory/project/user.md` — from Phase 1 answers
+- `.opencode/memory/project/tech-stack.md` — from Phase 2 detection
 
-## Phase 4: Detect Subsystems (--deep only)
+Use `write()` for markdown files on disk (not `memory-update()` which writes to SQLite).
 
-For projects with distinct subsystems, identify candidates for nested AGENTS.md:
+## Phase 5: Subsystems (--deep only)
 
-!`find . -type d \( -name "src" -o -name "packages" -o -name "apps" \) | head -10`
-
-Suggest nested AGENTS.md for:
+Identify candidates for nested AGENTS.md:
 
 - `packages/*/` in monorepos
-- `src/` vs `tests/` if patterns differ significantly
 - `frontend/` vs `backend/` directories
+- Significantly different subsystem patterns
 
-Output suggestion:
-
-```
-Detected subsystems that may benefit from nested AGENTS.md:
-- packages/api/ - API server patterns
-- packages/web/ - Frontend patterns
-- tests/ - Testing conventions
-
-Create nested AGENTS.md files? (y/n)
-```
-
-### Optional Follow-Up: Index Knowledge
-
-If the repo is large or keeps changing (monorepos especially), generate/refresh hierarchical `AGENTS.md` using:
-
-- `/index-knowledge`
-
-## Phase 5: Populate Memory Files
-
-Read templates, then use `write` tool to create actual markdown files:
-
-```typescript
-// 1. Read templates to understand structure
-read({ filePath: ".opencode/memory/_templates/user.md" });
-read({ filePath: ".opencode/memory/_templates/tech-stack.md" });
-
-// 2. Use WRITE tool to create/update actual markdown files
-// ⚠️ IMPORTANT: memory-update writes to SQLite, NOT markdown files!
-// Use write() for .md files, memory-update() for SQLite storage
-
-write({
-  filePath: ".opencode/memory/project/user.md",
-  content: "..." // Populated from Phase 1 answers
-});
-
-write({
-  filePath: ".opencode/memory/project/tech-stack.md",
-  content: "..." // Populated from Phase 2 detection
-});
-```
-
-**Critical distinction:**
-- `write()` → Updates **markdown files** on disk
-- `memory-update()` → Writes to **SQLite database** (memory system)
-
-### .opencode/memory/project/user.md
-
-Populate from Phase 1 answers:
-- Identity (name, git contributor)
-- Communication preferences (terse/detailed)
-- Workflow preferences (auto-commit/ask-first)
-- Custom rules
-
-### .opencode/memory/project/tech-stack.md
-
-Populate from Phase 2 detection:
-- Framework & version
-- Language & runtime
-- Key dependencies with versions
-- Key constraints
-
-**Note:** AI discovers commands, architecture, conventions, and gotchas organically and saves via `observation` tool.
+Ask user before creating nested files.
 
 ## Phase 6: Initialize Beads (if requested)
 
-If user said yes to beads:
-
 ```bash
-br init  # Initialize beads_rust task tracking
-```
-
-Create `.beads/` directory structure for task tracking.
-
-## Phase 7: Reflection
-
-Before finishing, verify:
-
-1. [ ] AGENTS.md is <60 lines (or has good reason to be longer)?
-2. [ ] Commands were validated and actually work?
-3. [ ] Boundaries section includes Never rules?
-4. [ ] At least one code example from actual codebase?
-5. [ ] Memory files created with accurate info?
-
-Fix any issues found.
-
-## Phase 8: Summary
-
-Report:
-
+br init
 ```
-Initialization Complete
-━━━━━━━━━━━━━━━━━━━━━━━
-
-Files created:
-- ./AGENTS.md ([N] lines)
-- .opencode/memory/user.md
-- .opencode/memory/project/tech-stack.md
-[- .beads/ (if initialized)]
 
-Tech stack: [detected]
-Commands validated: [yes/no]
+## Phase 7: Verify and Report
 
-Note: Commands, architecture, conventions, and gotchas are discovered
-organically and saved via the observation tool as the AI works.
-
-Suggested next steps:
-1. Review AGENTS.md and adjust boundaries
-2. Run /review-codebase to check conventions
-3. [If --deep suggested subsystems] Create nested AGENTS.md files
-```
+Verify:
 
-## File Locations
-
-```
-./AGENTS.md                              # Project-specific rules (created, <60 lines)
-.opencode/AGENTS.md                      # Global rules (untouched)
-.opencode/memory/_templates/user.md      # User template
-.opencode/memory/_templates/tech-stack.md # Tech stack template
-.opencode/memory/project/user.md         # User preferences (created from template)
-.opencode/memory/project/tech-stack.md   # Tech stack (created from template)
-.opencode/memory/observations/           # Learnings captured organically by AI
-[packages/*/AGENTS.md]                   # Subsystem rules (--deep, if requested)
-```
+- [ ] AGENTS.md is <60 lines (or justified if longer)
+- [ ] Commands validated and work
+- [ ] Boundaries include Never rules
+- [ ] At least one code example from actual codebase
+- [ ] Memory files created with accurate info
 
-## Anti-Patterns to Avoid
+Output:
 
-- ❌ Vague instructions: "Be helpful" or "Write good code"
-- ❌ Detailed style rules (use linters instead)
-- ❌ Every possible command (context bloat)
-- ❌ Auto-generated content without review
-- ❌ Code snippets that go stale (use pointers)
-````
+1. Files created (with line counts)
+2. Tech stack detected
+3. Commands validated (yes/no)
+4. Suggested next steps: review AGENTS.md, run `/review-codebase`