Skip to content

Commit 2dabfd2

Browse files
wahaniwahani
committed
Improve implementation command
1 parent bcc2d3e commit 2dabfd2

1 file changed

Lines changed: 131 additions & 111 deletions

File tree

‎.opencode/commands/create-implementation.md‎

Lines changed: 131 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,181 @@
11
---
2-
description: Execute active-plan.md by creating todos and implementing step-by-step
2+
description: Execute active-plan.md by delegating cycles to sub-agents with interruptible state tracking
33
agent: build
44
---
55

6-
You will execute the implementation plan in `.planning/active-plan.md` one step at a time, using opencode's todo system to track progress.
6+
You will execute the implementation plan in `.planning/active-plan.md` by delegating each cycle to a sub-agent. The main agent only tracks cycle-level progress, enabling interruption and resumption at any time.
77

88
**Input:**
99
Implementation plan from `.planning/active-plan.md`
1010

11+
**Architecture:**
12+
- **Main Agent (Orchestrator)**: Manages cycle-level todos, delegates implementation to sub-agents, syncs state to disk
13+
- **Sub-Agent (Implementer)**: Executes all tasks within a single cycle (STUB/TEST/IMPLEMENT/VERIFY/REFACTOR)
14+
1115
**Action:**
1216

13-
1. **Parse the Plan**
17+
1. **Parse the Plan and Restore State**
1418
- Read `.planning/active-plan.md`
1519
- Read `.planning/tech-spec.md` for implementation details
16-
- Identify all cycles and their tasks
20+
- Check which cycles are already marked `[x]` complete in active-plan.md
21+
- Identify remaining cycles that need implementation
1722

18-
2. **Create Todo List**
23+
2. **Create/Restore Cycle-Level Todo List**
1924

20-
Parse the plan structure and create todos using the `todowrite` tool. Each checkbox item becomes a todo task:
25+
Create todos ONLY for cycles (not individual tasks). Use the `todowrite` tool:
2126

22-
**For TDD Plans (New Features):**
2327
```
24-
Cycle 1: [Feature Name]
25-
- STUB: Create function signature
26-
- TEST: Write failing test
27-
- VERIFY FAIL: Run tests (expect failure)
28-
- IMPLEMENT: Replace stub with real logic
29-
- VERIFY PASS: Run tests (expect pass)
30-
- REFACTOR: Clean up code
31-
- VERIFY PASS: Run tests (expect pass)
28+
- Cycle 1: [Feature Name] (completed/pending/in_progress)
29+
- Cycle 2: [Feature Name] (pending)
30+
- Cycle 3: [Feature Name] (pending)
3231
```
3332

34-
**For Bugfix Plans (Red-Green-Refactor):**
35-
```
36-
Cycle 1: [Bug Fix Name]
37-
- RED: Write failing test that demonstrates bug
38-
- VERIFY FAIL: Run tests (confirm bug exists)
39-
- GREEN: Fix the bug
40-
- VERIFY PASS: Run tests (bug fixed)
41-
- REFACTOR: Clean up if needed
42-
- VERIFY PASS: Run tests (still passing)
43-
```
33+
If resuming after interruption:
34+
- Mark already-completed cycles (from active-plan.md checkboxes) as `completed`
35+
- Mark current cycle as `in_progress` if partially done
36+
- Remaining cycles as `pending`
4437

45-
3. **Execute Tasks Sequentially**
38+
3. **Execute Cycles via Sub-Agents**
4639

47-
For each todo task (in order):
40+
For each incomplete cycle, in order:
4841

49-
**STUB Tasks:**
50-
- Check if target file exists
51-
- Create file if missing, or read and update if exists
52-
- Add function signature with dummy return value (e.g., `return null`, `return true`)
53-
- Do NOT implement real logic yet
42+
**a. Mark Cycle In Progress**
43+
- Update todo: `pending` → `in_progress`
5444

55-
**TEST Tasks:**
56-
- Check if test file exists (create if missing)
57-
- Import the function/module being tested
58-
- Write test case that asserts the *real* expected behavior
59-
- Test should be specific and match tech-spec requirements
45+
**b. Delegate to Sub-Agent**
6046

61-
**RED Tasks (for Bugfixes):**
62-
- Write a test that demonstrates the current buggy behavior
63-
- The test should fail, proving the bug exists
47+
Use the `task` tool to launch a `general` sub-agent with this prompt structure:
6448

65-
**VERIFY FAIL Tasks:**
66-
- Run the test command from `AGENTS.md` (usually `npm run test:unit`)
67-
- **Expected**: Test FAILS (non-zero exit code)
68-
- **If passes**: STOP - the test is broken (false positive). Ask user for help.
49+
```
50+
Execute Cycle [N]: [Cycle Name] from .planning/active-plan.md
51+
52+
Read the cycle tasks from .planning/active-plan.md and execute them in order:
6953
70-
**IMPLEMENT Tasks:**
71-
- Read the failing test output to understand what's needed
72-
- Replace stub/buggy code with real implementation
73-
- Follow the approach described in `tech-spec.md`
54+
Tasks for this cycle:
55+
[List the specific tasks for this cycle from active-plan.md]
7456
75-
**GREEN Tasks (for Bugfixes):**
76-
- Fix the bug in the identified file/section
77-
- Follow the fix approach from `tech-spec.md`
57+
Execute each task:
58+
- STUB: Add function signature with dummy return
59+
- TEST: Write failing test matching tech-spec
60+
- VERIFY FAIL: Run tests (must fail)
61+
- IMPLEMENT: Replace stub with real logic per tech-spec.md
62+
- VERIFY PASS: Run tests (must pass)
63+
- REFACTOR: Clean up code (no behavior change)
64+
- VERIFY PASS: Run tests (must pass)
7865
79-
**VERIFY PASS Tasks:**
80-
- Run the test command from `AGENTS.md`
81-
- **Expected**: Test PASSES (exit code 0)
82-
- **If fails**: Debug and retry (up to 3 attempts), then ask for help
66+
Rules:
67+
- Follow test command from AGENTS.md (npm run test:unit)
68+
- Run lint/typecheck after implementation if specified in AGENTS.md
69+
- Do NOT modify tech-spec.md or story.md
70+
- Return SUCCESS when all cycle tasks complete, or FAILURE with error details
71+
```
8372

84-
**REFACTOR Tasks:**
85-
- Improve code for readability, performance, or maintainability
86-
- Do NOT change behavior
87-
- Focus on: naming, structure, removing duplication
73+
**c. Handle Sub-Agent Result**
8874

89-
4. **Progress Tracking**
75+
- **SUCCESS**:
76+
- Update todo: `in_progress` → `completed`
77+
- Sync to active-plan.md: Mark cycle checkbox as `[x]`
78+
- Report completion to user
79+
- Continue to next cycle
9080

91-
- Update todo status as you work:
92-
- `pending` → `in_progress` (when starting a task)
93-
- `in_progress` → `completed` (when task succeeds)
94-
- After completing a task, move to the next one
95-
- After completing a full cycle, report progress to user
81+
- **FAILURE**:
82+
- Keep cycle as `in_progress`
83+
- Report error to user
84+
- Ask user for guidance before retrying
85+
86+
**d. Sync State After Each Cycle**
87+
88+
After sub-agent completes successfully:
89+
1. Update active-plan.md checkbox: `- [ ]` → `- [x]`
90+
2. Update opencode todo list: cycle marked `completed`
91+
3. Report: "Cycle [N] complete. State synced."
9692

97-
5. **Cycle Boundaries**
93+
4. **Cycle Boundaries**
94+
95+
- **Within same session**: Continue to next cycle automatically
96+
- **After interruption**: Parse active-plan.md to find last completed cycle, resume from next
97+
- **User pause request**: Complete current cycle first, then stop (state is preserved)
98+
99+
5. **Interruption and Resumption**
100+
101+
This architecture enables clean resumption:
98102

99-
- If next task is in the **same cycle**: Continue automatically
100-
- If next task starts a **new cycle**:
101-
- Report completion of current cycle
102-
- Ask user: "Cycle [N] complete. Continue with next cycle?"
103+
```
104+
Session 1:
105+
→ Cycle 1: completed, synced to disk
106+
→ Cycle 2: completed, synced to disk
107+
→ Cycle 3: in_progress when interrupted
108+
109+
Session 2 (resumption):
110+
→ Parse active-plan.md: Cycles 1-2 marked [x]
111+
→ Create todos: Cycles 1-2 completed, Cycle 3 in_progress
112+
→ Re-delegate Cycle 3 to sub-agent
113+
→ Continue from there
114+
```
103115

104116
**Error Handling:**
105117

106118
- **No active-plan.md**: Report "No implementation plan found. Run `/create-active-plan` first."
107-
- **All tasks complete**: Report "All tasks in active-plan are complete!"
108-
- **Test unexpectedly passes** (VERIFY FAIL): STOP and ask user - test may be wrong
109-
- **Test fails 3 times** (VERIFY PASS): STOP and ask user for help
110-
- **Missing tech spec**: STOP - do not guess signatures, ask user
119+
- **All cycles complete**: Report "All cycles in active-plan are complete!"
120+
- **Sub-agent failure**: Report error, ask user for guidance
121+
- **Missing tech spec**: STOP - sub-agent cannot proceed without specifications
111122

112123
**Important Rules:**
113124

114-
- **NEVER** modify `tech-spec.md` or `story.md`
115-
- **Only** modify source code, test files, and files listed in tech-spec
116-
- **Always** run lint/typecheck after implementation if specified in AGENTS.md
117-
- **Follow** the exact test command from AGENTS.md (e.g., `npm run test:unit`)
125+
- **Main agent**: Only manages cycles, delegates all implementation to sub-agents
126+
- **Sub-agents**: Do all STUB/TEST/IMPLEMENT/VERIFY/REFACTOR work
127+
- **State sync**: After each cycle, update both active-plan.md AND todo list
128+
- **Never skip sync**: Always sync state before moving to next cycle
129+
- **Resumability**: Any session can resume by reading active-plan.md checkboxes
118130

119131
**Example Workflow:**
120132

121133
```
122134
→ Reading active-plan.md...
123-
→ Found 2 cycles with 14 total tasks
124-
→ Creating todo list...
125-
126-
✓ Cycle 1: getMultilineStatementRange
127-
[ ] STUB: Add function signature
128-
[ ] TEST: Write unit tests
129-
[ ] VERIFY FAIL: Run tests
130-
[ ] IMPLEMENT: Bracket balancing logic
131-
[ ] VERIFY PASS: Run tests
132-
[ ] REFACTOR: Clean up
133-
[ ] VERIFY PASS: Run tests
134-
135-
✓ Cycle 2: smartSelect Integration
136-
[ ] STUB: Call getMultilineStatementRange
137-
[ ] TEST: Write integration tests
138-
...
139-
140-
→ Starting Cycle 1, Task 1: STUB
141-
[in_progress] STUB: Add function signature
142-
→ Reading src/smartExecute/selection.ts...
143-
→ Adding function signature with dummy return...
144-
[completed] STUB: Add function signature
135+
→ Found 3 cycles, 2 already complete
136+
→ Restoring todo state...
137+
138+
[x] Cycle 1: getMultilineStatementRange (completed)
139+
[x] Cycle 2: smartSelect Integration (completed)
140+
[ ] Cycle 3: Edge Cases (pending)
141+
142+
→ Starting Cycle 3...
143+
[in_progress] Cycle 3: Edge Cases
144+
145+
→ Delegating to sub-agent...
146+
→ Sub-agent executing: STUB, TEST, VERIFY FAIL, IMPLEMENT, VERIFY PASS, REFACTOR, VERIFY PASS
147+
→ Sub-agent reports: SUCCESS
145148
146-
→ Starting Cycle 1, Task 2: TEST
147-
[in_progress] TEST: Write unit tests
148-
→ Creating test file...
149-
→ Writing test cases...
150-
[completed] TEST: Write unit tests
149+
→ Syncing state...
150+
→ Updated active-plan.md: Cycle 3 marked [x]
151+
→ Updated todo list: Cycle 3 completed
151152
152-
→ Cycle 1 complete. Continue with next cycle?
153+
→ Cycle 3 complete. State synced.
154+
→ All cycles complete!
155+
```
156+
157+
**Resumption Example:**
158+
159+
```
160+
→ Reading active-plan.md...
161+
→ Cycle 1: [x] complete
162+
→ Cycle 2: [ ] incomplete (was in progress when interrupted)
163+
→ Cycle 3: [ ] pending
164+
165+
→ Creating todos from saved state...
166+
[x] Cycle 1: getMultilineStatementRange (completed)
167+
[ ] Cycle 2: smartSelect Integration (in_progress)
168+
[ ] Cycle 3: Edge Cases (pending)
169+
170+
→ Resuming Cycle 2...
171+
→ Delegating to sub-agent...
172+
→ Sub-agent executing remaining tasks...
153173
```
154174

155175
**Quality Checklist:**
156176
- [ ] active-plan.md parsed correctly
157-
- [ ] Todos created for all tasks
158-
- [ ] Test command matches AGENTS.md
159-
- [ ] Each task executed in order
160-
- [ ] Verify steps actually run tests
161-
- [ ] Progress tracked via todo status
177+
- [ ] Only cycle-level todos created (not task-level)
178+
- [ ] Sub-agent receives complete cycle context
179+
- [ ] State synced to active-plan.md after each cycle
180+
- [ ] State synced to todo list after each cycle
181+
- [ ] Resumption works from saved state

0 commit comments

Comments
 (0)