flow

What this skill does

# 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):
   ```bash
   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`:
   ```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 -> Impleme