opencodekit 0.23.0 → 0.23.2

package/dist/template/.opencode/AGENTS.md

@@ -85,6 +85,18 @@ Reject changes that worsen overall code health.
 - If verification fails twice on the same approach, stop and escalate.
 - **Auto-detect project toolchain** — look for `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Makefile`, etc.
 
+### Fallow Codebase Gate
+Before committing or claiming completion, run the Fallow codebase gate to catch structural issues that linters and type checkers cannot see:
+
+- Run **`npx fallow audit --format json --quiet`** and check the `verdict`. If `"fail"`, resolve all findings before proceeding.
+- Run **`npx fallow`** for full codebase analysis (dead code, duplication, health) — this is the single-pass overview.
+- Use **`npx fallow fix --dry-run`** to preview safe auto-fixes for dead code.
+- Use **`npx fallow dead-code --trace FILE:EXPORT`** to investigate why a specific export is flagged before deleting it.
+
+Fallow builds a complete module graph (Rust-native, sub-second). Its analysis is **deterministic** — no AI inside the analyzer. It finds unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations across the entire codebase.
+
+See `.opencode/context/fallow.md` for the full command reference.
+
 ## Tool Discipline
 - Use tools whenever they materially improve correctness. Keep calling until the task is complete **and** verified.
 - If a tool returns empty, partial, or suspiciously narrow results, try 1-2 fallback strategies before reporting "no results found."
@@ -191,6 +203,9 @@ Prefer `edit` for modifications; reserve `write` for new files or deliberate ful
 - Keep context high-signal
 - Use DCP/VCC tools to compress completed phases and recover targeted history
 - After any context compaction, re-read: (1) this `AGENTS.md`, (2) the current task details, (3) active state
+- **The `<session_summary>` block in the system prompt** is the artifact trail. It tracks files read/modified/created, decisions made, and next steps. Use it to orient after compression — do not re-read files listed there without checking if you already have the information.
+- **Update the session summary** when you make a structural decision: the `observation(type:decision)` tool auto-populates the decisions section. For file operations (read/edit/write), tracking happens automatically via the session-summary plugin.
+- **Anchored summarization**: when compressing a range, check the session summary first. Your compression should preserve and update the information there — don't drop file paths or decisions that are still relevant.
 
 ---
 

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

@@ -6,34 +6,47 @@ agent: build
 
 # Init: $ARGUMENTS
 
-Initialize project setup. Run once per project. Supports three modes via argument flags.
+Initialize project setup. Run once per project.
 
 > **Next step for fresh projects:** `/plan` to create first implementation plan.  
-> **Next step for brownfield:** `/review-codebase` for deep codebase analysis.
+> **Next step for existing codebases:** `/review-codebase` for deep codebase analysis.
 
-## Load Skills
+## Idempotency Rules
+
+| File | Rule |
+|---|---|
+| `AGENTS.md` | Improve in-place — never overwrite blindly |
+| `tech-stack.md` | Overwrite with detected values (auto-regenerated) |
+| `roadmap.md` / `state.md` | Skip if exists, ask before overwrite |
+| `user.md` | Skip if exists, ask before overwrite |
+| `.opencode/opencode.json` `instructions[]` | Add to array — never remove existing entries |
+
+## Skills
 
 ```typescript
 skill({ name: "brainstorming" });
-skill({ name: "verification-before-completion" });
 ```
 
+Load `verification-before-completion` inside Mode 1 only (after AGENTS.md creation).
+
 ## Parse Arguments
 
 | Argument | Default | Description |
 |---|---|---|
 | `--deep` | false | Comprehensive research for AGENTS.md (~100+ tool calls) |
-| `--context` | false | Init planning context (roadmap, state) |
-| `--user` | false | Init user profile |
+| `--context` | false | Init planning context (roadmap.md, state.md) |
+| `--user` | false | Init user profile (user.md) |
 | `--all` | false | Full init: AGENTS.md + context + user profile |
 
 **Mode rules:**
-- No flags (default): Core project setup — AGENTS.md + tech stack only
+- No flags (default): Core project setup — AGENTS.md + tech-stack.md
 - `--context`: Planning context (roadmap.md, state.md)
 - `--user`: User profile (user.md)
 - `--all`: Everything
 - `--deep` applies to AGENTS.md generation only
 
+**Brownfield auto-detection:** Existing codebase = any `src/`, `lib/`, or `app/` directory with `.ts`, `.js`, `.tsx`, `.jsx`, `.py`, `.go`, or `.rs` files. Affects Mode 2 discovery scope.
+
 ---
 
 ## Mode 1: Core Setup (Default)
@@ -47,14 +60,38 @@ Detect and validate:
 - Existing AI rules (`.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`)
 - Top-level directory structure
 
-With `--deep`: Also analyze git history, source patterns, subsystem candidates.
+With `--deep`:
+- Analyze git history (last 50 commits for patterns)
+- Map source directory structure and subsystem candidates
+- Identify common patterns (error handling, logging, data flow)
+- Detect testing patterns and coverage gaps
 
 ### Phase 2: Preview Detection
 
-Show detected summary and ask for confirmation before writing.
+Show detected summary and ask for confirmation before writing:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Proceed?",
+      question: "Write AGENTS.md and tech-stack.md with the detected configuration?",
+      options: [
+        { label: "Yes (Recommended)", description: "Create both files" },
+        { label: "AGENTS.md only", description: "Skip tech-stack.md" },
+        { label: "Cancel", description: "Don't write anything" },
+      ],
+    },
+  ],
+});
+```
 
 ### Phase 3: Create AGENTS.md
 
+```typescript
+skill({ name: "verification-before-completion" });
+```
+
 Create `./AGENTS.md` — target <60 lines (max 150). Include:
 - Tech stack with versions, file structure, validated commands
 - Code example from actual codebase
@@ -64,7 +101,25 @@ Create `./AGENTS.md` — target <60 lines (max 150). Include:
 
 ### Phase 4: Create tech-stack.md
 
-Write detected values to `.opencode/memory/project/tech-stack.md`. Persist with memory update.
+Write detected values to `.opencode/memory/project/tech-stack.md`. Then persist:
+
+```typescript
+observation({
+  type: "feature",
+  title: "Project initialized — [tech stack summary]",
+  narrative: "Core setup completed: AGENTS.md, tech-stack.md created for [language/framework] project",
+  concepts: "project-setup, initialization",
+  confidence: "high",
+});
+```
+
+### Phase 5: Setup Fallow (if available)
+
+Check if fallow is available. If yes and no `.fallowrc.json` exists:
+
+```bash
+npx fallow init --quiet 2>/dev/null || true
+```
 
 ---
 
@@ -72,29 +127,109 @@ Write detected values to `.opencode/memory/project/tech-stack.md`. Persist with
 
 Initialize project planning context with roadmap and state files.
 
-### Phase 1: Discovery
+### Phase 1: Discovery (brownfield)
 
-If `--brownfield` (detected from existing codebase), run parallel codebase analysis:
-- `explore` for architecture patterns
-- `explore` for data flow
-- `explore` for domain boundaries
+If the project has existing code (brownfield — see auto-detection above), run parallel codebase analysis:
 
-If greenfield, skip to requirements gathering.
+```typescript
+task({
+  subagent_type: "explore",
+  description: "Map architecture patterns",
+  prompt: `Search the codebase for: architecture patterns, data flow, domain boundaries, and module structure.
+  Return: key architectural decisions, data flow patterns, main domains/modules.`,
+});
+
+task({
+  subagent_type: "explore",
+  description: "Map domain boundaries",
+  prompt: `Search the codebase for: domain boundaries, module organization, and subsystem structure.
+  Return: top-level domains, module boundaries, dependency direction.`,
+});
+```
+
+If greenfield (no existing code), skip to requirements gathering.
 
 ### Phase 2: Requirements Gathering
 
-Ask questions to define:
-- Project vision and goals (1-2 sentences each)
-- Target users and their needs
-- Core features (what must exist)
-- Technical constraints
-- Success criteria
+Ask questions to define project direction:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Project vision",
+      question: "What is the project vision? (1-2 sentences)",
+      options: [
+        { label: "Let me type it", description: "Custom input" },
+      ],
+    },
+    {
+      header: "Target users",
+      question: "Who are the primary users?",
+      multiple: true,
+      options: [
+        { label: "Developers", description: "Tooling, libraries, CLI" },
+        { label: "End users", description: "Consumer-facing application" },
+        { label: "Internal team", description: "Internal tool or service" },
+        { label: "Both", description: "Multiple user types" },
+      ],
+    },
+    {
+      header: "Success criteria",
+      question: "What defines success for this project? (select all that apply)",
+      multiple: true,
+      options: [
+        { label: "Stability", description: "Reliability and correctness first" },
+        { label: "Speed", description: "Performance and low latency" },
+        { label: "UX", description: "User experience and polish" },
+        { label: "Maintainability", description: "Code quality and extensibility" },
+      ],
+    },
+  ],
+});
+```
+
+### Phase 3: Preview
+
+Show the gathered requirements as a structured outline and ask for confirmation before writing files.
+
+### Phase 4: Create Files
+
+```typescript
+// Create roadmap.md
+write({
+  filePath: ".opencode/memory/project/roadmap.md",
+  content: `# Roadmap
+
+## Vision
+[1-2 sentences]
 
-### Phase 3: Create Files
+## Target Users
+- ...
 
-- `.opencode/memory/project/roadmap.md` — vision, goals, user personas, feature roadmap, constraints, success criteria
-- `.opencode/memory/project/state.md` — current status, active decisions, known issues, next priorities
-- Update `.opencode/opencode.json` instructions to include roadmap.md and state.md
+## Feature Roadmap
+- ...
+`,
+});
+
+// Create state.md
+write({
+  filePath: ".opencode/memory/project/state.md",
+  content: `# State
+
+## Current Status
+Initial setup
+
+## Active Decisions
+(none)
+
+## Next Priorities
+- ...
+`,
+});
+```
+
+Then update `.opencode/opencode.json` to include these files in `instructions[]` — append them to the existing array without removing `user.md`, `git-context.md`, or `fallow.md`.
 
 ---
 
@@ -104,19 +239,48 @@ Create personalized user profile at `.opencode/memory/project/user.md`.
 
 ### Phase 1: Gather Preferences
 
-Ask questions about:
-- **Identity**: Name, role, experience level
-- **Communication**: Verbosity preference, feedback style, update frequency
-- **Workflow**: Branch strategy, commit style, review expectations, test expectations
-- **Technical**: Preferred tools, avoided patterns, dev environment
+```typescript
+question({
+  questions: [
+    {
+      header: "Identity",
+      question: "What is your name and role?",
+      options: [
+        { label: "Set name", description: "Tell me your details" },
+      ],
+    },
+    {
+      header: "Communication",
+      question: "How detailed should AI responses be?",
+      options: [
+        { label: "Concise (Recommended)", description: "Short, direct answers" },
+        { label: "Detailed", description: "Full explanations and reasoning" },
+        { label: "Mixed", description: "Depends on context" },
+      ],
+    },
+    {
+      header: "Git workflow",
+      question: "How should git commits be handled?",
+      options: [
+        { label: "Ask first (Recommended)", description: "Always confirm before commit/push" },
+        { label: "Auto-commit", description: "Commit directly after completion" },
+      ],
+    },
+  ],
+});
+```
+
+### Phase 2: Preview
+
+Show the captured preferences as a summary and ask for confirmation before writing.
 
-### Phase 2: Create user.md
+### Phase 3: Create user.md
 
 Write to `.opencode/memory/project/user.md` with the captured preferences.
 
-### Phase 3: Update opencode.json
+### Phase 4: Ensure instructions[] includes user.md
 
-Ensure user.md is in `instructions[]` as one of the 4 auto-injected files (user.md, tech-stack.md, project.md, git-context.md).
+Check that `user.md` is listed in `.opencode/opencode.json` `instructions[]`. If missing, append it alongside the existing entries (`git-context.md`, `fallow.md`).
 
 > **Warning:** Do not add more files to `instructions[]` unless essential. Per-prompt injection of too many files causes session OOM. Use `memory-search({ file: "..." })` for on-demand access.
 

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

@@ -0,0 +1,137 @@
+---
+purpose: Fallow codebase intelligence commands for AI agents — dead code, duplication, complexity, and audit gating
+updated: 2026-06-04
+---
+
+# Fallow — Codebase Intelligence Reference
+
+## Overview
+
+Fallow is a Rust-native, deterministic static analysis tool for TypeScript/JavaScript codebases.
+**No AI inside the analyzer** — same input always produces the same output.
+It builds a complete module graph to find issues no linter or type checker can see.
+
+---
+
+## Commands
+
+### Full Analysis (single pass)
+
+```bash
+npx fallow                      # All analyses: dead code + duplication + health
+npx fallow --format json        # Structured output for agent parsing
+```
+
+### Dead Code
+
+```bash
+npx fallow dead-code                                   # Full dead code report
+npx fallow dead-code --format json --quiet              # JSON for agents
+npx fallow dead-code --unused-exports                   # Only unused exports
+npx fallow dead-code --unused-dependencies              # Only unused deps
+npx fallow dead-code --circular                         # Only circular deps
+npx fallow fix --dry-run                                # Preview safe auto-fixes
+npx fallow fix --yes                                    # Apply auto-fixes
+```
+
+### Trace (investigate before deleting)
+
+```bash
+npx fallow dead-code --trace FILE:EXPORT_NAME           # Why is this export flagged?
+npx fallow dead-code --trace-dependency PACKAGE_NAME    # Where is this dep imported?
+```
+
+### Duplication
+
+```bash
+npx fallow dupes                     # Find code clones
+npx fallow dupes --mode strict       # Exact matches only
+npx fallow dupes --mode weak         # Structural matches
+npx fallow dupes --trace FILE:LINE   # Deep-dive a specific clone group
+```
+
+### Health (complexity)
+
+```bash
+npx fallow health                    # Complexity hotspots + refactoring targets
+npx fallow health --format json      # Structured output
+```
+
+### Audit Gate (for CI / pre-commit)
+
+```bash
+npx fallow audit                     # Check changed files (verdict: pass/warn/fail)
+npx fallow audit --format json       # Structured verdict for agents
+npx fallow audit --gate new-only     # Only flag new issues, not pre-existing
+```
+
+---
+
+## Workflow Patterns
+
+### Post-Edit Verification Loop
+
+```bash
+# 1. Make changes
+# 2. Run audit
+npx fallow audit --format json --quiet
+# 3. If verdict is "fail", inspect findings
+# 4. Fix or investigate with --trace
+# 5. Re-run audit until pass
+```
+
+### Codebase Cleanup
+
+```bash
+npx fallow                           # Full picture
+npx fallow dead-code --format json   # Find unused code
+npx fallow fix --dry-run             # Preview auto-removals
+npx fallow fix --yes                 # Apply auto-fixes
+npx fallow dupes                     # Find duplication
+npx fallow health                    # Find complexity hotspots
+```
+
+### Monorepo / Workspace
+
+```bash
+npx fallow --workspace               # Analyze all workspaces
+npx fallow --workspace packages/pkg  # Analyze specific workspace
+```
+
+---
+
+## Understanding Output
+
+Every finding in `--format json` includes:
+
+```json
+{
+  "path": "src/utils/example.ts:42",
+  "issue_type": "unused-exports",
+  "actions": [
+    {
+      "type": "delete-export",
+      "auto_fixable": true,
+      "description": "Remove unused export"
+    }
+  ]
+}
+```
+
+The `actions[]` array is machine-actionable. Agents can inspect `auto_fixable` flags and apply safe fixes programmatically.
+
+---
+
+## Config
+
+Fallow auto-detects your project. For custom config, run:
+
+```bash
+npx fallow init    # Generates .fallow/config.yaml with auto-detected settings
+```
+
+Common config patterns:
+- `ignorePatterns` — exclude directories from analysis (e.g., `.opencode/`)
+- `entry` — declare additional entry points
+- `publicPackages` — packages with public API surface
+- `rules` — custom issue severity rules

package/dist/template/.opencode/dcp-prompts/overrides/compress-range.md

@@ -0,0 +1,89 @@
+Collapse a range in the conversation into a detailed summary.
+
+THE SUMMARY
+Your summary must be EXHAUSTIVE. Use the following 7-section structure to ensure nothing is lost.
+Capture file paths, function signatures, decisions made, constraints discovered, key findings, tool outcomes, and user intent... EVERYTHING that preserves the value of the compressed range.
+
+STRUCTURED SUMMARY FORMAT
+When summarizing the range, organize findings into these sections (omit empty sections):
+
+1. **Session Intent** — What the user requested. Quote exact instructions when short.
+2. **Key Technical Details** — File paths with line ranges (`path/file.ts:42-67`). Function signatures. Error messages verbatim. Code snippets critical to understanding.
+3. **Artifact Map** — Enumeration of files created, modified, and read, with what changed in each:
+   - `file created: path/to/new.ts` — what the file contains
+   - `file modified: path/to/existing.ts` — what changed (functions added/removed, logic changed)
+   - `file read: path/to/examined.ts` — why it was examined, key findings
+4. **Decisions** — What was decided, alternatives considered, rationale. Preserve the reasoning chain.
+5. **Problem Solving** — Approaches tried (including failures). What worked and why. Root cause analysis.
+6. **Current State** — Where we are in the task: what's done, what's active, what's blocked.
+7. **Continuation** — Exact next steps to resume work without re-fetching context. Include pending tasks with status.
+
+USER INTENT FIDELITY
+When the compressed range includes user messages, preserve the user's intent with extra care. Do not change scope, constraints, priorities, acceptance criteria, or requested outcomes.
+Directly quote user messages when they are short enough to include safely. Direct quotes are preferred when they best preserve exact meaning.
+
+Yet be LEAN. Strip away the noise: failed attempts that led nowhere, verbose tool outputs, back-and-forth exploration. What remains should be pure signal — golden nuggets of detail that preserve full understanding with zero ambiguity.
+
+COMPRESSED BLOCK PLACEHOLDERS
+When the selected range includes previously compressed blocks, use this exact placeholder format when referencing one:
+
+- `(bN)`
+
+Compressed block sections in context are clearly marked with a header:
+
+- `[Compressed conversation section]`
+
+Compressed block IDs always use the `bN` form (never `mNNNN`) and are represented in the same XML metadata tag format.
+
+Rules:
+
+- Include every required block placeholder exactly once.
+- Do not invent placeholders for blocks outside the selected range.
+- Treat `(bN)` placeholders as RESERVED TOKENS. Do not emit `(bN)` text anywhere except intentional placeholders.
+- If you need to mention a block in prose, use plain text like `compressed bN` (not as a placeholder).
+- Preflight check before finalizing: the set of `(bN)` placeholders in your summary must exactly match the required set, with no duplicates.
+
+These placeholders are semantic references. They will be replaced with the full stored compressed block content when the tool processes your output.
+
+FLOW PRESERVATION WITH PLACEHOLDERS
+When you use compressed block placeholders, write the surrounding summary text so it still reads correctly AFTER placeholder expansion.
+
+- Treat each placeholder as a stand-in for a full conversation segment, not as a short label.
+- Ensure transitions before and after each placeholder preserve chronology and causality.
+- Do not write text that depends on the placeholder staying literal (for example, "as noted in `(b2)`").
+- Your final meaning must be coherent once each placeholder is replaced with its full compressed block content.
+
+BOUNDARY IDS
+You specify boundaries by ID using the injected IDs visible in the conversation:
+
+- `mNNNN` IDs identify raw messages
+- `bN` IDs identify previously compressed blocks
+
+Each message has an ID inside XML metadata tags like `<dcp-message-id>m0001</dcp-message-id>`.
+The same ID tag appears in every tool output of the message it belongs to — each unique ID identifies one complete message.
+Treat these tags as boundary metadata only, not as tool result content.
+
+Rules:
+
+- Pick `startId` and `endId` directly from injected IDs in context.
+- IDs must exist in the current visible context.
+- `startId` must appear before `endId`.
+- Do not invent IDs. Use only IDs that are present in context.
+
+BATCHING
+When multiple independent ranges are ready and their boundaries do not overlap, include all of them as separate entries in the `content` array of a single tool call. Each entry should have its own `startId`, `endId`, and `summary`.
+
+THE FORMAT OF COMPRESS
+
+```
+{
+  topic: string,           // Short label (3-5 words) for the overall batch
+  content: [               // One or more ranges to compress independently
+    {
+      startId: string,     // ID at range start: mNNNN or bN
+      endId: string,       // ID at range end: mNNNN or bN
+      summary: string      // Complete technical summary replacing that range (use 7-section format above)
+    }
+  ]
+}
+```