| name | executing-tasks |
| description | Executes structured tasks from docs/tasks/ with phase-by-phase workflow. Use when user says "execute task", "run task", or provides task path. Reads CONTEXT.md for state, delegates phases to developer-agent, updates progress automatically. |
Executing Tasks
Contents
Execution Flow
1. Load task (README.md + CONTEXT.md)
2. Identify current phase from CONTEXT.md
3. If starting Phase 01: Run `make up APP={app}` first
4. For each incomplete phase:
a. Update README → In progress
b. Delegate to developer-agent
c. Validate result
d. Update README → Complete
e. Update CONTEXT.md
f. Continue immediately (no pausing)
5. Final summary
Key rules:
- Developer-agent handles: implementation, tests, commits
- Orchestrator handles: status updates, CONTEXT.md, continuation
- Phase 01 only: Run
make up APP={app} before delegating
- Never pause between phases unless blocked
- Be concise (~3-4 lines output per phase)
Phase Execution Checklist
Copy and track for each phase:
Phase 01 (first phase only):
- [ ] Run `make up APP={app}` to ensure containers are running
- [ ] Read phase file
- [ ] Update README.md → In progress
- [ ] Delegate to developer-agent
- [ ] Check result (tests passed?)
- [ ] Verify commit: feat({task}): Phase 01 - {Title}
- [ ] Update README.md → Complete
- [ ] Update CONTEXT.md
- [ ] Continue to next phase
Phase {N} (subsequent phases):
- [ ] Read phase file
- [ ] Update README.md → In progress
- [ ] Delegate to developer-agent
- [ ] Check result (tests passed?)
- [ ] Verify commit: feat({task}): Phase 0{N} - {Title}
- [ ] Update README.md → Complete
- [ ] Update CONTEXT.md
- [ ] Continue to next phase
Orchestrator vs Developer-Agent
| Responsibility | Who |
|---|
| Load task, track status | Orchestrator |
Run make up APP=... (Phase 01) | Orchestrator |
| Update README.md status | Orchestrator |
| Update CONTEXT.md | Orchestrator |
| Read phase instructions | Developer-agent |
| Implement code changes | Developer-agent |
Run make test APP=... | Developer-agent |
| Create commits | Developer-agent |
| Return summary | Developer-agent |
Developer-Agent Delegation
Use Task tool with subagent_type: "general-purpose":
**TASK:** docs/tasks/{task-name}/
**PHASE:** {N} - {phase-name}
**READ:** docs/tasks/{task-name}/0{N}-{phase-name}.md
**REQUIRED SKILLS:** (from README.md)
- skill: core/critical-rules
- skill: {domain skill}
- skill: testing/pytest
**APP:** {app-name}
**DO:**
1. Follow phase file steps exactly
2. Run tests: `make test APP={app}`
3. **COMMIT (REQUIRED):** `feat({task-name}): Phase 0{N} - {Phase Title}`
**RETURN:**
- Files changed (paths)
- Tests: Passing/Failed (count)
- Commit: {short hash} (MUST have commit)
- Success criteria: Met/Not met
See delegation.md for full format.
Testing-Polish Phases
Phases with Type: testing-polish are handled differently - they use testing-polish-agent instead of developer-agent.
Detection
A phase is testing-polish if:
- Has
**Type:** testing-polish in the file
- OR title contains "Testing" + "Polish"
Agent Selection
Read phase file
│
▼
Has "Type: testing-polish"? ──YES──► Use testing-polish-agent
│
NO
│
▼
Use developer-agent (default)
Different Handling
| Aspect | developer-agent | testing-polish-agent |
|---|
| Focus | Build features | Verify & fix |
| Main tools | Code editors, make test | Playwright |
| Commit prefix | feat({task}) | fix({task}) |
| Success | Tests pass | Scenarios pass OR documented |
| Agent file | .claude/agents/developer-agent.md | .claude/agents/testing-polish-agent.md |
Testing-Polish Delegation
Use Task tool with subagent_type: "general-purpose":
**TASK:** docs/tasks/{task-name}/
**PHASE:** {N} - Testing & Polish
**TYPE:** testing-polish
**AGENT:** Read and follow `.claude/agents/testing-polish-agent.md`
**READ:**
1. `.claude/agents/testing-polish-agent.md` (agent behavior)
2. `docs/tasks/{task-name}/0{N}-testing-polish.md` (test scenarios)
3. `.claude/shared/playwright-testing.md` (Playwright commands)
**APP:** {app-name}
**KEY BEHAVIOR:**
You are a FIXER, not just a tester.
- Execute test scenarios via Playwright
- If fail → diagnose → fix code → retest
- Repeat until passing (max 3 attempts per scenario)
- After 3 failures → document in KNOWN_ISSUES.md, continue
**COMMIT (if fixes made):**
fix({task-name}): Phase 0{N} - {brief fix summary}
**RETURN:**
- Scenarios: {passed}/{total}
- Fixed: {list of what was fixed}
- Known Issues: {count} (if any)
- Commit: {hash} (if fixes made)
Testing-Polish Checklist
Testing-Polish Phase:
- [ ] Detect phase type (look for "Type: testing-polish")
- [ ] Verify Playwright: curl http://localhost:9876/health
- [ ] Update README.md → In progress
- [ ] Delegate to testing-polish-agent (see prompt above)
- [ ] Check result (scenarios passed?)
- [ ] If fixes made: verify commit with fix() prefix
- [ ] Update README.md → Complete
- [ ] Update CONTEXT.md
- [ ] Continue to next phase
Output Format (Testing-Polish)
Phase {N}: Testing & Polish
Delegating to testing-polish-agent...
Complete - Scenarios: {pass}/{total} | Fixed: {count} | Known Issues: {count}
CONTEXT.md Protocol
On Task Load
- Read
CONTEXT.md first
- Check current phase and status
- Resume from documented state
After Each Phase
Update CONTEXT.md with:
**Last Updated:** {now}
**Current Phase:** {N+1}
## Files Modified
- `{new files from this phase}`
## Next Steps
1. {What phase N+1 will do}
On Blockers
**Status:** Blocked
## Blockers
- {Description of blocker}
## Open Questions
- [ ] {Question for user}
Before Session End
Always update CONTEXT.md with current state to preserve context.
Output Format
Per phase (concise):
Phase {N}: {name}
Delegating to developer-agent...
Complete - Files: {count} | Tests: {pass}/{total} | Commit: {hash}
Final summary:
Task Complete: {task-name}
Phases: {N} executed
Commits: {M} created
Tests: All passing ({count})
Location: docs/tasks/{task-name}/
Error Handling
| Situation | Action |
|---|
| Tests fail | Show output, attempt fix, retry once |
| Success criteria not met | List failures, ask user |
| Agent reports blocker | Update CONTEXT.md, ask user |
| Phase file missing | Skip or ask user |
See error-handling.md for details.
Resuming Interrupted Tasks
- Read CONTEXT.md
- Find current phase and status
- Confirm with user: "Resuming from Phase {N}. Proceed?"
- Continue execution flow
References
