# 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 `br 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.
