workflow-interactive

name	workflow-interactive
description	Development workflow for implementation tasks. Use when: implementing features, fixing bugs, creating components, writing routes, integrating APIs, or any task that involves writing production code. Provides the standard TDD-first development cycle with code review and validation steps. Do NOT use for research, documentation-only, or planning-only tasks.

Interactive Development Workflow

Standard development workflow for human-in-the-loop implementation tasks. Follow these steps sequentially. Each step MUST complete before proceeding.

---

Mode Selection (Auto-Detect)

After Phase 1 planning, auto-detect execution mode based on task scope:

Criteria	Mode	Description
1-3 files, single feature	Sequential	Main agent handles all phases directly
4-10 files, 2-3 features	Delegated	Supervisor pattern with worker agents
10+ files, complex features	Team	Use /workflow-team instead

Mode Detection Algorithm:
1. Count files to be modified from plan
2. Count distinct features/components
3. IF files <= 3 AND features == 1:
     → Sequential Mode
   ELSE IF files <= 10:
     → Delegated Mode (Supervisor)
   ELSE:
     → Recommend /workflow-team

User Override: User can explicitly request mode: "use sequential mode" or "use delegated mode"

---

Phase 1: Plan (Both Modes)

Step	Action
1	Enter PlanMode
2	Analyze current state thoroughly
3	Create detailed step-by-step plan
4	Count files and features → determine execution mode
5	Exit PlanMode → wait for plan approval

After plan approval, create tasks via TaskCreate and execute immediately. No separate confirmation needed.

---

Phase 2: TDD (after user approval)

Git Setup (Both Modes)

Step	Action
6	Fetch latest and switch to development branch: git fetch origin development && git checkout development && git pull origin development (create if not exists)
7	Create feature branch from development

Sequential Mode (Small Tasks: 1-3 files)

Step	Action
8	Run unit-test-writer sub-agent → verify tests FAIL (Red Phase). NEVER analyze patterns or write test code yourself — always delegate to the unit-test-writer subagent.
9	Implement code to pass tests → run the project's test command (see CLAUDE.md Commands) → verify ALL pass (Green Phase)

Auto-verify (no human wait needed):

• After Step 8: If tests pass immediately → review test logic, likely not testing correctly
• After Step 9: If any test fails → fix implementation before proceeding

Delegated Mode (Medium Tasks: 4-10 files)

Step	Action
8	Spawn task-executor worker agent with task context
9	Supervisor waits — do NOT implement yourself
10	Receive summary from task-executor
11	Verify summary: Status=Success, Coverage>=90%

Supervisor Context During Delegation:
- Store only: task ID, file list, expected outcomes
- Do NOT read test code or implementation details
- Wait for worker summary

💡 Context tip: Consider /clear here. Plan context is no longer needed.

Commit: Per workflow-commits.md — Red/Green phase

---

Phase 3: Review

Sequential Mode

Step	Action
10	Run code-reviewer sub-agent (unified: quality + security + performance)
11	Read report in /docs/reports/code-review/ → fix ALL issues where status ≠ "complete"

Delegated Mode

Step	Action
12	Spawn quality-gate worker agent with changed files list
13	Supervisor waits — do NOT review yourself
14	Receive pass/fail summary from quality-gate
15	IF Status=FAIL: Spawn task-executor to fix blocking issues
16	IF Status=PASS: Proceed to Phase 4

Quality Gate Loop:
WHILE quality-gate returns FAIL:
  1. Extract blocking issues from summary
  2. Spawn task-executor with fix instructions
  3. Re-run quality-gate
  4. Max 3 iterations, then escalate to user

Commit: Per workflow-commits.md — Review phase

💡 Context tip: Consider /clear here. Review details are no longer needed.

---

Phase 4: Validate & Finalize

Sequential Mode

Step	Action
12	Run e2e-tester sub-agent
13	Fix bugs discovered in E2E (skip if all pass)
14	Run development-planner sub-agent
15	Merge feature branch to development

Delegated Mode

Step	Action
17	E2E already run by quality-gate — check summary
18	IF E2E failed: Spawn task-executor for fixes, re-run quality-gate
19	Run development-planner sub-agent (Supervisor handles directly)
20	Merge feature branch to development

Commit: Per workflow-commits.md — E2E fix phase (if needed)

---

Failure Recovery

IF any step fails:
  1. Log failure to docs/reports/failures/{timestamp}-{step}.md
  2. Retry SAME approach (1 attempt)
  3. Retry DIFFERENT approach (1 attempt)
  4. After 3 total failures → STOP, report to user, WAIT for instruction

---

Context Management

• /clear after Phase 2 (TDD complete): plan + test exploration no longer needed
• /clear after Phase 3 (review complete): review reports no longer needed
• Target: stay under 60k tokens per phase
• If unsure: /context to check usage

Context Limit Warning Protocol

IF context exceeds 80k tokens before Phase completion:
  1. Summarize current progress to user (completed steps, pending steps)
  2. Recommend `/clear` with checkpoint description
  3. Provide resume instructions:
     - Current phase and step number
     - Files modified so far
     - Next action to take
  4. After `/clear`, resume from checkpoint

Checkpoint Template

## Checkpoint Summary
- **Phase**: [1-4] - [Phase Name]
- **Last Completed Step**: [Step Number]
- **Files Modified**: [List]
- **Next Action**: [Description]
- **Blockers**: [If any]

---

Supervisor Pattern Architecture (Delegated Mode)

┌─────────────────────────────────────────────────────────────┐
│                 Supervisor (Main Agent)                      │
│  • Orchestration only — minimal context                     │
│  • Stores: task IDs, file lists, worker summaries           │
│  • Does NOT: read code, write tests, review details         │
└─────────────────────────────────────────────────────────────┘
                    │                           │
         ┌──────────┴──────────┐     ┌──────────┴──────────┐
         ▼                     ▼     ▼                     ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  task-executor  │     │  quality-gate   │     │ development-    │
│    (Sonnet)     │     │    (Sonnet)     │     │    planner      │
├─────────────────┤     ├─────────────────┤     │   (Opus)        │
│ • TDD cycle     │     │ • Code review   │     └─────────────────┘
│ • Red → Green   │     │ • E2E tests     │
│ • Commits       │     │ • Pass/Fail     │
└────────┬────────┘     └────────┬────────┘
         │                       │
         ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│ unit-test-writer│     │  code-reviewer  │
│    (Sonnet)     │     │    (Sonnet)     │
└─────────────────┘     ├─────────────────┤
                        │   e2e-tester    │
                        │    (Sonnet)     │
                        └─────────────────┘

Benefits of Delegated Mode

Aspect	Sequential	Delegated
Context usage	All in main	Distributed
Cost	Higher (Opus all)	Lower (Sonnet workers)
Parallelization	None	Workers can overlap
Recovery	Manual	Auto-retry via workers
Scalability	Limited	Extensible

When to Use Each Mode

Scenario	Recommended Mode
Quick bug fix (1-2 files)	Sequential
New component (3-5 files)	Delegated
Feature with multiple components	Delegated
Cross-cutting refactor (10+ files)	/workflow-team
Exploration / research	Sequential (no workers)