Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ Rust: clippy for linting, cargo test for tests. No TypeScript, no npm. Skills an
- **Review comparison**: `flowctl review-backend --compare <files>` or `--epic <id>` detects consensus/conflict across review receipts (auto-archived to `.flow/reviews/`)
- **Domain tagging**: `flowctl task create --domain <domain>` tags tasks (frontend/backend/architecture/testing/docs/ops/general), filterable via `tasks --domain`
- **Epic archival**: `flowctl epic archive <id>` moves closed epic + tasks + specs + reviews to `.flow/.archive/`; `flowctl epic clean` archives all closed epics at once
- **Learning loop**: plan injects memory (Step 1b), worker saves lessons (Phase 5b, included in default sequence when memory.enabled is true), epic close prompts retro, retro verifies stale entries via `flowctl memory verify <id>`
- **Learning loop**: plan injects memory (Step 6), worker saves lessons (Phase 11, included in default sequence when memory.enabled is true), epic close prompts retro, retro verifies stale entries via `flowctl memory verify <id>`
- **Task duration**: `flowctl done` auto-tracks `duration_seconds` from start to completion, rendered in evidence
- **File ownership**: `flowctl task create --files <paths>` declares owned files; `flowctl files --epic <id>` shows ownership map + conflict detection
- **File locking (Teams)**: `flowctl lock --task <id> --files <paths>` acquires runtime file locks; `flowctl unlock --task <id>` releases on completion; `flowctl lock-check --file <path>` inspects lock state; `flowctl unlock --all` clears all locks between waves
Expand All @@ -95,9 +95,9 @@ Rust: clippy for linting, cargo test for tests. No TypeScript, no npm. Skills an
- **Review circuit breaker**: impl-review fix loop capped at `MAX_REVIEW_ITERATIONS` (default 3) — prevents infinite NEEDS_WORK cycles
- **Auto-improve analysis-driven**: generates custom program.md from codebase analysis (hotspots, lint, coverage, memory) with Action Catalog ranked by impact — not static templates
- **Auto-improve quantitative**: captures before/after metrics per experiment, commit messages include delta `[lint:23→21]`
- **Worker self-review**: Phase 2.5 runs guard + structured diff review (correctness, quality, performance, testing) before commit
- **Worker self-review**: Phase 6 runs guard + structured diff review (correctness, quality, performance, testing) before commit
- **Plan auto-execute**: `/flow-code:plan` defaults to auto-execute work after planning (Teams mode handles any task count); `--plan-only` to opt out
- **Goal-backward verification**: worker Phase 5 re-reads acceptance criteria and verifies each is actually satisfied before completing
- **Goal-backward verification**: worker Phase 10 re-reads acceptance criteria and verifies each is actually satisfied before completing
- **Full-auto by default**: `/flow-code:plan` and `/flow-code:work` require zero interactive questions — AI reads git state, `.flow/` config, and request context to make branch, review, and research decisions autonomously. Default mode is Worktree + Teams + Phase-Gate (all three active). Work resumes from `.flow/` state on every startup (not a special "resume mode"). All tasks done → auto push + draft PR (`--no-pr` to skip)
- **Cross-platform**: flowctl is a single Rust binary (macOS/Linux). RP plan-review auto-degrades to Codex on platforms where rp-cli is unavailable. Bash hooks degrade gracefully on Windows (skip, don't block)
- **Session start**: CLAUDE.md instruction (not an enforced hook) — if `.flow/` exists, run `flowctl status --interrupted` to check for unfinished work from a previous session and resume with the suggested `/flow-code:work <id>` command
Expand Down
76 changes: 38 additions & 38 deletions agents/worker.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ You implement a single flow-code task. Your prompt contains configuration values
- `FLOWCTL` - path to flowctl CLI
- `REVIEW_MODE` - none, rp, or codex
- `RALPH_MODE` - true if running autonomously
- `TDD_MODE` - true to enforce test-first development (Phase 2a)
- `RP_CONTEXT` - mcp, cli, or none (controls RP-powered context gathering in Phase 1.5)
- `TDD_MODE` - true to enforce test-first development (Phase 4)
- `RP_CONTEXT` - mcp, cli, or none (controls RP-powered context gathering in Phase 3)

## Environment

Expand All @@ -38,7 +38,7 @@ You execute phases one at a time via flowctl commands.
4. Run: `$FLOWCTL worker-phase done --task $TASK_ID --phase <N> --json`
5. Repeat from step 1 until response has `all_done: true`

Do NOT skip phases. Do NOT execute phases out of order. The gate enforces sequential execution — attempting to complete phase 3 before phase 2 will be rejected.
Do NOT skip phases. Do NOT execute phases out of order. The gate enforces sequential execution — attempting to complete phase 5 before phase 4 will be rejected.
<!-- /section:core -->

<!-- section:team -->
Expand Down Expand Up @@ -129,7 +129,7 @@ After `flowctl done`, send a `task_complete` message, then wait for next assignm
<!-- /section:team -->

<!-- section:team -->
## Phase 0: Verify Configuration (CRITICAL)
## Phase 1: Verify Configuration (CRITICAL)

**If TEAM_MODE is `true`:**

Expand All @@ -139,7 +139,7 @@ After `flowctl done`, send a `task_complete` message, then wait for next assignm
SendMessage(to: "coordinator", summary: "Blocked: <TASK_ID>",
message: "Task <TASK_ID> is blocked.\nReason: TEAM_MODE=true but OWNED_FILES is empty or missing.\nBlocked by: orchestrator configuration error")
```
- Do NOT proceed to Phase 1
- Do NOT proceed to Phase 2

2. **Verify TASK_ID matches prompt**
- Confirm the `TASK_ID` from your prompt matches what `flowctl show` returns
Expand All @@ -148,11 +148,11 @@ After `flowctl done`, send a `task_complete` message, then wait for next assignm
3. **Log owned files for audit trail**
- Print `OWNED_FILES: <file1>, <file2>, ...` so the conversation log captures your ownership set

**If TEAM_MODE is not set or `false`:** proceed directly to Phase 1 (unrestricted file access).
**If TEAM_MODE is not set or `false`:** proceed directly to Phase 2 (unrestricted file access).
<!-- /section:team -->

<!-- section:core -->
## Phase 1: Re-anchor (CRITICAL - DO NOT SKIP)
## Phase 2: Re-anchor (CRITICAL - DO NOT SKIP)

Use the FLOWCTL path and IDs from your prompt:

Expand Down Expand Up @@ -217,13 +217,13 @@ GIT_BASELINE_REV=$(git rev-parse HEAD)
echo "GIT_BASELINE_REV=$GIT_BASELINE_REV"
git diff --stat HEAD 2>/dev/null || true
```
Save `GIT_BASELINE_REV` — you'll use it in Phase 5 to generate workspace change evidence.
Save `GIT_BASELINE_REV` — you'll use it in Phase 10 to generate workspace change evidence.
<!-- /section:core -->

<!-- section:core -->
## Phase 1.5: Pre-implementation Investigation
## Phase 3: Pre-implementation Investigation

**If the task spec contains `## Investigation targets` with content, execute this phase. Otherwise skip to Phase 2a/2.**
**If the task spec contains `## Investigation targets` with content, execute this phase. Otherwise skip to Phase 4/5.**

### Step 0: RP-powered deep context (if RP_CONTEXT != none)

Expand All @@ -237,15 +237,15 @@ IF RP_CONTEXT == "mcp":
Timeout: 120 seconds. If context_builder does not return within 120s, log:
"RP context_builder timed out after 120s, using built-in fallback"
and skip to Step 1.
Use the returned plan to guide Phase 2 implementation.
Use the returned plan to guide Phase 5 implementation.

ELIF RP_CONTEXT == "cli":
Run with 120s timeout:
timeout 120 rp-cli -e 'builder "<task title>: <description + acceptance criteria>" --response-type plan'
If timeout or failure, log:
"rp-cli builder timed out or failed, using built-in fallback"
and skip to Step 1.
Use the returned plan to guide Phase 2 implementation.
Use the returned plan to guide Phase 5 implementation.

ELSE (RP_CONTEXT == "none"):
Skip to Step 1 (existing behavior, unchanged).
Expand Down Expand Up @@ -286,11 +286,11 @@ END

3. Read **Optional** files as needed based on Step 1 findings.

4. Continue to Phase 2a/2 only after investigation is complete.
4. Continue to Phase 4/5 only after investigation is complete.
<!-- /section:core -->

<!-- section:tdd -->
## Phase 2a: TDD Red-Green (if TDD_MODE=true)
## Phase 4: TDD Red-Green (if TDD_MODE=true)

**Skip this phase if TDD_MODE is not `true`.**

Expand All @@ -303,15 +303,15 @@ Before implementing the feature, write failing tests first:
```
If tests pass already, the feature may already be implemented. Investigate before proceeding.

2. **Green** — Now implement the minimum code to make tests pass (this IS Phase 2).
2. **Green** — Now implement the minimum code to make tests pass (this IS Phase 5).

3. **Refactor** — After tests pass, clean up without changing behavior. Run tests again to confirm still green.

The key constraint: **no implementation code before a failing test exists**. This ensures every change is test-driven.
<!-- /section:tdd -->

<!-- section:core -->
## Phase 2: Implement
## Phase 5: Implement

**First, capture base commit for scoped review:**
```bash
Expand Down Expand Up @@ -401,7 +401,7 @@ If during implementation you discover the spec is wrong, incomplete, or contradi
- What the spec says vs what reality requires
- Why the spec approach won't work
- A suggested correction (if you have one)
3. **Return early** with status `SPEC_CONFLICT` in your Phase 6 summary
3. **Return early** with status `SPEC_CONFLICT` in your Phase 12 summary
4. Do NOT mark the task as done — leave it `in_progress`

The main conversation will resolve the conflict and re-dispatch you (or update the spec).
Expand All @@ -414,7 +414,7 @@ The main conversation will resolve the conflict and re-dispatch you (or update t
<!-- /section:core -->

<!-- section:core -->
## Phase 2.3: Plan Alignment Check
### Plan Alignment Check

Quick sanity check — did implementation stay within plan scope?

Expand All @@ -431,11 +431,11 @@ Quick sanity check — did implementation stay within plan scope?
Drift: <description of what changed and why>
```

**This is a 30-second check, not a full re-review.** Read the spec, glance at your diff, note any drift. Then proceed to Phase 2.5.
**This is a 30-second check, not a full re-review.** Read the spec, glance at your diff, note any drift. Then proceed to Phase 6.
<!-- /section:core -->

<!-- section:core -->
## Phase 2.5: Verify & Fix
## Phase 6: Verify & Fix

**After implementing, before committing — verify your code works. This is normal development: implement → test → fix → retest → pass → commit.**

Expand All @@ -451,7 +451,7 @@ Continue until guard passes. There is no retry limit — this is not a retry loo

**If the failure is not a code bug but a spec problem** (e.g., spec asks for something impossible, acceptance criteria contradict each other, required API doesn't exist):
- Do NOT keep trying to fix code
- Return early with `SPEC_CONFLICT` status (see Phase 2 spec conflict protocol)
- Return early with `SPEC_CONFLICT` status (see Phase 5 spec conflict protocol)
- In Teams mode, send a `Spec conflict` message to the coordinator

**Teams mode constraint:** When `TEAM_MODE=true`, only fix files in `OWNED_FILES`. If the failure is caused by a file you don't own, request access via `flowctl approval create --kind file_access` + `approval show --wait` (or fallback `Need file access:` SendMessage), then wait for a resolution. If access is rejected or times out, note the issue in your completion summary.
Expand All @@ -473,11 +473,11 @@ If you find issues, fix them and re-run `<FLOWCTL> guard` to verify.

**Rules:**
- Only fix issues in YOUR changes — don't refactor unrelated code
- If unsure whether something is an issue, leave it for Phase 4 (external review)
- If unsure whether something is an issue, leave it for Phase 8 (external review)
<!-- /section:core -->

<!-- section:core -->
## Phase 3: Commit
## Phase 7: Commit

```bash
git add -A
Expand All @@ -493,9 +493,9 @@ Use conventional commits. Scope from task context.
<!-- /section:core -->

<!-- section:review -->
## Phase 4: Review (MANDATORY if REVIEW_MODE != none)
## Phase 8: Review (MANDATORY if REVIEW_MODE != none)

**If REVIEW_MODE is `none`, skip to Phase 5.**
**If REVIEW_MODE is `none`, skip to Phase 10.**

**If REVIEW_MODE is `rp` or `codex`, you MUST invoke impl-review and receive SHIP before proceeding.**

Expand All @@ -520,13 +520,13 @@ If NEEDS_WORK:
3. Commit fixes
4. Re-invoke the skill: `/flow-code:impl-review <TASK_ID> --base $BASE_COMMIT`

Continue until SHIP verdict. Save final `REVIEW_ITERATIONS` count for Phase 5 evidence.
Continue until SHIP verdict. Save final `REVIEW_ITERATIONS` count for Phase 10 evidence.
<!-- /section:review -->

<!-- section:core -->
## Phase 5: Complete
## Phase 10: Complete

**Prerequisite:** Phase 5c (Outputs Dump) must have run if `outputs.enabled=true`. The phase registry orders 5c before 5 so the narrative handoff file exists before dependents unblock.
**Prerequisite:** Phase 9 (Outputs Dump) must have run if `outputs.enabled=true`. The phase registry orders 9 before 10 so the narrative handoff file exists before dependents unblock.

**Verify before completing:**
```bash
Expand All @@ -547,7 +547,7 @@ Go through each `- [ ]` acceptance criterion in the spec:

**Rules:**
- This is a 1-minute sanity check, not a full re-review
- Only check acceptance criteria, not general quality (Phase 2.5 already did that)
- Only check acceptance criteria, not general quality (Phase 6 already did that)
- If you discover a gap, fix + commit + re-run guard
- If you discover the criterion is impossible, note it in the summary (not SPEC_CONFLICT at this stage)

Expand All @@ -556,7 +556,7 @@ Capture the commit hash:
COMMIT_HASH=$(git rev-parse HEAD)
```

Capture workspace changes (compare against Phase 1 baseline):
Capture workspace changes (compare against Phase 2 baseline):
```bash
# Generate workspace change summary
DIFF_STAT=$(git diff --stat "$GIT_BASELINE_REV"..HEAD 2>/dev/null || echo "no diff")
Expand All @@ -574,7 +574,7 @@ EOF

**If a review was done (REVIEW_MODE != none)**, append the review receipt to evidence so it gets auto-archived:
```bash
# Only if RECEIPT_PATH exists from Phase 4
# Only if RECEIPT_PATH exists from Phase 8
if [ -f "${RECEIPT_PATH:-/tmp/impl-review-receipt.json}" ]; then
# Merge review_receipt into evidence JSON
python3 -c "
Expand Down Expand Up @@ -610,9 +610,9 @@ Status MUST be `done`. If not:
<!-- /section:core -->

<!-- section:outputs -->
## Phase 5c: Outputs Dump (if outputs.enabled)
## Phase 9: Outputs Dump (if outputs.enabled)

**Runs BEFORE Phase 5 completion.** Phase 5c must produce the handoff artifact before `flowctl done` fires, otherwise a dependent task can start re-anchoring and race past the missing file. The phase registry in `flowctl-cli/src/commands/workflow/phase.rs` enforces this ordering (5c before 5).
**Runs BEFORE Phase 10 completion.** Phase 9 must produce the handoff artifact before `flowctl done` fires, otherwise a dependent task can start re-anchoring and race past the missing file. The phase registry in `flowctl-cli/src/commands/workflow/phase.rs` enforces this ordering (9 before 10).

**Skip if `outputs.enabled` is false.** This is gated on its own config key — independent from `memory.enabled`. Outputs are a lightweight narrative handoff layer (plain markdown, no verification), separate from the verified memory system.

Expand Down Expand Up @@ -645,18 +645,18 @@ fi
- All three sections are allowed to be missing or empty — downstream readers handle that gracefully
- Focus on narrative handoff: what would help the next worker, not comprehensive docs
- Don't repeat spec content — only things you learned while working
- This is narrative handoff, NOT verified memory. Save verified pitfalls/conventions in Phase 5b.
- This is narrative handoff, NOT verified memory. Save verified pitfalls/conventions in Phase 11.
<!-- /section:outputs -->

<!-- section:memory -->
## Phase 5b: Memory Auto-Save (if memory enabled)
## Phase 11: Memory Auto-Save (if memory enabled)

**Skip if memory.enabled is false or was not checked in Phase 1.**
**Skip if memory.enabled is false or was not checked in Phase 2.**

After completing the task, capture any non-obvious lessons learned:

```bash
# Check if memory is enabled (already checked in Phase 1)
# Check if memory is enabled (already checked in Phase 2)
<FLOWCTL> config get memory.enabled --json
```

Expand Down Expand Up @@ -686,7 +686,7 @@ If enabled, reflect on what you discovered during implementation and save **only
<!-- /section:memory -->

<!-- section:core -->
## Phase 6: Return
## Phase 12: Return

Return a concise summary to the main conversation:
- What was implemented (1-2 sentences)
Expand Down
Loading
Loading