cfcf and cf² are used interchangeably. Both are pronounced "cf square". cfcf is used in code and commands; cf² in documentation.
This guide walks through the complete cf² workflow: from setting up a project to running iterative AI agent development cycles.
cfcf can be driven from either the CLI or the web GUI (served by the same local server at http://localhost:7233). This guide uses CLI commands in examples, but every action shown here has a web UI equivalent. See cli-usage.md for the CLI reference.
┌──────────────────────────────────────────────────────────────┐
│ USER DOES THIS │
│ │
│ 1. Start server (once) │
│ 2. Create repo + init project │
│ 3. Populate Problem Pack (problem, success criteria, etc.) │
│ 4. (Recommended) Consult Solution Architect for feedback │
│ └─ iterate on Problem Pack until satisfied │
│ 5. Launch the iterative development process │
│ └─ review & provide feedback at pause cadence │
│ 6. (Optional) Re-consult the Architect or run ad-hoc │
│ Reflection if you want to extend a finished project │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ cf² HANDLES THIS │
│ │
│ Each iteration: │
│ • Assemble context (CLAUDE.md/AGENTS.md + cfcf-docs/) │
│ • Launch dev agent on feature branch │
│ • Capture logs, parse handoff + signals │
│ • Launch judge agent, parse assessment │
│ • Launch reflection agent (unless judge opts out) │
│ • Decide: continue / pause / stop │
│ • Produce three separate commits (dev / judge / reflect) │
│ • On SUCCESS: run documenter to produce final docs │
│ • Alert user when input is needed │
│ Cross-iteration plumbing: │
│ • Preserve user's content in CLAUDE.md/AGENTS.md │
│ (sentinel-delimited cfcf block) │
│ • Rebuild iteration-history.md from per-iteration logs │
│ • Non-destructively protect completed plan items │
└──────────────────────────────────────────────────────────────┘
cf² has seven independently configurable agent roles. Five are non-interactive (fire-and-forget, signal-file workflow):
| Role | Purpose | When it runs |
|---|---|---|
| Solution Architect | Reviews Problem Pack, produces initial plan + doc stubs. On re-review: extends the plan non-destructively when new requirements appear. | User-invoked via cfcf review (polling client to a server-side headless spawn — not interactive in the TUI sense, despite the user-driven invocation), AND on refine_plan resume actions, AND pre-loop when autoReviewSpecs=true |
| Developer | Writes code, runs tests, produces handoff + iteration-log | Each iteration |
| Iteration Judge | Reviews dev work, determines progress, may opt out of reflection | After each dev iteration |
| Reflection Agent | Reads the full cross-iteration history, classifies iteration health, may rewrite pending plan items non-destructively | After the judge on every iteration, unless the judge explicitly opts out |
| Documenter | Produces polished final documentation | Auto post-SUCCESS, or cfcf document on demand |
Two are interactive — the agent CLI's TUI takes over your shell until you exit:
| Role | Purpose | When it runs |
|---|---|---|
| Product Architect | Helps you author + iterate the Problem Pack interactively; drives git init / cfcf workspace init if needed; refines specs before/after loops. Has the full cf² docs in its system prompt. |
cfcf spec; see product-architect.md |
| Help Assistant | Interactive cf² support: answers "how does X work?", reads your Clio memory, runs diagnostics. | cfcf help assistant |
Each role can use a different agent and model. Reflection is the strongest-context role -- the project's full history is its input -- so the recommended default is the most capable model available (Claude Opus, GPT-5, etc.). The Product Architect defaults to Sonnet for claude-code (Help Assistant defaults to Haiku for its Q&A workload). You can configure each role separately in cfcf init or via cfcf config edit.
Adapter choice — Anthropic policy + log visibility:
- Interactive roles (
Product Architect,Help Assistant):claude-codeis the recommended choice. These are the only two roles that take over your shell viaBun.spawn(... { stdio: "inherit" })— you watch progress live in the terminal. No policy concern (Anthropic permits interactive subscription use) and no log-visibility concern. - Unattended roles (dev / judge / reflection / documenter / architect): the loop — and
cfcf review, since it just polls a status endpoint while the server runs the architect headlessly in the background — spawns the agent CLI withclaude -p(or equivalent) and pipes stdout to a log file. No TUI takeover anywhere. That's where the trade-offs matter:codexis the recommended unattended default — streams progress live to the log file (visible during the run), policy-clean (OpenAI's API-key path explicitly endorses CLI automation).opencode-ollama/opencode— also stream live, also policy-clean.claude-code-ollama— policy-clean (no Anthropic credential involved; local ollama serves the model), but shares Claude Code's-pstdout-buffering behaviour: the log file stays silent during the run and only dumps the final response when the agent exits. Pick this if you specifically prefer Claude's tool-call format / instruction-file conventions and don't need live monitoring.claude-code(direct) — avoid for unattended roles: violates Anthropic's third-party-harness policy AND has the same silent-log issue.
cf² surfaces an inline warning in cfcf init and the web UI when claude-code is picked for an unattended role (yellow callout, policy-grade) and a softer info note when claude-code-ollama is picked (blue callout, log-visibility). Neither blocks the choice. Full breakdown: anthropic-policy.md (also cfcf help anthropic-policy after install).
cf² evaluates every iteration at three levels:
- Mechanical -- tests, type-checks, linters. The dev agent runs them and the judge verifies them.
- Per-iteration judgment -- the Judge assesses the latest iteration only: did it make meaningful progress? Any anomalies? Is the code quality acceptable?
- Strategic reflection -- the Reflection agent reads the entire project history (all iteration logs, all prior judge assessments, the decision log, the git log of iteration branches, the tail of the most recent dev log) and classifies trajectory:
converging | stable | stalled | diverging | inconclusive. Reflection can non-destructively rewrite the pending portion ofcfcf-docs/plan.mdwhen the evidence warrants a strategic shift, or flagrecommend_stopto pause the loop for you.
Reflection is the only role allowed to edit a plan that already has completed work.
The cf² server must be running for all CLI commands to work. Start it once and leave it running:
# Check if already running
cfcf server status
# Start if needed
cfcf server startThe server runs in the background. You can stop it anytime with cfcf server stop. The web GUI is reachable at http://localhost:7233. The top bar has Workspaces + Settings links. The Settings page (/#/server) is a full editor for the global config -- same keys as cfcf config edit on the CLI, same endpoint (PUT /api/config). Per-workspace overrides live in each workspace's Config tab.
Run once after installing cf²:
cfcf initThis detects installed AI agents (Claude Code, Codex), asks for configuration defaults for all five roles (dev, judge, architect, documenter, reflection), asks for reflectSafeguardAfter (how many consecutive judge opt-outs before cfcf forces reflection -- default 3), explains the permission flags, and saves the config. The configuration can be changed later with:
cfcf config edit # or: cfcf init --forcecf² works with any git repository. You either:
Create a new repo (for a greenfield project):
mkdir my-project && cd my-project
git init
echo "# my-project" > README.md
git add -A && git commit -m "init"Use an existing repo (to add features, refactor, fix bugs):
cd /path/to/existing/project
# Ensure there's at least one commitcfcf will preserve any existing CLAUDE.md / AGENTS.md in the repo. Iteration-specific instructions are inserted between sentinel markers (<!-- cfcf:begin --> ... <!-- cfcf:end -->); your own content outside the markers is never touched. See "CLAUDE.md / AGENTS.md" below.
cfcf workspace init --repo /path/to/my-project --name my-projectThis creates:
- A project config in cf²'s config directory
- A
problem-pack/directory in your repo with template files
Before you start writing the Problem Pack, it helps to know which files in the repo you own and which cfcf treats as generated copies.
| Directory | Role | Edit here? |
|---|---|---|
problem-pack/ |
User-owned source of truth. problem.md, success.md, and the optional constraints.md / hints.md / style-guide.md / context/* live here. |
✅ Yes -- this is where you describe the problem. |
cfcf-docs/problem.md and friends |
Generated copies. cfcf copies from problem-pack/ into cfcf-docs/ at the start of every run (iteration, pre-loop review, architect review) so agents have a single cfcf-docs/ surface to read. |
❌ No -- cfcf overwrites these on every run. Every generated copy also carries a banner at the top saying so. |
cfcf-docs/plan.md |
Agent-maintained -- dev agent + reflection role + architect re-review mode edit it through cfcf's controlled path. | Read-only for you, except when the loop is paused and you want to manually hand-edit before resuming. |
cfcf-docs/iteration-logs/iteration-N.md |
Written by the dev agent at the end of each iteration. cfcf rebuilds iteration-history.md from these. |
Read-only. |
cfcf-docs/iteration-handoff.md |
Live forward-looking handoff for the current iteration. The dev agent writes their handoff here; judge + reflection read it within the same iteration. On a brownfield loop this file starts with the previous iteration's handoff as context — the dev reads it, then replaces it with their own. | Read-only for you; the dev agent manages the content. |
cfcf-docs/iteration-handoffs/iteration-N.md |
Per-iteration archive of iteration-handoff.md. cfcf copies the live handoff here at end of each iteration (same pattern as iteration-reviews/ and reflection-reviews/). |
Read-only audit trail. |
cfcf-docs/iteration-reviews/iteration-N.md |
Per-iteration archive of judge-assessment.md. |
Read-only audit trail. |
cfcf-docs/reflection-reviews/reflection-N.md |
Per-iteration archive of reflection-analysis.md. |
Read-only audit trail. |
cfcf-docs/decision-log.md |
Multi-role append-only journal (dev, judge, architect, reflection, user all append tagged entries). | You may append entries (use the [role: user] tag). |
cfcf-docs/*-signals.json |
Machine-readable signal files. Reset before each agent spawn, read by cfcf after. | Don't edit by hand. |
CLAUDE.md / AGENTS.md (at the repo root) |
The cfcf-generated block lives between <!-- cfcf:begin --> and <!-- cfcf:end -->. Anything outside those markers is yours and cfcf never touches it. |
Edit OUTSIDE the sentinel block (above or below). Never edit inside -- those lines get rewritten every iteration. |
Rule of thumb: if you want a change to persist across runs, edit a file in problem-pack/ or outside the sentinels in CLAUDE.md/AGENTS.md. Never edit a file in cfcf-docs/ unless you are appending to decision-log.md.
cfcf prepends a comment banner to every generated copy under cfcf-docs/ so this is visible in the file itself:
<!--
cfcf: this file is generated from problem-pack/problem.md and is overwritten
on every run (pre-loop review, iteration, or architect review).
DO NOT EDIT HERE -- your changes will be lost. Edit the source at
problem-pack/problem.md instead.
-->This is where the user defines what the AI agent should build. cf² scaffolds templates, but the user MUST replace the template content with real problem definitions. Without this, the agent has no direction.
There are two ways to do this:
A. Interactive (recommended): the Product Architect.
cd /path/to/your/repo
cfcf speccfcf spec launches the Product Architect — an interactive agent that helps you draft + iterate each Problem Pack file. It has the full cf² docs in its system prompt, so it understands what each file is for + how downstream agents will use them. It asks clarifying questions, surfaces edge cases, and drafts content with you. Disk + Clio memory ensure your spec history persists across sessions. See product-architect.md for the full reference.
PA also handles the prerequisites: it'll offer to run git init (if needed) + cfcf workspace init (if no workspace is registered yet) before drafting the Problem Pack. So this step CAN be run before Step 3 — you'd run cfcf spec on a fresh repo, and PA drives the rest.
B. Manual: edit the files directly.
Below are the canonical Problem Pack files + recommended structures. Either author them yourself, or use them as a guide for what PA should help you produce.
problem-pack/problem.md -- What needs to be built or fixed:
# Problem Definition
## What Needs to Be Built
A REST API for user management with signup, login, and profile endpoints.
## Current State
Empty project. No existing code.
## Expected Behavior
- POST /signup creates a new user with email/password
- POST /login returns a JWT token
- GET /profile returns the authenticated user's profile
- All endpoints validate input and return proper error codes
## Scope
- In scope: API endpoints, input validation, JWT auth, tests
- Out of scope: Frontend, deployment, database migrationsproblem-pack/success.md -- How success is measured:
# Success Criteria
## Tests Must Pass
- Signup creates a user and returns 201
- Duplicate email returns 409
- Login with valid credentials returns a JWT
- Login with invalid credentials returns 401
- Profile endpoint requires authentication (401 without token)
- Profile returns user data with valid token
- All input validation works (missing fields, invalid email format)
## Code Quality
- TypeScript with proper type annotations
- Error handling with descriptive messages
- Tests cover all endpoints and edge casesproblem-pack/constraints.md-- Guardrails: "must use Express.js", "no ORMs", "must be compatible with Node 20"problem-pack/hints.md-- Technical guidance: "use bcrypt for passwords", "prefer Zod for validation"problem-pack/style-guide.md-- Code conventions: "use 2-space indentation", "prefer async/await over callbacks"problem-pack/context/-- Reference files: API specs, architecture docs, data model descriptions
- Be specific. "Build an auth system" is vague. "Build JWT-based auth with signup, login, and profile endpoints" is actionable.
- Define success concretely. The agent needs to know when it's done. List specific test cases.
- Set boundaries. What's in scope and what isn't? What libraries should (or shouldn't) be used?
- Provide context for existing repos. If there's existing code, describe the architecture so the agent understands what it's working with.
Before launching the development process, you can ask cf²'s Solution Architect agent to review your Problem Pack. This is an advisory tool -- not a gate or requirement. You can skip it entirely, or iterate as many times as you want.
cfcf review --workspace my-projectThe Solution Architect reads your Problem Pack and produces:
cfcf-docs/architect-review.md-- readiness assessment, gaps, ambiguities, security considerations, risk factors, recommendationscfcf-docs/plan.md-- initial implementation plan outline for the dev agent to build ondocs/architecture.md,docs/api-reference.md,docs/setup-guide.md-- initial documentation stubs (first-run only)cfcf-docs/cfcf-architect-signals.json-- structured readiness signal (READY / NEEDS_REFINEMENT / BLOCKED / SCOPE_COMPLETE)
First-run mode. cfcf-docs/plan.md doesn't exist (or has no completed items yet). The architect scaffolds a fresh plan from the Problem Pack.
Re-review mode. cfcf-docs/plan.md already has completed items ([x]) -- i.e. previous iterations have shipped. The architect:
- Reads the full history first (iteration logs, decision log, reflection reviews) to understand what was already delivered.
- Compares to the current Problem Pack. If new requirements appeared (e.g. you added a new section to
problem.md), the architect appends new pending iterations toplan.mdrather than rewriting it. - If the current plan still covers the Problem Pack, the architect leaves
plan.mduntouched and says so inarchitect-review.md. - Never deletes completed items or iteration headers. cfcf enforces this: any destructive rewrite is auto-reverted and logged.
This means you can safely re-run cfcf review mid-project or after a finished loop when you've added new requirements -- the architect won't erase the audit trail.
┌──────────────────────────────────────────────────┐
│ 1. Run: cfcf review --workspace my-project │
│ 2. Read: cfcf-docs/architect-review.md │
│ 3. The architect points out gaps/suggestions │
│ 4. User updates problem-pack/ files │
│ 5. Run cfcf review again if desired │
│ └─ Repeat until satisfied │
└──────────────────────────────────────────────────┘
Important: The user decides when the Problem Pack is ready. The architect provides advice, not permission. You can launch development at any time, even if the architect suggests refinements.
When you feel the Problem Pack adequately describes the problem, launch the dark factory:
# Launch cf² -- it takes over from here
cfcf run --workspace my-projectThis is the last user action until cf² needs input. From this point, cf² manages everything autonomously.
┌──────────────────────────────────────────────────────────────────┐
│ PRE-LOOP (conditional, only when autoReviewSpecs=true; item 5.1) │
│ │
│ REVIEW (agent) Solution Architect runs against the │
│ current Problem Pack. Output (review + │
│ plan + doc stubs) commits to main (NOT an │
│ iteration branch). readinessGate decides │
│ whether the loop proceeds: │
│ "never" -> always proceed (informational)│
│ "blocked" -> stop only on BLOCKED │
│ "needs_refinement_or_blocked" -> stop on │
│ anything but READY. │
│ On block: loop pauses with the architect's │
│ gaps as pending questions. │
│ │
├──────────────────────────────────────────────────────────────────┤
│ ITERATION N │
│ │
│ PREPARE (cf²) Assemble context -- merge cfcf block into │
│ CLAUDE.md/AGENTS.md, rebuild │
│ iteration-history.md from iteration-logs, │
│ create branch cfcf/iteration-N │
│ │
│ DEV (agent) Fresh agent process; reads plan.md + │
│ previous iteration-handoff.md (if any) for │
│ forward-looking context, executes the next │
│ pending chunk, updates plan.md with │
│ [x] + notes, writes iteration-logs/ │
│ iteration-N.md, REPLACES │
│ iteration-handoff.md with this iteration's │
│ handoff, fills iteration signals │
│ → commit: "cfcf iteration N dev (<adapter>)"│
│ cfcf then archives iteration-handoff.md → │
│ iteration-handoffs/iteration-N.md │
│ │
│ JUDGE (agent) Fresh agent process; assesses this │
│ iteration; writes judge-assessment.md │
│ + signals (determination, quality score, │
│ tests, concerns, reflection_needed opt-out) │
│ → commit: "cfcf iteration N judge (...)" │
│ │
│ REFLECT (agent, Conditional. Runs unless the judge set │
│ conditional) reflection_needed:false AND we're still │
│ under the reflectSafeguardAfter ceiling. │
│ Reads FULL history. Writes │
│ reflection-analysis.md + signals. May │
│ rewrite pending plan items non- │
│ destructively (completed items are │
│ protected; destructive rewrites are auto- │
│ reverted). May flag recommend_stop. │
│ → commit: "cfcf iteration N reflect │
│ (<health>): <key_observation>" │
│ │
│ DECIDE (cf²) Read all signals. Decision engine picks: │
│ SUCCESS → run documenter, merge, push │
│ PROGRESS → continue to next iteration │
│ STALLED → apply onStalled policy │
│ ANOMALY → pause, alert user │
│ reflection.recommend_stop → pause │
│ (takes precedence over judge) │
│ pause cadence reached → pause, alert │
│ Auto-merge the branch to main if configured │
│ │
│ DOCUMENT (agent) Only on SUCCESS. Produces polished │
│ docs/ (architecture, api-reference, │
│ setup-guide, README). Skipped when │
│ autoDocumenter=false (item 5.1) -- user │
│ can invoke `cfcf document` manually. │
└──────────────────────────────────────────────────────────────────┘
This deserves its own walkthrough -- it's a tight user-in-the-loop pattern for getting the Problem Pack right before burning iterations.
Branching. Pre-loop review runs on the current branch (typically main). No iteration branch is created yet. Review artifacts -- architect-review.md, plan.md, cfcf-architect-signals.json, the docs/*.md stubs, and user-feedback.md -- all commit to main as a single cfcf pre-loop review (<readiness>) commit. Iteration branches come later, after the readiness gate accepts the review.
The gate cycle.
- Start Loop (web UI) or
cfcf run(CLI) → cfcf runs the architect as the first phase. Web UI showsReview (agent)lit up in the PhaseIndicator. - Architect writes its output and exits. cfcf reads the readiness signal.
- If
readinessGateaccepts (default"blocked"means accept anything butBLOCKED): cfcf proceeds to iteration 1. The iteration branchcfcf/iteration-1is created frommainand inherits the architect's artifacts +user-feedback.md. - If
readinessGaterejects: cfcf pauses the loop withpauseReason: "anomaly"and the architect's gaps populated aspendingQuestions. The web UI shows the FeedbackForm; the CLI prints the questions viacfcf statusand offerscfcf resume. The PhaseIndicator stays atReview (agent) -- PAUSED. - User refines and resumes. Pick one of the three applicable resume actions for a pre-loop block (per the matrix in User actions at pause points):
- Edit the source first. Open
problem-pack/problem.mdand/orproblem-pack/success.mdin your editor and tighten the spec based on the architect's listed gaps. (Remember:cfcf-docs/problem.mdis a generated copy -- see the "Files you edit vs. files cfcf regenerates" section above.) - Pick
Continue(with optional feedback) orRefine plan(with feedback as architect direction) — both re-run the architect against the source you just edited. The text you provide is written tocfcf-docs/user-feedback.mdso the architect sees it. Especially useful when the gap is small and doesn't warrant reopening the Problem Pack. - Pick
Stop loop nowif you've decided to abandon and rewrite the strategy.
- Edit the source first. Open
- cfcf re-runs the architect (same
pre_loop_reviewingphase, newarchitect-NNN.logsequence). Back to step 2. - Eventually the gate accepts and the loop moves on.
state.userFeedbackcarries through to iteration 1'suser-feedback.mdso the dev agent reads it too; it clears automatically after iteration 1's DECIDE phase.
History-tab label. Pre-loop reviews appear in the History tab as "Pre-loop review" (loop-triggered). Manual cfcf review runs stay labeled "Review". Both share the same ArchitectReview expanded-row detail -- only the top-line label distinguishes them.
Stopping vs resuming. If the pre-loop gate never accepts and you want to bail out entirely (rewrite the problem pack wholesale, change strategy), cfcf stop --workspace <name> ends the loop in a clean terminal state. The pre-loop review commit on main is preserved (useful for audit); you can start a fresh loop later.
Three settings shape whether Review runs inside the loop and whether the Documenter auto-runs on SUCCESS. Each is available at three tiers with the standard priority order: per-run CLI flag → project config → global config → hard default.
| Key | Default | Effect |
|---|---|---|
autoReviewSpecs |
false |
When true, Start Loop first runs the Solution Architect as a pre-loop phase; the standalone Review button is hidden in the web UI; a leading Review (agent) step appears in the phase indicator. |
autoDocumenter |
true |
When false, the loop reaches SUCCESS and skips the Documenter; the Document step is absent from the phase indicator; the standalone cfcf document command still works. |
readinessGate |
"blocked" |
Only consulted when autoReviewSpecs=true. Levels: "never" (always proceed), "blocked" (stop only on BLOCKED), "needs_refinement_or_blocked" (strictest; stop on anything but READY). |
Per-run CLI overrides on cfcf run:
--auto-review / --no-auto-review
--auto-document / --no-auto-document
--readiness-gate <never|blocked|needs_refinement_or_blocked>
Example: "try once without the pre-loop review even though the project default has it on":
cfcf run --workspace my-project --no-auto-reviewEach iteration produces up to three separate commits (dev / judge / reflect) on the feature branch, so git log --oneline cfcf/iteration-N reads as a clean per-iteration story.
Every agent invocation is a separate, clean process -- no session continuity, no memory carried over except files on disk. cf² enforces and leverages this:
- The Solution Architect's
cfcf-docs/plan.mdmaps phases to concrete iterations (## Iteration 1 -- Foundation,## Iteration 2 -- Core features, ...). - Each iteration's generated
CLAUDE.md(for Claude Code) orAGENTS.md(for Codex) includes an Iteration Scope section instructing the dev agent to execute only the next pending chunk from the plan. - Before exiting, the dev agent marks completed items
[x]inplan.mdwith a short note and writes a per-iteration changelog atcfcf-docs/iteration-logs/iteration-N.md. cf² uses those log files to rebuilditeration-history.mdbefore the next iteration, so history survives server restarts. - The next iteration -- a brand new agent process -- picks up from there.
You do not have to configure this -- it is baked into the dev-agent prompt generated for every iteration.
cf² regenerates a block of iteration-specific context for the dev agent every iteration. To avoid destroying user-authored content, it uses sentinel markers:
<!-- cfcf:begin -->
# cfcf Iteration N Instructions
…generated each iteration…
<!-- cfcf:end -->
# My project notes
…your own content, never touched by cfcf…
Rules:
- File doesn't exist → cfcf creates it with the marked block only.
- File exists without markers → cfcf prepends the marked block, preserves your content below untouched.
- File exists with markers → cfcf updates only the content between markers. Your content outside is inviolate, byte-for-byte.
- You removed the markers by hand → cfcf falls back to the "prepend" branch on the next iteration (no data loss, just re-inserts the sentinel section).
Rule of thumb: Anything between the sentinel markers is cfcf-owned and will be overwritten. Anything outside is yours.
Project: my-project
Mode: dark factory (iteration loop)
Iteration loop started (max 10 iterations)
Will pause for review every 3 iterations
preparing [iteration 1]
dev_executing [iteration 1] 3m 22s
judging [iteration 1] 1m 05s
reflecting [iteration 1] 55s
preparing [iteration 2]
dev_executing [iteration 2] 2m 48s
judging [iteration 2] 58s
reflecting [iteration 2] 1m 10s
…
paused [iteration 3]
=== Loop PAUSED ===
Project: my-project
Iteration: 3/10
Reason: cadence
Last judge: PROGRESS (quality: 8/10)
Last reflect: stable · "Auth layer is coming together cleanly."
- A pulsing blue dot + phase label (e.g.
my-project: reflect #3) appears in the top bar whenever any agent is running anywhere. - The dashboard's workspace cards show a per-card pulse-animated chip (e.g.
● review running) when any agent is alive on that workspace — including standalone Review / Document / Reflect runs that don't touch the workspace's loop status. TheStatusBadgenext to the chip stays the source of truth for loop state (idle / running / paused / completed / failed / stopped). v0.24 / F.22. - The History tab shows each iteration plus a separate row per reflection run. Clicking a row expands it to show the full parsed signals (determination, quality, test counts, key concerns, reflection opt-out, iteration health, plan-modified vs rejected-with-reason, etc.).
- The PhaseIndicator component labels each step with
(cf²)or(agent)so you can tell at a glance which phases are deterministic plumbing vs LLM invocations. v0.24 added areflectagent type so manualcfcf reflectruns render their own three-phase indicator parallel to Review and Document. - The workspace-detail page surfaces inline error banners when a standalone Review / Document / Reflect run fails. Pre-v0.24 only the loop's
errorfield rendered; standalone-run failures were silently buried until the next successful run replaced the in-memory state.
# Quick status
cfcf status --workspace my-project
# Watch the current iteration's live log
tail -f ~/.cfcf/logs/<project-id>/iteration-NNN-dev.log
tail -f ~/.cfcf/logs/<project-id>/reflection-NNN.log
# Check the latest judge assessment
cat cfcf-docs/judge-assessment.md
# Check the latest reflection analysis
cat cfcf-docs/reflection-analysis.md
# View iteration history (rebuilt from iteration-logs each iteration)
cat cfcf-docs/iteration-history.md
# Browse per-iteration changelogs
ls cfcf-docs/iteration-logs/
# Read the cross-role decision log
cat cfcf-docs/decision-log.mdWhen running unattended, cf² can notify you via terminal bell + native macOS/Linux notifications when a loop pauses, completes, or an agent fails. Configured during cfcf init. See docs/guides/cli-usage.md under "Notifications" for details.
When the decision log grows past 50 iterations, cf² fires a single informational notification suggesting you consider archiving it. No auto-trim -- the log is yours.
| Situation | What happens |
|---|---|
| Pause cadence (every N iterations) | cf² shows a summary. User reviews, provides feedback, resumes or stops. |
| Agent has questions | Dev agent flagged user_input_needed in signal file. cf² presents the questions. |
| Judge flags anomaly | Token exhaustion, circling, regression detected. cf² alerts user. |
| Judge says STALLED | No progress for N consecutive iterations. cf² alerts user. |
Reflection flags recommend_stop |
Reflection believes the loop is fundamentally stuck. cf² pauses and alerts the user. This takes precedence over a judge PROGRESS vote. |
Architect returns SCOPE_COMPLETE |
A mid-loop architect re-review concluded the Problem Pack is already fully delivered. cf² pauses with pauseReason: "scope_complete"; the resume-action menu narrows to finish_loop / stop_loop_now / refine_plan. |
| Success | All criteria met. cf² runs documenter, merges to main, pushes, notifies user. |
| Max iterations reached | cf² stops and reports final state. |
When cf² pauses, you choose one structured action to drive the harness, plus optional free-text feedback that becomes context for whichever destination the action implies. The web UI shows the applicable buttons; the CLI uses --action. (Item 6.25, 2026-05-02.)
The five actions:
| Action | What the harness does | Where free-text feedback goes |
|---|---|---|
| Continue (default) | Run the next iteration with your feedback as guidance for the dev agent. | Next dev iteration's prompt |
| Finish loop | End the loop on a successful note. Documenter runs if autoDocumenter=true; if false, just terminate. |
Documenter prompt (when it runs) |
| Stop loop now | Terminate immediately. No documenter regardless of config. | Audit history (history.json event + iteration-history.md narrative paragraph) |
| Refine plan | Run the architect synchronously with your feedback to update plan.md, then continue with the next iteration. |
Architect prompt |
| Ask Reflection to decide | Spawn reflection in consult mode with your feedback. Reflection sets harness_action_recommendation in its signals; harness routes per the recommendation. |
Reflection prompt (consult mode) |
Which actions are available depends on why the loop paused — the UI hides actions that don't make sense for the current pause case (e.g. you can't Refine plan when the dev agent is mid-iteration asking a question; you can't Finish loop when the loop hasn't started yet because the pre-loop review was blocked). The CLI rejects inapplicable --action values with a clear error and the list of allowed actions.
Special pause case: SCOPE_COMPLETE (architect verdict, item 6.25 follow-up). When the Solution Architect determines that your Problem Pack describes work that's already implemented + tested in the source tree (e.g. you re-launched a loop on a previously-completed workspace), the loop pauses with pauseReason: "scope_complete" regardless of your readinessGate setting. The available actions narrow to:
- Finish loop — refresh the documenter (if
autoDocumenter=true) and end on a positive note. Useful when you want updated docs but no new implementation. - Stop loop now — accept that the project is done; terminate the loop and capture any feedback you provide as audit history.
- Refine plan — add new requirements to
problem-pack/problem.md+success.md, then re-run the architect with your feedback as direction.
Continue and Ask Reflection to decide are hidden because there's no work to continue with and no iterations for reflection to reflect on.
No bare "Resume." You always pick an action. The textarea is optional context; the action button is required. This forces clarity of intent — no silent "resume = continue" shortcut.
Examples:
# Review the state before deciding
cat cfcf-docs/judge-assessment.md
cat cfcf-docs/reflection-analysis.md
cat cfcf-docs/plan.md
# Continue with guidance for the dev agent
cfcf resume --workspace my-project --action continue --feedback "Focus on error handling"
# We're done — wrap up properly (runs documenter if autoDocumenter=true)
cfcf resume --workspace my-project --action finish_loop
# Wrong direction; stop immediately, no docs
cfcf resume --workspace my-project --action stop_loop_now --feedback "Wrong approach; will rewrite the spec"
# Plan needs work; route through architect first, then iterate
cfcf resume --workspace my-project --action refine_plan --feedback "Drop the Redis dependency; use in-memory store"
# Not sure; let reflection decide
cfcf resume --workspace my-project --action consult_reflection --feedback "I think the loop is converging but iter-3 worried me; what do you think?"
# Hard stop independent of pause (kills the loop process)
cfcf stop --workspace my-projectstop_loop_now vs Stop loop (the CLI cfcf stop command). Different concepts:
stop_loop_nowresume action: requires the loop to be paused first; captures your feedback as audit; clean shutdown.cfcf stop: works whenever the loop is running; kills agent processes; no feedback capture; for "I need this to stop right now regardless of state."
Outside the iteration loop, you can invoke the Reflection role manually:
cfcf reflect --workspace my-project
cfcf reflect --workspace my-project --prompt "focus on the auth-layer drift"This is useful when you:
- Want a strategic health-check on a long-running project without running another iteration.
- Added new requirements and want reflection to suggest plan changes before kicking off the next loop.
- Want to see whether the reflection agent would recommend stopping (its
recommend_stopsignal).
Ad-hoc reflection does NOT modify loop-state.json and does NOT write an iteration-log (no iteration happened). It DOES write reflection-analysis.md, update cfcf-reflection-signals.json, and append a decision-log.md entry so the strategic note survives for the next loop.
When the judge determines SUCCESS, cf² automatically runs the Documenter agent before completing the loop. The documenter reads the final codebase and produces polished documentation:
docs/architecture.md-- system architecture, components, data flowdocs/api-reference.md-- API endpoints, data models, error handlingdocs/setup-guide.md-- prerequisites, installation, running, testingdocs/README.md-- project overview and quick start
These build on the doc stubs created by the architect and maintained by the dev agent.
You can also run the documenter manually at any time:
cfcf document --workspace my-projectThis is useful for regenerating docs after manual code changes, or if you want to run it on a project that didn't go through the full loop.
After the process completes (success, max iterations, or user stop):
# See the per-iteration commits -- dev / judge / reflect appear as a three-commit story
cd /path/to/my-project
git log --oneline --all | grep "cfcf iteration"
# Read the final handoff
cat cfcf-docs/iteration-handoff.md
# Read the judge's final assessment
cat cfcf-docs/judge-assessment.md
# Read the latest reflection analysis
cat cfcf-docs/reflection-analysis.md
# Review the full iteration history (rebuilt from iteration-logs)
cat cfcf-docs/iteration-history.md
# Browse per-iteration changelogs
ls cfcf-docs/iteration-logs/
cat cfcf-docs/iteration-logs/iteration-3.md
# Browse archived reflection analyses
ls cfcf-docs/reflection-reviews/
# Check the cross-role decision log
cat cfcf-docs/decision-log.md
# Read the generated documentation
cat docs/architecture.md
cat docs/setup-guide.md
# View any iteration's full agent log
cat ~/.cfcf/logs/<project-id>/iteration-NNN-dev.log
cat ~/.cfcf/logs/<project-id>/reflection-NNN.logcf² is designed for the "add more work later" case. The flow for extending a successful project:
1. Edit problem-pack/problem.md + success.md with the new requirements.
2. cfcf review --workspace my-project
→ architect enters re-review mode, reads the full history, appends
new pending iterations to plan.md (or says "plan is still valid")
3. (Optional) cfcf reflect --workspace my-project
→ ad-hoc reflection confirms health + notes any strategic concerns
4. cfcf run --workspace my-project
→ loop picks up the next pending iteration in the appended plan
Because the non-destructive rules are applied to both architect re-review and reflection-during-loop, completed work from prior iterations is never lost.
SCOPE_COMPLETE is the architect's verdict for this scenario. When you re-launch a loop on a workspace whose Problem Pack is already fully delivered (e.g. you ran cfcf run on a finished project without editing the spec), the pre-loop architect review returns readiness: SCOPE_COMPLETE and the loop pauses before iteration 1 with pauseReason: "scope_complete". From there:
cfcf resume --workspace <name> --action refine_plan --feedback "<new requirements>"— extend the scope. Architect reads your feedback + the (now-edited) Problem Pack and appends new pending iterations toplan.md. The loop resumes with the next iteration.cfcf resume --workspace <name> --action finish_loop— wrap up via the documenter to refresh the final docs (ifautoDocumenter=true) and end on a positive note.cfcf resume --workspace <name> --action stop_loop_now— accept that the project is done and terminate without running the documenter; any--feedbackbecomes audit history on the newloop-stoppedevent.
| Task | When | Required? |
|---|---|---|
| Start the server | Before any cf² commands | Yes (once) |
Run cfcf init |
First use only | Yes (once) |
| Create/provide the git repo | Before project init | Yes |
Run cfcf workspace init |
Once per project | Yes |
Write problem.md |
Before launching iterations | Yes -- critical |
Write success.md |
Before launching iterations | Yes -- critical |
Write constraints.md |
Before launching iterations | Optional |
Write hints.md |
Before launching or between iterations | Optional |
Write style-guide.md |
Before launching iterations | Optional |
Add context/*.md files |
Before launching iterations | Optional (recommended for existing repos) |
Run cfcf review (Solution Architect) |
Before launching iterations, or to re-review after adding requirements | Optional (recommended) |
Launch cfcf run |
When Problem Pack is ready | Yes (once per development cycle) |
| Review results at pause points | When cf² pauses and asks | Recommended |
| Provide feedback at pause points | When cf² pauses and asks | Optional but valuable |
Run cfcf reflect |
Ad-hoc strategic health-check, or between extending-loop invocations | Optional |
| Task | When |
|---|---|
Scaffold problem-pack/ templates |
On cfcf workspace init |
| Solution Architect review (first-run or re-review) | On cfcf review (user-triggered, advisory) |
| Assemble context (sentinel-merged CLAUDE.md/AGENTS.md + cfcf-docs/) | Before each iteration |
| Preserve user content in CLAUDE.md/AGENTS.md outside sentinel markers | Every iteration |
Rebuild iteration-history.md from committed iteration-logs |
Before each iteration |
| Create git feature branches | Before each iteration |
| Launch dev agent with proper flags | Each iteration |
| Capture and store agent logs | During each iteration |
| Parse handoff document + signal file | After each iteration |
| Launch judge agent | After each iteration |
| Launch reflection agent (unless judge opts out and safeguard not hit) | After each judge |
| Non-destructively validate plan rewrites by reflection or architect | Each time plan.md changes |
| Produce three separate commits per iteration (dev / judge / reflect) | Each iteration |
| Determine next action (continue/stop/alert) | After each iteration |
| Merge to main on iteration completion | After each iteration (auto-merge mode) |
| Archive judge assessments + reflection analyses | After each iteration |
| Emit pulsing activity indicator in web UI | Whenever any agent is running anywhere |
| Alert user when input is needed | When detected |
| Warn when decision log crosses 50 entries | Once per loop run |
| Run documenter on SUCCESS | After judge says SUCCESS |
| Persist loop state to disk | On every phase transition |
| Monitor and report progress via CLI | Continuously during execution |
# One-time setup
cfcf server start # Start server
cfcf init # First-run config (five agent roles)
# Per-project setup
cfcf workspace init --repo <path> --name <name> # Register project
# Edit problem-pack/problem.md and success.md # USER WRITES THESE
# Solution Architect review (optional, recommended)
cfcf review --workspace <name> # Get feedback + plan outline
# (re-review-aware on existing projects)
# Read cfcf-docs/architect-review.md # Review suggestions
# Refine problem-pack/ files, repeat if desired
# Launch the dark factory
cfcf run --workspace <name> # cf² takes over
# Monitor (while running)
cfcf status --workspace <name> # Current state
tail -f ~/.cfcf/logs/<id>/iteration-NNN-dev.log # Live dev output
tail -f ~/.cfcf/logs/<id>/reflection-NNN.log # Live reflection output
# At pause points
cfcf resume --workspace <name> # Continue after review
cfcf resume --workspace <name> --feedback "..." # Continue with direction
cfcf stop --workspace <name> # Stop the process
# Strategic health-check (ad-hoc, no iteration)
cfcf reflect --workspace <name>
cfcf reflect --workspace <name> --prompt "focus on X"
# Documentation (on-demand, also runs auto post-SUCCESS)
cfcf document --workspace <name> # Generate polished docs
# Manual mode (testing)
cfcf run --workspace <name> -- <cmd> # Run a specific command
# Management
cfcf workspace show <name> # Project config
cfcf workspace list # All projects
cfcf config show # Global config
cfcf server stop # Stop server