opencodekit 0.10.0 → 0.11.1

package/dist/template/.opencode/command/new-feature.md

@@ -1,137 +1,473 @@
 ---
-description: Create a new feature with bead, spec, and plan
-argument-hint: "<feature-name> [--priority=high|medium|low] [--type=feature|bug|refactor]"
+description: Create a new feature with discovery, spec, plan, and sub-tasks
+argument-hint: "<feature-name> [--priority=<0-4>] [--type=<type>] [--branch] [--quick]"
 agent: planner
 model: proxypal/gemini-3-flash-preview
 ---
 
 # New Feature: $ARGUMENTS
 
+Create a complete feature track with discovery, specification, implementation plan, and sub-tasks.
+
+## Load Beads Skill
+
+```typescript
+skill({ name: "beads" });
+```
+
+This skill provides Epic → Task → Subtask hierarchy for complex features.
+
+## Parse Arguments
+
+| Argument     | Default  | Options                              |
+| ------------ | -------- | ------------------------------------ |
+| Feature name | required | Descriptive name                     |
+| `--priority` | 2        | 0 (critical) to 4 (backlog)          |
+| `--type`     | feature  | feature, bug, refactor, chore        |
+| `--branch`   | false    | Create git branch                    |
+| `--quick`    | false    | Skip brainstorming, use minimal spec |
+
+---
+
+## Phase 1: Context Gathering
+
+Before creating anything, understand the landscape:
+
+```bash
+# Check for related existing work
+bd_ls({ status: "all", limit: 20, offset: 0 })
+
+# Analyze codebase structure
+glob pattern="src/**/*.{ts,tsx,py}"
+lsp_workspace_symbols({ query: "[relevant-terms]" })
+
+# Check recent changes in related areas
+git log --oneline -10 -- src/[relevant-path]/
+```
+
+**Report:**
+
+```
+Context Analysis
+━━━━━━━━━━━━━━━━
+
+Related beads found:
+- bd-abc123: "User auth system" (closed)
+- bd-def456: "Session management" (in_progress)
+
+Relevant code areas:
+- src/auth/ (12 files)
+- src/api/users/ (5 files)
+
+Recent changes:
+- 3 commits in last week to src/auth/
+```
+
+---
+
+## Phase 2: Brainstorming (unless --quick)
+
 **Load skill:** `skill({ name: "brainstorming" })`
 
-Create a complete feature track with bead, specification, and implementation plan.
+Before filling templates, explore the problem space:
+
+### Discovery Questions
+
+Ask the user (or infer from context):
+
+1. **Problem**: What specific problem are we solving?
+2. **Users**: Who benefits from this feature?
+3. **Success**: How will we know it's working?
+4. **Alternatives**: What other approaches exist?
+5. **Risks**: What could go wrong?
+6. **Dependencies**: What does this need to work?
+7. **Scope**: What's explicitly NOT included?
+
+### Exploration
+
+```
+Brainstorming: [Feature Name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Problem understood:
+[Summarize the core problem]
+
+Considered approaches:
+1. [Approach A] - Pros: [...] Cons: [...]
+2. [Approach B] - Pros: [...] Cons: [...]
+3. [Approach C] - Pros: [...] Cons: [...]
+
+Recommended approach: [X]
+Rationale: [Why this approach]
 
-## Instructions
+Key risks identified:
+- [Risk 1]: Mitigation: [...]
+- [Risk 2]: Mitigation: [...]
 
-Parse from `$ARGUMENTS`:
+Proceed with spec? (yes/modify/explore-more)
+```
 
-- Feature name (required)
-- Priority (default: medium)
-- Type (default: feature)
+**STOP and wait for approval** before proceeding.
 
-## Workflow
+---
 
-### Step 1: Create Bead
+## Phase 3: Create Epic Bead
 
 ```typescript
-bd_add({ title: "[feature-name]", type: "[type]", pri: [priority] });
+bd_add({
+  title: "[Feature Name]",
+  type: "epic",
+  pri: [priority],
+  desc: "[Brief description from brainstorming]",
+  tags: ["feature", ...inferred_tags],
+});
 ```
 
-Capture the bead ID from output.
+Capture the bead ID for artifact creation.
+
+---
 
-### Step 2: Create Specification
+## Phase 4: Create Specification
 
-Create `.beads/[bead-id]/spec.md`:
+Create `.beads/artifacts/[bead-id]/spec.md`:
 
 ```markdown
 # [Feature Name] Specification
 
 ## Overview
 
-[Brief description of the feature]
+[1-2 paragraph summary of the feature]
 
 ## Problem Statement
 
-[What problem does this solve?]
+**Current state:** [What exists now / what's broken]
+**Desired state:** [What we want to achieve]
+**Gap:** [The specific problem to solve]
 
 ## User Stories
 
-- As a [user], I want [goal], so that [benefit]
+- As a [user type], I want [goal], so that [benefit]
+- As a [user type], I want [goal], so that [benefit]
 
 ## Acceptance Criteria
 
+Must-have (P0):
+
 - [ ] [Criterion 1]
 - [ ] [Criterion 2]
+
+Should-have (P1):
+
 - [ ] [Criterion 3]
 
-## Technical Considerations
+Nice-to-have (P2):
+
+- [ ] [Criterion 4]
+
+## Technical Design
+
+### Approach
+
+[Chosen approach from brainstorming]
+
+### Architecture Changes
 
-- [Consideration 1]
-- [Consideration 2]
+- [Component 1]: [Change description]
+- [Component 2]: [Change description]
+
+### API Changes
+
+| Endpoint | Method | Description    |
+| -------- | ------ | -------------- |
+| /api/... | POST   | [What it does] |
+
+### Database Changes
+
+- [ ] New table: [table_name]
+- [ ] New column: [table.column]
+- [ ] Migration needed: [yes/no]
+
+### Dependencies
+
+- External: [APIs, services]
+- Internal: [Other features, beads]
+
+## Estimation
+
+| Size       | Effort      | Confidence        |
+| ---------- | ----------- | ----------------- |
+| [S/M/L/XL] | [X-Y hours] | [High/Medium/Low] |
+
+Breakdown:
+
+- Design: [X hours]
+- Implementation: [X hours]
+- Testing: [X hours]
+- Documentation: [X hours]
+
+## Risks
+
+| Risk     | Likelihood | Impact | Mitigation              |
+| -------- | ---------- | ------ | ----------------------- |
+| [Risk 1] | Medium     | High   | [How to prevent/handle] |
+| [Risk 2] | Low        | Medium | [How to prevent/handle] |
 
 ## Out of Scope
 
-- [What we're NOT doing]
+Explicitly NOT included in this feature:
+
+- [Thing 1]
+- [Thing 2]
+
+## Success Metrics
+
+How we'll measure success:
+
+- [ ] [Metric 1]: [Target]
+- [ ] [Metric 2]: [Target]
 
-## Dependencies
+## Open Questions
 
-- [Other features/systems this depends on]
+- [ ] [Question that needs answering]
+- [ ] [Question that needs answering]
 ```
 
-### Step 3: Create Plan
+---
+
+## Phase 5: Validate Specification
+
+Before proceeding to plan, validate spec completeness:
+
+```
+Spec Validation
+━━━━━━━━━━━━━━━
+
+✓ Problem statement clear
+✓ User stories defined
+✓ Acceptance criteria measurable
+⚠ Technical design incomplete - missing API details
+✓ Estimation provided
+✓ Risks identified
+⚠ Open questions remain (2 items)
+
+Validation: PASS with warnings
+
+Proceed to plan? (yes/fix-warnings/cancel)
+```
+
+---
+
+## Phase 6: Create Implementation Plan
 
-Create `.beads/[bead-id]/plan.md`:
+Create `.beads/artifacts/[bead-id]/plan.md`:
 
 ```markdown
 # [Feature Name] Implementation Plan
 
-## Phases
+## Overview
+
+**Epic:** [bead-id]
+**Estimated effort:** [X-Y hours]
+**Target completion:** [Date or sprint]
+
+## Phase 1: Foundation [S]
+
+**Estimate:** 2-4 hours
+**Assignee:** [role or @mention]
 
-### Phase 1: [Name]
+Tasks:
+
+1. [ ] Set up database schema
+2. [ ] Create base API types
+
+**Exit criteria:** Database migrated, types compile
+
+## Phase 2: Core Implementation [M]
+
+**Estimate:** 4-8 hours
+**Depends on:** Phase 1
+
+Tasks:
+
+1. [ ] Implement [core feature]
+2. [ ] Add business logic
+3. [ ] Connect to existing systems
 
-**Estimate:** [X hours]
+**Exit criteria:** Core functionality works in isolation
+
+## Phase 3: Integration [M]
+
+**Estimate:** 4-8 hours
+**Depends on:** Phase 2
 
 Tasks:
 
-1. [ ] [Task 1]
-2. [ ] [Task 2]
+1. [ ] Integrate with [system]
+2. [ ] Add error handling
+3. [ ] Implement edge cases
 
-### Phase 2: [Name]
+**Exit criteria:** Feature works end-to-end
 
-**Estimate:** [X hours]
+## Phase 4: Testing & Polish [S]
+
+**Estimate:** 2-4 hours
+**Depends on:** Phase 3
 
 Tasks:
 
-1. [ ] [Task 1]
-2. [ ] [Task 2]
+1. [ ] Write unit tests
+2. [ ] Write integration tests
+3. [ ] Manual testing
+4. [ ] Fix bugs found
+
+**Exit criteria:** Tests pass, no critical bugs
 
 ## Testing Strategy
 
-- [ ] Unit tests for [what]
-- [ ] Integration tests for [what]
+| Type        | Coverage      | Focus                |
+| ----------- | ------------- | -------------------- |
+| Unit        | Core logic    | [specific modules]   |
+| Integration | API endpoints | [specific endpoints] |
+| E2E         | Critical path | [user flow]          |
 
 ## Rollout Plan
 
-1. [Step 1]
-2. [Step 2]
+1. [ ] Deploy to staging
+2. [ ] QA verification
+3. [ ] Deploy to production (feature flag)
+4. [ ] Monitor metrics
+5. [ ] Gradual rollout (10% → 50% → 100%)
 
 ## Rollback Plan
 
-[How to revert if needed]
+If issues detected:
+
+1. Disable feature flag
+2. Revert database migration (if applicable)
+3. Deploy previous version
+4. Investigate and fix
+
+## Definition of Done
+
+- [ ] All acceptance criteria met
+- [ ] Tests written and passing
+- [ ] Code reviewed
+- [ ] Documentation updated
+- [ ] Feature flag configured
+- [ ] Monitoring in place
 ```
 
-### Step 4: Update Bead
+---
 
-Update bead status by adding a note via `bd_msg` or updating the spec.
+## Phase 7: Create Sub-Task Beads
 
-## Output
+Break phases into individual trackable beads:
 
-Report:
+```typescript
+// Phase 1 tasks
+bd_add({
+  title: "Set up database schema for [feature]",
+  type: "task",
+  pri: 2,
+  parent: "<epic-id>",
+  desc: "Phase 1 of [feature]. Create tables and migrations.",
+  tags: ["backend", "database"],
+});
+
+// Phase 2 tasks (with dependency)
+bd_add({
+  title: "Implement [core feature]",
+  type: "task",
+  pri: 2,
+  parent: "<epic-id>",
+  deps: ["<phase-1-bead-id>"],
+  tags: ["backend"],
+});
+
+// Continue for all phases...
+```
 
-- Bead ID created
-- Spec file path
-- Plan file path
-- Next command to run: `/implement [bead-id]`
+---
 
-## Follow-up Commands
+## Phase 8: Create Branch (if --branch)
 
 ```bash
-# View the feature
-bd_show({ id: "[bead-id]" })
+# Create feature branch
+git checkout -b feature/[feature-name]
+
+# Or with bead ID
+git checkout -b feature/[bead-id]-[feature-name]
+```
+
+---
 
-# Start implementation
-/implement [bead-id]
+## Output
+
+```
+Feature Created: [Feature Name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Epic: [bead-id]
+Priority: P[X]
+Estimated effort: [X-Y hours]
 
-# Check status
-/status [bead-id]
+Artifacts:
+├── .beads/artifacts/[bead-id]/spec.md
+└── .beads/artifacts/[bead-id]/plan.md
+
+Sub-tasks created:
+├── [task-id-1]: Set up database schema [S]
+├── [task-id-2]: Implement core feature [M] → blocked by task-1
+├── [task-id-3]: Integration [M] → blocked by task-2
+└── [task-id-4]: Testing & polish [S] → blocked by task-3
+
+Branch: feature/[feature-name] (if --branch)
+
+Next Steps:
+├── View feature: bd_show({ id: "[bead-id]" })
+├── Start first task: /implement [task-id-1]
+└── View ready work: bd_ls({ status: "ready" })
 ```
+
+---
+
+## Quick Mode (--quick)
+
+Skip brainstorming, use minimal spec:
+
+- No discovery questions
+- Minimal spec template
+- Single-phase plan
+- No sub-task breakdown
+
+Use for: Small features, bug fixes, well-understood work.
+
+---
+
+## Estimation Framework
+
+| Size | Hours    | Typical Scope                            |
+| ---- | -------- | ---------------------------------------- |
+| XS   | 1-2      | Config change, typo fix                  |
+| S    | 2-4      | Simple feature, single file              |
+| M    | 4-8      | Multi-file feature, some complexity      |
+| L    | 1-3 days | Significant feature, multiple components |
+| XL   | 3-5 days | Major feature, architecture impact       |
+
+**Confidence levels:**
+
+- **High**: Done this before, clear path
+- **Medium**: Some unknowns, general approach clear
+- **Low**: Significant unknowns, may need spikes
+
+---
+
+## Related Commands
+
+| Need                 | Command                     |
+| -------------------- | --------------------------- |
+| Start implementation | `/implement <bead-id>`      |
+| View feature status  | `/status <bead-id>`         |
+| Import existing plan | `/import-plan`              |
+| Complete feature     | `/finish <bead-id>`         |
+| Revert feature       | `/revert-feature <bead-id>` |