ForgeFlow

A software delivery workshop for Claude Code and Codex.

Turn an idea into a scoped brief, working code, an evidence-backed review, and a clear shipping handoff. ForgeFlow coordinates specialist agents, keeps useful project context, and makes reported work visible in a local dashboard with Ember, a small robot tending the forge.

Visit the ForgeFlow website · Built by Cory Ebert

Start here: Visual user guide · 19-page PDF · Documentation · Install

Development: Roadmap and implementation progress · Current status and next session

Workshop screenshot uses illustrative example data.

Intelligent capabilities: nine procedures implemented

ForgeFlow can select specialized procedures from task intent, affected code and workflow phase. Selection supports mixed-domain tasks, explicit overrides and bounded reassessment. Managed Claude Code and Codex workflows include the selection entry points.

All nine planned capabilities are implemented for controlled evaluation:

Capability	What it checks
Change propagation	Sources, consumers, generated artifacts and freshness
Visual acceptance	Surrounding layout, responsive behavior, typography and accessibility
Persistence recovery	Interrupted writes, stale readers, concurrent cleanup and reload behavior
Review calibration	Verified defects, missed defects, unsupported findings and severity
Provider compatibility	Response drift, partial failures, cancellation and stale data
Release qualification	Served web artifacts and native installation, restart, update and rollback
Benchmark verification	Executing backend, effective controls, correctness and separate performance metrics
Money/calendar correctness	Amount units, rounding, conservation, recurrence anchors, missing data and read-only behavior
CAD/fabrication acceptance

Use capabilities when the task needs them

The task owner can pull a relevant procedure on demand after recording a grounded reason, bounded scope, available prerequisites and a budget within the authorized task. Keywords and include overrides alone do not activate a procedure. Existing permissions, explicit exclusions and required acceptance checks still apply. Reuse current agents and evidence; selecting a procedure does not start a benchmark or another review cohort.

All nine procedures retain evaluation benefit labels. Existing studies report mixed, case-specific outcomes; they establish no general accuracy, speed or cost advantage. Managed Claude Code and Codex installations support assessed selection. The lean Codex plugin does not expose the managed capability entry point. Live client discovery, additional platforms, live providers and physical fabrication remain separate qualification work.

See the selection policy, capability contract and host support, readiness assessment and historical evidence.

New in 4.7.0

• Immutable review evidence: pin complete source bytes and review inputs, retrieve exact references, and detect stale or interrupted evidence.
• Bounded specialist follow-up: preserve focused assignments and cumulative request limits; denied or exhausted requests remain explicit uncertainty.
• One review preparation operation: collect scope, compile packets, measure budgets and prepare bounded waves. Return ready inputs or a named blocker while preserving required coverage and proof. Reuse completed preparation only when its inputs and source still match.
• On-demand capability use: let the task owner choose procedures within the existing task authority and budget.
• Proportional validation: use one relevant owned-PR walkthrough and focused safety checks for ordinary feature work. Comparative benefit studies require a separate request.

The GitHub release includes a managed-runtime archive and SHA-256 checksums. It omits evaluation fixtures and completion study runners; use the source checkout for research reproduction.

Read the 4.7.0 release notes and review and execution guide. Update managed installations and restart host sessions to load the new instructions. The illustrated guide remains a source-edition walkthrough; this README and wiki describe the current release.

New in 4.6.3

Workflow state and review attribution stay local. Public drafts omit internal evidence links, publication checks block tracked session state, and both host installations receive the same local-only rules. See the 4.6.3 release notes.

New in 4.6.2

Local shipping previews now include staged and unstaged edits and nonignored new files alongside committed branch changes. Each path appears once, and the count matches the file list. Renames appear as a deletion and an addition. Task validation and reviewer approval remain separate from file inclusion. See shipping preview behavior and the 4.6.2 release notes.

Communication guidance from 4.6.1

ForgeFlow's writing guidance now asks agents to match the reader's background, explain useful findings during progress updates, and describe concrete user outcomes. Final replies summarize relevant checks and keep uncertainty explicit. The update preserves exact technical details and required output formats. See the communication guide and 4.6.1 release notes.

Agent names introduced in 4.6.0

Agents now use names that describe their work: Builder, Guardian, Designer, Coordinator, Architect, Product Lead, and Verifier. Logs and dashboards show explicit task context, and agent prompts apply Orwell's six writing rules for clear CLI output.

Upgrading from legacy role names: use the source-checkout upgrade procedure for this first migration. Do not start it with an old installed updater. The new installer preserves edited legacy agents and installs the updater used for later releases.

This release also fixes historical learning IDs, mixed-name report totals, stale context packets, cleanup scope, rollback snapshots, lifecycle limits, and debate instructions. See the 4.6.0 release notes. ForgeFlow's repository runs validation locally; GitHub Actions remains disabled.

Your first ForgeFlow session

For a change you want to carry across sessions, use /task in Claude Code or $task in Codex. Tasks connect acceptance criteria to the code that was checked, preserve interrupted phase history, and appear at the top of the workshop. Changed source or evidence makes earlier proof stale while preserving the historical result. See task evidence and recovery for check commands, resume, evaluation, memory feedback, fleet contracts, and local maintenance drafts.

You do not need the whole command catalog to start. Pick one small, observable improvement, such as a clearer empty state or a focused bug fix.

Step	Claude Code	Codex	What you should get
Design the change	/consult	$consult	A concrete brief with scope, behavior, and validation
Build it	/implement	$implement	Focused code changes and the results of relevant checks
Review it	/review	$forge-review	Findings tied to evidence, followed by a technical verdict
Prepare to ship	/ship	$ship	A summary, presentation, and proposed PR description

Add your task after the command. Run one phase at a time, inspect the result, and steer the assistant when something needs to change. In Codex, use $forge-review for ForgeFlow; /review is the host’s built-in review.

For example, after installation, type this into Codex:

$consult plan a helpful empty state for the task list. Reuse the existing Create task form, include keyboard behavior, and keep the change local.
$implement execute the current brief and run the relevant checks
$forge-review review the current changes against the brief
$ship prepare the branch and summarize validation

Use the Claude Code equivalents from the table in that host. When you are ready for remote actions, explicitly request the commit, push, PR, or deployment you want. Preparing a shipping handoff does not itself authorize every release action.

Visual user guide

The illustrated guide takes a new user through installation, a first project, every delivery phase, the workshop dashboard, Ember’s states, context and memory, troubleshooting, and shipping.

• Interactive HTML guide: 18 chapters, annotated screenshots, examples for both hosts, copy controls, and a checklist saved in your browser. Read it on the website, or download the standalone HTML file from GitHub and open it in a browser. Images, styles, and scripts are embedded, so the guide works offline; linked reference documents need a connection.
• Printable PDF guide: 19 pages with a linked contents page, both hosts’ examples, and the visual reference material. Ready to share with someone new to ForgeFlow.

The guide identifies the source commit it describes. For the latest implementation details, use this README and the workflow reference.

Quick start

Upgrading an existing installation to the renamed roles: follow the source-checkout migration before running an installed updater. The old updater cannot preserve edited legacy role files.

You need Git, Node.js with npm, Bash for the shell helpers, and a working Claude Code or Codex setup with access to the models you intend to use. Use Node.js 24 for this repository's local validation. The examples below use Bash; keep the host, installation, and project in the same shell environment.

RTK is optional. The installer checks rtk --version and rtk gain; ordinary installation does not download RTK. Use direct commands when it is unavailable. To opt in to a Cargo-based RTK installation, add --install-rtk (preview with --install-rtk --dry-run). See optional RTK setup.

Clone the source:

git clone https://github.com/BrandedTamarasu-glitch/ForgeFlow.git
cd ForgeFlow

Install into Codex

Preview the managed destinations, then install:

node scripts/forgeflow/install-template.js --target codex --dry-run --json
node scripts/forgeflow/install-template.js --target codex

Restart Codex so it discovers the agents and skills. The installer respects CODEX_HOME, copies runtime helpers into its forgeflow/ directory, and preserves unrelated host configuration. It does not merge the repository’s sample config into yours.

Use $quick or $consult in your project to confirm discovery. All ForgeFlow agents inherit your Codex session's model and reasoning settings by default. If an older installation reports a model unsupported by your account, update the checkout, rerun the Codex installer, and start a fresh session. Custom model overrides must use models available to your account. See Codex first run.

Install into Claude Code

From the same source checkout:

node scripts/forgeflow/install-template.js --target claude --dry-run --json
node scripts/forgeflow/install-template.js --target claude

Restart Claude Code. The installer registers Ember's UserPromptSubmit hook, preserves existing settings, and backs up settings before changing them. Merge the other documented hooks and status line manually, avoiding duplicate registrations. See Settings and Recovery.

After the canonical-role migration above, /update-forgeflow is the regular Claude updater; --repair reinstalls missing or damaged managed files. The source updater also supports --target codex. Both targets can restore the previous managed-file snapshot with --rollback when available. Codex's $update-forgeflow skill handles checkout synchronization; use the recovery instructions for installed-runtime rollback.

To install both hosts from a checkout, use --target both. See the template installer for custom home directories.

Enable the optional dashboard

Set the runtime path for the host you installed:

# Codex:
FF_RUNTIME="${CODEX_HOME:-$HOME/.codex}/forgeflow"

# Or Claude Code:
# FF_RUNTIME="$HOME/.claude/forgeflow"

The installer prepares the local services' locked dependencies automatically. If setup reports missing dependencies, repair them with:

npm ci --prefix "$FF_RUNTIME/services/dashboard" --ignore-scripts --no-audit --no-fund
npm ci --prefix "$FF_RUNTIME/services/agent-chat" --ignore-scripts --no-audit --no-fund

On the first eligible ForgeFlow workflow invocation in a desktop session, ForgeFlow starts or reuses the dashboard and activity service, reports the phase, and opens http://127.0.0.1:4003/. Later invocations reuse the services without opening more tabs. Automatic startup never installs dependencies.

Start in your application repository

Replace the example path with the repository you want to improve:

cd /path/to/your-project
git status --short
bash "$FF_RUNTIME/scripts/forgeflow/ensure-forgeflow-state.sh"
node "$FF_RUNTIME/scripts/forgeflow/seed-budget-config.js" --json

The helpers create project-local workflow state and seed a context budget without overwriting an existing budget config. Inspect the repository state, choose a suitably scoped branch, and start with the first-session commands above. Your application work belongs in this repository, not in the ForgeFlow source checkout unless ForgeFlow itself is the project.

Choose your workflow

flowchart LR
    D[Discuss] --> R[Research]
    R --> P[Plan]
    P --> C[Consult]
    C --> I[Implement]
    I --> V[Review]
    V -->|Corrections needed| I
    V -->|Conditions resolved| S[Ship]

Enter where the work needs you:

• Quick: a small, clear task or bounded orientation. /quick or $quick selects useful specialists.
• Consult → implement → review → ship: a feature with a known goal that needs a concrete design and validation.
• Discuss → research → plan: an uncertain product or architecture decision before implementation begins.
• Audit: a deeper look at a subsystem’s security, systems, or code quality.

Focused research explains whether it chooses normal or divergent research. Use --no-diverge for a focused investigation or --diverge when you deliberately want independent approaches to a consequential decision. See research routing.

The Claude command catalog is larger than the installed Codex skill set. Do not assume every slash command has a dollar-prefixed equivalent. The user paths and workflow reference cover the extended tools, including UI iteration, fleet work, and handoffs.

The agents

Agent	Responsibility
Builder	Backend craft, data structures, naming, and maintainability
Guardian	Security, validation, system boundaries, and reuse
Designer	UX, accessibility, frontend quality, and connectivity
Coordinator	Scope, coordination, project memory, implementation notes, and developer shipping summaries
Architect	Architecture synthesis, implementation briefs, integration checks, technical verdicts, and debate judging
Product Lead	Problem framing, research, planning, acceptance validation, final review, and stakeholder shipping summaries
Verifier	Neutral verification of high-risk findings using visible evidence

ForgeFlow chooses agents according to the task. A small change need not invoke the full cast. The agent reference covers phase responsibilities, host identifiers, and the old-to-new name mapping. /debate or $debate uses a code sample and a withheld answer key to assess false positives and misses; Product Lead validates the final debate against that key.

Dashboard

Installers now prepare Ember dependencies and Claude’s prompt hook automatically, preserving existing settings. Setup failures are non-blocking and include repair instructions. Use the dashboard readiness check when moving to another computer.

The workshop balances what is happening now, what needs attention, and how recorded review outcomes change over time.

Area	What it shows
Task evidence	Acceptance criteria, current or stale proof, phase history, and next action for tasks in the launched repository
Ember	Explicit activity in the current chat room, including planning, research, implementation, review, testing, waiting, failure, and completion
Project health	Saved readiness evidence for the repository that launched the dashboard, with a copy-only next action
Review outcomes	All-time verdict totals for the selected summary project; conditional approvals have their own total
Review trends	Verdicts across all projects for the latest 4, 12, or all recorded ISO weeks
Live activity	Reported phases and agent messages, with filters and bounded recent history

Ember blinks, polishes, and dozes when idle. Animation studio lets you preview poses without changing live reports. Pause motion and reduced-motion preferences leave activity updates running. Offline means disconnected; an active report over 90 seconds old becomes Waiting for an update. Success requires an explicit completion report.

Readiness separates actionable problems from informational evidence. Missing optional benchmarks, cross-host probes, release snapshots, or failure digests do not imply that the installation is broken. Saved blockers and unreadable evidence still require attention. Expand the details to see the underlying status.

Empty charts can be normal: they require recorded verdicts. Codex review and implementation skills explicitly save real Architect and Product Lead decisions with evidence and a stable event ID to prevent duplicates. Planning or test activity does not create approvals, and older unrecorded reviews are not inferred or backfilled.

Refresh data updates tasks, metrics, and readiness independently, preserving a previous snapshot with a stale label if a refresh fails. The summary project selector does not change the launched readiness scope or Ember’s current room.

Set FORGEFLOW_DASHBOARD_AUTO_OPEN=off to disable automatic startup and opening. CI, SSH, headless Linux, and sessions without a stable host session ID skip it automatically. To run the dashboard manually from the intended project:

node "$FF_RUNTIME/services/dashboard/server.js"

Start the activity service with $agent-chat-on in Codex or /agent-chat:on in Claude Code. That service also provides a separate chat view at http://127.0.0.1:4001/. See the dashboard reference and activity reporting contract.

Review routing and evidence

ForgeFlow's workflow instructions carry five questions through design, implementation, validation, review, and shipping: Is this the simplest effective change? Is its complexity proportional to the app and its risks? Does it serve one concern? Why does it work? What was checked, and what happened? Agents must connect their answers to the actual change and observed evidence; their assessment does not substitute for human approval.

Consultation starts with the primary domain specialist and adds specialists for concrete risks or uncertainty. An explicit full-team request still selects the full team. Architect synthesizes the brief, and downstream validation and review remain separate checks.

Review routing chooses skip, thin, full, or deep mode based on the change and explains the decision. High-risk findings can pass through Verifier before they become blockers.

Architect returns APPROVE, CONDITIONAL APPROVE, REVISE, or BLOCK. Product Lead can CONFIRM or CHALLENGE the verdict. Read the scope, conditions, and validation behind those labels; a verdict is not a substitute for the checks your project requires.

Claude’s /review-auto provides conservative repair paths with additional constraints. /forgeflow-review-auto-classify previews finding categories before repair. See review routing for context preparation and verification details.

Context that carries forward

ForgeFlow stores plans, briefs, implementation notes, review evidence, and compact context under .forgeflow/<project-name>/, ignored by Git by default.

• Focused context: file scope, memory selection, ownership packets, and context budgets help keep agent inputs relevant. Dependency advice requires a task reference; focused memory uses module references and links broader history instead of repeating it.
• Project intelligence: code maps, operating models, architecture, ownership, and invocation hints guide unfamiliar work.
• Implementation notes: decisions, tradeoffs, deviations, follow-ups, and validation stay available for review and handoff.
• Project learnings: repeated patterns and observed outcomes inform the next task, subject to current code and instructions.
• Explicit preferences: local advisory profiles capture how you want the assistant to work; they do not override your current request.

Lean guidance keeps the implementation proportional to the task: prefer the stdlib, native platform capabilities, and installed dependencies before adding new machinery, and run at least one focused check that demonstrates the intended behavior. Smaller scope must preserve trust-boundary validation, data-loss prevention, security, accessibility, and explicit requirements. Calibration and tuning remain evidence-driven; sparse telemetry is a reason to collect real outcomes, not to weaken those checks.

For Claude workflows, /forgeflow-trends --refresh refreshes project guidance, and /forgeflow-learnings --project --check inspects the learning quality gate. Existing focused context packets are preserved during learning smoke checks. From a ForgeFlow checkout, node scripts/forgeflow/smoke-check.js --json checks downstream readiness; use the installed helper path when working in another repository.

See context intelligence, project learnings, implementation notes, and user profile guidance.

Forgeflow stores memory locally by default; Obsidian is not required. For the same project on multiple computers, optionally connect an Obsidian vault to share curated notes. Local memory continues working if the vault is unavailable. Forgeflow retrieves relevant shared notes and checks referenced source files; your vault sync service handles device transfer.

Optional Obsidian memory sharing

• Edit ordinary YAML properties, rename notes, and keep personal annotations separate from shared guidance.
• Retain failed memory publications in a local queue and retry them without duplicating revisions.
• Generate a project home page and curated handoffs for continuing on another computer.
• Withhold stale or conflicting shared guidance; transferred notes never count as current test evidence.

Opt in separately for each checkout, using the same project ID on both computers:

node scripts/forgeflow/vault-memory.js connect --vault /path/to/vault --project-id my-project --publish-learnings
node scripts/forgeflow/vault-memory.js status
node scripts/forgeflow/vault-memory.js home

Use the installed helper path when working outside the ForgeFlow source checkout. No Obsidian plugin or account integration is required. See the vault guide for note and handoff inputs, explicit retry, disconnect, and recovery limits.

Local data and sharing

The dashboard and saved workflow evidence are local. Metrics use ~/.claude/projects/ and ~/.codex/projects/ by default; configured runtime-home and metrics-root overrides are respected. Dashboard controls inspect, filter, refresh, expand, or copy commands. They do not execute the suggested fixes.

Local-first does not mean offline AI: your host may send task context to its model provider, and dependency installation or GitHub operations use the network. Review context packets, telemetry, notes, and support bundles before sharing. Keep credentials and private project details out of public artifacts.

See local data and privacy and team privacy boundaries.

Development and releases

From the ForgeFlow source checkout:

npm ci --ignore-scripts
npm test

ForgeFlow runs tests, builds, and agent reviews locally. GitHub Actions is disabled for this repository, which uses GitHub only for release pushes and release artifacts. Keep development changes and shipping evidence local until an explicitly requested release. Downstream projects choose their own CI and deployment policy.

Use the release process and release gate before tagging or publishing ForgeFlow itself. A commit on main and a packaged release version describe different things; the visual guide identifies the source revision it documents.

Documentation

You want to…	Start here
Learn ForgeFlow from beginning to end	Visual guide · PDF
Find a command or choose an entry point	User paths · Workflow reference
Install or recover a host setup	Template installer · Codex first run · Settings and recovery
Understand context and evidence	Context intelligence · Lean evidence · Telemetry readiness
Try ForgeFlow with a team	Adoption pack · Team adoption criteria

License

MIT. See LICENSE.

Local-only workflow boundary

• Treat every .forgeflow/ directory, its contents, and workflow agent identities as local working context only. Never stage, commit, push, attach, upload, or sync this state, including through memory-sync commands. Use Git's local info/exclude for generated state; never force-add it. Ignore rules do not protect already tracked files.
• Never include local artifact paths, agent names, persona names, role labels, agent verdict attribution, or workflow signatures in PR titles, bodies, comments, commit messages, release notes, or published artifacts. Describe the change and observed validation in ordinary engineering language. Keep detailed review attribution and evidence links in local reports.
• Never insert workflow agent identities or local evidence references into application source, comments, docstrings, tests, fixtures, identifiers, UI text, or shipped documentation. Use domain-based names and explain technical reasons without agent attribution.
• Before staging or publishing, inspect the actual staged diff, outgoing commits, and public text. A local-state file or workflow attribution leak blocks the action until corrected. Do not silently delete local evidence or rewrite existing history; report already tracked or committed state for cleanup.
• These rules govern project work produced with Forgeflow. Forgeflow's own maintained agent definitions, integration code, and documentation may name the agents and state paths needed to implement the tool; generated session state is always local. Ordinary domain terms that happen to match a role name are not workflow attribution.
• Local CLI labels, orchestration messages, and local report schemas may retain identities. This boundary takes precedence over instructions to copy local reports into public output or sync session memory.