Executing Tasks

Executing Tasks

Contents

• Execution Flow
• Phase Execution Checklist
• Testing-Polish Phases
• CONTEXT.md Protocol
• Output Format
• References

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

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

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

1. Read CONTEXT.md first
2. Check current phase and status
3. 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

See error-handling.md for details.

Resuming Interrupted Tasks

1. Read CONTEXT.md
2. Find current phase and status
3. Confirm with user: "Resuming from Phase {N}. Proceed?"
4. Continue execution flow

References

• delegation.md - Full agent prompt format
• error-handling.md - Error cases
• validation.md - Success criteria checking
• testing-polish-agent.md - Testing & polish agent
• playwright-testing.md - Playwright commands reference

Converted and distributed by TomeVault — claim your Tome and manage your conversions.