opencodekit 0.17.10 → 0.17.12

package/dist/template/.opencode/AGENTS.md

@@ -44,23 +44,44 @@ When instructions conflict:
 - Read files before editing
 - Delegate when work is large, uncertain, or cross-domain
 
+### Anti-Redundancy
+
+- **Search before creating** — always check if a utility, helper, or component already exists before creating a new one
+- **No wrapper files** — don't create files that only re-export from other files; import directly from the source
+- **One home per concept** — if a function/class already exists somewhere, use it; don't duplicate in a new location
+
 ### Verification Before Completion
 
 - No success claims without fresh evidence
+- **Verify external APIs before using** — check local type definitions, source code, or official docs; never guess library method signatures or options
 - Run relevant commands (typecheck/lint/test/build) after meaningful changes
 - If verification fails twice on the same approach, stop and escalate with blocker details
+- **Lint churn auto-resolution** — if staged diffs are formatting-only, auto-resolve without asking. If a commit was already requested, auto-stage formatting follow-ups.
+- **Auto-detect project toolchain** — look for `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Makefile`, etc. and run the appropriate verification commands
+- **Common verification patterns:**
+
+| Indicator        | Typecheck                               | Lint                    | Test            |
+| ---------------- | --------------------------------------- | ----------------------- | --------------- |
+| `package.json`   | `npm run typecheck`                     | `npm run lint`          | `npm test`      |
+| `Cargo.toml`     | `cargo check`                           | `cargo clippy`          | `cargo test`    |
+| `pyproject.toml` | `mypy .` or `pyright`                   | `ruff check .`          | `pytest`        |
+| `go.mod`         | `go vet ./...`                          | `golangci-lint run`     | `go test ./...` |
+| `pom.xml`        | `mvn compile`                           | `mvn checkstyle:check`  | `mvn test`      |
+| `build.gradle`   | `gradle compileJava`                    | `gradle checkstyleMain` | `gradle test`   |
+| `Makefile`       | Check for `check`/`lint`/`test` targets |                         |                 |
 
 ---
 
 ## Hard Constraints (Never Violate)
 
-| Constraint    | Rule                                              |
-| ------------- | ------------------------------------------------- |
-| Security      | Never expose/invent credentials                   |
-| Git Safety    | Never force push main/master; never bypass hooks  |
-| Honesty       | Never fabricate tool output; never guess URLs     |
-| Paths         | Use absolute paths for file operations            |
-| Reversibility | Ask first before destructive/irreversible actions |
+| Constraint    | Rule                                                                              |
+| ------------- | --------------------------------------------------------------------------------- |
+| Security      | Never expose/invent credentials                                                   |
+| Git Safety    | Never force push main/master; never bypass hooks                                  |
+| Git Restore   | Never run `reset --hard`, `checkout .`, `clean -fd` without explicit user request |
+| Honesty       | Never fabricate tool output; never guess URLs                                     |
+| Paths         | Use absolute paths for file operations                                            |
+| Reversibility | Ask first before destructive/irreversible actions                                 |
 
 ---
 
@@ -76,6 +97,18 @@ If blocked, report the blocker; do not bypass constraints.
 
 ---
 
+## Multi-Agent Safety
+
+When multiple agents or subagents work on the same codebase:
+
+- **Don't create git stash or worktree** unless the user explicitly requests it
+- **Scope commits to your changes only** — don't stage unrelated files
+- **Never use `git add .`** — stage specific files you modified
+- **Coordinate on shared files** — if another agent is editing the same file, wait or delegate
+- **No speculative cleanup** — don't reformat or refactor files you didn't need to change
+
+---
+
 ## Delegation Policy
 
 Use specialist agents by intent:
@@ -167,11 +200,14 @@ For major tracked work:
 
 ### File Size Guidance
 
+Files over ~500 lines become hard to maintain and review. Extract helpers, split modules, or refactor when approaching this threshold.
+
 | Size          | Strategy                          |
 | ------------- | --------------------------------- |
 | < 100 lines   | Full rewrite often easier         |
 | 100-400 lines | Structured edit with good context |
 | > 400 lines   | Strongly prefer structured edits  |
+| > 500 lines   | Consider splitting the file       |
 
 **Use the `structured-edit` skill for complex edits.**
 

package/dist/template/.opencode/agent/plan.md

@@ -36,7 +36,7 @@ You are opencode, an interactive CLI tool that helps users with software enginee
 - Prefer specialized tools over shell for file operations:
   - Use Read to view files, Edit to modify files, and Write only when needed.
   - Use Glob to find files by name and Grep to search file contents.
-- Use Bash for terminal operations (git, bun, builds, tests, running scripts).
+- Use Bash for terminal operations (git, npm/pnpm, builds, tests, running scripts).
 - Run tool calls in parallel when neither call needs the other's output; otherwise run sequentially.
 
 # Planning Guidelines

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

@@ -0,0 +1,143 @@
+---
+description: Extract and persist learnings from completed work into institutional memory
+argument-hint: "[bead-id]"
+---
+
+# Compound: $ARGUMENTS
+
+Capture what was learned. This is the flywheel step — each cycle makes the next cycle faster.
+
+> **Workflow:** `/plan` → `/ship` → `/review` → **`/compound`** → `/pr`
+>
+> Run after every completed task, review, or PR merge. The value compounds over time.
+
+## What This Does
+
+Extracts learnings from the just-completed work and stores them as structured observations in memory,
+so future Plan and Ship cycles start with institutional knowledge instead of blank slates.
+
+## Phase 1: Gather Evidence
+
+```bash
+# Get what changed
+git diff origin/main..HEAD --stat
+git log origin/main..HEAD --oneline
+
+# Get review comments if any
+br comments list $ARGUMENTS 2>/dev/null || echo "No bead"
+
+# Get bead context if provided
+br show $ARGUMENTS 2>/dev/null || echo "No bead specified"
+```
+
+Collect from all available sources:
+
+- Git diff (what files changed, what patterns were used)
+- Bead comments (review findings, decisions made)
+- Current session context (what was discovered, what was hard)
+- Any error messages that were solved
+
+## Phase 2: Classify Learnings
+
+For each finding, assign a type:
+
+| Type        | When to Use                                                | Example                                         |
+| ----------- | ---------------------------------------------------------- | ----------------------------------------------- |
+| `pattern`   | A reusable approach confirmed to work in this codebase     | "Always use X pattern for Y type of component"  |
+| `bugfix`    | A non-obvious bug and its root cause                       | "Bun doesn't support X, use Y instead"          |
+| `decision`  | An architectural or design choice with rationale           | "Chose JWT over sessions because..."            |
+| `gotcha`    | A footgun, constraint, or thing that looks wrong but isn't | "Don't modify dist/ directly, build overwrites" |
+| `discovery` | A non-obvious fact about the codebase or its dependencies  | "Build copies .opencode/ to dist/template/"     |
+| `warning`   | Something that will break if not followed                  | "Always run lint:fix before commit"             |
+
+**Quality bar:** Only record learnings that would save future-you 15+ minutes.
+Skip obvious things. Skip things already in AGENTS.md.
+
+## Phase 3: Store Observations
+
+For each learning worth keeping, create an observation:
+
+```typescript
+observation({
+  type: "pattern", // or bugfix, decision, gotcha, discovery, warning
+  title: "[Concise, searchable title — what someone would search for]",
+  narrative: "[What happened, why it matters, how to apply it]",
+  facts: "[comma, separated, key, facts]",
+  concepts: "[searchable, keywords, for, future, retrieval]",
+  files_modified: "[relevant/file.ts if applicable]",
+  confidence: "high", // high=verified, medium=likely, low=speculative
+});
+```
+
+**Minimum viable:** title + narrative. Everything else is bonus.
+
+## Phase 4: Check AGENTS.md / Skill Updates
+
+Ask: does this learning belong as a permanent rule?
+
+If YES (it's a codebase-level constraint everyone must follow):
+
+- Suggest updating `.opencode/memory/project/gotchas.md`
+- Or the relevant skill file if it's procedure-level
+
+If MAYBE (it's a pattern, not a rule):
+
+- The observation is sufficient
+- Don't pollute AGENTS.md with every finding
+
+**Rule:** AGENTS.md changes require user confirmation. Observations are automatic.
+
+## Phase 5: Search for Related Past Observations
+
+```typescript
+// Check if this updates or supersedes an older observation
+memory_search({ query: "[key concept from the finding]", limit: 3 });
+```
+
+If a newer finding contradicts or updates an older one, note it:
+
+```typescript
+observation({
+  type: "decision",
+  title: "...",
+  narrative: "...",
+  supersedes: "42", // ID of the older observation
+});
+```
+
+## Phase 6: Output Summary
+
+Report what was codified:
+
+```
+## Compound Summary
+
+**Work reviewed:** [brief description]
+**Learnings captured:** [N] observations
+
+| # | Type      | Title                        | Concepts               |
+|---|-----------|------------------------------|------------------------|
+| 1 | pattern   | ...                          | auth, jwt              |
+| 2 | gotcha    | ...                          | node, build            |
+| 3 | bugfix    | ...                          | typecheck, strict-mode |
+
+**AGENTS.md updates suggested:** [yes/no - describe if yes]
+**Next recommended:** /pr  (or /plan <next-bead-id>)
+```
+
+## When Nothing to Compound
+
+If the work was trivial (a config change, 1-line fix with no surprises):
+
+> "Nothing worth compounding. Work was straightforward — no non-obvious patterns, bugs, or decisions encountered."
+
+Don't force observations. Quality over quantity.
+
+## Related Commands
+
+| Need                   | Command   |
+| ---------------------- | --------- |
+| Full chain             | `/lfg`    |
+| Review before compound | `/review` |
+| Ship the work          | `/ship`   |
+| Create PR              | `/pr`     |

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

@@ -0,0 +1,171 @@
+---
+description: Full autonomous chain - Plan → Ship → Review → Compound in one command
+argument-hint: "<bead-id> [--skip-plan]"
+---
+
+# LFG (Let's Fucking Go): $ARGUMENTS
+
+Full compound engineering cycle. One command, all four steps.
+
+> **When to use:** You have a bead in `in_progress` state with a PRD. You want maximum autonomous execution with minimum hand-holding.
+>
+> **Checkpoints happen** at decision points. Everything automatable is automated.
+
+## Parse Arguments
+
+| Argument      | Default  | Description                             |
+| ------------- | -------- | --------------------------------------- |
+| `<bead-id>`   | required | The bead to execute                     |
+| `--skip-plan` | false    | Skip planning if plan.md already exists |
+
+## Phase 0: Preflight
+
+```bash
+br show $BEAD_ID
+ls .beads/artifacts/$BEAD_ID/
+```
+
+Verify:
+
+- Bead exists and is `in_progress`
+- `prd.md` exists
+- If `plan.md` exists and `--skip-plan` not set: ask user whether to replan or use existing
+
+Report:
+
+```
+## LFG: <bead-id> — <title>
+
+Cycle: Plan → Ship → Review → Compound
+Review mode: [Standard 3-agent / Deep 5-agent]
+Plan: [create new / use existing]
+```
+
+## Step 1: PLAN
+
+Load and execute the `/plan` command for this bead:
+
+```typescript
+skill({ name: "writing-plans" });
+// Run full /plan flow including Phase 0 institutional research
+// Output: .beads/artifacts/$BEAD_ID/plan.md
+```
+
+Checkpoint if plan has major unknowns or architecture questions. Otherwise proceed automatically.
+
+## Step 2: WORK
+
+Execute the plan:
+
+```typescript
+skill({ name: "executing-plans" });
+// Load plan.md, execute wave-by-wave
+// Per-task commits after each task passes verification
+```
+
+Run verification after each wave:
+
+- `npm run typecheck`
+- `npm run lint`
+- `vitest` (if tests exist for changed areas)
+
+Checkpoint only at `checkpoint:human-verify` or `checkpoint:decision` tasks.
+
+## Step 3: REVIEW
+
+```bash
+BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~$(git log --oneline | wc -l | tr -d ' '))
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+Load and run the review skill:
+
+```typescript
+skill({ name: "requesting-code-review" });
+```
+
+Dispatch 5 specialized agents in parallel.
+
+Wait for all agents to return. Synthesize findings.
+
+**Auto-fix rule:**
+
+- Critical issues → fix inline, re-verify, continue
+- Important issues → fix inline, continue
+- Minor issues → add to bead comments, continue
+
+If Critical issues cannot be auto-fixed:
+
+```
+## CHECKPOINT: Review Blocker
+
+Critical issue found that requires architectural decision:
+[description]
+
+Options:
+1. [option A]
+2. [option B]
+
+Awaiting your decision before continuing.
+```
+
+## Step 4: COMPOUND
+
+Load and run the compound command:
+
+```typescript
+// Run /compound $BEAD_ID
+// Extract learnings from the full cycle
+// Store observations to memory
+// Suggest AGENTS.md updates if conventions changed
+```
+
+## Step 5: Report & Next
+
+```
+## LFG Complete: <bead-id>
+
+### Cycle Summary
+
+| Step     | Status | Notes                        |
+|----------|--------|------------------------------|
+| Plan     | ✓      | [N] waves, [M] tasks         |
+| Work     | ✓      | [N] commits, [M] files       |
+| Review   | ✓      | [N] agents, [M] fixes        |
+| Compound | ✓      | [N] observations stored      |
+
+### Learnings Captured
+[list of observation titles]
+
+### Verification
+- typecheck: pass
+- lint: pass
+- tests: pass ([N] passing)
+
+### Next Steps
+- Review the changes: `git diff origin/main`
+- Create PR: `/pr`
+- Or continue with next bead: `/lfg <next-bead-id>`
+```
+
+## Swarm Mode (sLFG)
+
+For large plans with 6+ independent tasks, run Work step in swarm mode:
+
+```typescript
+skill({ name: "swarm-coordination" });
+// Dispatch parallel worker agents per wave
+// Leader monitors and synthesizes
+```
+
+Use when: plan has 2+ independent waves with no shared file mutations.
+
+## Related Commands
+
+| Need            | Command          |
+| --------------- | ---------------- |
+| Plan only       | `/plan <id>`     |
+| Ship only       | `/ship <id>`     |
+| Review only     | `/review`        |
+| Compound only   | `/compound <id>` |
+| Create PR after | `/pr`            |

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

@@ -36,6 +36,63 @@ skill({ name: "writing-plans" }); // TDD plan format
 - **Split signals**: Create child beads for complex work
 - **Vertical slices**: Each task should cover one feature end-to-end
 
+## Phase 0: Institutional Research (Mandatory)
+
+Before touching the PRD or planning anything, load what the codebase already knows.
+
+**This step is not optional.** Skipping it means planning in the dark.
+
+### Step 1: Search institutional memory
+
+```typescript
+// Search for past decisions, patterns, gotchas related to this work
+memory_search({ query: "<bead-title or feature keywords>", limit: 5 });
+memory_search({ query: "<key technical concept from bead>", type: "bugfix", limit: 3 });
+memory_read({ file: "handoffs/last" }); // Check last session context
+```
+
+If relevant observations found: incorporate them directly into the plan. Don't re-solve solved problems.
+
+### Step 2: Mine git history
+
+```bash
+# What has changed recently in affected areas?
+git log --oneline -20
+
+# Who wrote the relevant code and when?
+git log --oneline --follow -- <relevant-file-path>
+
+# What patterns appear in recent commits?
+git log --oneline --all | head -30
+```
+
+Look for:
+
+- Commit conventions (how this team names things)
+- Recent changes to files you'll touch (merge conflict risk)
+- How similar features were implemented before
+- Any "fix:", "revert:", "hotfix:" commits near your scope (footgun zones)
+
+### Step 3: Spawn learnings-researcher (if Level 2-3 work)
+
+```typescript
+task({
+  subagent_type: "explore",
+  description: "Search codebase for patterns related to this work",
+  prompt: `Search the codebase for patterns, conventions, and existing implementations related to: [FEATURE].
+
+  Run these searches:
+  - grep for relevant function names and patterns
+  - Find similar existing features
+  - Check test patterns for this domain
+  - Look for any TODO/FIXME comments in relevant files
+
+  Return: existing patterns to follow, files to be aware of, and any gotchas.`,
+});
+```
+
+**Only after completing Phase 0** do you proceed to planning. The research phases must use this context.
+
 ## Phase 1: Guards
 
 ```bash

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

@@ -58,6 +58,34 @@ ls .beads/artifacts/$ARGUMENTS/
 
 Read the PRD to extract goal and success criteria for the PR description.
 
+## Phase 2B: Pre-PR Review
+
+This is the last gate before code hits GitHub. Run it every time.
+
+Load the review skill:
+
+```typescript
+skill({ name: "requesting-code-review" });
+```
+
+Run **5 parallel agents**: security/correctness, performance/architecture, type-safety/tests, conventions/patterns, simplicity/completeness.
+
+```bash
+BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git merge-base HEAD origin/main)
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+Fill placeholders:
+
+- `{WHAT_WAS_IMPLEMENTED}`: what this PR delivers (from git log summary)
+- `{PLAN_OR_REQUIREMENTS}`: PRD path or brief requirements
+- `{BASE_SHA}` / `{HEAD_SHA}`: from above
+
+**Gate rule:** All Critical issues must be resolved before pushing. No exceptions.
+Important issues: fix or document as known limitation in PR body.
+
+After fixing issues, re-run verification gates from Phase 1 if code was changed.
+
 ## Phase 3: Push and Confirm
 
 Show what will be pushed and ask the user:

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

@@ -245,31 +245,36 @@ If any gate fails, fix before proceeding.
 
 ## Phase 6: Review
 
-### 5A: Code Review
-
-Spawn review agent to check changes against the PRD:
+Load and run the review skill:
 
 ```typescript
-Task({
-  subagent_type: "review",
-  description: "Review changes for $ARGUMENTS",
-  prompt: `Review changes for bead $ARGUMENTS.
-
-Read PRD: .beads/artifacts/$ARGUMENTS/prd.md
-Review: git diff HEAD
+skill({ name: "requesting-code-review" });
+```
 
-Check:
-1. Changes satisfy PRD success criteria
-2. Correctness, edge cases, security
-3. No scope creep beyond PRD files
+Run **5 parallel agents**: security/correctness, performance/architecture, type-safety/tests, conventions/patterns, simplicity/completeness.
 
-Return: findings by severity, whether success criteria are met.`,
-});
+```bash
+BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~1)
+HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-If review finds critical issues → fix → re-run Phase 4 → re-review.
+Fill placeholders:
+
+- `{WHAT_WAS_IMPLEMENTED}`: bead title + brief summary of what changed
+- `{PLAN_OR_REQUIREMENTS}`: `.beads/artifacts/$ARGUMENTS/prd.md`
+- `{BASE_SHA}` / `{HEAD_SHA}`: from above
+
+Wait for all 5 agents to return. Synthesize findings.
+
+**Auto-fix rule:**
+
+- Critical issues → fix inline, re-run Phase 5 gates, continue
+- Important issues → fix inline, continue
+- Minor issues → add to bead comments, note for `/compound` step
+
+If review finds critical issues that require architectural decisions → stop → present options to user.
 
-### 5B: Goal-Backward Verification (if plan.md exists)
+### Goal-Backward Verification (if plan.md exists)
 
 Verify that tasks completed ≠ goals achieved:
 
@@ -328,7 +333,7 @@ br close $ARGUMENTS --reason "Shipped: all PRD tasks pass, verification + review
 br sync --flush-only
 ```
 
-Record significant learnings with `observation()`.
+Record significant learnings with `/compound $ARGUMENTS` after closing.
 
 ## Output
 

package/dist/template/.opencode/memory/project/project.md

@@ -43,9 +43,9 @@ OpenCodeKit (`ock`) enables developers to bootstrap AI-assisted development envi
 
 ## Tech Stack
 
-- **Runtime:** Bun >= 1.3.2
+- **Runtime:** Node.js >= 20.19.0
 - **Language:** TypeScript (ESNext, strict mode)
-- **Build:** `bun build` + rsync for template bundling
+- **Build:** tsdown + rsync for template bundling
 - **CLI Framework:** cac
 - **UI Prompts:** @clack/prompts
 - **Validation:** zod

package/dist/template/.opencode/memory/project/state.md

@@ -43,9 +43,9 @@ updated: 2026-02-12
 
 ### Technical
 
-- Bun runtime required (>= 1.3.2)
+- Node.js runtime required (>= 20.19.0)
 - TypeScript strict mode enforced
-- Build uses rsync to bundle .opencode/ template
+- Build uses tsdown + rsync to bundle .opencode/ template
 - oxlint for linting (fast, modern)
 
 ### Product

package/dist/template/.opencode/memory/project/tech-stack.md

@@ -1,6 +1,6 @@
 ---
 purpose: Tech stack, constraints, and integrations for AI context injection
-updated: 2026-02-02
+updated: 2026-02-24
 ---
 
 # Tech Stack
@@ -11,34 +11,34 @@ This file is automatically injected into ALL AI prompts via `opencode.json` inst
 
 - **Framework:** CLI tool (cac for argument parsing)
 - **Language:** TypeScript (ESNext, strict mode, bundler moduleResolution)
-- **Runtime:** Bun >= 1.3.2
+- **Runtime:** Node.js >= 20.19.0
 
 ## Key Dependencies
 
 - **CLI Framework:** cac (^6.7.14) - Command-line argument parsing
 - **UI Prompts:** @clack/prompts (^0.7.0) - Interactive CLI prompts
-- **TUI Framework:** @opentui/core (^0.1.72) + @opentui/solid (^0.1.72) - Terminal UI
 - **Validation:** zod (^3.25.76) - Schema validation
 - **Task Tracking:** beads-village (^1.3.3) - Git-backed task management
 - **AI SDK:** @ai-sdk/provider (^3.0.6) - AI provider integration
 
 ## Build & Tools
 
-- **Build:** `bun run build.ts` + rsync for template bundling
+- **Build:** tsdown + rsync for template bundling
 - **Lint:** oxlint (^1.38.0) - Fast JavaScript/TypeScript linter
 - **Format:** oxfmt (^0.23.0) - Code formatter
-- **TypeCheck:** TypeScript 5.9.3
+- **TypeCheck:** tsgo (@typescript/native-preview)
+- **Dev Runner:** tsx - TypeScript execution for development
 
 ## Testing
 
-- **Unit Tests:** bun test (native Bun test runner)
+- **Unit Tests:** vitest
 - **Test Location:** src/\*_/_.test.ts (colocated)
-- **Run Single:** bun test src/commands/init.test.ts
+- **Run Single:** vitest src/commands/init.test.ts
 
 ## Key Constraints
 
-- Must maintain Bun compatibility (engines.bun >= 1.3.2)
-- Node.js not officially supported
+- Node.js >= 20.19.0 required (engines.node in package.json)
+- pnpm for package management
 - Build copies .opencode/ to dist/template/ - don't edit dist/ directly
 - Keep .opencode/ structure minimal and focused
 

package/dist/template/.opencode/memory/project/user.md

@@ -23,9 +23,9 @@ updated: 2025-01-06
 
 ## Technical Preferences
 
-- Runtime: Bun
+- Runtime: Node.js
 - Language: TypeScript
-- Linter: Biome
+- Linter: oxlint
 
 ## Rules to Always Follow