opencodekit 0.20.2 → 0.20.3

package/dist/index.js

@@ -20,7 +20,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 //#endregion
 //#region package.json
-var version = "0.20.2";
+var version = "0.20.3";
 
 //#endregion
 //#region src/utils/license.ts

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

@@ -8,6 +8,10 @@ permission:
     "git push*": ask
     "rm -rf*": ask
     "sudo*": ask
+    "git add .": deny
+    "git add -A": deny
+    "*--no-verify*": deny
+    "cat .env*": deny
   write:
     "*": allow
   edit:

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

@@ -21,6 +21,10 @@ permission:
     "git commit*": deny
     "git reset*": deny
     "sudo*": deny
+    "git add .": deny
+    "git add -A": deny
+    "*--no-verify*": deny
+    "cat .env*": deny
 ---
 
 You are OpenCode, the best coding agent on the planet.

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

@@ -9,6 +9,10 @@ permission:
     "git commit*": ask
     "rm -rf*": deny
     "sudo*": deny
+    "git add .": deny
+    "git add -A": deny
+    "*--no-verify*": deny
+    "cat .env*": deny
 ---
 
 You are OpenCode, the best coding agent on the planet.

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

@@ -20,6 +20,10 @@ permission:
     "git commit*": deny
     "git reset*": deny
     "npm publish*": deny
+    "git add .": deny
+    "git add -A": deny
+    "*--no-verify*": deny
+    "cat .env*": deny
   question: allow
 ---
 

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

@@ -17,6 +17,10 @@ permission:
     "git push*": deny
     "git commit*": deny
     "git reset*": deny
+    "git add .": deny
+    "git add -A": deny
+    "*--no-verify*": deny
+    "cat .env*": deny
 ---
 
 You are opencode, an interactive CLI tool that helps users with software engineering tasks.

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

@@ -22,6 +22,10 @@ permission:
     "git commit*": deny
     "git reset*": deny
     "npm publish*": deny
+    "git add .": deny
+    "git add -A": deny
+    "*--no-verify*": deny
+    "cat .env*": deny
 ---
 
 You are OpenCode, the best coding agent on the planet.

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

@@ -1,30 +1,32 @@
 ---
-description: Create a bead with specification from a description
-argument-hint: "<description> [--type epic|feature|task|bug]"
+description: Create a bead with specification, claim it, and prepare workspace
+argument-hint: "<description> [--type epic|feature|task|bug] [--spec-only]"
 agent: build
 ---
 
 # Create: $ARGUMENTS
 
-Create a bead and its specification (PRD) from a description.
+Create a bead, write its specification (PRD), claim it, set up the workspace, and convert to executable tasks — ready for `/ship`.
 
-> **Workflow:** **`/create`** → `/start <id>` → `/ship <id>`
+> **Workflow:** **`/create`** → `/ship <id>`
 >
-> This command creates the specification ONLY. Do NOT write any implementation code.
+> Use `--spec-only` to create the specification without claiming or setting up workspace.
 
 ## Load Skills
 
 ```typescript
 skill({ name: "beads" });
 skill({ name: "prd" }); // PRD template guidance
+skill({ name: "prd-task" }); // PRD → executable tasks (Phase 8)
 ```
 
 ## Parse Arguments
 
-| Argument        | Default       | Description                        |
-| --------------- | ------------- | ---------------------------------- |
-| `<description>` | required      | What to build/fix (quoted string)  |
-| `--type`        | auto-detected | Override: epic, feature, task, bug |
+| Argument        | Default       | Description                               |
+| --------------- | ------------- | ----------------------------------------- |
+| `<description>` | required      | What to build/fix (quoted string)         |
+| `--type`        | auto-detected | Override: epic, feature, task, bug        |
+| `--spec-only`   | false         | Create spec without claiming or workspace |
 
 ## Determine Input Type
 
@@ -39,7 +41,7 @@ skill({ name: "prd" }); // PRD template guidance
 - **Be certain**: Only create beads you're confident have clear scope
 - **Don't over-spec**: If the description is vague, ask clarifying questions first
 - **Check duplicates**: Always run Phase 1 duplicate check
-- **No implementation**: This command creates specs only, don't write code
+- **No implementation**: This command creates specs and workspace — don't write implementation code
 - **Verify PRD**: Before saving, verify all sections are filled (no placeholders)
 
 ## Available Tools
@@ -52,11 +54,24 @@ skill({ name: "prd" }); // PRD template guidance
 
 ## Phase 1: Duplicate Check
 
+### 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.
+
+### Bead List Check
+
 ```bash
 br list --status=open --status=in_progress
 ```
 
-If a matching bead exists, stop and tell the user to use `/start <id>` instead.
+If a matching bead exists, stop and tell the user to use `/ship <id>` instead.
 
 ## Phase 2: Classify Type
 
@@ -137,13 +152,9 @@ BEAD_ID=$(br create --title "$TITLE" --description "$DESCRIPTION" --type $BEAD_T
 mkdir -p ".beads/artifacts/$BEAD_ID"
 ```
 
-Extract title and description from `$ARGUMENTS`:
-- Single line input: use as both title and description
-- Multi-line input: first line as title, full text as description
-
 ## Phase 6: Write PRD
 
-Copy and fill the PRD template using context from Phase 3:
+Copy and fill the PRD template using context from Phase 4:
 
 Read the PRD template from `.opencode/memory/_templates/prd.md` and write it to `.beads/artifacts/$BEAD_ID/prd.md`.
 
@@ -156,10 +167,10 @@ Read the PRD template from `.opencode/memory/_templates/prd.md` and write it to
 | Proposed Solution | Codebase patterns + user intent                            | Always            |
 | Success Criteria  | User verification + test commands (must include `Verify:`) | Always            |
 | Technical Context | Explore agent findings                                     | Always            |
-| Affected Files    | Explore agent findings (real paths from Phase 3)           | Always            |
+| Affected Files    | Explore agent findings (real paths from Phase 4)           | Always            |
 | Tasks             | Derived from scope + solution                              | Always            |
 | Risks             | Codebase exploration                                       | Feature/epic only |
-| Open Questions    | Unresolved items from Phase 3                              | If any exist      |
+| Open Questions    | Unresolved items from Phase 4                              | If any exist      |
 
 ### Task Format
 
@@ -184,14 +195,97 @@ Before saving, verify:
 
 If any check fails, fix it — don't ask the user.
 
-## Phase 8: Report
+## Phase 8: Claim and Prepare Workspace
+
+**If `--spec-only` was passed, skip to Phase 10 (Report).**
+
+### Workspace Check
+
+```bash
+git status --porcelain
+git branch --show-current
+br list --status=in_progress
+```
+
+- If uncommitted changes: ask user to stash, commit, or continue
+- If other tasks in progress: warn before claiming another
+
+### Claim Bead
+
+```bash
+br update $BEAD_ID --status in_progress
+```
+
+### Create Branch
+
+Ask user how to handle workspace:
+
+```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:**
+
+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:**
+
+```typescript
+skill({ name: "using-git-worktrees" });
+```
+
+**If current branch:** Continue without branch creation.
+
+## Phase 9: Convert PRD to Tasks
+
+Use `prd-task` skill to convert PRD markdown → executable JSON (`prd.json`).
+
+## Phase 10: Report
 
 Output:
 
 1. Bead ID and type
 2. PRD location (`.beads/artifacts/$BEAD_ID/prd.md`)
 3. Summary: task count, success criteria count, affected files count
-4. Next steps: `/start $BEAD_ID` or `/plan $BEAD_ID`
+4. Branch name and workspace (if claimed)
+5. Next step: `/ship $BEAD_ID` (or `/plan $BEAD_ID` for complex work)
 
 ```bash
 br comments add $BEAD_ID "Created prd.md with [N] tasks, [M] success criteria"
@@ -201,8 +295,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>`  |
-| Start working   | `/start <id>` |
+| Need               | Command       |
+| ------------------ | ------------- |
+| Research first     | `/research`   |
+| Plan after spec    | `/plan <id>`  |
+| Implement and ship | `/ship <id>`  |

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

@@ -8,7 +8,7 @@ agent: vision
 
 Design a component, page, or design system with a clear aesthetic point of view.
 
-> **Design track (optional):** Not part of the core `/create → /start → /ship` workflow.
+> **Design track (optional):** Not part of the core `/create → /ship` workflow.
 > Use when you need visual design guidance before or during implementation.
 
 ## Parse Arguments
@@ -108,5 +108,4 @@ observation({
 | Need               | Command         |
 | ------------------ | --------------- |
 | Review existing UI | `/ui-review`    |
-| Start building     | `/start <bead>` |
 | Ship it            | `/ship <bead>`  |

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

@@ -0,0 +1,234 @@
+---
+description: Audit .opencode/ configuration for consistency, stale references, and enforcement gaps
+argument-hint: "[--fix] [--layer <intent|knowledge|control>]"
+agent: review
+---
+
+# Health Check: $ARGUMENTS
+
+Self-audit the .opencode/ configuration for drift, inconsistencies, and enforcement gaps.
+
+## Load Skills
+
+```typescript
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument  | Default | Description                                         |
+| --------- | ------- | --------------------------------------------------- |
+| `--fix`   | false   | Auto-fix safe issues (stale refs, dead links)       |
+| `--layer` | all     | Focus on specific layer: intent, knowledge, control |
+
+## Overview
+
+This command runs a multi-layer health check inspired by three-layer defense:
+
+1. **Intent** (AGENTS.md) — policies and rules
+2. **Knowledge** (Skills) — procedures and workflows
+3. **Control** (Agent frontmatter, hooks) — structural enforcement
+
+A rule that exists at intent but not control is a gap. This command finds those gaps.
+
+## Phase 1: Inventory
+
+Build an inventory of all .opencode/ artifacts:
+
+```bash
+# Count artifacts
+echo "=== Skills ==="
+ls .opencode/skill/ | wc -l
+echo "=== Commands ==="
+ls .opencode/command/ | wc -l
+echo "=== Agents ==="
+ls .opencode/agent/ | wc -l
+echo "=== Tools ==="
+ls .opencode/tool/ 2>/dev/null | wc -l
+echo "=== Plugins ==="
+ls .opencode/plugin/ 2>/dev/null | wc -l
+```
+
+Report totals as a summary table.
+
+## Phase 2: Stale Reference Detection
+
+Check for references to skills, commands, or agents that don't exist:
+
+### 2a. Skill references in commands and AGENTS.md
+
+For every `skill({ name: "X" })` call found in `.opencode/command/*.md` and `AGENTS.md`:
+
+- Verify `.opencode/skill/X/SKILL.md` exists
+- Flag any that don't exist as **CRITICAL**
+
+### 2b. Command references in skills and AGENTS.md
+
+For every `/command-name` reference found in `.opencode/skill/*/SKILL.md` and `AGENTS.md`:
+
+- Verify `.opencode/command/command-name.md` exists
+- Flag missing as **IMPORTANT**
+
+### 2c. Agent references
+
+For every `agent: X` in command frontmatter:
+
+- Verify `.opencode/agent/X.md` exists (or is a built-in agent)
+- Flag missing as **CRITICAL**
+
+### 2d. Cross-references between skills
+
+For every `dependencies: [X, Y]` in skill YAML frontmatter:
+
+- Verify each dependency skill exists
+- Flag missing as **IMPORTANT**
+
+Report format:
+
+```text
+| Reference Type       | Source File           | Target        | Status  |
+|---------------------|-----------------------|---------------|---------|
+| skill()             | command/ship.md:15    | beads         | OK      |
+| skill()             | command/plan.md:22    | old-skill     | MISSING |
+| /command             | skill/X/SKILL.md:45   | /deploy       | MISSING |
+```
+
+## Phase 3: Skill Quality Audit
+
+For each skill in `.opencode/skill/*/SKILL.md`:
+
+1. **Frontmatter check:**
+   - [ ] Has `name:` field
+   - [ ] Has `description:` field
+   - [ ] `name:` matches directory name
+   - [ ] Starts with `---` on line 1
+
+2. **Content check:**
+   - [ ] Has `## When to Use` section
+   - [ ] Has `## When NOT to Use` section
+   - [ ] Under 200 lines (warn if over)
+   - [ ] Has `## Gotchas` section (advisory — new skills may not have one yet)
+
+3. **Description trigger check:**
+   - [ ] Description starts with action trigger (Use when, MUST load, Use INSTEAD OF)
+   - Flag descriptions that don't specify when to load as **MINOR**
+
+Report as a scorecard:
+
+```text
+| Skill                   | Frontmatter | Content | Trigger | Gotchas | Lines | Grade |
+|-------------------------|-------------|---------|---------|---------|-------|-------|
+| verification-before-... | OK          | OK      | OK      | NO      | 237   | B+    |
+| skill-creator           | OK          | OK      | OK      | NO      | 157   | B     |
+```
+
+Grade scale:
+
+- **A** — all checks pass including gotchas
+- **B+** — all required checks pass, missing gotchas (acceptable for newer skills)
+- **B** — missing one optional section
+- **C** — missing required section or over 200 lines
+- **D** — frontmatter issues
+- **F** — broken (missing name, missing description, invalid YAML)
+
+## Phase 4: Three-Layer Defense Audit
+
+Check the top safety rules from AGENTS.md for three-layer coverage:
+
+| Rule                           | Intent (AGENTS.md) | Knowledge (Skill) | Control (Agent/Hook) |
+| ------------------------------ | ------------------ | ----------------- | -------------------- |
+| Never force push main          | ?                  | ?                 | ?                    |
+| Never bypass hooks             | ?                  | ?                 | ?                    |
+| Never expose credentials       | ?                  | ?                 | ?                    |
+| Read before write/edit         | ?                  | ?                 | ?                    |
+| Verify before completion       | ?                  | ?                 | ?                    |
+| Never `git add .`              | ?                  | ?                 | ?                    |
+| Review agents are read-only    | ?                  | ?                 | ?                    |
+| Never fabricate tool output    | ?                  | ?                 | ?                    |
+| Ask before destructive actions | ?                  | ?                 | ?                    |
+
+For each rule:
+
+- **Intent**: grep AGENTS.md for the policy statement
+- **Knowledge**: check if any skill documents the procedure
+- **Control**: check if any agent frontmatter enforces it (tools: false, permission: deny)
+
+Flag rules with intent but no control as **IMPORTANT** gaps.
+
+## Phase 5: Agent Tool Restriction Audit
+
+For each agent in `.opencode/agent/*.md`:
+
+1. Read the agent's YAML frontmatter
+2. Check `tools:` restrictions (which tools are disabled)
+3. Check `permission:` restrictions (which commands are denied/asked)
+4. Compare against the agent's stated role
+
+Flag:
+
+- **CRITICAL**: Write-capable agents that should be read-only (review, explore, scout)
+- **IMPORTANT**: Agents with no tool restrictions at all
+- **MINOR**: Agents with restrictions that could be tighter
+
+## Phase 6: Report
+
+Output a health report:
+
+```markdown
+## Health Report
+
+**Date:** [timestamp]
+**Configuration:** [X skills, Y commands, Z agents]
+
+### Summary
+
+| Layer   | Issues Found | Critical | Important | Minor |
+| ------- | ------------ | -------- | --------- | ----- |
+| Refs    | N            | N        | N         | N     |
+| Skills  | N            | N        | N         | N     |
+| Defense | N            | N        | N         | N     |
+| Agents  | N            | N        | N         | N     |
+| TOTAL   | N            | N        | N         | N     |
+
+### Critical Issues
+
+- [list]
+
+### Important Issues
+
+- [list]
+
+### Minor Issues
+
+- [list]
+
+### Recommendations
+
+- [prioritized list of fixes]
+```
+
+If `--fix` flag is provided, auto-fix `safe_auto` issues:
+
+- Remove stale skill references from commands (after confirmation)
+- Add missing `## Gotchas` placeholder sections to skills
+- Fix frontmatter formatting issues
+
+Record findings:
+
+```typescript
+observation({
+  type: "discovery",
+  title: "Health check: [summary]",
+  narrative: "[Key findings and gaps discovered]",
+  concepts: "health, audit, configuration",
+  confidence: "high",
+});
+```
+
+## Related Commands
+
+| Need                | Command            |
+| ------------------- | ------------------ |
+| Review code         | `/review-codebase` |
+| Check project state | `/status`          |
+| Verify a bead       | `/verify <id>`     |

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

@@ -79,6 +79,21 @@ updated: [today]
 - [Rule 3]
 ```
 
+### Persist to Memory System
+
+After writing the file, also store key preferences as a memory observation for cross-session retrieval:
+
+```typescript
+observation({
+  type: "decision",
+  title: "User profile: [name]",
+  narrative: "User preferences captured: [style], [workflow prefs], [technical prefs]. Source: /init-user command.",
+  concepts: "user-profile, preferences",
+  confidence: "high",
+  files_modified: ".opencode/memory/project/user.md",
+});
+```
+
 ## Phase 3: Update opencode.json
 
 Ensure `user.md` is loaded in `instructions` (bare paths, no `file://` prefix).

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

@@ -6,11 +6,11 @@ agent: plan
 
 # Plan: $ARGUMENTS
 
-Create a detailed implementation plan with TDD steps. Optional deep-planning between `/start` and `/ship`.
+Create a detailed implementation plan with TDD steps. Optional deep-planning between `/create` and `/ship`.
 
-> **Workflow:** `/create` → `/start <id>` → **`/plan <id>`** (optional) → `/ship <id>`
+> **Workflow:** `/create` → **`/plan <id>`** (optional) → `/ship <id>`
 >
-> Bead MUST be `in_progress` with `prd.md`. Use `/start` first.
+> Bead MUST be `in_progress` with `prd.md`. Use `/create` first.
 >
 > **When to use:** Complex tasks where PRD verification steps aren't enough guidance. Skip for simple tasks.
 
@@ -350,6 +350,5 @@ br comments add $ARGUMENTS "Created plan.md: Level [N] discovery, [X] waves, [Y]
 | Need           | Command       |
 | -------------- | ------------- |
 | Create spec    | `/create`     |
-| Start working  | `/start <id>` |
 | Execute plan   | `/ship <id>`  |
 | Research first | `/research`   |

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

@@ -43,6 +43,19 @@ If any gate fails, stop. Fix errors first, then run `/pr` again.
 
 ## Phase 2: Gather Context
 
+### Memory Grounding
+
+Search memory for relevant decisions, known issues, and prior review findings:
+
+```typescript
+memory-search({ query: "$ARGUMENTS" });
+memory-search({ query: "<branch or feature keywords>", limit: 5 });
+```
+
+Include relevant findings in the PR description (e.g., architectural decisions, known limitations).
+
+### Git Context
+
 ```bash
 git branch --show-current
 git log main...HEAD --oneline

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

@@ -64,7 +64,19 @@ br show $ARGUMENTS
 
 Read PRD if it exists and extract questions that need answering.
 
-Check memory for previous research on this topic.
+### Memory Search (Required)
+
+Always search memory before spawning research agents:
+
+```typescript
+memory-search({ query: "$ARGUMENTS" });
+memory-search({ query: "<topic keywords>", limit: 10 });
+```
+
+If memory returns relevant findings, use them to:
+- Skip questions already answered
+- Narrow research scope to gaps only
+- Avoid contradicting prior decisions without justification
 
 ## Phase 2: Research
 
@@ -120,6 +132,6 @@ Report:
 
 | Need          | Command       |
 | ------------- | ------------- |
-| Create spec   | `/create`     |
+| Create + start | `/create`     |
 | Plan details  | `/plan <id>`  |
-| Start working | `/start <id>` |
+| Pick up work   | `/ship <id>`  |

package/dist/template/.opencode/command/review-codebase.md

@@ -120,7 +120,17 @@ Include:
 3. Verdict: Ready to merge / With fixes / No
 4. Reasoning (1-2 sentences)
 
-Record significant findings with `observation()`.
+Record significant findings with `observation()`:
+
+```typescript
+observation({
+  type: "discovery", // or "warning", "pattern", "bugfix"
+  title: "Review: [scope] [key finding]",
+  narrative: "[What was found, severity, file:line, recommended fix]",
+  concepts: "code-review, [category]",
+  confidence: "high",
+});
+```
 
 ## Related Commands