# Plan: Implement `/create` Command for Bead Artifacts

## Summary

Implement a new CLI command `ock create <bead-id>` that creates structured artifacts for beads using templates. This command will set up the artifact directory structure and copy appropriate templates (spec.md, prd.md, or proposal.md) based on flags.

## Phases

### Phase 1: Create Command Implementation

**Owner**: @build
**Deliverable**: `src/commands/create.ts` file
**Files to Create**:

- `src/commands/create.ts` - Main command implementation

**Implementation Details**:

The command follows the established pattern from `skill.ts` and `command.ts`:

1. **Argument Parsing**:
   - `<bead-id>` (required) - The bead to create artifacts for
   - `--prd` flag - Use PRD template (combined format)
   - `--proposal` flag - Create proposal.md first (for epics)

2. **Validation**:
   - Check if `.opencode/` exists (project initialized)
   - Check if `.beads/` exists (beads initialized)
   - Validate bead-id format (lowercase, alphanumeric, hyphens)
   - Check if artifact directory already exists

3. **Directory Structure**:
   - Create `.beads/artifacts/<bead-id>/` directory
   - Copy templates from `.opencode/memory/_templates/`

4. **Template Selection Logic**:
   | Flag | Template(s) Created |
   |------|---------------------|
   | (none) | spec.md |
   | `--prd` | prd.md |
   | `--proposal` | proposal.md + spec.md |

5. **Template Variable Substitution**:
   - Replace `[bead-id]` with actual bead ID
   - Replace `[date]` with current date (YYYY-MM-DD)
   - Replace `[YYYY-MM-DD]` with current date

6. **Interactive Prompts** (when no flags):
   - Ask for bead title/description if not provided
   - Ask for template type preference

**Validation Steps**:

- Run `npm run typecheck` - TypeScript compiles without errors
- Run `npm run lint` - No linting errors

### Phase 2: Register Command in CLI

**Owner**: @build
**Deliverable**: Updated `src/index.ts`
**Files to Modify**:

- `src/index.ts` - Add command registration

**Changes**:

1. Import `createCommand` from `./commands/create.js`
2. Register CLI command:
   ```typescript
   cli
     .command("create <bead-id>", "Create structured artifacts for a bead")
     .option("--prd", "Use PRD template (combined format)")
     .option("--proposal", "Create proposal.md first (for epics)")
     .action(createCommand);
   ```

**Validation Steps**:

- Run `bun run src/index.ts create --help` - Shows help text
- Run `npm run typecheck` - No type errors

### Phase 3: Testing

**Owner**: @build
**Deliverable**: Verified command works end-to-end

**Test Cases**:

1. **Basic spec creation**:

   ```bash
   ock create test-bead-123
   # Expected: Creates .beads/artifacts/test-bead-123/spec.md
   ```

2. **PRD template**:

   ```bash
   ock create test-bead-456 --prd
   # Expected: Creates .beads/artifacts/test-bead-456/prd.md
   ```

3. **Proposal template**:

   ```bash
   ock create test-epic-789 --proposal
   # Expected: Creates .beads/artifacts/test-epic-789/proposal.md AND spec.md
   ```

4. **Error cases**:
   - Missing bead-id: Shows usage help
   - Invalid bead-id format: Shows validation error
   - Project not initialized: Shows "Run: ock init" error
   - Beads not initialized: Shows warning
   - Artifact already exists: Shows confirmation prompt

**Validation Steps**:

- Run `bun test src/commands/create.test.ts` (if test file created)
- Manual testing of all scenarios above

## Dependencies

- Phase 2 depends on Phase 1 completion
- Phase 3 depends on Phase 2 completion

## Risks

| Risk                           | Likelihood | Impact | Mitigation                                                     |
| ------------------------------ | ---------- | ------ | -------------------------------------------------------------- |
| Template files not found       | Low        | High   | Check template existence, show clear error with fix suggestion |
| Bead ID validation too strict  | Medium     | Low    | Allow common formats, provide clear validation messages        |
| Overwriting existing artifacts | Low        | High   | Check before creating, prompt for confirmation                 |

## Acceptance Criteria

- [ ] `ock create <bead-id>` creates `.beads/artifacts/<bead-id>/spec.md` from template
- [ ] `ock create <bead-id> --prd` creates `prd.md` instead
- [ ] `ock create <bead-id> --proposal` creates both `proposal.md` and `spec.md`
- [ ] Template variables (bead-id, date) are substituted correctly
- [ ] Validates project is initialized (`.opencode/` exists)
- [ ] Validates beads is initialized (`.beads/` exists) or warns
- [ ] Shows clear error for invalid bead-id format
- [ ] Prompts for confirmation if artifacts already exist
- [ ] TypeScript compiles without errors (`npm run typecheck`)
- [ ] No linting errors (`npm run lint`)
- [ ] Command appears in `ock --help` output

## Critical Files to Modify

| File                     | Purpose                    |
| ------------------------ | -------------------------- |
| `src/commands/create.ts` | New command implementation |
| `src/index.ts`           | CLI registration           |

## Templates Used

| Template    | Path                                      |
| ----------- | ----------------------------------------- |
| spec.md     | `.opencode/memory/_templates/spec.md`     |
| prd.md      | `.opencode/memory/_templates/prd.md`      |
| proposal.md | `.opencode/memory/_templates/proposal.md` |

## Notes

- Follow existing command patterns from `skill.ts` and `command.ts`
- Use `@clack/prompts` for interactive elements
- Use `picocolors` for styling
- Reuse error utilities from `src/utils/errors.ts`
- Bead ID validation: lowercase letters, numbers, hyphens (start with letter)
