opencodekit 0.20.5 → 0.20.7

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

@@ -0,0 +1,299 @@
+---
+description: Organize, deduplicate, and curate knowledge in project memory
+argument-hint: "[--scope recent|all] [--auto-merge]"
+agent: build
+---
+
+# Curate: $ARGUMENTS
+
+Organize accumulated knowledge. Surface conflicts, merge duplicates, archive stale observations.
+
+> **Workflow:** `/ship` → `/compound` → **`/curate`** → `/pr`
+>
+> Run periodically (weekly or after major work) to keep memory sharp. Inspired by ByteRover's structured curation pipeline.
+
+## Load Skills
+
+```typescript
+skill({ name: "memory-system" });
+skill({ name: "verification-before-completion" });
+```
+
+## Parse Arguments
+
+| Argument       | Default  | Description                                      |
+| -------------- | -------- | ------------------------------------------------ |
+| `--scope`      | `recent` | `recent` = last 30 days, `all` = entire memory   |
+| `--auto-merge` | false    | Auto-merge exact duplicates without confirmation |
+
+## Phase 1: Inventory
+
+Take stock of current memory state:
+
+```typescript
+memory_admin({ operation: "status" });
+memory_admin({ operation: "capture-stats" });
+```
+
+Report:
+
+```
+## Memory Inventory
+
+| Metric | Count |
+|--------|-------|
+| Total observations | [N] |
+| Recent (30 days) | [N] |
+| By type | pattern: N, decision: N, bugfix: N, ... |
+| Confidence distribution | high: N, medium: N, low: N |
+```
+
+## Phase 2: Domain Detection
+
+Analyze observations to extract semantic domains — groups of related knowledge.
+
+```typescript
+// Get memory status for inventory
+memory_admin({ operation: "status" });
+
+// Search by common concept categories to build domain map
+const domains = [];
+for (const concept of ["build", "test", "memory", "git", "agent", "auth", "ui", "config"]) {
+  const results = memory_search({ query: concept, limit: 20 });
+  // Group results by concept affinity
+}
+```
+
+Categorize observations into domains based on their `concepts` and `title` fields:
+
+| Domain         | Example Concepts                   | Observation Count |
+| -------------- | ---------------------------------- | ----------------- |
+| `build_system` | build, tsdown, rsync, dist         | [N]               |
+| `testing`      | vitest, test, TDD, coverage        | [N]               |
+| `memory`       | observation, FTS5, sqlite, handoff | [N]               |
+| `git_workflow` | commit, branch, push, PR           | [N]               |
+| `agent_system` | subagent, delegation, skills       | [N]               |
+
+**Domain naming rules:**
+
+- snake_case, 1-3 words
+- Semantically meaningful (not just "misc")
+- Maximum 10 domains (merge small groups)
+
+## Phase 3: Conflict & Duplicate Detection
+
+### 3a. Exact Duplicates
+
+```typescript
+memory_admin({ operation: "lint" });
+```
+
+Flag observations with identical or near-identical titles and narratives. Present for merge:
+
+```
+### Duplicates Found
+
+| Obs A | Obs B | Similarity | Recommended Action |
+|-------|-------|------------|-------------------|
+| #12 "Use JWT for auth" | #45 "JWT chosen for auth" | 95% title match | MERGE → keep #45 (newer) |
+| #8 "Build copies .opencode/" | #33 "Build copies .opencode/" | 100% title match | MERGE → keep #33 (newer) |
+```
+
+### 3b. Contradictions
+
+Search for observations where:
+
+- Same concepts but different decisions
+- Same file paths but conflicting patterns
+- Confidence downgrade without supersedes link
+
+```
+### Contradictions Found
+
+| Obs A | Obs B | Conflict | Recommended Action |
+|-------|-------|----------|-------------------|
+| #5 "Always use X pattern" | #29 "Avoid X pattern" | Opposite recommendations | RESOLVE — ask user which is current |
+```
+
+### 3c. Stale Observations
+
+Flag observations where:
+
+- Referenced files no longer exist
+- Referenced patterns no longer appear in codebase
+- Over 90 days old with no related recent activity
+
+```
+### Stale Observations
+
+| Obs | Age | Reason | Recommended Action |
+|-----|-----|--------|-------------------|
+| #3 "src/old-file.ts pattern" | 120 days | File deleted | ARCHIVE |
+| #7 "Use moment.js for dates" | 95 days | Dependency removed | ARCHIVE |
+```
+
+## Phase 4: Present Curation Plan
+
+Compile all findings into a review table:
+
+```
+## Curation Plan
+
+### Actions Required
+
+| # | Observation | Action | Reason |
+|---|------------|--------|--------|
+| 1 | #12 + #45 | MERGE | Duplicate — keep newer |
+| 2 | #5 vs #29 | RESOLVE | Contradicting patterns |
+| 3 | #3 | ARCHIVE | Referenced file deleted |
+| 4 | #7 | ARCHIVE | Dependency removed |
+| 5 | #18 | UPDATE | Low confidence → verify |
+```
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Curation Plan",
+      question: "Review the curation plan. Proceed with all actions?",
+      options: [
+        { label: "Execute all (Recommended)", description: "Apply all actions above" },
+        { label: "Let me cherry-pick", description: "I'll approve individually" },
+        { label: "Skip curation", description: "No changes to memory" },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 5: Execute Curation
+
+For each approved action:
+
+### MERGE (duplicates)
+
+```typescript
+// Read both observations
+const older = memory_get({ ids: "<older-id>" });
+const newer = memory_get({ ids: "<newer-id>" });
+
+// Union-merge: combine comma-separated lists, deduplicate (case-insensitive), existing items first
+// Example: older.facts="auth, jwt" + newer.facts="jwt, session" → "auth, jwt, session"
+
+// Create merged observation (newer as base, merge fields from older)
+observation({
+  type: newer.type,
+  title: newer.title,
+  narrative: newer.narrative,
+  // Manually combine comma-separated fields: keep all unique items from both
+  facts: "[combined unique facts from older + newer]",
+  concepts: "[combined unique concepts from older + newer]",
+  files_modified: "[combined unique file paths from older + newer]",
+  confidence: newer.confidence, // Newer confidence wins
+  supersedes: "<older-id>",
+  subtitle: "Merged from #<older-id> + #<newer-id>",
+});
+```
+
+**Union merge rule:** Combine comma-separated lists, deduplicate (case-insensitive), existing items first.
+
+### RESOLVE (contradictions)
+
+Present the conflicting observations side-by-side:
+
+```
+### Contradiction: #5 vs #29
+
+**#5 (older, high confidence):**
+> Always use X pattern for Y components
+
+**#29 (newer, medium confidence):**
+> Avoid X pattern — causes Z issues
+
+Which is the current truth?
+```
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Resolve Conflict",
+      question: "Which observation reflects the current codebase reality?",
+      options: [
+        { label: "#5 (older) is correct", description: "Archive #29, keep #5" },
+        { label: "#29 (newer) is correct", description: "Supersede #5 with #29" },
+        { label: "Both partially correct", description: "I'll write a reconciled version" },
+      ],
+    },
+  ],
+});
+```
+
+### ARCHIVE (stale)
+
+```typescript
+// Verify staleness by checking codebase
+// If file doesn't exist or pattern not found:
+observation({
+  type: "warning",
+  title: "Archived: [original title]",
+  narrative: "Archived during curation — [reason]. Original observation #<id>.",
+  supersedes: "<stale-id>",
+  confidence: "low",
+});
+```
+
+### UPDATE (low confidence → verify)
+
+```typescript
+// Search codebase for evidence
+// If evidence found → upgrade confidence
+// If evidence not found → archive
+```
+
+## Phase 6: Compile Knowledge Index
+
+After curation, regenerate the knowledge index:
+
+```typescript
+memory_admin({ operation: "compile" });
+memory_admin({ operation: "index" });
+```
+
+## Phase 7: Report
+
+```
+## Curation Summary
+
+**Scope:** [recent / all]
+**Observations reviewed:** [N]
+**Domains identified:** [N]
+
+| Action | Count | Details |
+|--------|-------|---------|
+| Merged | [N] | [list merged pairs] |
+| Resolved | [N] | [list resolved conflicts] |
+| Archived | [N] | [list archived observations] |
+| Updated | [N] | [list confidence changes] |
+| No change | [N] | |
+
+**Memory health:** [Healthy / Needs attention: describe]
+**Next recommended:** /pr or continue work
+```
+
+## When Nothing to Curate
+
+If all observations are clean, well-organized, and non-conflicting:
+
+> "Memory is clean. No duplicates, contradictions, or stale observations found. [N] observations across [M] domains."
+
+Don't force curation. Quality memory means less curation needed.
+
+## Related Commands
+
+| Need                    | Command                        |
+| ----------------------- | ------------------------------ |
+| Extract learnings first | `/compound`                    |
+| Full chain              | `/lfg`                         |
+| Check memory health     | `/health`                      |
+| Search memory           | Use `memory-search()` directly |

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: