opencodekit 0.15.21 → 0.16.1

package/dist/template/.opencode/plans/1770013678126-witty-planet.md

@@ -0,0 +1,278 @@
+# Plan: Implement `/init` Command for OpenCodeKit
+
+## Summary
+
+Implement the `/init` slash command that provides one-command project onboarding. This command creates project-root `AGENTS.md` and populates memory files with detected project information. The command is defined in `.opencode/command/init.md` and executed by the `@plan` agent.
+
+## Current State
+
+- **CLI `ock init`**: Already exists in `src/commands/init.ts` - bootstraps `.opencode/` directory
+- **Slash `/init`**: Defined in `.opencode/command/init.md` - AI-assisted project analysis workflow
+- **Templates**: Exist in `.opencode/memory/_templates/` (user.md, tech-stack.md)
+- **Memory system**: SQLite-based with tools in `.opencode/tool/`
+
+## Phases
+
+### Phase 1: Verify Command Registration
+
+**Owner**: @build
+**Deliverable**: Ensure `/init` command is properly registered and accessible
+**Files**:
+
+- `.opencode/command/init.md` (exists, verify content)
+- `.opencode/opencode.json` (verify command registration)
+
+**Validation**:
+
+- [ ] Command appears in `ock command list`
+- [ ] Command has correct frontmatter (agent: plan, subtask: true)
+- [ ] Command description is accurate
+
+### Phase 2: Enhance Project Detection Logic
+
+**Owner**: @build
+**Deliverable**: Robust project detection with comprehensive tech stack identification
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 2 section)
+- Create utility functions for detection if needed
+
+**Implementation Details**:
+
+1. Detect tech stack from:
+   - `package.json` → Node.js/Bun/JavaScript projects
+   - `go.mod` → Go projects
+   - `pyproject.toml`, `requirements.txt` → Python projects
+   - `Cargo.toml` → Rust projects
+   - `composer.json` → PHP projects
+   - `Gemfile` → Ruby projects
+   - `pom.xml`, `build.gradle` → Java projects
+
+2. Extract key information:
+   - Language & version
+   - Framework & version
+   - Build tool
+   - Test command
+   - Lint command
+   - Key dependencies
+
+3. Validate commands by attempting to run them
+
+**Validation**:
+
+- [ ] Correctly detects this project's stack (Bun, TypeScript)
+- [ ] Correctly detects various project types in test scenarios
+- [ ] Command validation works (build, test, lint)
+
+### Phase 3: Implement AGENTS.md Generation
+
+**Owner**: @build
+**Deliverable**: Template-based AGENTS.md generation with project-specific content
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 3 section)
+- Potentially create template files
+
+**Implementation Details**:
+
+1. Create AGENTS.md template structure:
+   - Project name (from package.json or directory name)
+   - Tech stack section (from Phase 2 detection)
+   - File structure section
+   - Commands section (validated commands)
+   - Code examples section (extract from actual codebase)
+   - Testing section
+   - Boundaries section (Always/Ask First/Never rules)
+   - Gotchas section
+
+2. Target: <60 lines (max 150 lines)
+
+3. If AGENTS.md exists:
+   - Read existing content
+   - Merge/improve rather than overwrite
+   - Preserve user-added sections
+
+**Validation**:
+
+- [ ] Generated AGENTS.md is <60 lines
+- [ ] Contains accurate tech stack
+- [ ] Commands are validated and working
+- [ ] Includes at least one code example from codebase
+- [ ] Has proper Boundaries section with Never rules
+
+### Phase 4: Implement Memory File Population
+
+**Owner**: @build
+**Deliverable**: Populate `.opencode/memory/project/user.md` and `tech-stack.md`
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 5 section)
+- `.opencode/memory/_templates/user.md`
+- `.opencode/memory/_templates/tech-stack.md`
+
+**Implementation Details**:
+
+1. Load templates from `_templates/`
+
+2. Populate `user.md` from Phase 1 answers:
+   - Identity (name, git contributor)
+   - Communication preferences (terse/detailed)
+   - Workflow preferences (auto-commit/ask-first)
+   - Custom rules
+
+3. Populate `tech-stack.md` from Phase 2 detection:
+   - Framework & version
+   - Language & runtime
+   - Key dependencies with versions
+   - Key constraints
+   - Active integrations
+
+**Validation**:
+
+- [ ] user.md created with accurate information
+- [ ] tech-stack.md created with detected stack
+- [ ] Templates are properly used as base
+
+### Phase 5: Implement Optional Beads Initialization
+
+**Owner**: @build
+**Deliverable**: Initialize `.beads/` directory when user opts in
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 6 section)
+
+**Implementation Details**:
+
+1. If user says yes to beads:
+   - Run `bd init` if available
+   - Or create basic structure manually:
+     - `.beads/config.yaml`
+     - `.beads/issues.jsonl`
+     - `.beads/metadata.json`
+
+**Validation**:
+
+- [ ] Beads initializes correctly when requested
+- [ ] No errors if beads already exists
+
+### Phase 6: Add --deep Mode Support
+
+**Owner**: @build
+**Deliverable**: Comprehensive research mode with subsystem detection
+**Files**:
+
+- `.opencode/command/init.md` (enhance Phase 4 section)
+
+**Implementation Details**:
+
+1. When `--deep` flag is passed:
+   - Git history analysis (contributors, commit conventions)
+   - Branching strategy detection
+   - Source file pattern analysis
+   - Subsystem identification for nested AGENTS.md
+
+2. Suggest nested AGENTS.md for:
+   - `packages/*/` in monorepos
+   - `src/` vs `tests/` if patterns differ
+   - `frontend/` vs `backend/` directories
+
+**Validation**:
+
+- [ ] --deep flag triggers additional research
+- [ ] Subsystem detection works for monorepos
+- [ ] Suggestions are relevant and actionable
+
+### Phase 7: Testing & Validation
+
+**Owner**: @build
+**Deliverable**: End-to-end testing of the `/init` command
+**Files**:
+
+- Test in a fresh project directory
+- Test in existing project with AGENTS.md
+- Test with --deep flag
+
+**Test Scenarios**:
+
+1. Fresh project (no AGENTS.md):
+   - [ ] Asks upfront questions
+   - [ ] Detects tech stack correctly
+   - [ ] Creates AGENTS.md
+   - [ ] Populates memory files
+   - [ ] Shows completion summary
+
+2. Existing project (with AGENTS.md):
+   - [ ] Reads existing AGENTS.md
+   - [ ] Merges/improves rather than overwriting
+   - [ ] Preserves user content
+
+3. With --deep flag:
+   - [ ] Performs git analysis
+   - [ ] Detects subsystems
+   - [ ] Suggests nested AGENTS.md
+
+4. With --skip-questions:
+   - [ ] Skips upfront questions
+   - [ ] Infers identity from git config
+
+**Validation**:
+
+- [ ] All test scenarios pass
+- [ ] Generated files are valid and useful
+- [ ] Command completes without errors
+
+## Dependencies
+
+- Phase 2 depends on Phase 1 (command registration verification)
+- Phase 3 depends on Phase 2 (tech stack detection)
+- Phase 4 depends on Phase 1 (templates exist) and Phase 2 (detection data)
+- Phase 5 is independent but uses Phase 1 answers
+- Phase 6 is optional enhancement
+- Phase 7 depends on all previous phases
+
+## Risks
+
+| Risk                                              | Likelihood | Impact | Mitigation                                           |
+| ------------------------------------------------- | ---------- | ------ | ---------------------------------------------------- |
+| Command detection fails for exotic project types  | Medium     | Medium | Fallback to generic templates, allow manual override |
+| AGENTS.md generation produces stale code examples | Low        | Medium | Use pointers instead of inline code where possible   |
+| Memory file templates change structure            | Low        | Low    | Version templates, update command accordingly        |
+| User preferences not captured correctly           | Low        | Medium | Validate with user before writing files              |
+| --deep mode takes too long                        | Medium     | Low    | Add progress indicators, allow cancellation          |
+
+## Acceptance Criteria
+
+- [ ] `/init` command is accessible and runs without errors
+- [ ] Creates `./AGENTS.md` with project-specific information (<60 lines target)
+- [ ] Populates `.opencode/memory/project/user.md` with user preferences
+- [ ] Populates `.opencode/memory/project/tech-stack.md` with detected stack
+- [ ] Validates commands (build, test, lint) actually work
+- [ ] Handles existing AGENTS.md gracefully (merges/improves)
+- [ ] Supports `--deep` flag for comprehensive analysis
+- [ ] Supports `--skip-questions` flag for non-interactive use
+- [ ] Optional beads initialization works
+- [ ] Shows clear completion summary with next steps
+
+## Questions
+
+1. Should we add a `--dry-run` flag to preview what would be created without writing files?
+2. Should we support importing from existing `.cursorrules` or `.github/copilot-instructions.md` files?
+3. Should the command suggest running `/review-codebase` after initialization?
+
+## Implementation Notes
+
+The `/init` command is already defined in `.opencode/command/init.md`. The implementation involves:
+
+1. **Verifying** the command definition is complete and accurate
+2. **Enhancing** the command instructions with robust detection logic
+3. **Testing** the command end-to-end in various scenarios
+
+The command uses the `@plan` agent (subtask: true) which means it runs as a separate planning task. The instructions in the markdown file guide the AI through the 8-phase process.
+
+Key files to verify/modify:
+
+- `.opencode/command/init.md` - Main command definition
+- `.opencode/memory/_templates/user.md` - User profile template
+- `.opencode/memory/_templates/tech-stack.md` - Tech stack template
+
+No new CLI commands needed - this is a slash command enhancement.