Your first idea.
Your next finished feature.

MEET EMBER

Make the work visible.

ForgeFlow gives your coding assistant a repeatable way to understand a task, involve specialists, build carefully, and check the result. Ember shows the workflow’s reported activity.

Workflow reference verified against ForgeFlow commit 1353184 · 6 September 2026
Visual identity and workshop screenshot refreshed 22 September 2026. The workshop screenshot uses illustrative example data. Ember gallery images use its labeled preview controls. Example project prompts describe a teaching scenario, not a completed project.

Choose the smallest useful entry point

Not every task needs every agent or every phase. A route can be skip, thin, full, or deep, depending on the change. Ask for the reason when the route is unclear.

Brief: the implementation contract. Artifact: a saved local result, such as that brief. Host: Claude Code or Codex, where you talk to the assistant.

The repository’s CI validates on Node.js 24. These terminal examples use Bash; Windows users need a compatible Bash environment, such as WSL, with the host and files in that same environment. ForgeFlow uses your host’s available model access and permissions.

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

Choose one host below. Preview the destinations, then install. This runs from the ForgeFlow checkout, not from your application repository.

node scripts/forgeflow/install-template.js --target codex --dry-run --json
node scripts/forgeflow/install-template.js --target codex
FF_RUNTIME="${CODEX_HOME:-$HOME/.codex}/forgeflow"

node scripts/forgeflow/install-template.js --target claude --dry-run --json
node scripts/forgeflow/install-template.js --target claude
FF_RUNTIME="$HOME/.claude/forgeflow"

To install both, use --target both. The template installer copies managed files and preserves unrelated configuration; it does not merge your host settings.

Enable the optional local dashboard

npm install --prefix "$FF_RUNTIME/services/dashboard" --ignore-scripts
npm install --prefix "$FF_RUNTIME/services/agent-chat" --ignore-scripts

Claude Code hook wiring checklist

Use the repository’s manual settings guidance as the source for the merge. A command should use an expanded home path, such as node "$HOME/.claude/hooks/forgeflow-telemetry.js". Ask the assistant to inspect the existing settings and present the exact additions before applying them.

Inspect my existing Claude Code settings and ForgeFlow’s post-install hook guidance. Show the additions needed for hooks and the status line, preserving unrelated settings and avoiding duplicate registrations.

Validate the resulting JSON, restart Claude Code, and run /forgeflow-health. See Settings and Recovery for the detailed wiring and recovery reference.

Open the repository you actually want to improve. Replace the example path below, confirm the Git state, and choose a new branch name.

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

The first helper creates local workflow folders and ignores .forgeflow/. The budget helper seeds a config without overwriting an existing one. Inspect any repository changes before committing.

Give the assistant a bounded orientation task

$quick inspect this repository. Identify how to run it, its relevant tests, and a small first task. Read only; do not edit files.

/quick inspect this repository. Identify how to run it, its relevant tests, and a small first task. Read only; do not edit files.

Optional deeper orientation

Ask for the first-run guide, a project code map, or a project operating model if the repository is unfamiliar. Missing optional reports are normal before you generate them. The general health helper includes Claude installation assumptions; use Codex file discovery and its actual skills to verify a Codex installation rather than treating every Claude inventory item as required.

$consult produce an implementation brief for an empty task-list state. Show “No tasks yet” and a Create task button using the existing form. Cover keyboard access, loading, and errors. Keep the change local.

/consult produce an implementation brief for an empty task-list state. Show “No tasks yet” and a Create task button using the existing form. Cover keyboard access, loading, and errors. Keep the change local.

1. Read the brief

   Confirm where the change belongs, what is out of scope, and which checks will prove it works. Correct misunderstandings now.

2. Implement the brief

   Run the implementation command below. The assistant should name the files changed and explain validation.

3. Try the feature

   Open the app, visit an empty list, and activate Create task with both mouse and keyboard. Check loading and error states too.

4. Request a review

   Run the review command. Ask for concrete findings tied to this change. Resolve required corrections and rerun affected checks.

5. Prepare the handoff

   Run Ship to prepare a summary. Inspect the diff and test results before requesting a commit, push, or deployment.

$implement execute the current brief
$forge-review review the current changes against the brief
$ship prepare the branch and summarize validation

/implement execute the current brief
/review review the current changes against the brief
/ship prepare the branch and summarize validation

$discuss users cannot tell whether an empty task list means no tasks, loading, or an error. Frame the behavior and acceptance criteria.
$research compare ways to reuse the current task form from the empty state. Inspect existing patterns first.

/discuss users cannot tell whether an empty task list means no tasks, loading, or an error. Frame the behavior and acceptance criteria.
/research compare ways to reuse the current task form from the empty state. Inspect existing patterns first.

Three questions to answer before planning

When research branches

Focused research automatically chooses normal or divergent research and explains the route. Use --no-diverge for a focused investigation, or --diverge when you deliberately want independent approaches to a consequential decision.

$research --no-diverge investigate why the current task form loses keyboard focus

/research --no-diverge investigate why the current task form loses keyboard focus

$plan create a phased plan for the empty-state change, including keyboard validation and scope boundaries.
$consult turn the plan into a concrete implementation brief using existing components.

/plan create a phased plan for the empty-state change, including keyboard validation and scope boundaries.
/consult turn the plan into a concrete implementation brief using existing components.

The usual local files are .forgeflow/<project>/current-plan.md and current-brief.md. The implementation workflow expects the current brief, so check that it describes this task rather than a previous one.

$implement execute the current brief. Preserve unrelated edits, run relevant checks, and report any scope change before broadening the work.

/implement execute the current brief. Preserve unrelated edits, run relevant checks, and report any scope change before broadening the work.

1. Confirm the starting point

   The assistant reads the current brief, identifies relevant files, and uses compact context and ownership notes when available.

2. Build in focused pieces

   Specialists work where useful. A shared interface or overlapping file ownership should be resolved before parallel edits cause conflicts.

3. Validate the behavior

   Product Lead focuses on the required checks; integration review checks that the pieces fit. The exact commands depend on your application.

4. Record decisions and gaps

   Implementation notes preserve choices, tradeoffs, deviations, follow-ups, and validation evidence for the next phase.

Useful steering while the assistant works

Keep the change limited to the task-list view and its tests.
Explain the test failure before changing the implementation.
Show what changed from the brief and why.
Pause before any database migration or deployment.

$forge-review review this branch against main and the current brief. Prioritize concrete correctness, security, and accessibility findings.

/review review this branch against main and the current brief. Prioritize concrete correctness, security, and accessibility findings.

Product Lead can CONFIRM or CHALLENGE the verdict. Verifier can confirm, reject, or block a high-risk finding from visible evidence. These are different roles, not interchangeable approval labels.

What a useful finding contains

A location, a concrete trigger, an explanation of the effect, and enough evidence to judge the proposed correction. Ask for clarification if a finding is only a preference or a vague prediction.

Fix the confirmed findings from this review. Keep the patch scoped, rerun the affected checks, and request a follow-up review.

For a deeper examination of a subsystem, use /audit or $audit. For conservative automated repair in Claude Code, /review-auto has additional rules and limits. There is no matching installed Codex $review-auto skill in this edition.

Gallery captured using Animation studio previews. The live text label is the authoritative description, including for screen readers.

When several agents report, fresh failures and waiting states take priority over active work; active work takes priority over completion. Ember may therefore show an issue even while another agent has finished.

Readiness has two distinct kinds of information

Watch with zero actionable warnings can mean optional evidence is still incomplete. It does not mean those optional activities were performed or passed. Lean injection can remain unavailable when evidence is too thin; the underlying status stays visible.

Refresh and freshness

Refresh data fetches metrics and readiness separately. A failed refresh keeps the previous snapshot and labels it stale. Initial errors say Unavailable. The live WebSocket connects independently. Refresh the browser after installing a new dashboard version.

Most local artifacts live under .forgeflow/<project>/. Treat them as advisory context. Current instructions, code, and test evidence take precedence.

When the context budget warns

Ask the assistant to identify the oversized packet, narrow the file list, and trim unrelated memory or split the work into review waves. Do not increase a budget just to turn a warning green. The default compact-token limit is 16,000 unless project configuration changes it.

node "$FF_RUNTIME/scripts/forgeflow/check-context-budget.js" --root .forgeflow --warn-only --json
node "$FF_RUNTIME/scripts/forgeflow/advise-context.js" --root .forgeflow --record --json

The advisor can record local trend history. Token figures are estimates; they are not a bill or proof of a model’s actual usage.

Preferences and resuming

Tell ForgeFlow how you want it to work, such as concise updates and explicit validation status. Ask to record only preferences you intentionally choose. Keep project-specific design preferences local to that project.

Before we stop, summarize the current goal, decisions, changed files, checks completed, unresolved issues, and the next concrete step. Save this as local handoff context.

$ship prepare this branch for handoff. Summarize the behavior change, validation, known limits, and proposed PR description.

/ship prepare this branch for handoff. Summarize the behavior change, validation, known limits, and proposed PR description.

What Ship prepares

Under .forgeflow/<project>/ship/, inspect ship-summary.json, ship-presentation.html, and pr-body.md.

Ask the assistant to refine generated summaries against the final change. A report assembled from old notes can be incomplete; read it before publishing.

Example authorization after inspection

Commit these reviewed changes, push this branch, create a draft PR to main, and monitor its CI. Fix failures caused by this change. Do not deploy.

For an already agreed main-branch workflow, state that target explicitly instead. The assistant should respect repository policy and your intended release process.

Manual dashboard startup

From the intended project, keep this terminal process running; then open the URL in a browser on the same machine.

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

Update or repair

Codex: in a clean ForgeFlow source checkout, run git pull --ff-only, rerun install-template.js --target codex, and restart Codex. Resolve local source edits before pulling.

Claude Code: use /update-forgeflow; use --repair for missing managed files. The updater’s --rollback restores its previous managed-file snapshot when one exists. Restart and verify. That rollback mechanism is not a general Codex rollback.

Local report helpers for either host

Run from your project with the FF_RUNTIME set during installation. Read each result before deciding on the next action.

node "$FF_RUNTIME/scripts/forgeflow/build-project-operating-model.js" --json
node "$FF_RUNTIME/scripts/forgeflow/show-project-trends.js" --refresh --json
node "$FF_RUNTIME/scripts/forgeflow/render-lean-prime.js" --json
node "$FF_RUNTIME/scripts/forgeflow/render-release-readiness.js" --plan-only --json

The model and trend helpers write or refresh local guidance. Lean Prime here reports readiness; release readiness with --plan-only previews checks rather than running them. None of these examples asks for a commit or deployment.

Explore advanced paths after a first useful run

UI iteration: measured browser and accessibility checks. Fleet: independent work in isolated worktrees. Review-auto: conservative repair with its own evidence rules. Lean and context waves: control context volume. Team adoption: collect real outcomes before making quality or efficiency claims.

Availability differs by host. The Claude command catalog is larger than the installed Codex skill set; do not assume every slash command has a dollar-prefixed equivalent.

Go deeper when you need to

Guide sources: repository README, template installer and manifest, workflow skills, dashboard server/readiness/Ember implementations, and the linked documentation at commit 1353184. Workflow instructions document that implementation; later versions may differ. The visual identity and workshop screenshot were refreshed on 22 September 2026.

ONE CLEAR OUTCOME. ONE WELL-FORGED CHANGE.