opencodekit 0.18.2 → 0.18.4

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

@@ -27,58 +27,6 @@ You are a general implementation subagent. You output minimal in-scope changes p
 
 Execute clear, low-complexity coding tasks quickly (typically 1-3 files) and report concrete results.
 
-## Principles
-
-### Default to Action
-
-- If scope is clear, execute immediately
-- Don't wait for permission on reversible changes
-
-### Scope Discipline
-
-- If scope grows beyond 3 files or requires architecture decisions, **delegate**
-- When requirements are underspecified, choose the safest reasonable default
-
-### Verification
-
-- Verify with relevant checks before claiming done
-- Never revert or discard user changes you did not create
-
-## Rules
-
-- Read code before editing
-- Keep changes minimal and in-scope
-- Ask before irreversible actions (commit, push, destructive ops)
-
-## Workflow
-
-1. Read relevant files
-2. Confirm scope is small and clear
-3. Make surgical edits
-4. Run validation (lint/typecheck/tests as applicable)
-5. Report changed files with `file:line` references
-
-## Output
-
-- What changed
-- Validation evidence
-- Assumptions/defaults chosen (if any)
-- Remaining risks/blockers (if any)
-
-# General Agent
-
-**Purpose**: Surgical implementer — small scope, fast execution, concrete results.
-
-> _"If the lever is small, pull it quickly. If the lever is large, escalate."_
-
-## Identity
-
-You are a general implementation subagent. You output minimal in-scope changes plus validation evidence only.
-
-## Task
-
-Execute clear, low-complexity coding tasks quickly (typically 1-3 files) and report concrete results.
-
 ## Personality
 
 - Concise, direct, and friendly

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

@@ -190,6 +190,16 @@ must_haves:
 - Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description
 - Level 3: "architecture/design/system", multiple external services, data modeling, auth design
 
+### Research Execution (Level 2+)
+
+For any research at Level 2 or above, follow the 3-pass pattern:
+
+1. **Plan**: List 3-6 sub-questions the research must answer
+2. **Retrieve**: Search each sub-question; follow 1-2 second-order leads per question
+3. **Synthesize**: Resolve contradictions between sources, write findings with citations
+
+Stop only when further searching is unlikely to change the conclusion.
+
 ## Context Budget Rules
 
 **Quality Degradation Curve:**

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

@@ -0,0 +1,79 @@
+---
+description: Lightweight runner for trivial shell, git, and filesystem operations
+mode: subagent
+temperature: 0.0
+permission:
+  bash:
+    "*": allow
+    "git push*": ask
+    "git commit*": ask
+    "git merge*": ask
+    "git reset*": ask
+    "rm*": ask
+    "sudo*": deny
+  write:
+    "*": deny
+  edit:
+    "*": deny
+---
+
+You are OpenCode, the best coding agent on the planet.
+
+# Runner Agent
+
+**Purpose**: Execute trivial operations — scripts, git commands, file system ops. No code reasoning.
+
+## Identity
+
+You are the runner agent. You execute simple, well-defined operations quickly and reliably. You don't write code or make architectural decisions.
+
+## Model Guidance
+
+- Use the cheapest/fastest available model for execution tasks
+- Temperature: 0.0 (deterministic execution)
+
+## Capabilities
+
+- Run shell commands and scripts
+- Git operations (commit, push, pull, tag, branch, merge)
+- File system operations (move, copy, delete — with confirmation for destructive ops)
+- Run build/test/lint commands
+- Read command output and report results
+
+## Restrictions
+
+- **Never edit source code files** — delegate to general or build agent
+- **Never make architectural decisions** — escalate to plan agent
+- **No complex reasoning** — if a task requires understanding code logic, escalate
+- **No implementation work** — do not fix bugs or build features
+
+## When to Use
+
+- Simple shell commands
+- Git operations (commit, push, tag, merge)
+- Running build/test/lint scripts
+- File system operations (move, copy, delete with confirmation)
+
+## When NOT to Use
+
+- Code changes or refactors
+- Bug fixes or feature implementation
+- Tasks requiring code logic analysis
+- Architecture or design decisions
+
+## Rules
+
+1. Execute exactly what is requested — no improvisation
+2. Report command output faithfully — never fabricate
+3. Ask before destructive operations (delete, force push, reset)
+4. If a command fails, report the error — don't attempt creative fixes
+5. Stage specific files only — never `git add .`
+
+## Output Format
+
+For every operation:
+1. Show the command being run
+2. Show the output
+3. Confirm success or report failure
+
+Keep output minimal. No explanations unless something fails.

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

@@ -127,8 +127,20 @@ Based on research depth choice, spawn agents:
 
 ## Phase 5: Create Bead
 
+Extract bead title and description from `$ARGUMENTS` before creating the bead.
+
+- If user provided a single line, use it for both title and description.
+- If user provided multiple lines, use first line as title and full text as description.
+
 ```bash
-BEAD_ID=$(br create "$DESCRIPTION" --type $BEAD_TYPE --json | jq -r '.id')
+TITLE=$(echo "$ARGUMENTS" | head -n1)
+DESCRIPTION=$(echo "$ARGUMENTS")
+
+if [ "$TITLE" = "$DESCRIPTION" ]; then
+  DESCRIPTION="$TITLE"
+fi
+
+BEAD_ID=$(br create --title "$TITLE" --description "$DESCRIPTION" --type $BEAD_TYPE --json | jq -r '.id')
 mkdir -p ".beads/artifacts/$BEAD_ID"
 ```
 

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

@@ -8,6 +8,8 @@ agent: build
 
 Initialize GSD-style project planning with integrated skill usage.
 
+`tech-stack.md` is the default baseline project memory file. This command adds the optional planning files (`project.md`, `roadmap.md`, `state.md`) used for richer multi-session project context.
+
 ## Load Skills
 
 ```typescript
@@ -35,10 +37,10 @@ ls .opencode/memory/project/ 2>/dev/null && HAS_CONTEXT=true || HAS_CONTEXT=fals
 cat .opencode/memory/project/project.md 2>/dev/null | head -20
 ```
 
-**If context exists:**
+**If planning context exists:**
 
 ```
-Existing planning context found:
+Existing optional planning context found:
 - project.md: [exists/size]
 - roadmap.md: [exists/size]
 - state.md: [exists/size]
@@ -64,7 +66,7 @@ Task({
   subagent_type: "explore",
   description: "Analyze tech stack",
   prompt:
-    "Analyze the codebase technology stack. Write findings to .opencode/memory/project/tech-analysis.md covering: languages, frameworks, dependencies, build tools. Return file path and line count only.",
+    "Analyze the codebase technology stack. Write findings to .opencode/memory/project/codebase/tech-analysis.md covering: languages, frameworks, dependencies, build tools. Return file path and line count only.",
 });
 
 // Agent 2: Map architecture
@@ -72,7 +74,7 @@ Task({
   subagent_type: "explore",
   description: "Analyze architecture",
   prompt:
-    "Analyze the codebase architecture. Write findings to .opencode/memory/project/arch-analysis.md covering: patterns, directory structure, entry points. Return file path and line count only.",
+    "Analyze the codebase architecture. Write findings to .opencode/memory/project/codebase/arch-analysis.md covering: patterns, directory structure, entry points. Return file path and line count only.",
 });
 
 // Wait for agents and collect confirmations
@@ -217,7 +219,7 @@ br update <bead-id> --status closed --reason="Context files created"
 
 ## Output
 
-Creates in `.opencode/memory/project/`:
+Creates optional planning context in `.opencode/memory/project/`:
 
 | File         | Purpose                                  | Lines (typical) |
 | ------------ | ---------------------------------------- | --------------- |
@@ -233,12 +235,23 @@ Additional files in `.opencode/memory/project/codebase/`:
 
 ## Success Criteria
 
-- [ ] All required documents created from templates
+- [ ] All `/init-context` planning documents created from templates
 - [ ] Documents follow template structure
 - [ ] No secrets leaked in generated files
 - [ ] Files pass basic validation (readable, non-empty)
 - [ ] User informed of next steps
 
+## Phase 6: Custom Context (Optional)
+
+Inform user about `.opencode/context/` for additional project-specific context:
+
+```
+Custom context folder available at .opencode/context/
+- Add .md files with architecture decisions, domain knowledge, team agreements
+- Add file paths to opencode.json → instructions[] for AI prompt injection
+- This folder is preserved during init --force and upgrade
+```
+
 ## Next Steps
 
 After init-context completes:
@@ -246,6 +259,7 @@ After init-context completes:
 1. **For new projects:** Use `/plan` to create first implementation plan
 2. **For brownfield:** Review codebase analysis, then `/plan`
 3. **For existing beads:** Use `/resume` to continue tracked work
+4. **For custom context:** Add `.md` files to `.opencode/context/` and reference in `opencode.json` instructions
 
 ---
 

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

@@ -55,25 +55,24 @@ updated: [today]
 
 ## Identity
 
-- **Name:** [from answers]
-- **Git:** [user.name] <[user.email]>
+- Name: [from answers]
+- Git email: [user.email]
 
 ## Communication Preferences
 
-- **Style:** [Terse/Detailed]
-- **Tone:** [Professional/Casual]
+- Style: [Terse/Detailed]
+- Tone: [Professional/Casual]
 
 ## Workflow Preferences
 
-- **Commits:** [Auto/Ask-first]
-- **Beads updates:** [Auto/Ask-first]
+- Git commits: [Auto/Ask-first]
+- Beads updates: [Auto/Ask-first]
 
 ## Technical Preferences
 
-- **Languages:** [Preferred languages]
-- **Frameworks:** [Preferred frameworks]
+- Languages/frameworks: [Preferred languages/frameworks]
 
-## Rules to Always Follow
+## Things to Remember
 
 - [Rule 1]
 - [Rule 2]
@@ -82,15 +81,15 @@ updated: [today]
 
 ## Phase 3: Update opencode.json
 
-Ensure user.md is loaded in instructions:
+Ensure `user.md` is loaded in `instructions` (bare paths, no `file://` prefix).
+
+`tech-stack.md` is the core project memory file. Other files such as `project.md`, `roadmap.md`, `state.md`, and `gotchas.md` are optional/project-specific and should only be added if they actually exist and you want them injected.
+
+Example minimal setup:
 
 ```json
 {
-  "instructions": [
-    "file://.opencode/AGENTS.md",
-    "file://.opencode/memory/project/tech-stack.md",
-    "file://.opencode/memory/project/user.md"
-  ]
+  "instructions": [".opencode/memory/project/user.md", ".opencode/memory/project/tech-stack.md"]
 }
 ```
 
@@ -100,4 +99,7 @@ Output:
 
 1. user.md created at `.opencode/memory/project/user.md`
 2. Preferences captured
-3. Next step: `/init-context` for GSD planning workflow
+3. `tech-stack.md` is the only required project memory file by default
+4. Additional project memory files are optional and can be added later
+5. Custom context available at `.opencode/context/` (preserved during init --force and upgrade)
+6. Next step: `/init-context` if the user wants fuller project-planning memory files

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

@@ -63,11 +63,10 @@ skill({ name: "executing-plans" });
 // Per-task commits after each task passes verification
 ```
 
-Run verification after each wave:
+Follow the [Verification Protocol](../skill/verification-before-completion/references/VERIFICATION_PROTOCOL.md):
 
-- `npm run typecheck`
-- `npm run lint`
-- `vitest` (if tests exist for changed areas)
+- Use **full mode** for final verification
+- Use **incremental mode** between implementation waves
 
 Checkpoint only at `checkpoint:human-verify` or `checkpoint:decision` tasks.
 

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

@@ -193,55 +193,13 @@ After each task completes (verification passed):
 - Modifying files outside task scope → stop, ask user
 - Rule 4 deviation encountered → stop, present options
 
-## Phase 4: Choose Verification Gates
+## Phase 4: Verification
 
-Ask user which gates to run:
+Follow the [Verification Protocol](../skill/verification-before-completion/references/VERIFICATION_PROTOCOL.md):
 
-```typescript
-question({
-  questions: [
-    {
-      header: "Verification Gates",
-      question: "Which verification gates should run?",
-      options: [
-        {
-          label: "All (Recommended)",
-          description: "build + test + lint + typecheck — full validation",
-        },
-        {
-          label: "Essential only",
-          description: "build + test — faster, basic validation",
-        },
-        {
-          label: "Test only",
-          description: "Just run tests",
-        },
-        {
-          label: "Skip gates",
-          description: "Trust my changes, skip verification",
-        },
-      ],
-    },
-  ],
-});
-```
-
-## Phase 5: Run Verification Gates
-
-Based on selection, run appropriate gates. Detect project type:
-
-| Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
-| --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
-| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`                | `npm run typecheck` or `tsc --noEmit` |
-| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` | (included in build)                   |
-| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
-| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
-
-Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first.
-
-Also run PRD `Verify:` commands.
-
-If any gate fails, fix before proceeding.
+- Use **full mode** (shipping requires all gates)
+- All 4 gates must pass before proceeding to commit/push
+- Also run PRD `Verify:` commands
 
 ## Phase 6: Review
 
@@ -268,7 +226,7 @@ Wait for all 5 agents to return. Synthesize findings.
 
 **Auto-fix rule:**
 
-- Critical issues → fix inline, re-run Phase 5 gates, continue
+- Critical issues → fix inline, re-run Phase 4 verification, continue
 - Important issues → fix inline, continue
 - Minor issues → add to bead comments, note for `/compound` step
 

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

@@ -98,8 +98,25 @@ question({
 
 **If feature branch selected:**
 
+Map bead type to branch prefix:
+
+| Bead Type | Branch Prefix |
+| --------- | ------------- |
+| feature   | feat          |
+| bug       | fix           |
+| task      | task          |
+| epic      | epic          |
+
 ```bash
-git checkout -b feat/$ARGUMENTS-$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+PREFIX=$(case "$BEAD_TYPE" in
+  feature) echo "feat" ;;
+  bug) echo "fix" ;;
+  task) echo "task" ;;
+  epic) echo "epic" ;;
+  *) echo "task" ;;
+esac)
+TITLE_SLUG=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+git checkout -b $PREFIX/$ARGUMENTS-$TITLE_SLUG
 ```
 
 **If worktree selected:**
@@ -110,13 +127,13 @@ skill({ name: "using-git-worktrees" });
 
 **If current branch:** Continue without branch creation.
 
-## Phase 4: Convert PRD to Tasks
+## Phase 5: Convert PRD to Tasks
 
 If `prd.json` doesn't exist yet, use `prd-task` skill to convert PRD markdown → executable JSON.
 
 If `prd.json` already exists, show progress (completed/total tasks).
 
-## Phase 5: Report and Route
+## Phase 6: Report and Route
 
 Output:
 

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

@@ -1,6 +1,6 @@
 ---
 description: Verify implementation completeness, correctness, and coherence
-argument-hint: "<bead-id> [--quick] [--fix]"
+argument-hint: "<bead-id> [--quick] [--full] [--fix]"
 agent: review
 ---
 
@@ -17,11 +17,12 @@ skill({ name: "verification-before-completion" });
 
 ## Parse Arguments
 
-| Argument    | Default  | Description                      |
-| ----------- | -------- | -------------------------------- |
-| `<bead-id>` | required | The bead to verify               |
-| `--quick`   | false    | Gates only, skip coherence check |
-| `--fix`     | false    | Auto-fix lint/format issues      |
+| Argument    | Default  | Description                                    |
+| ----------- | -------- | ---------------------------------------------- |
+| `<bead-id>` | required | The bead to verify                             |
+| `--quick`   | false    | Gates only, skip coherence check               |
+| `--full`    | false    | Force full verification mode (non-incremental) |
+| `--fix`     | false    | Auto-fix lint/format issues                    |
 
 ## Determine Input Type
 
@@ -63,21 +64,15 @@ Extract all requirements/tasks from the PRD and verify each is implemented:
 
 ## Phase 3: Correctness
 
-Detect project type and run the appropriate verification gates:
+Follow the [Verification Protocol](../skill/verification-before-completion/references/VERIFICATION_PROTOCOL.md):
 
-| Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
-| --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
-| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`                | `npm run typecheck` or `tsc --noEmit` |
-| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` | (included in build)                   |
-| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
-| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
-
-Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first — prefer those over generic defaults.
+- Use **incremental mode** for `verify` (pre-commit checks)
+- Use **full mode** if `--full` flag is passed
+- Run parallel group first, then sequential group
+- Report results in gate results table format
 
 If `--fix` flag provided, run the project's auto-fix command (e.g., `npm run lint:fix`, `ruff check --fix`, `cargo clippy --fix`).
 
-Report gate results (pass/warn/fail for each).
-
 ## Phase 4: Coherence (skip with --quick)
 
 Cross-reference artifacts for contradictions:

package/dist/template/.opencode/context/README.md

@@ -0,0 +1,29 @@
+# Project Context
+
+Files in this directory are automatically injected into all AI prompts via the `instructions` array in `opencode.json`.
+
+## Purpose
+
+Put project-specific context here that you want the AI to always know about:
+- Architecture decisions
+- Business domain knowledge  
+- API conventions
+- Team agreements
+- Anything the AI needs as background context
+
+## How it works
+
+1. Add `.md` files to this directory
+2. Add the file path to `opencode.json` → `instructions[]`:
+   ```json
+   "instructions": [
+     ".opencode/context/your-file.md"
+   ]
+   ```
+3. The file content will be injected into every AI prompt
+
+## Important
+
+- This directory is **preserved** during `init --force` and `upgrade`
+- Keep files concise — every token counts in the AI context window
+- Use markdown format for best results

package/dist/template/.opencode/memory/_templates/{STATE.md → state.md}

@@ -12,7 +12,7 @@ updated: 2024-12-21
 **Active Bead:** br-xxx - [Title]
 **Status:** [In Progress / Blocked / Review]
 **Started:** [Date]
-**Phase:** [Phase name from ROADMAP.md]
+**Phase:** [Phase name from roadmap.md]
 
 ## Recent Completed Work