opencodekit 0.21.9 → 0.22.0

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

@@ -1,356 +0,0 @@
----
-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: 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`:
-
-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 7: 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-context.md

@@ -1,297 +0,0 @@
----
-description: Initialize project planning context (roadmap, state) with optional brownfield analysis
-argument-hint: "[--skip-questions] [--brownfield]"
-agent: build
----
-
-# Init-Context: $ARGUMENTS
-
-Initialize project planning context files from templates.
-
-## Architecture
-
-**Auto-injected files** (always loaded into every prompt via `instructions[]`):
-- `user.md` — identity, preferences
-- `tech-stack.md` — framework, constraints
-- `project.md` — vision, success criteria, principles
-- `git-context.md` — spatial awareness
-
-**On-demand files** (created by this command, loaded via `memory-read` when needed):
-- `roadmap.md` — phases, milestones, bead planning
-- `state.md` — current position, blockers, next actions
-
-> **Warning:** Do NOT add roadmap.md or state.md to `instructions[]`. Per-prompt injection of too many files causes session OOM crashes. Use `memory-read({ file: "project/roadmap" })` or `memory-read({ file: "project/state" })` when needed.
-
-## Load Skills
-
-```typescript
-skill({ name: "context-initialization" });
-skill({ name: "brainstorming" });
-skill({ name: "verification-before-completion" });
-```
-
-## Parse Arguments
-
-```typescript
-const args = {
-  skipQuestions: $ARGUMENTS.includes("--skip-questions"),
-  brownfield: $ARGUMENTS.includes("--brownfield"),
-  focus: $ARGUMENTS.match(/--focus=(\w+)/)?.[1], // Optional: api, ui, db, etc.
-};
-```
-
-## Phase 1: Discovery
-
-### 1.1 Check Existing Context
-
-Use tilth or Read to check for existing files:
-
-```typescript
-tilth_tilth_files({ pattern: "*.md", scope: ".opencode/memory/project" });
-// Or: Read({ filePath: ".opencode/memory/project/project.md", limit: 20 });
-```
-
-**If planning context exists:**
-
-```
-Existing planning context found:
-- project.md: [exists/size] (auto-injected)
-- roadmap.md: [exists/size] (on-demand)
-- state.md: [exists/size] (on-demand)
-
-Options:
-1. Refresh - Delete and recreate from templates
-2. Update - Keep existing, only update state.md
-3. Skip - Use existing context as-is
-```
-
-Wait for user selection.
-
-### 1.2 Brownfield Codebase Analysis (if --brownfield)
-
-If `--brownfield` flag is set:
-
-```typescript
-skill({ name: "swarm-coordination" });
-
-// Agent 1: Map tech stack
-task({
-  subagent_type: "explore",
-  description: "Analyze tech stack",
-  prompt:
-    "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
-task({
-  subagent_type: "explore",
-  description: "Analyze architecture",
-  prompt:
-    "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
-```
-
-## Phase 2: Requirements Gathering
-
-### 2.1 Brainstorming (if not --skip-questions)
-
-```typescript
-if (!args.skipQuestions) {
-  // brainstorming skill already loaded in Load Skills phase
-  // Follow brainstorming process for project vision
-  // Ask questions one at a time (as per brainstorming skill)
-  // Output: Refined vision, success criteria, target users
-}
-```
-
-### 2.2 Quick Mode (if --skip-questions)
-
-Use template defaults with placeholders for:
-
-- Project vision
-- Success criteria
-- Target users
-- Phases
-- Current phase
-
-## Phase 3: Document Creation
-
-### 3.1 Update project.md (auto-injected)
-
-This file is auto-injected into every prompt. Keep it concise.
-
-**Load template:**
-
-```typescript
-Read({ filePath: ".opencode/memory/_templates/project.md" });
-```
-
-**Fill with gathered data:**
-
-- Vision from brainstorming OR template placeholder
-- Success criteria (3-7 measurable outcomes)
-- Target users (primary/secondary)
-- Core principles (convention over config, minimal, extensible)
-- Current phase (from user input or template default)
-
-**Write using memory tools:**
-
-```typescript
-memory-update({ file: "project/project", content: filledContent, mode: "replace" });
-```
-
-### 3.2 Create roadmap.md (on-demand)
-
-This file is NOT auto-injected. Access via `memory-read({ file: "project/roadmap" })`.
-
-**Parse phases from input:**
-
-```typescript
-// Convert user-provided phases into structured roadmap
-// Example: "Discovery, MVP, Launch, Scale" → table rows
-```
-
-**Structure:**
-
-```markdown
-| Phase     | Goal   | Status   | Beads |
-| --------- | ------ | -------- | ----- |
-| [Phase 1] | [Goal] | [Status] | [#]   |
-```
-
-**Write using memory tools:**
-
-```typescript
-memory-update({ file: "project/roadmap", content: roadmapContent, mode: "replace" });
-```
-
-### 3.3 Create state.md (on-demand)
-
-This file is NOT auto-injected. Access via `memory-read({ file: "project/state" })`.
-
-**Initialize with:**
-
-- Active Bead: (blank or from bead context)
-- Status: In Progress
-- Started: [current date]
-- Phase: [from roadmap]
-- Recent Completed Work: (empty table)
-- Active Decisions: (empty table)
-- Blockers: (empty table)
-- Open Questions: (empty table)
-- Next Actions: (empty list)
-
-**Write using memory tools:**
-
-```typescript
-memory-update({ file: "project/state", content: stateContent, mode: "replace" });
-```
-
-### 3.4 Brownfield Analysis Integration (if applicable)
-
-If `--brownfield` analysis was run:
-
-```typescript
-// Append tech/arch findings to project.md Context Notes section
-// Or create separate .opencode/memory/project/codebase/ documents
-```
-
-## Phase 4: Verification & Security
-
-### 4.1 Verify Documents Created
-
-```typescript
-tilth_tilth_files({ pattern: "*.md", scope: ".opencode/memory/project" });
-// Verify each file exists and has content
-Read({ filePath: ".opencode/memory/project/project.md", limit: 5 });
-Read({ filePath: ".opencode/memory/project/roadmap.md", limit: 5 });
-Read({ filePath: ".opencode/memory/project/state.md", limit: 5 });
-```
-
-**Check:**
-
-- [ ] project.md exists and >20 lines
-- [ ] roadmap.md exists and >20 lines
-- [ ] state.md exists and >20 lines
-- [ ] All files are readable
-
-### 4.2 Secret Scan
-
-```bash
-# Scan for accidentally leaked secrets in generated docs
-grep -rE '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|AKIA[A-Z0-9]{16}|ghp_[a-zA-Z0-9]{36}|xoxb-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY)' .opencode/memory/project/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
-```
-
-**If secrets found:** Alert user and pause before proceeding.
-
-### 4.3 Run Verification
-
-```typescript
-// verification-before-completion skill already loaded
-// Run verification checklist:
-// 1. IDENTIFY: Files created, structure valid
-// 2. RUN: Validation commands
-// 3. READ: Check file contents
-// 4. VERIFY: All success criteria met
-// 5. CLAIM: Context initialization complete
-```
-
-## Output
-
-Creates planning context in `.opencode/memory/project/`:
-
-| File         | Purpose                                  | Injection   | Access                                       |
-| ------------ | ---------------------------------------- | ----------- | -------------------------------------------- |
-| `project.md` | Vision, success criteria, principles     | Auto-injected | Updated in-place (already in `instructions[]`) |
-| `roadmap.md` | Phases, milestones, bead planning        | On-demand   | `memory-read({ file: "project/roadmap" })`   |
-| `state.md`   | Current position, blockers, next actions | On-demand   | `memory-read({ file: "project/state" })`     |
-
-**If `--brownfield`:**
-Additional files in `.opencode/memory/project/codebase/`:
-
-- `tech-analysis.md` - Stack and dependencies
-- `arch-analysis.md` - Architecture patterns
-
-## Success Criteria
-
-- [ ] All 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 and access patterns
-
-## 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
-- This folder is preserved during init --force and upgrade
-
-⚠️  Only add files to instructions[] if they are essential for EVERY prompt.
-    Per-prompt injection adds ~2-4KB each. Too many files cause session OOM.
-    Prefer memory-read() for on-demand access instead.
-```
-
-## Next Steps
-
-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/` (on-demand via Read, not auto-injected)
-
----
-
-## Skill Integration Summary
-
-| Skill                            | When Used                         | Purpose                        |
-| -------------------------------- | --------------------------------- | ------------------------------ |
-| `context-initialization`         | Phase 1                           | Template verification          |
-| `brainstorming`                  | Phase 2 (if not --skip-questions) | Refine vision and requirements |
-| `swarm-coordination`             | Phase 1.2 (if --brownfield)       | Parallel codebase analysis     |
-| `verification-before-completion` | Phase 4                           | Validate created files         |