opencodekit 0.20.4 → 0.20.6

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

@@ -16,6 +16,8 @@ Create a bead, write its specification (PRD), claim it, set up the workspace, an
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "workspace-setup" });
 skill({ name: "prd" }); // PRD template guidance
 skill({ name: "prd-task" }); // PRD → executable tasks (Phase 8)
 ```
@@ -43,6 +45,7 @@ skill({ name: "prd-task" }); // PRD → executable tasks (Phase 8)
 - **Check duplicates**: Always run Phase 1 duplicate check
 - **No implementation**: This command creates specs and workspace — don't write implementation code
 - **Verify PRD**: Before saving, verify all sections are filled (no placeholders)
+- **Flag uncertainty**: Use `[NEEDS CLARIFICATION]` markers for unknowns — never guess silently
 
 ## Available Tools
 
@@ -56,14 +59,7 @@ skill({ name: "prd-task" }); // PRD → executable tasks (Phase 8)
 
 ### Memory Search
 
-Search memory for prior work on the same topic before creating a new bead:
-
-```typescript
-memory - search({ query: "<description keywords>" });
-memory - search({ query: "<description keywords>", type: "decision" });
-```
-
-If memory shows a related decision or completed bead, inform the user before proceeding.
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: duplicate bead detection, prior decisions.
 
 ### Bead List Check
 
@@ -152,13 +148,57 @@ BEAD_ID=$(br create --title "$TITLE" --description "$DESCRIPTION" --type $BEAD_T
 mkdir -p ".beads/artifacts/$BEAD_ID"
 ```
 
-## Phase 6: Write PRD
+## Phase 6: Determine PRD Rigor
+
+Not every change needs a full spec. Assess complexity to choose the right PRD level:
+
+| Signal | Lite PRD | Full PRD |
+| --- | --- | --- |
+| Type | `bug`, `task` | `feature`, `epic` |
+| Files affected | 1-3 | 4+ |
+| Scope | Clear, single-concern | Cross-cutting, multi-system |
+| Research depth | Skip or Minimal | Standard or Deep |
+| Description | "Fix X in Y" | "Implement X with Y and Z" |
+
+**Auto-detect:** If type is `bug` or `task` AND research was Skip/Minimal AND description is a single sentence → default to Lite.
+
+### Lite PRD Format
+
+For simple, well-scoped work (bugs, small tasks):
+
+```markdown
+# [Title]
+
+## Problem
+[1-2 sentences: what's wrong or what's needed]
+
+## Solution
+[1-2 sentences: what to do]
 
-Copy and fill the PRD template using context from Phase 4:
+## Affected Files
+- `src/path/to/file.ts`
+
+## Tasks
+- [ ] [Task description] → Verify: `[command]`
+
+## Success Criteria
+- Verify: `npm run typecheck && npm run lint`
+- Verify: `[specific test or check]`
+```
+
+### Full PRD Format
+
+For features and complex work, use the full template:
 
 Read the PRD template from `.opencode/memory/_templates/prd.md` and write it to `.beads/artifacts/$BEAD_ID/prd.md`.
 
-### Required Sections
+## Phase 7: Write PRD
+
+Copy and fill the PRD template (lite or full) using context from Phase 4.
+
+**If Lite PRD:** Fill the lite format directly. No template file needed.
+
+**If Full PRD:** Read the template and fill all required sections:
 
 | Section           | Source                                                     | Required          |
 | ----------------- | ---------------------------------------------------------- | ----------------- |
@@ -181,7 +221,7 @@ Tasks must follow the `prd-task` skill format:
 - Metadata block: `depends_on`, `parallel`, `conflicts_with`, `files`
 - At least one verification command per task
 
-## Phase 7: Validate PRD
+## Phase 8: Validate PRD
 
 Before saving, verify:
 
@@ -192,12 +232,13 @@ Before saving, verify:
 - [ ] Tasks have `[category]` headings
 - [ ] Each task has verification
 - [ ] No implementation code in the PRD
+- [ ] No unresolved `[NEEDS CLARIFICATION]` markers remain (convert to Open Questions or resolve)
 
 If any check fails, fix it — don't ask the user.
 
-## Phase 8: Claim and Prepare Workspace
+## Phase 9: Claim and Prepare Workspace
 
-**If `--spec-only` was passed, skip to Phase 10 (Report).**
+**If `--spec-only` was passed, skip to Phase 12 (Report).**
 
 ### Workspace Check
 
@@ -218,66 +259,21 @@ br update $BEAD_ID --status in_progress
 
 ### Create Branch
 
-Ask user how to handle workspace:
+### Workspace Setup
 
-```typescript
-question({
-  questions: [
-    {
-      header: "Workspace",
-      question: "How do you want to set up the workspace?",
-      options: [
-        {
-          label: "Create feature branch (Recommended)",
-          description: "git checkout -b feat/<bead-id>-<title>",
-        },
-        {
-          label: "Use current branch",
-          description: "Work on current branch",
-        },
-        {
-          label: "Create worktree",
-          description: "Isolated git worktree for this bead",
-        },
-      ],
-    },
-  ],
-});
-```
-
-**If feature branch selected:**
+Follow the [workspace-setup](../skill/workspace-setup/SKILL.md) skill protocol.
 
-Map bead type to branch prefix:
-
-| Bead Type | Branch Prefix |
-| --------- | ------------- |
-| feature   | feat          |
-| bug       | fix           |
-| task      | task          |
-| epic      | epic          |
-
-Create the branch:
-
-```bash
-# Example: feat/br-42-add-auth
-git checkout -b $PREFIX/$BEAD_ID-$TITLE_SLUG
-```
-
-Slugify the title (lowercase, spaces to hyphens) and use the bead type to determine the prefix.
-
-**If worktree selected:**
+Additionally offer a "Create worktree" option:
 
 ```typescript
 skill({ name: "using-git-worktrees" });
 ```
 
-**If current branch:** Continue without branch creation.
-
-## Phase 9: Convert PRD to Tasks
+## Phase 10: Convert PRD to Tasks
 
 Use `prd-task` skill to convert PRD markdown → executable JSON (`prd.json`).
 
-## Phase 10: Report
+## Phase 11: Report
 
 Output:
 
@@ -295,8 +291,8 @@ br comments add $BEAD_ID "Created prd.md with [N] tasks, [M] success criteria"
 
 ## Related Commands
 
-| Need               | Command       |
-| ------------------ | ------------- |
-| Research first     | `/research`   |
-| Plan after spec    | `/plan <id>`  |
-| Implement and ship | `/ship <id>`  |
+| Need               | Command      |
+| ------------------ | ------------ |
+| Research first     | `/research`  |
+| Plan after spec    | `/plan <id>` |
+| Implement and ship | `/ship <id>` |

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

@@ -0,0 +1,170 @@
+---
+description: Think through an idea with structured alternatives before committing to a change
+argument-hint: "<idea or question>"
+agent: plan
+---
+
+# Explore: $ARGUMENTS
+
+Think through an idea, problem, or approach with structured alternatives and tradeoffs — before committing to a bead or plan.
+
+> **Workflow:** **`/explore`** → `/create` (if worth pursuing) or discard
+>
+> Use when you're not sure WHAT to build or HOW to approach it. This is ideation with rigor, not open-ended brainstorming.
+>
+> **When to use:** Before `/create`, when the approach isn't obvious. Skip for clear, well-scoped work.
+
+## Load Skills
+
+```typescript
+skill({ name: "brainstorming" }); // Collaborative refinement
+skill({ name: "memory-grounding" }); // Load past decisions
+```
+
+## Phase 1: Ground
+
+Search for prior art and past decisions:
+
+```typescript
+memory_search({ query: "<topic keywords>", limit: 5 });
+```
+
+```bash
+# What exists in the codebase already?
+git log --oneline -20 | grep -i "<keyword>"
+```
+
+Spawn an explore agent to understand the current state:
+
+```typescript
+task({
+  subagent_type: "explore",
+  description: "Map existing patterns for this area",
+  prompt: `Search the codebase for existing implementations, patterns, and conventions related to: $ARGUMENTS
+
+  Return: what exists today, what patterns are used, what files are involved.`,
+});
+```
+
+## Phase 2: Frame the Problem
+
+Before proposing solutions, state the problem clearly:
+
+1. **What's the goal?** (outcome, not task)
+2. **What constraints exist?** (tech stack, time, compatibility, user preferences)
+3. **What's the risk of doing nothing?** (is this urgent or nice-to-have?)
+
+If the problem isn't clear after reading context, ask the user to clarify — but max 2 questions.
+
+## Phase 3: Generate Alternatives
+
+Produce 2-3 approaches. For each:
+
+| Aspect       | What to Cover                          |
+| ------------ | -------------------------------------- |
+| **Approach** | 1-2 sentence summary                   |
+| **How**      | Key implementation steps (3-5 bullets) |
+| **Pros**     | What this gets right                   |
+| **Cons**     | What this gets wrong or makes harder   |
+| **Effort**   | S (<1h), M (1-3h), L (1-2d), XL (>2d)  |
+| **Risk**     | What could go wrong                    |
+
+**Rules for alternatives:**
+
+- At least one must be the simplest viable option
+- At least one must be different in kind, not just degree (different architecture, not just different library)
+- Don't pad with bad options to make the recommended one look good
+
+## Phase 4: Recommend
+
+Pick one approach and explain why:
+
+```markdown
+## Recommendation
+
+**Approach:** [Name]
+**Effort:** [S/M/L/XL]
+**Why:** [2-3 sentences — why this over the others]
+**When to reconsider:** [What signals would make you switch to an alternative]
+```
+
+## Phase 5: Output Proposal
+
+Write the proposal as a structured document:
+
+```markdown
+# Exploration: [Topic]
+
+## Problem
+
+[What we're trying to solve]
+
+## Constraints
+
+- [Constraint 1]
+- [Constraint 2]
+
+## Alternatives
+
+### Option A: [Name]
+
+- **How:** ...
+- **Pros:** ...
+- **Cons:** ...
+- **Effort:** S/M/L/XL
+
+### Option B: [Name]
+
+- **How:** ...
+- **Pros:** ...
+- **Cons:** ...
+- **Effort:** S/M/L/XL
+
+### Option C: [Name] (if applicable)
+
+...
+
+## Recommendation
+
+**Option [X]** because [reasoning].
+**Reconsider if:** [triggers for switching]
+
+## Next Step
+
+`/create "[description based on chosen approach]"`
+```
+
+**If a bead exists:** Save to `.beads/artifacts/$BEAD_ID/exploration.md`
+**If no bead:** Display inline, don't create files.
+
+## Phase 6: Ask User
+
+Present the proposal and ask:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Approach",
+      question: "Which approach do you want to pursue?",
+      options: [
+        { label: "Option A (Recommended)", description: "[brief]" },
+        { label: "Option B", description: "[brief]" },
+        { label: "Option C", description: "[brief]" },
+        { label: "None — need more research", description: "Spawn scout agents" },
+      ],
+    },
+  ],
+});
+```
+
+If user picks an approach → suggest `/create "[description]"` with the chosen approach baked in.
+If user wants more research → spawn `@scout` for the specific unknowns.
+
+## Related Commands
+
+| Need                      | Command                             |
+| ------------------------- | ----------------------------------- |
+| Commit to an approach     | `/create`                           |
+| Research external options | `/research`                         |
+| Open-ended ideation       | Load `brainstorming` skill directly |

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

@@ -155,7 +155,129 @@ For each rule:
 
 Flag rules with intent but no control as **IMPORTANT** gaps.
 
-## Phase 5: Agent Tool Restriction Audit
+## Phase 5: AI Governance Audit
+
+Audit AI-facing configuration for token efficiency, rule health, and instruction quality.
+
+### 5a. Token Budget Estimation
+
+Estimate the total token cost of context injected into each command execution:
+
+```bash
+# Base context (always injected)
+echo "=== Base Context ==="
+wc -c AGENTS.md
+wc -c .opencode/memory/project/user.md .opencode/memory/project/tech-stack.md .opencode/memory/project/project.md 2>/dev/null
+echo "=== Agent Prompts ==="
+wc -c .opencode/agent/*.md 2>/dev/null
+```
+
+For each command, estimate total context = Base + Agent prompt + Skills loaded:
+
+| Command | Base | Agent    | Skills Loaded                                          | Est. Tokens | Budget             |
+| ------- | ---- | -------- | ------------------------------------------------------ | ----------- | ------------------ |
+| `/ship` | [N]  | build.md | beads, memory-grounding, workspace-setup, verification | [total]     | [OK/HEAVY/BLOATED] |
+| `/plan` | [N]  | plan.md  | beads, memory-grounding, writing-plans                 | [total]     | [OK/HEAVY/BLOATED] |
+| ...     | ...  | ...      | ...                                                    | ...         | ...                |
+
+**Thresholds:**
+
+- **OK**: < 15k tokens total injected context
+- **HEAVY**: 15-30k tokens (warn — leaves less room for codebase context)
+- **BLOATED**: > 30k tokens (flag — likely causing quality degradation)
+
+Rough token estimate: `bytes / 4` for English text.
+
+### 5b. Rule Echo Detection
+
+Find instructions duplicated across layers:
+
+```bash
+# Find common instruction phrases across AGENTS.md and agent prompts
+# Look for exact or near-duplicate paragraphs
+grep -hF "Never" AGENTS.md .opencode/agent/*.md | sort | uniq -c | sort -rn | head -20
+grep -hF "Always" AGENTS.md .opencode/agent/*.md | sort | uniq -c | sort -rn | head -20
+grep -hF "MUST" AGENTS.md .opencode/agent/*.md | sort | uniq -c | sort -rn | head -20
+```
+
+Also check for:
+
+- Rules in AGENTS.md that are repeated verbatim in agent prompts (redundant — AGENTS.md is already injected)
+- Rules in agent prompts that contradict AGENTS.md (dangerous)
+- Rules in skills that duplicate AGENTS.md content (bloat)
+
+Report:
+
+| Rule Text (truncated)   | Found In            | Count | Issue                       |
+| ----------------------- | ------------------- | ----- | --------------------------- |
+| "Never force push main" | AGENTS.md, build.md | 2     | ECHO — remove from build.md |
+| "Stage specific files"  | AGENTS.md, ship.md  | 2     | ECHO — remove from ship.md  |
+
+### 5c. Instruction Bloat Detection
+
+Flag oversized configuration files:
+
+| File             | Lines | Tokens (est.) | Status            |
+| ---------------- | ----- | ------------- | ----------------- |
+| AGENTS.md        | [N]   | [N]           | [OK/WARN/BLOATED] |
+| [skill]/SKILL.md | [N]   | [N]           | [OK/WARN/BLOATED] |
+| [command].md     | [N]   | [N]           | [OK/WARN/BLOATED] |
+
+**Thresholds:**
+
+- Skills: WARN > 200 lines, BLOATED > 400 lines
+- Commands: WARN > 300 lines, BLOATED > 500 lines
+- AGENTS.md: WARN > 500 lines, BLOATED > 800 lines
+
+### 5d. Compression Opportunities
+
+Identify repeated boilerplate across skills and commands:
+
+````bash
+# Find common blocks across skills
+for f in .opencode/skill/*/SKILL.md; do
+  grep -c "## When to Use" "$f"
+  grep -c "## When NOT to Use" "$f"
+done
+
+# Find repeated code blocks
+grep -rh "```typescript" .opencode/command/*.md | wc -l
+grep -rh "skill({ name:" .opencode/command/*.md | sort | uniq -c | sort -rn | head -10
+````
+
+Flag opportunities:
+
+- Skills that share >50% identical content (candidates for merging or shared base)
+- Commands with identical boilerplate sections (candidates for shared template)
+- Repeated `skill({ name: "X" })` calls across commands (consider making X a dependency)
+
+### AI Governance Report
+
+```text
+## AI Governance Summary
+
+Token Budget:
+- Lightest command: [command] ([N] tokens)
+- Heaviest command: [command] ([N] tokens)
+- Commands over budget: [list]
+
+Rule Health:
+- Echo rules found: [N] (wasted tokens on duplicates)
+- Contradictions found: [N] (CRITICAL)
+- Compression opportunities: [N]
+
+Instruction Bloat:
+- Oversized skills: [N]
+- Oversized commands: [N]
+- AGENTS.md status: [OK/WARN/BLOATED]
+
+Recommendations:
+1. [Most impactful recommendation]
+2. [Second recommendation]
+3. [Third recommendation]
+```
+
+## Phase 6: Agent Tool Restriction Audit
 
 For each agent in `.opencode/agent/*.md`:
 
@@ -170,7 +292,7 @@ Flag:
 - **IMPORTANT**: Agents with no tool restrictions at all
 - **MINOR**: Agents with restrictions that could be tighter
 
-## Phase 6: Report
+## Phase 7: Report
 
 Output a health report: