opencodekit 0.23.1 → 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."

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