flow

Flow - Unified Development Workflow

The single command for all development workflows. Handles the entire feature lifecycle from creation to merge.

Arguments: $ARGUMENTS

Overview

All workflows run through this single entry point with flags:

/claude-harness:flow "Add dark mode support"           # Standard workflow
/claude-harness:flow --autonomous                      # Batch process all features
/claude-harness:flow --plan-only "Big refactor"        # Plan only, implement later
/claude-harness:flow --team "Add user login"           # ATDD with Agent Team (3 teammates)

Lifecycle: Context -> Creation -> [Subagent Delegation] -> Planning -> Implementation -> Verification -> Checkpoint -> Merge -> [Result Processing]

Context Isolation: In standard mode, Phases 3-6 run inside an isolated subagent (via Task tool). The main context stays clean after feature completion -- no /clear needed between features.

ATDD Team Lifecycle (with --team): Context -> Creation (with Gherkin criteria) -> [Subagent Delegation] -> Planning -> Team Spawn -> Acceptance Tests (RED) -> Implementation (GREEN) -> Review -> Verify -> Checkpoint -> Merge

---

Effort Controls (Opus 4.6+)

Phase	Effort	Why
Context Compilation	low	Mechanical data loading
Feature Creation / Selection / Conflict Detection	low	Template-based, deterministic
Planning	max	Determines approach quality, avoids past failures
Implementation	high	Core coding, escalate to max on retry
Verification / Debug	max	Root-cause analysis needs deepest reasoning
Checkpoint / Merge	low	Mechanical operations
Subagent Delegation (autonomous)	low	Mechanical prompt assembly and result parsing

Adaptive Escalation (progressive on retries): Attempts 1-5: high. Attempts 6-10: max. Attempts 11-15: max + full procedural memory.

On models without effort controls, all phases run at default effort.

---

Phase 0.1: Argument Parsing

1. Parse arguments:

   • Empty: Show interactive menu for feature selection
   • Matches feature-\d+: Resume existing feature
   • Matches fix-feature-\d+-\d+: Resume existing fix
   • --fix <feature-id> "description": Create fix linked to feature
   • Otherwise: Create new feature from description

2. Parse options:

   • --no-merge: Skip merge phase (stop at checkpoint)
   • --quick: Implement directly without planning phase
   • --plan-only: Stop after Phase 3. Resume later with feature ID.
   • --autonomous: Outer loop -- iterate all active features
   • --team: Use Agent Teams for ATDD implementation (requires agentTeams.enabled in config.json)

3. Mode validation:

   • --autonomous: Compatible with --no-merge, --quick, and --team. Proceed to Autonomous Wrapper.
   • --plan-only: Proceeds through Phases 0-3 then STOPS. Incompatible with --team.
   • --team: Compatible with --autonomous, --no-merge. Incompatible with --quick and --plan-only.

---

Phase 0.2: Team Preflight (if --team)

Read ${CLAUDE_SKILL_DIR}/references/team-atdd.md for full Agent Teams ATDD details.

• Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var is set to 1
• If not set: display error with instructions to enable, then STOP
• Read .claude-harness/config.json agentTeams section: verify enabled is true
• Cache team config: defaultTeamSize, roles, requirePlanApproval, teammateModel

---

Autonomous Wrapper (if --autonomous)

When --autonomous is set, the flow operates as a lean orchestrator loop that iterates all active features. Each feature is executed in an isolated subagent context via the Task tool.

Read ${CLAUDE_SKILL_DIR}/references/autonomous-wrapper.md for the full autonomous orchestration phases (A.1 through A.7).

Context Isolation (All Modes)

Both standard and autonomous modes delegate feature implementation to a general-purpose subagent via the Task tool. This provides:

• Fresh context window: Each feature starts with zero accumulated context
• Clean token budget: No context waste from previous features
• Contained failures: A failing feature's debugging context does not pollute the next feature
• Memory continuity: Orchestrator persists memory updates between features
• Team containment: When --team is used, the Agent Team lifecycle is fully contained within the subagent
• No manual /clear needed: After feature completion, the main context is clean

Standard mode (Phase 2.5): Single feature delegated after creation. Autonomous mode (Phase A.4): Multiple features delegated in a loop.

---

Phase 1: Context Compilation (Auto-Start)

Read all memory layers IN PARALLEL for speed.

1. Set paths:

   • FEATURES_FILE=".claude-harness/features/active.json"
   • MEMORY_DIR=".claude-harness/memory/"
   • ARCHIVE_FILE=".claude-harness/features/archive.json"

2. Parse and cache GitHub repo (do this ONCE):

   REMOTE_URL=$(git remote get-url origin 2>/dev/null)
   

   Parse owner/repo from SSH or HTTPS URL. Store for reuse.

3. Read IN PARALLEL: failures.json, successes.json, decisions.json, rules.json, active.json

4. Compile working context to .claude-harness/sessions/{session-id}/context.json:

   {
     "version": 3, "computedAt": "{ISO}", "sessionId": "{session-id}",
     "github": { "owner": "{parsed}", "repo": "{parsed}" },
     "activeFeature": null,
     "relevantMemory": { "recentDecisions": [], "projectPatterns": [], "avoidApproaches": [], "learnedRules": [] }
   }
   

5. Display context summary: memory stats, GitHub info.

---

Phase 2: Feature Creation

Use cached GitHub owner/repo from Phase 1.

1. Generate feature ID: Read active.json, find highest ID, generate next feature-XXX.

2. Define acceptance criteria (ATDD -- always on):

   • If feature has existing acceptanceCriteria (from PRD breakdown): use those
   • Otherwise: generate Gherkin acceptance criteria from feature description
   • Format as structured Gherkin: { "scenario", "given", "when", "then" }
   • Aim for 2-5 scenarios covering: happy path, error cases, edge cases

3. Create GitHub Issue: mcp__github__create_issue with labels ["feature", "claude-harness", "flow"], body with Problem/Solution/Acceptance Criteria (Gherkin)/Verification. STOP if fails.

4. Create and checkout branch: mcp__github__create_branch, then git fetch origin && git checkout feature/feature-XXX.

5. Create feature entry in active.json: id, name, status "in_progress", acceptanceCriteria, github refs, verificationCommands, maxAttempts 15.

---

Phase 2.5: Context Isolation (Standard Mode)

Skip this phase if --plan-only or --autonomous.

After feature creation, delegate the remaining lifecycle to an isolated subagent for clean context. Read ${CLAUDE_SKILL_DIR}/references/implementation.md for the full subagent prompt format and result processing logic.

Summary:

1. Compile subagent prompt (feature entry, verification commands, memory, GitHub info, flags)
2. Delegate to Task tool with subagent_type="general-purpose"
3. Subagent runs Phases 3-6 autonomously in fresh context
4. Parse RESULT block from subagent response
5. Process result: archive on success, persist memory, clean up branches
6. Skip to Phase 7

---

Phase 3: Planning (unless --quick)

Note: In standard mode, this phase runs inside the delegated subagent. It only runs inline when --plan-only is set.

1. Query procedural memory (effort: max): Check past failures/successes. Warn if planned approach matches past failure.
2. Analyze requirements: Break down, identify files, calculate impact.
3. Generate plan: Store in feature entry or session context.

---

Phase 3.5: Create Task Breakdown

Uses Claude Code's native Tasks for visual progress tracking.

• Create task chain (6 tasks): Research -> Plan -> Implement -> Verify -> Accept -> Checkpoint
• Each blocked by previous. Store IDs in loop-state.
• Mark Task 1 as in_progress.

---

Phase 3.7: Team Roster (if --team)

Read ${CLAUDE_SKILL_DIR}/references/team-atdd.md for full team roster and ATDD spawn prompts.

Summary: Prepare team structure with tester, implementer, reviewer roles. Prepare ATDD spawn prompts for each role.

---

Phase 3.8: Plan-Only Gate (if --plan-only)

If --plan-only: display plan summary (feature ID, issue, branch) with resume command and EXIT.

---

Phase 4: Implementation

Read ${CLAUDE_SKILL_DIR}/references/implementation.md for full implementation details including loop state schema, standard vs team implementation, and verification.

Standard (no --team):

1. Branch verification: STOP if on main/master
2. Initialize loop state (canonical Loop-State Schema v9)
3. Implement feature following ATDD: acceptance tests first (RED), implement to pass (GREEN), refactor
4. Run verification commands after implementation
5. On failure: record to failures.json, increment attempts, retry with escalation

Team (--team):

Read ${CLAUDE_SKILL_DIR}/references/team-atdd.md for full ATDD team implementation including team creation, monitoring, shutdown gate, and cleanup.

Phase 4.1: Verification and Memory Updates

• Fail: append to failures.json, increment attempts, retry
• Pass: append to successes.json, mark loop "completed", update tasks
• Escalation (max attempts): show summary, offer options. Do NOT checkpoint.

---

Phase 5: Auto-Checkpoint

Triggers when verification passes. Read ${CLAUDE_SKILL_DIR}/references/checkpoint.md for detailed checkpoint phases.

Summary:

1. Update .claude-harness/claude-progress.json with session summary
2. Capture working context to session-scoped file
3. Compile session briefing to .claude-harness/session-briefing.md
4. Persist to all memory layers (episodic, semantic, procedural)
5. Auto-reflect on user corrections
6. Persist orchestration memory
7. Commit, push, create/update PR

---

Phase 6: Auto-Merge (unless --no-merge)

Only proceeds if PR approved and CI passes.

1. Check PR status via mcp__github__get_pull_request_status
2. If ready: merge (squash), close issue, delete remote branch, update status to "passing", archive feature
3. If needs review: display PR URL with resume/merge commands
4. Final cleanup: switch to main, delete local feature branch (git branch -d), prune refs, clear loop state

---

Phase 7: Completion Report

1. Clean up tasks (all 6 should be completed).
2. Display final status: feature ID, description, issue (closed), PR (merged), tasks 6/6, attempts, duration, memory updates.

---

Resume Behavior

• /claude-harness:flow feature-XXX:
  • Check interrupt recovery (priority): Read .claude-harness/sessions/.recovery/interrupted.json
  • If marker matches: display recovery banner, present options (FRESH APPROACH / RETRY SAME / RESET)
  • In autonomous: always FRESH APPROACH
  • If no marker: resume from feature status: pending -> Phase 3, in_progress -> Phase 4, needs_review -> Phase 6, passing -> already complete

---

Error Handling

• GitHub API failures: Retry with exponential backoff. If persistent: pause and inform user.
• Verification failures: Record to procedural memory, try alternative, escalate after maxAttempts.
• Merge conflicts: Inform user, offer rebase or manual resolution.

---

Quick Reference

Command	Behavior
/flow "Add X"	Full lifecycle with context isolation: implement -> verify -> checkpoint -> merge
/flow feature-XXX	Resume existing feature from current phase
/flow --no-merge "Add X"	Stop at checkpoint
/flow --quick "Simple fix"	Skip planning, implement directly
/flow --plan-only "Big feature"	Plan only, implement later
/flow --fix feature-001 "Bug"	Create and complete a bug fix
/flow --autonomous	Batch process all features
/flow --autonomous --no-merge	Batch, stop at checkpoint
/flow --autonomous --quick	Autonomous without planning
/flow --team "Add X"	ATDD with Agent Team: tester + implementer + reviewer
/flow --team --no-merge "Add X"	Team ATDD, stop at checkpoint
/flow --team --autonomous	Teams for each feature in autonomous batch

Flag combinations: --no-merge --plan-only (plan before implementing), --autonomous --no-merge --quick (fast batch without merge), --team --autonomous --no-merge (team ATDD batch without merge)

---

When to Use Each Mode

Mode	Use Case
Default (/flow "desc")	Standard feature development (context-isolated via subagent)
--no-merge	Review PR before merging
--plan-only	Complex features needing upfront design
--quick	Simple fixes -- skips planning
--autonomous	Batch processing feature backlog unattended
--team	Complex features benefiting from parallel review + ATDD
--team --autonomous	High-quality batch processing with code review