opencodekit 0.12.7 → 0.13.1

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

@@ -1,22 +1,20 @@
 ---
 description: Create a new feature with discovery, spec, plan, and sub-tasks
-argument-hint: "<feature-name> [--priority=<0-4>] [--type=<type>] [--branch] [--quick]"
+argument-hint: "<feature-name> [--priority=<0-4>] [--type=<type>] [--worktree] [--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.
+Create a complete feature track with Epic → Task → Subtask hierarchy, proper worktree isolation, and subagent delegation.
 
-## Load Beads Skill
+## Load Skills
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "brainstorming" });
 ```
 
-This skill provides Epic → Task → Subtask hierarchy for complex features.
-
 ## Parse Arguments
 
 | Argument     | Default  | Options                              |
@@ -24,23 +22,67 @@ This skill provides Epic → Task → Subtask hierarchy for complex features.
 | Feature name | required | Descriptive name                     |
 | `--priority` | 2        | 0 (critical) to 4 (backlog)          |
 | `--type`     | feature  | feature, bug, refactor, chore        |
-| `--branch`   | false    | Create git branch                    |
+| `--worktree` | false    | Create git worktree for isolation    |
 | `--quick`    | false    | Skip brainstorming, use minimal spec |
 
 ---
 
+## Hierarchy Model
+
+```
+Epic (feature-level)
+├── Task 1 (domain or phase)
+│   ├── Subtask 1.1 (atomic work unit)
+│   └── Subtask 1.2
+├── Task 2 (blocked by Task 1)
+│   └── Subtask 2.1
+└── Task 3 (blocked by Task 2)
+```
+
+| Level   | Scope        | Typical Duration | Agent Work                |
+| ------- | ------------ | ---------------- | ------------------------- |
+| Epic    | Full feature | Days-weeks       | Coordinate, not implement |
+| Task    | Domain/phase | Hours-day        | May implement or delegate |
+| Subtask | Atomic unit  | 30min-2hrs       | Implement directly        |
+
+---
+
 ## Phase 1: Context Gathering
 
-Before creating anything, understand of landscape:
+Before creating anything, understand the landscape.
 
-!`bd list --status all --limit 20`
+### Parallel Subagent Research
 
-# Analyze codebase structure
+```typescript
+// Fire both in parallel - planner is read-only
+Task({
+  subagent_type: "explore",
+  prompt: `Research codebase for "${$ARGUMENTS}":
+    1. Find similar implementations or patterns
+    2. Identify likely affected directories
+    3. Find existing tests in related areas
+    4. Check for related beads (open or closed)
+    Return: File paths, patterns, test locations, related beads`,
+  description: "Explore codebase for feature",
+});
+
+Task({
+  subagent_type: "scout",
+  prompt: `Research best practices for "${$ARGUMENTS}":
+    1. Industry patterns for this type of feature
+    2. Library/framework recommendations
+    3. Common pitfalls to avoid
+    Return: Recommendations, code examples, warnings`,
+  description: "Scout best practices",
+});
+```
 
-glob pattern="src/\*_/_.{ts,tsx,py}"
-lsp_lsp_workspace_symbols({ query: "[relevant-terms]" })
+### Check Existing Work
 
-!`git log --oneline -10 -- src/[relevant-path]/`
+```bash
+bd list --status all --limit 20 | grep -i "[relevant-terms]"
+git log --oneline -10 -- src/[relevant-path]/
+```
 
 **Report:**
 
@@ -48,25 +90,24 @@ lsp_lsp_workspace_symbols({ query: "[relevant-terms]" })
 Context Analysis
 ━━━━━━━━━━━━━━━━
 
-Related beads found:
+Related beads:
 - bd-abc123: "User auth system" (closed)
 - bd-def456: "Session management" (in_progress)
 
-Relevant code areas:
-- src/auth/ (12 files)
-- src/api/users/ (5 files)
+Codebase signals:
+- Similar patterns in: src/auth/, src/api/
+- Test patterns: src/__tests__/*.test.ts
+- Recent activity: 3 commits this week
 
-Recent changes:
-- 3 commits in last week to src/auth/
+External research:
+- [Key findings from scout]
 ```
 
 ---
 
 ## Phase 2: Brainstorming (unless --quick)
 
-**Load skill:** `skill({ name: "brainstorming" })`
-
-Before filling templates, explore the problem space:
+Before filling templates, explore the problem space.
 
 ### Discovery Questions
 
@@ -80,7 +121,7 @@ Ask the user (or infer from context):
 6. **Dependencies**: What does this need to work?
 7. **Scope**: What's explicitly NOT included?
 
-### Exploration
+### Present Options
 
 ```
 Brainstorming: [Feature Name]
@@ -114,13 +155,17 @@ Proceed with spec? (yes/modify/explore-more)
 bd create "[Feature Name]" -t epic -p [priority]
 ```
 
-Capture the bead ID for artifact creation.
+Capture the bead ID (e.g., `bd-a1b2c3`) for artifact creation.
+
+```bash
+mkdir -p .beads/artifacts/[bead-id]
+```
 
 ---
 
 ## Phase 4: Create Specification
 
-Create `.beads/artifacts/[bead-id]/spec.md`:
+Write `.beads/artifacts/[bead-id]/spec.md`:
 
 ```markdown
 # [Feature Name] Specification
@@ -166,21 +211,15 @@ Nice-to-have (P2):
 - [Component 1]: [Change description]
 - [Component 2]: [Change description]
 
-### API Changes
+### Files Affected
 
-| Endpoint | Method | Description    |
-| -------- | ------ | -------------- |
-| /api/... | POST   | [What it does] |
-
-### Database Changes
-
-- [ ] New table: [table_name]
-- [ ] New column: [table.column]
-- [ ] Migration needed: [yes/no]
+| File      | Change         |
+| --------- | -------------- |
+| `src/...` | [What changes] |
 
 ### Dependencies
 
-- External: [APIs, services]
+- External: [APIs, services, libraries]
 - Internal: [Other features, beads]
 
 ## Estimation
@@ -189,203 +228,207 @@ Nice-to-have (P2):
 | ---------- | ----------- | ----------------- |
 | [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] |
+| Risk     | Likelihood | Impact | Mitigation      |
+| -------- | ---------- | ------ | --------------- |
+| [Risk 1] | Medium     | High   | [How to handle] |
 
 ## Out of Scope
 
-Explicitly NOT included in this feature:
-
 - [Thing 1]
 - [Thing 2]
 
 ## Success Metrics
 
-How we'll measure success:
-
 - [ ] [Metric 1]: [Target]
 - [ ] [Metric 2]: [Target]
-
-## Open Questions
-
-- [ ] [Question that needs answering]
-- [ ] [Question that needs answering]
 ```
 
 ---
 
-## Phase 5: Validate Specification
+## Phase 5: Create Task Breakdown
 
-Before proceeding to plan, validate spec completeness:
+Decompose epic into tasks, tasks into subtasks.
 
-```
-Spec Validation
-━━━━━━━━━━━━━━━
+### Decomposition Rules
 
-✓ Problem statement clear
-✓ User stories defined
-✓ Acceptance criteria measurable
-⚠ Technical design incomplete - missing API details
-✓ Estimation provided
-✓ Risks identified
-⚠ Open questions remain (2 items)
+| Signal                                        | Create Separate Task |
+| --------------------------------------------- | -------------------- |
+| Different domain (frontend vs backend)        | Yes                  |
+| Natural phase boundary                        | Yes                  |
+| Could be done in parallel by different agents | Yes                  |
+| Strong dependency chain                       | Yes, with blockers   |
+| Same file, same concern                       | No - keep together   |
 
-Validation: PASS with warnings
+### Task Creation with Dependencies
 
-Proceed to plan? (yes/fix-warnings/cancel)
+```bash
+# Phase 1: Foundation (no blockers - starts immediately)
+bd create "Setup database schema" -t task -p 2
+# Returns: bd-xxx1
+
+# Phase 2: Core (blocked by Phase 1)
+bd create "Implement core API endpoints" -t task -p 2
+bd dep add bd-xxx2 bd-xxx1 --type blocks
+# Returns: bd-xxx2
+
+# Phase 3: Frontend (blocked by Phase 2)
+bd create "Build UI components" -t task -p 2
+bd dep add bd-xxx3 bd-xxx2 --type blocks
+# Returns: bd-xxx3
+
+# Phase 4: Integration (blocked by Phase 3)
+bd create "Integration and E2E tests" -t task -p 2
+bd dep add bd-xxx4 bd-xxx3 --type blocks
+# Returns: bd-xxx4
+
+# Link all tasks to epic
+bd dep add bd-xxx1 [epic-id]
+bd dep add bd-xxx2 [epic-id]
+bd dep add bd-xxx3 [epic-id]
+bd dep add bd-xxx4 [epic-id]
 ```
 
----
-
-## Phase 6: Create Implementation Plan
+### Subtask Creation (for complex tasks)
 
-Create `.beads/artifacts/[bead-id]/plan.md`:
+```bash
+# For Task 2 (API endpoints), create subtasks:
+bd create "POST /api/users endpoint" -t subtask -p 2
+bd dep add bd-xxx2.1 bd-xxx2
 
-```markdown
-# [Feature Name] Implementation Plan
+bd create "GET /api/users/:id endpoint" -t subtask -p 2
+bd dep add bd-xxx2.2 bd-xxx2
+bd dep add bd-xxx2.2 bd-xxx2.1 --type blocks  # Sequential if needed
+```
 
-## Overview
+### Verify Hierarchy
 
-**Epic:** [bead-id]
-**Estimated effort:** [X-Y hours]
-**Target completion:** [Date or sprint]
+```bash
+bd dep tree [epic-id]
+```
 
-## Phase 1: Foundation [S]
+Expected output:
 
-**Estimate:** 2-4 hours
-**Assignee:** [role or @mention]
+```
+bd-epic: [Feature Name]
+├── bd-xxx1: Setup database schema ← READY
+├── bd-xxx2: Implement core API (blocked by bd-xxx1)
+│   ├── bd-xxx2.1: POST /api/users
+│   └── bd-xxx2.2: GET /api/users/:id (blocked by bd-xxx2.1)
+├── bd-xxx3: Build UI components (blocked by bd-xxx2)
+└── bd-xxx4: Integration tests (blocked by bd-xxx3)
+```
 
-Tasks:
+---
 
-1. [ ] Set up database schema
-2. [ ] Create base API types
+## Phase 6: Create Implementation Plan
 
-**Exit criteria:** Database migrated, types compile
+Write `.beads/artifacts/[bead-id]/plan.md`:
 
-## Phase 2: Core Implementation [M]
+```markdown
+# [Feature Name] Implementation Plan
 
-**Estimate:** 4-8 hours
-**Depends on:** Phase 1
+**Epic:** [bead-id]
+**Estimated effort:** [X-Y hours total]
+**Approach:** [Selected from brainstorming]
 
-Tasks:
+## Task 1: [Title] [S/M]
 
-1. [ ] Implement [core feature]
-2. [ ] Add business logic
-3. [ ] Connect to existing systems
+**Bead:** bd-xxx1
+**Estimate:** 2-4 hours
+**Blocked by:** None (start immediately)
 
-**Exit criteria:** Core functionality works in isolation
+Work:
 
-## Phase 3: Integration [M]
+- [ ] [Specific task]
+- [ ] [Specific task]
 
-**Estimate:** 4-8 hours
-**Depends on:** Phase 2
+Verify: `[command to verify]`
 
-Tasks:
+---
 
-1. [ ] Integrate with [system]
-2. [ ] Add error handling
-3. [ ] Implement edge cases
+## Task 2: [Title] [M]
 
-**Exit criteria:** Feature works end-to-end
+**Bead:** bd-xxx2  
+**Estimate:** 4-6 hours
+**Blocked by:** Task 1
 
-## Phase 4: Testing & Polish [S]
+Subtasks:
 
-**Estimate:** 2-4 hours
-**Depends on:** Phase 3
+- bd-xxx2.1: [Subtask title]
+- bd-xxx2.2: [Subtask title]
 
-Tasks:
+Work:
 
-1. [ ] Write unit tests
-2. [ ] Write integration tests
-3. [ ] Manual testing
-4. [ ] Fix bugs found
+- [ ] [Specific task]
 
-**Exit criteria:** Tests pass, no critical bugs
+Verify: `[command to verify]`
 
-## Testing Strategy
+---
 
-| Type        | Coverage      | Focus                |
-| ----------- | ------------- | -------------------- |
-| Unit        | Core logic    | [specific modules]   |
-| Integration | API endpoints | [specific endpoints] |
-| E2E         | Critical path | [user flow]          |
+[Continue for all tasks...]
 
-## Rollout Plan
+## Verification Checklist
 
-1. [ ] Deploy to staging
-2. [ ] QA verification
-3. [ ] Deploy to production (feature flag)
-4. [ ] Monitor metrics
-5. [ ] Gradual rollout (10% → 50% → 100%)
+- [ ] All acceptance criteria met
+- [ ] Tests pass: `npm test`
+- [ ] Types check: `npm run typecheck`
+- [ ] Lint clean: `npm run lint`
 
 ## Rollback Plan
 
 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
+1. [Step 1]
+2. [Step 2]
 ```
 
 ---
 
-## Phase 7: Create Sub-Task Beads
+## Phase 7: Worktree Setup (if --worktree)
+
+For epic-level work, create an isolated workspace:
 
-Break phases into individual trackable beads:
+```typescript
+skill({ name: "using-git-worktrees" });
+```
 
 ```bash
-# Phase 1 tasks
-bd create "Set up database schema for [feature]" -t task -p 2
-bd dep add <task-id> <epic-id>
+# Ensure .gitignore has worktree directory
+grep -q "^\.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
 
-# Phase 2 tasks (with dependency)
-bd create "Implement [core feature]" -t task -p 2
-bd dep add <task-id> <epic-id>
-bd dep add <task-id> <phase-1-bead-id>
+# Create worktree for the epic
+git worktree add .worktrees/[epic-id] -b feature/[feature-name]
 
-# Continue for all phases...
+# Setup in worktree
+cd .worktrees/[epic-id]
+npm install  # or appropriate setup
+
+# Verify clean baseline
+npm test
 ```
 
+**Worktree + Beads Integration:**
+
+- `.beads/` database is shared (main repo)
+- All `bd` commands work normally
+- Commits go to the feature branch
+- Merge back to main when epic complete
+
 ---
 
-## Phase 8: Create Branch (if --branch)
+## Phase 8: Sync and Report
 
 ```bash
-# Create feature branch
-git checkout -b feature/[feature-name]
-
-# Or with bead ID
-git checkout -b feature/[bead-id]-[feature-name]
+bd sync
 ```
 
----
-
-## Output
+**Output:**
 
 ```
 Feature Created: [Feature Name]
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Epic: [bead-id]
 Priority: P[X]
@@ -395,50 +438,48 @@ 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
+Hierarchy:
+├── [task-id-1]: [Title] [S] ← READY
+├── [task-id-2]: [Title] [M] → blocked by task-1
+│   ├── [subtask-2.1]: [Title]
+│   └── [subtask-2.2]: [Title]
+├── [task-id-3]: [Title] [M] → blocked by task-2
+└── [task-id-4]: [Title] [S] → blocked by task-3
 
-Branch: feature/[feature-name] (if --branch)
+Workspace: [main | worktree: .worktrees/[epic-id]]
 
 Next Steps:
-├── View feature: bd show [bead-id]
-├── Start first task: /implement [task-id-1]
-└── View ready work: bd list --status ready
+├── Start first task: /start [task-id-1]
+├── View ready work: bd ready
+└── View full tree: bd dep tree [epic-id]
 ```
 
 ---
 
 ## Quick Mode (--quick)
 
-Skip brainstorming, use minimal spec:
+Skip brainstorming, minimal spec:
 
 - No discovery questions
-- Minimal spec template
-- Single-phase plan
-- No sub-task breakdown
+- Single-paragraph spec
+- Flat task list (no subtasks)
+- No worktree
 
 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       |
+## Subagent Delegation Summary
 
-**Confidence levels:**
+| Phase              | Subagent   | Purpose                    |
+| ------------------ | ---------- | -------------------------- |
+| Context gathering  | `@explore` | Find codebase patterns     |
+| Context gathering  | `@scout`   | Research best practices    |
+| Brainstorming      | None       | Interactive with user      |
+| Spec/Plan creation | None       | Planner writes artifacts   |
+| Implementation     | `@build`   | `/start` then `/implement` |
 
-- **High**: Done this before, clear path
-- **Medium**: Some unknowns, general approach clear
-- **Low**: Significant unknowns, may need spikes
+**Key Rule:** Planner creates structure, Build executes work. Subagents research, leaders act.
 
 ---
 
@@ -446,8 +487,8 @@ Use for: Small features, bug fixes, well-understood work.
 
 | 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>` |
+| Start first task     | `/start <task-id>`          |
+| View feature status  | `bd dep tree <epic-id>`     |
+| Import external plan | `/import-plan`              |
+| Complete feature     | `/finish <epic-id>`         |
+| Abandon feature      | `/revert-feature <epic-id>` |