opencodekit 0.10.0 → 0.11.0

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

@@ -10,7 +10,7 @@ One command to onboard a project. Creates project-root AGENTS.md and populates m
 
 ## Options
 
-- `--deep`: Comprehensive research (~100+ tool calls). Git history, patterns, contributors.
+- `--deep`: Comprehensive research (~100+ tool calls). Git history, patterns, contributors, subsystem detection.
 - `--skip-questions`: Skip upfront questions, infer from git config.
 
 Default: Standard research (~20-50 tool calls).
@@ -23,6 +23,7 @@ Unless `--skip-questions`, ask in one message:
 2. **Communication**: "Terse or detailed responses?"
 3. **Workflow**: "Auto-commit or ask-first?"
 4. **Rules**: "Any rules I should always follow?"
+5. **Beads**: "Use beads for task tracking? (y/n)"
 
 If skipped, infer identity from `git config user.name` and `git config user.email`.
 
@@ -30,11 +31,20 @@ If skipped, infer identity from `git config user.name` and `git config user.emai
 
 ### Always Check
 
-- `package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml` - tech stack
+- `package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml` - tech stack WITH VERSIONS
 - `README.md` - project description
 - `.github/workflows/`, `.gitlab-ci.yml` - CI/CD
 - `Makefile`, `justfile` - build commands
 - Existing rules: `.cursor/rules/`, `.cursorrules`, `.github/copilot-instructions.md`
+- Top-level directories - identify structure
+
+### Validate Commands
+
+```bash
+# Actually run detected commands to verify they work
+npm run build 2>&1 | head -5  # Check for errors
+npm test -- --help 2>&1 | head -3  # Verify test syntax
+```
 
 ### With --deep
 
@@ -42,34 +52,99 @@ If skipped, infer identity from `git config user.name` and `git config user.emai
 - `git log --format="%s" -50` - commit conventions
 - `git branch -a` - branching strategy
 - Source file analysis for patterns
+- Identify subsystems needing nested AGENTS.md
 
 ## Phase 3: Create Project-Root AGENTS.md
 
-Create `./AGENTS.md` (project root, ~20-30 lines):
+Create `./AGENTS.md` - **TARGET: <60 lines** (max 150 lines).
+
+Research shows: Frontier LLMs reliably follow ~150-200 instructions. More = degraded quality across ALL instructions.
 
 ```markdown
-## Build/Lint/Test Commands
+# [Project Name]
+
+## Tech Stack
+
+- [Language] [version] with [framework] [version]
+- [Key dependencies with versions]
+- [Build tool]: [tool name]
+
+## File Structure
+```
+
+src/ # Source code
+tests/ # Test files  
+docs/ # Documentation
+scripts/ # Build/deploy scripts
+
+````
+
+## Commands
+
+**Build**: `[detected command]`
+**Test**: `[detected command]` (single test: `[syntax]`)
+**Lint**: `[detected command]`
+**Dev**: `[detected command]`
+
+## Code Examples
+
+Good pattern (from your codebase):
+
+```[language]
+[Actual code snippet showing preferred style - 5-10 lines]
+````
+
+## Testing
+
+- Tests live in: `[path]`
+- Run single test: `[command]`
+- Verify changes: `[command]`
+
+## Boundaries
+
+✅ **Always**: Run lint before commit, include tests for new features
+⚠️ **Ask first**: Schema changes, new dependencies, file deletions
+🚫 **Never**: Commit secrets, modify vendor/, force push main, skip tests
+
+## Gotchas
 
-**Build**: [detected command]
-**Test**: [detected command, include single-test syntax]
-**Lint**: [detected command]
+- [Known issue or edge case]
+- [Thing that will waste 2+ hours if forgotten]
 
-## Code Style
+````
 
-**Imports**: [detected pattern]
-**Formatting**: [tool used, e.g., prettier, black]
-**Types**: [strict, optional, none]
-**Naming**: [conventions detected]
-**Error Handling**: [pattern detected]
+**Key principles:**
+- Examples > Explanations (LLMs are in-context learners)
+- Pointers > Copies ("See docs/architecture.md" not inline everything)
+- If AGENTS.md exists, improve it - don't overwrite blindly
 
-## Project-Specific Rules
+## Phase 4: Detect Subsystems (--deep only)
+
+For projects with distinct subsystems, identify candidates for nested AGENTS.md:
+
+```bash
+# Find directories with significant code
+find . -type d -name "src" -o -name "packages" -o -name "apps" | head -10
+````
+
+Suggest nested AGENTS.md for:
+
+- `packages/*/` in monorepos
+- `src/` vs `tests/` if patterns differ significantly
+- `frontend/` vs `backend/` directories
+
+Output suggestion:
 
-[Include any rules from .cursorrules, copilot-instructions, or user-provided]
 ```
+Detected subsystems that may benefit from nested AGENTS.md:
+- packages/api/ - API server patterns
+- packages/web/ - Frontend patterns
+- tests/ - Testing conventions
 
-If AGENTS.md exists, improve it - don't overwrite blindly.
+Create nested AGENTS.md files? (y/n)
+```
 
-## Phase 4: Populate Memory Files
+## Phase 5: Populate Memory Files
 
 ### .opencode/memory/user.md
 
@@ -108,15 +183,20 @@ updated: [today]
 
 ## Build
 
-[detected]
+`[detected and validated]`
 
 ## Test
 
-[detected, include single-test example]
+`[detected]`
+Single test: `[syntax with example]`
 
 ## Lint
 
-[detected]
+`[detected]`
+
+## Dev Server
+
+`[detected]`
 ```
 
 ### .opencode/memory/project/architecture.md
@@ -131,11 +211,15 @@ updated: [today]
 
 ## Structure
 
-[detected directory layout]
+[detected directory layout with purpose annotations]
 
 ## Key Modules
 
-[identified entry points, core modules]
+[identified entry points, core modules, their responsibilities]
+
+## Data Flow
+
+[how data moves through the system - if detectable]
 ```
 
 ### With --deep, also create:
@@ -143,34 +227,69 @@ updated: [today]
 - `project/conventions.md` - from git log analysis
 - `project/gotchas.md` - from bug-fix patterns in history
 
-## Phase 5: Reflection
+## Phase 6: Initialize Beads (if requested)
 
-Before finishing:
+If user said yes to beads:
 
-1. Did you create both AGENTS.md AND memory files?
-2. Are commands accurate and tested?
-3. Any typos or unclear descriptions?
-4. Would this help your future self?
+```bash
+bd init  # or equivalent initialization
+```
+
+Create `.beads/` directory structure for task tracking.
+
+## Phase 7: Reflection
+
+Before finishing, verify:
+
+1. [ ] AGENTS.md is <60 lines (or has good reason to be longer)?
+2. [ ] Commands were validated and actually work?
+3. [ ] Boundaries section includes Never rules?
+4. [ ] At least one code example from actual codebase?
+5. [ ] Memory files created with accurate info?
 
-Fix issues found.
+Fix any issues found.
 
-## Phase 6: Summary
+## Phase 8: Summary
 
 Report:
 
-- Files created/updated
-- Tech stack detected
-- Key findings
-- Suggested next steps (e.g., "Run /review-codebase to check conventions")
+```
+Initialization Complete
+━━━━━━━━━━━━━━━━━━━━━━━
+
+Files created:
+- ./AGENTS.md ([N] lines)
+- .opencode/memory/user.md
+- .opencode/memory/project/commands.md
+- .opencode/memory/project/architecture.md
+[- .beads/ (if initialized)]
+
+Tech stack: [detected]
+Commands validated: [yes/no]
+
+Suggested next steps:
+1. Review AGENTS.md and adjust boundaries
+2. Run /review-codebase to check conventions
+3. [If --deep suggested subsystems] Create nested AGENTS.md files
+```
 
 ## File Locations
 
 ```
-./AGENTS.md                              # Project-specific rules (created)
+./AGENTS.md                              # Project-specific rules (created, <60 lines)
 .opencode/AGENTS.md                      # Global rules (untouched)
 .opencode/memory/user.md                 # User preferences (created)
 .opencode/memory/project/commands.md     # Build commands (created)
 .opencode/memory/project/architecture.md # Structure (created)
 .opencode/memory/project/conventions.md  # Patterns (--deep only)
 .opencode/memory/project/gotchas.md      # Warnings (--deep only)
+[packages/*/AGENTS.md]                   # Subsystem rules (--deep, if requested)
 ```
+
+## Anti-Patterns to Avoid
+
+- ❌ Vague instructions: "Be helpful" or "Write good code"
+- ❌ Detailed style rules (use linters instead)
+- ❌ Every possible command (context bloat)
+- ❌ Auto-generated content without review
+- ❌ Code snippets that go stale (use pointers)