Forge Flow: engineering workflow for coding agents.

GitHub stars
6

Install

/plugin install ff@forge-flow

Run it inside Claude Code after adding the marketplace with /plugin marketplace add pbvcity/Forge-Flow.

Contents

Discovered from source

Skills 11

auto

Follow ../../playbook/default.md (relative to this skill's directory). Read its "Long tasks" and "Failures" sections now.

1. Check the plan

PLAN.md needs an exit condition that can be decided, and an Accept: command per task. If it is missing or lacks these, run the plan skill first. Do not ask whether to begin.

Tasks blocked by "Needs a person" or an open direction choice wait. Everything else goes ahead, and business details do not block.

2. Run

node <this skill's directory>/../../cli/ff.mjs run --all

It starts in the background and returns at once, so it does not depend on host timers or wake-ups. It needs a headless builder. If roles.builder is host, run the setup skill, or use step 4.

After starting the run, if the host supports background tasks, start node <this skill's directory>/../../cli/ff.mjs wait as a host background task. When it returns, read the final status and summary and perform step 6. Exit 0 means complete, 1 means another ending (or no run), and 3 means the optional --timeout-min <n> expired; on timeout, use ff status and wait again while the run is live. If the host has no background tasks, end the turn and use ff status in a later session.

For each task it starts a clean process, runs acceptance itself, and commits on a run branch. When a task fails its first attempt, the reviewer diagnoses it read-only and the same builder tries again with the diagnosis. If the cause stays unclear, roles.consult is asked when it is set, at most 2 times per run; without it the task is parked. A task whose environment is at fault is held with the reason in its note. After 3 attempts, or when the spec is at fault, the task is parked on a branch and the rest carry on. A parked or stuck task goes to a clean lead process on the reviewer's model, which may narrow or split it. A provider limit pauses the run, or hands it to roles.fallback when that is set; nothing else changes the executor. Contract and high tasks are reviewed. It never pushes or goes live.

When several tasks declare disjoint Files:, run them in parallel:

node <this skill's directory>/../../cli/ff.mjs run --all --dry-run --lanes 2
node <this skill's directory>/../../cli/ff.mjs run --all --lanes 2

The first shows the grouping and why any task stays serial. Each lane gets its own worktree, and the tool merges lanes back one at a time, reruns their acceptance after merging, and removes the worktrees. A conflict moves those tasks to a serial pass at the end. Two lanes is the default; more costs more and rarely pays.

3. Pick up

In any new session, on any host:

node <this skill's directory>/../../cli/ff.mjs status

Then read PLAN.md and git log, and check open PRs and worktrees before starting anything. If a run is live, leave its worktree alone; editing PLAN.md is how to change course mid-run. If it ended, read .ff/runs/<id>/summary.md. Its task rows name the ladder each task went through, such as diagnosed: slip; consulted: slip; 3 attempts, and the diagnosis and consult files under .ff/runs/<id>/. Decide what to do about failed and held tasks, edit the plan if needed, and run again: done tasks are skipped and failed tasks get a fresh try.

4. Without the tool

If ff run is missing or fails, do not block. Work through the tasks here, in order:

  1. Take the next task whose dependencies are done.
  2. Use a clean host sub-agent with a work card, or do it in this session if the host has none.
  3. Rerun its Accept: command yourself.
  4. Tick it in PLAN.md, and add one line under a ## Log heading: task, result, time.

5. On failure, without the tool

  • Environment flake: retry once, unchanged.
  • Tool problem: fix it once.
  • Product defect: have the read-only ff-diagnose sub-agent (ff:ff-diagnose in Claude Code, ff_diagnose in Codex) name the cause from the task, the acceptance output, and the diff, then let the same executor fix once with that diagnosis. When the cause stays unclear or the same premise has failed twice, stop that task, record the premise and the evidence in PLAN.md, and go on with tasks that do not depend on it.
  • Provider limit: switch to roles.fallback when it is set, otherwise wait. A failed attempt never changes the executor.
  • Unsafe action or a stop from "When to stop": skip that task, record it, continue with the rest.

6. Finish

The tool tests a command exit condition when every task is done. A prose one needs you or another observer. Passing all tasks does not replace it. Never relax it to finish. If it fails, say what is missing, and continue if work remains that you can do.

Read .ff/runs/<id>/summary.md, the commits, and the diff. Routine tasks are not reviewed by the run, so the lead decides whether they need it, and any "tests weakened" flag needs a look.

Run the project's checks before closing the branch: run commits skipped git hooks, so passing task acceptance alone is not enough. Fix failures and rerun the affected checks, then follow build step 5 under the project's rules: push the work branch, open a PR, and read the CI result before calling it finished. Follow that step's no-remote path when applicable. The tool itself still never pushes or merges.

After the PR merges, run ff wt clean --apply and ff cleanup --apply without asking: they delete only what is proven merged or expired. Anything they list but keep is for the user to decide.

Notices: the run sends its own for each stuck task, each finished phase, each finished task outside a phase, and the end. Without the tool, run node <this skill's directory>/../../cli/ff.mjs notify send "<text>" at the same points. End your final reply with <!-- ff-done --> when the work is finished, or <!-- ff-await --> when it needs the user; write neither on progress reports. A turn woken by a heartbeat, a scheduled wakeup, or a background-task notice is not a new request: if it only reports progress, write no marker. Write each marker once; after <!-- ff-await -->, do not write it again until the user replies.

Going live and open items in DECISIONS.md follow the playbook: continue development, record provisional business decisions, and wait for confirmation of each open item the release carries before going live.

When a plan is finished, ff archive moves it to <planning folder>/done/.

Leave one summary for the user: what got done, every open item in DECISIONS.md for them to confirm one by one, what needs them (with steps), what they may want changed, and the state of the exit condition.

The user does not read summary.md; you do. If it has a ## Needs your look section, copy every item from it into that summary verbatim, each with its task id, as its own short list. Never replace them with a pointer to summary.md.

build

Follow ../../playbook/default.md (relative to this skill's directory). Read "Verification" and "Checks" now, "Failures" when something fails, and "Business decisions" when a detail is left open. Read ../../playbook/packs/ files that fit the subject.

1. Start

Read PLAN.md if there is one, and run:

node <this skill's directory>/../../cli/ff.mjs status

If the tool is missing or fails, use PLAN.md and git log. Skip tasks already done. Never commit directly to the main branch. If the repository has a remote, branch from the latest main.

2. Do each task

Use the reuse ladder before writing code: does this need to exist, does the repository do it, the standard library, the platform, an existing dependency, one line? Then write the smallest version.

  • Choose the evidence that fits the work, using the key points in go. Not every change needs a new test.
  • Contract and high, where a test can express the behavior: write the failing test first and watch it fail. A new test that passes at once proves nothing.
  • A shortcut with a known limit gets a comment: shortcut: <the limit>, <when to upgrade>.
  • If you find a bug outside the task, fix it if the fix is small and clear. Otherwise note it.
  • Run the task's Accept: commands and tick the task in PLAN.md only on real passing output.
  • In a fix round, rerun only the tests the fix touches. Run the full suite once at the end.

3. Dispatch when it helps

Work in the current session by default. Dispatch when the configured builder differs from you, or when independent tasks can run in parallel. Check roles.builder in ~/.ff/config.json.

Write a work card from "Work cards" in the playbook, and add ../../playbook/executors/<profile>.md, using generic, gpt, or claude.

node <this skill's directory>/../../cli/ff.mjs run <card file>

If ff run is missing or fails, use a host sub-agent with the same card. If the host has none, do the task here. Note which one happened. Do not block on the tool.

For read-only reads of a result, the plugin ships two agents: ff:ff-review and ff:ff-diagnose on Claude Code, and ff_review and ff_diagnose on Codex (synced by ff into ~/.codex/agents/, read-only by instruction only). Give them the diff or patch path and the evidence, never a request to change files.

The exit code is not the result. After any dispatch, read the real diff and rerun acceptance yourself.

If a dispatched task fails, do not retry blind. Have the read-only ff-diagnose sub-agent (ff:ff-diagnose in Claude Code, ff_diagnose in Codex; elsewhere a read-only sub-agent with the same inputs) read the card, the acceptance output, and the diff and name the cause. Then dispatch the same executor again with that diagnosis on the card. Change executor only after a provider limit. At most 3 attempts; then hold the task and say why.

4. Audit

node <this skill's directory>/../../cli/ff.mjs audit --base <ref>

It lists new checks, config, states, and weakened tests. Treat the list as hints, and for each new check ask what loss it prevents and what a misfire costs. Delete what has no answer. A weakened test blocks: restore it or explain why the behavior changed.

If the tool is missing, read the diff for the same things yourself.

5. Verify and close

Meet the verification row for the tier. Then:

  1. Update docs that the change made wrong: node <this skill's directory>/../../cli/ff.mjs docs lists candidates from the changed files. Do small follow-ups now. On contract or high work, put each dated "Next look" into the repository's FOLLOWUPS.md as - [ ] YYYY-MM-DD What to check. Evidence: <command or where to look>. Later checks stay open until their evidence is gathered and reported.
  2. Hand to the review skill for contract and high. For routine, the lead decides as "Risk tiers" describes.
  3. After a branch merges, run ff wt clean --apply and ff cleanup --apply without asking: they delete only worktrees, ff/* branches, and old records proven merged or expired. Items they list but keep (branches outside ff/, stale ff/failed/*, old temp/ entries) are the user's decision.
  4. If the repository has a remote, close through its normal flow: work branch, commit, PR, CI. Read the CI result before calling it finished. Without a remote, leave the changes in the working tree unless the user asked for commits, and say so.
  5. In a long build, run node <this skill's directory>/../../cli/ff.mjs notify send "<text>" when a phase finishes or a task is stuck. End the final reply with <!-- ff-done --> when the work is finished, or <!-- ff-await --> when it needs the user; write neither on progress reports. A turn woken by a heartbeat, a scheduled wakeup, or a background-task notice is not a new request: if it only reports progress, write no marker. Write each marker once; after <!-- ff-await -->, do not write it again until the user replies.
  6. End your report with what changed, what you ran with real results, what you skipped or left unchecked, the remaining risk, and every open item in DECISIONS.md for the user to confirm one by one. Going live waits until the user has confirmed the items the release carries. If a run's .ff/runs/<id>/summary.md has a ## Needs your look section, copy every item from it into the report verbatim, each with its task id, as its own short list; never only point to summary.md.

cleanup

Follow ../../playbook/default.md (relative to this skill's directory). Run everything yourself.

1. Preview

node <this skill's directory>/../../cli/ff.mjs wt clean
node <this skill's directory>/../../cli/ff.mjs cleanup

Both change nothing. wt clean covers managed worktrees; cleanup covers ff/* branches, .ff run, review, and council records past retention, and leftover run temp folders.

2. Apply

node <this skill's directory>/../../cli/ff.mjs wt clean --apply
node <this skill's directory>/../../cli/ff.mjs cleanup --apply

Apply without asking: they delete only what is proven merged or expired, and never a worktree with uncommitted work or a live run, or a worktree or record with a backup name. After a merge this is part of closing the work.

3. Report

Say what was removed and how much space was freed. List what they kept and why, such as branches outside ff/, stale ff/failed/* branches, or old temp/ entries, as the user's decision; never delete those yourself without the user naming them.

council

Follow ../../playbook/default.md (relative to this skill's directory).

1. Is it worth it?

Use it only when all three hold:

  • The decision is expensive to reverse: architecture, a data model, a public contract, a direction.
  • You cannot tell which option is right on your own.
  • A test, a small prototype, or the rules cannot settle it.

Otherwise decide, or build the prototype. To check finished work, use the review skill. A council costs several models and proves nothing about the code.

2. Frame it

Write a short file: the decision, the options, the facts and constraints, and the paths worth reading. Give your own leaning only if you want it attacked. State facts plainly, because a slanted question gets an agreeable answer.

3. Ask

node <this skill's directory>/../../cli/ff.mjs council <file> [--members <a,b,c>]

Each member works alone and read-only, and sees nobody else's answer. Members default to review.panel, then roles.reviewer and roles.second.

Different models, not different personas. A second copy of one model shares its blind spots, so say so if only one family answered.

If the tool is missing or fails, or members are host, use read-only host sub-agents with the same file. If you have only yourself, argue the strongest case against your leaning, and say that no independent view was available.

4. Decide

Read the answers in full, then decide. You own the decision, and counting votes is not deciding. Weigh evidence, not confidence. Where members disagree, find the fact that separates them, and check it. One round is enough. If a fact is still missing, go and get it instead of asking again.

5. Report

Give the decision, the reasons, what you rejected and why, and what would change your mind. Keep it short, without pasting answers. Record business outcomes in DECISIONS.md. If it is a direction choice the user should own, bring it to them with your recommendation before starting.

design

Follow ../../playbook/default.md (relative to this skill's directory). Read ../../playbook/packs/frontend-visual.md now: it holds what to check once things render.

1. Look at what exists

Read the project's tokens, components, and real screens, and look at them rendered if you can. An existing design system or brand wins over taste and over anything in this skill.

Then decide how much this project needs:

The projectDo
Has rules and a project skillUse that skill. This one adds only direction and motion.
Has a look but no written rules, and will keep growingWrite down the real system: step 5.
Is new, and will have several screensDirection first, then build the system: steps 3 to 5.
Is one page or a throwawayA one-page DESIGN.md is enough: steps 3 and 4.

If the look is already decided, skip step 3.

2. Find the intent

Answer in a sentence each: who is this for, what should they feel, and what is the one thing this screen must get done? Take the answers from the request and the repository where you can.

3. Offer directions

When the look is open, as with a new product, a brand, or a large redesign, give two or three directions that really differ.

Before proposing, open references: at least two per direction, with your browser or web fetch tool, following references/references.md. Writing directions from memory is what makes every product look the same. Only when no tool can load a page, write references not opened with the error. Then use references/styles.md so the directions differ on at least two axes. Each direction has:

  • The idea in one sentence, and who it suits.
  • What it gives up.
  • References you opened, and what you took from each. Say so if you have none. Never invent a link, a screenshot, or a source.

For a large redesign, render each direction as one static screen, such as a single HTML page, and show the screenshots side by side. People choose far better from a picture than from a paragraph. The samples help the choice and are not the build.

Recommend one. A direction is a choice that can waste much of the work, so ask before building. If the user is away, take your recommendation, record it in DECISIONS.md, and carry on: a look can be changed in development, and it is confirmed before going live.

Avoid the generic defaults models reach for: the same purple gradient, the same three feature cards, centered everything. Make a choice someone could disagree with.

4. Write DESIGN.md

One page, kept next to the plan. Leave out what does not apply.

# <surface>

Intent: <who, feeling, the one job>
Target: <what this must beat, such as a named reference or the current page, and what would count as not good enough>
Direction: <chosen, and why the others lost; for a mix, which leads and what each adds>
Tokens: <color, type, spacing, radius; names from the project where they exist>
Layout: <grid, widths, what collapses on a phone>
States: <empty, loading, error, long text>
Motion: <personality; element class -> recipe>
Icons: <one family, its license>
References: <links you opened, the date, what you took from each, and a license note when reusing code, fonts, images, or icons>
Not doing: <what was left out>

5. Build the project's system

Follow references/design-system.md: tokens, components, rules, a showcase, and a project skill that loads them for every later UI change. This is what keeps the product consistent after today's work is finished, so do it before building screens. The first pass has five parts, listed at the top of that file. Topics grow with real pages.

6. Motion

Read references/motion.md when anything moves, and references/atomic-motion.md for interface details such as hover, menus, and toggles.

  • Name easing and duration from the tables. "Smooth" and "premium" tell a builder nothing.
  • One recipe per element class across the whole product. Consistency matters more than any single animation.
  • New products adopt the recipes by default. A product with its own motion style keeps it, and the recipes do not get mixed in.

7. Build and see it

Build shared parts first, then screens. Then follow the frontend pack: look at the real render, on every changed page, at desktop and phone widths, and judge it as its "Judge the look" section says.

Motion cannot be judged from a screenshot, the DOM, or a keyframe. Record a few seconds or capture a frame sequence, and check it against the rubric in references/motion.md. If you cannot, write motion not seen in the report.

When the user corrects the look and it reads as a lasting rule, write it into the project's rules in the same change.

go

If the request is plainly micro (docs, copy, a small style change, an existing setting) and touches nothing others depend on, skip everything below. A bug fix, a logic change, or a changed error code or API value is never micro, however small the diff. For a micro change: make the edit, run the related check, read your diff, and report in a few lines.

Otherwise, follow ../../playbook/default.md (relative to this skill's directory). Read only its "Always" and "Risk tiers" sections now, and the rest as stages come up.

1. Orient

Read PLAN.md if present. If PLAN.md, .ff/, or FOLLOWUPS.md exists, run:

node <this skill's directory>/../../cli/ff.mjs status

If the tool is missing or fails, use PLAN.md and git log instead and continue. Pick up unfinished work rather than starting over when the request continues it.

When ff status lists due follow-ups, handle them first unless the user asked for something else: gather the evidence yourself, report what it shows, and tick the item in FOLLOWUPS.md. Use node <this skill's directory>/../../cli/ff.mjs followups to list all open checks and malformed lines. Keep a check open when its evidence still needs a real external dependency.

2. Classify

Read enough of the code to know what the change reaches. Decide the tier by loss type, not by size, and state it:

Risk: <tier>. <one-line reason>.

The user can change it with a sentence. Raise it later, and say so, if you find a higher loss. If the subject calls for a pack in ../../playbook/packs/, read it.

If the request is ambiguous, resolve it from the repository. Ask, before starting, only when a wrong guess would throw away much of the work and the repository cannot answer. Other open details are decisions to record.

3. Route

Take the lightest path that fits:

RequestPath
A questionAnswer. Change nothing.
microDo it now, run the related check, report. No plan file, no review.
routineImplement with the build skill, using only the parts that help. No PLAN.md or REVIEW.md. Get a clean review when the playbook says it is worth it, and put the result in your report.
contract, highplan if there are several steps, then build, then always review.
Several tasks, or the user wants it run unattendedplan, then auto.
Review of existing changesreview.

For a micro change:

  1. Make the smallest edit that does what was asked, and look at nearby code for the same wording or value.
  2. Run the related test or check, and read your own diff.
  3. Report in a few lines: what changed, what you ran, anything unverified.

4. Check before you report

If you changed or removed any existing test, you are not finished until this has run. It takes a second, and reading your own diff does not replace it. If it reports a weakened test, restore the test or say why the behavior changed.

node <this skill's directory>/../../cli/ff.mjs audit --base <commit you started from>

If the tool is missing or fails, quote the error and read the diff for the same things.

For contract and high, you are also not finished until this has run. Do it once the change passes its tests, however small the diff. Reading your own diff does not count.

node <this skill's directory>/../../cli/ff.mjs review --base <commit you started from> --risk <tier>

Read each reviewer's output in full, fix what is real, rerun only the tests those fixes touch, and say in your report who reviewed and what they found. If the command exits 2 or 3, use a read-only sub-agent with the diff and ../../playbook/review.md. You may report without a review only after both really failed, and you quote the errors. Skipping it by choice is not allowed.

5. Key points

Know these even if you open nothing else. For more than a small change in one of these subjects, read its pack in ../../playbook/packs/.

  • Writing code: Ask first whether it needs to exist, then whether the repository, standard library, platform, or an existing dependency already does it. Never cut validation at trust boundaries, error handling that prevents data loss, security, or accessibility.
  • Tests and CI (ci-and-tests): Fit the evidence to the work; a test file is only one kind. Logic and state: unit tests, with boundaries and the failure paths that matter. APIs and jobs: a test through the real entry point. Queries: a real database when the project has one. UI: the real render, with tests only for logic and key flows. Config and deploy: start it for real. Refactors: existing tests unchanged and passing. Scripts: a run on real or sample input. Prompts and skills: real sample runs. Docs and copy: links and your diff, and for statements others will rely on about how the code behaves (docs, release notes, published copy, answers to factual questions), read every branch behind each one, write in its conditions, limits, and exceptions, then have a read-only sub-agent on a cheaper model check the draft against the source, given the draft and the paths but not your conclusion; with none available, say it was not cross-checked. A fixed bug gets a test that fails without the fix whenever a test can express it. Add a lasting test only where the behavior could break unnoticed and matters. Mock only real external boundaries. Choose checks from the changed files. In a fix round, rerun only the tests the fix touches. Run the full suite once at the end, push once, read the result. Reuse builds and caches. Never skip tests or loosen assertions to get green. A flaky test is a bug. Passing acceptance by a trick is a failure: if the task cannot be done as written, say so and hold it. When a project has run for over a week, a merge check takes about an hour, or a problem shows up only in the full run for the second time, review the test process itself once: see "When to review the test process" in the pack.
  • Failures: In a run, a task's first failure goes to the reviewer for a read-only diagnosis, then back to the same builder with the advice. An unclear cause, or a slip whose retry failed again, gets a consult only when roles.consult is set, at most 2 per run; a third attempt needs that consult to find a slip. roles.fallback steps in only after a provider limit. At most 3 attempts per task; then the task is parked and a lead on the reviewer's model replans. In a session, have the read-only ff-diagnose sub-agent (ff:ff-diagnose in Claude Code, ff_diagnose in Codex) name the cause before the same executor retries.
  • Needs your look: The user does not read summary files. Every ## Needs your look item in a run's summary.md, and every finding you reject or defer without high confidence, goes into your final report verbatim with its task id, as its own short list.
  • Docs: Before every commit, run node <this skill's directory>/../../cli/ff.mjs docs and put the documents your change made wrong into the same commit. Docs declare what they cover with a Covers: line.
  • Concurrency: State can change across any await. Take the balance, stock, or order state before the wait, and recheck after it. Ask what a cancel or a second caller does in that gap.
  • UI (frontend-visual): The project's own UI skill and rules come first. Use only its tokens and components. Look at the real render at desktop and phone widths, or write not seen rendered. Build every state: empty, loading, error, long text.
  • Data (data-migration): Back up and confirm it restores. Count the real rows read-only first. Try it on a copy. Expand, migrate, contract. Delete only exact, listed targets.
  • Money (payments): The server recomputes every amount. Store integer minor units. Verify callbacks and make them idempotent. A refund cannot exceed what remains. When state is unclear, do not charge twice. Run one real small cycle before going live.
  • Read-only agents: For an independent read or a failure diagnosis, use the plugin's read-only agents instead of a general sub-agent: ff:ff-review and ff:ff-diagnose on Claude Code, ff_review and ff_diagnose on Codex (synced by ff; read-only by instruction only). Give them the diff or patch path and the evidence.
  • Windows (windows): Set UTF-8 explicitly, and read back non-ASCII writes. Use absolute paths. Close stdin for headless tools. Kill whole process trees. bash may be the WSL launcher.
  • Temp files: Maintained test scripts, fixtures, and helpers are source code: keep them under git in tests/, test/, e2e/, or scripts/, never in temp/. Throwaway scripts, logs, reports, downloads, and generated test output go in this checkout's temp/, sorted by kind as ff init sets it up, in a folder the run alone owns; never the system or user temp folder (%TEMP%, /tmp), the home folder, or another project's or parallel run's folder. Before cleaning, stop the services, browsers, and processes you started, report what could not be removed, and keep what is unsafe to delete; ff run manages temp/tmp/ itself.
  • Notifications: A turn ending does not notify; you decide. End the final reply of a turn with <!-- ff-done --> when the work the user asked for is finished, or <!-- ff-await --> when you stop and need the user. Write neither on progress reports, while background work runs, or before more tool calls. A turn woken by a heartbeat, a scheduled wakeup, or a background-task notice is not a new request: if it only reports progress, write no marker. Write each marker once; after <!-- ff-await -->, do not write it again until the user replies. To reach the user mid-work, for example from a heartbeat, run node <this skill's directory>/../../cli/ff.mjs notify send "<text>", with --await when they must answer. Say what happened and what the user should do. From a heartbeat, send only when something changed since your last notice. If a session note says Forge Flow's rules changed since a rules file was aligned, offer the init skill once.
  • Cleanup: After a PR merges, run ff wt clean --apply and ff cleanup --apply without asking: they delete only what is proven merged or expired. Items they list but do not delete (branches outside ff/, stale ff/failed/*, old temp/ entries) are the user's call. ff status says when there is something to clean.

6. Keep going

Moving from one skill to the next is not a stop. Continue until the work is done or a stop from "When to stop" applies. For a stop, give the user what they need to decide, and finish everything that does not depend on it.

init

Follow ../../playbook/default.md (relative to this skill's directory). Run everything yourself; the user should not need another terminal.

1. Preview

node <this skill's directory>/../../cli/ff.mjs init

It changes nothing and lists what it would add: missing folders (docs/, the planning folder, the temp folder sorted by kind), the temp ignore line, runtime git excludes, and the Files and folders and Notifications sections of the rules file (AGENTS.md, or an existing CLAUDE.md). It keeps names the project already uses, such as temp-ignore/, and never rewrites an existing section. Its last lines name rules files that need aligning (step 3).

2. Apply

Show the user the preview in a few lines: which folders, which file gets which section. Then apply when they agree:

node <this skill's directory>/../../cli/ff.mjs init --apply

Running it again later adds only what is missing, so it is safe in a project initialized by an older version.

3. Align rules

Forge Flow's rules live in rules files: Files and folders and Notifications in the project's AGENTS.md or CLAUDE.md, and the Delegation section from setup in ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, or ~/.pi/agent/AGENTS.md. Each file carries one <!-- forge-flow rules N --> line saying which version of the rules it was aligned with; a file with Forge Flow rules but no such line is at version 1.

node <this skill's directory>/../../cli/ff.mjs init --rules

It lists each file with Forge Flow rules, its version, and the later changes that apply to it; when a file is behind, it also prints the current project sections in English. For each file with changes listed:

  1. Read the file. Find the content that carries Forge Flow's rules, in whatever language and wording it uses now; it may be translated or adapted to the project.
  2. Compare its meaning with the changes listed and with the current sections. Note only rules that are missing or say something different; wording is not a difference.
  3. Propose the edits: the file, the lines as they are, and the lines as you would write them, in the file's own language and style. Keep what the user added for their project. Do not add sections the user removed.
  4. Apply only what the user agrees to. Then record the file as aligned, also when they keep it as it is, so later sessions stop asking:
node <this skill's directory>/../../cli/ff.mjs init --rules --mark <file>

Never change a user rules file outside the Forge Flow sections, and never mark a file the user has not decided on.

4. Report

Say what was created, appended, or aligned, then run node <this skill's directory>/../../cli/ff.mjs doctor and report its Files and folders, Notifications rule, Rules version, and Temp folder lines. If a rules file is tracked by git, the changes are uncommitted: commit them through the project's normal flow. Start a new session to work under the aligned files.

plan

Follow ../../playbook/default.md (relative to this skill's directory). Output: planning/PLAN.md by default; an existing root PLAN.md still works. For several plans side by side, keep each in its own file and pass --plan <path> to the tool.

1. Understand

Read the code the work will touch. Then ask yourself:

  • What would an expert do here that was not requested?
  • What is the rawest source of truth for this: real data, the real API, the running system?
  • Who or what will prove the result right?
  • For data work: which decision does this drive, who acts on it, and how is it measured? If nobody can say, raise that first.

Answer from the repository where you can. Before starting, ask in one message about facts the repository cannot give and direction choices where a different answer would throw away much of the work, each with your recommendation. This is the time to ask. Once work starts, run on your own.

2. Cut

Before listing tasks, ask of each piece whether it needs to exist, and whether the repository, standard library, platform, or an existing dependency already does it. If a piece is uncertain, prefer a small prototype to more planning.

3. Write PLAN.md

# <goal>

Risk: <tier>. <reason>.
Outcome: <what a user or system can observe when this is done>
Exit condition: `<command>`, or a sentence for an observer
Not doing: <what is out of scope, and optional items left out>

## Tasks

### <phase, optional>

- [ ] T1 <outcome of this task>
  Accept: `<runnable command>`
  Files: <every path or glob this task writes>
  Shared: <port, database, or service it needs alone, if any>
  Depends: <task IDs, or none>
  Risk: <tier, when it differs from the plan>
  Executor: <optional executor name or pi:vendor/model:effort>

## Needs a person

- [ ] <action>. Why: <reason>. Steps: <exact steps>. Blocks: <task IDs, or nothing>.

## Direction choices

- [ ] <choice>. Options: <...>. Recommended: <...>. Work at stake: <...>. Blocks: <task IDs, or all>.

Record business details you choose in DECISIONS.md, not here, so they reach the list the user confirms.

Omit Executor: to use roles.builder. A task's Executor: overrides that default; unknown executors produce a plan note and hold only that task. roles.fallback is empty by default. When configured, it becomes the run's builder only after a provider limit; a failed attempt is diagnosed by the reviewer and retried by the same builder. Further limits use the existing wait schedule. Reports name the executor used.

  • Each task has at least one Accept: command that exits non-zero on failure. Run it now if it can run, so you know it is well formed.
  • Before writing an enum value, status, config key, or field name into a plan or doc, search its source of truth and use the name found there.
  • If only a person can accept something (real device, real money, a look at the page), put it under "Needs a person" with exact steps.
  • A task that changes behavior, a command, or configuration also lists the documents it makes out of date in Files:, so the same task updates them.
  • Files: decides what can run in parallel, so list every path the task writes. A task without Files:, a high-risk task, or one touching repository-wide files such as package.json runs serially. Shared: names a port, database, or service that two tasks cannot use at once.
  • Put the plan in the planning folder, planning/PLAN.md by default, or planning/<topic>/PLAN.md for several at once, run with --plan. An existing root PLAN.md still works.
  • When the work has stages, group tasks under ### <phase> headings inside ## Tasks. With configured notifications, a run then sends one message per finished phase instead of one per task.
  • Keep tasks to about 30 minutes each, since a process is stopped at 60. Split where write sets separate, and mark real dependencies only, so tasks can run independently.
  • High tier: add tasks for real-environment acceptance, the kill switch or rollback, and the before/after comparison.
  • Follow "Business decisions" in the playbook: choose details yourself, including prices and permissions. Only direction choices wait for an answer, and a ticked one no longer holds its tasks.

4. Check

For contract and high, have one reviewer read the plan using ../../playbook/review.md. Fix what it finds, and stop after one round: plans have no run result to converge on.

For routine, reread it once as if you were the executor. Could you start without asking anything?

5. Hand on

Continue with the build skill, or auto if the user wants it run unattended. If an open direction choice blocks every task, put it to the user and stop. Otherwise go on with the tasks it does not block.

review

Follow ../../playbook/review.md (relative to this skill's directory): it holds the finding format, severity caps, rounds, and stop conditions. General rules are in ../../playbook/default.md.

1. Scope

Settle the range (base..HEAD, a PR, or a path), the risk tier, and the acceptance criteria. Read REVIEW.md for known-accepted items and pass them on.

TierReviewers
microCheck your own diff. No file needed.
routineThe lead decides. One clean reviewer when it helps.
contract, highA clean reviewer, however small the diff, plus a second family if configured. A panel in round one if review.panel is configured.

--panel opens a panel at any tier when the user asks for one.

2. Run

node <this skill's directory>/../../cli/ff.mjs review --base <ref> --risk <tier> [--panel] [--brief <file>]

Reviewers get a brief, not the diff: the tool writes the full redacted patch to .ff/reviews/<id>/diff.patch and gives them a file inventory, the patch path, and the working tree to read. Claude reviewers can also run read-only git commands (log, show, blame, diff) under --restricted and dontAsk; Codex reviewers work in its read-only sandbox; Pi reviewers read git through ff's git_read tool, with other extensions off; OpenCode reviewers read files only. For contract and high, write a short brief first (in temp/ or .ff/) and pass it with --brief: the purpose, what changed, the interfaces touched, and what to look at first. Each reviewer ends with Not read: and the files it skipped; treat a skipped file that matters as unreviewed.

The tool records who ran, on which model, and the raw output. An unparseable result does not count as a pass.

If the tool is missing or fails, do not block. Use a read-only host sub-agent per reviewer, with the brief, the file list, the range or a patch file path to read, the acceptance criteria, and the reviewer prompt at the end of review.md, in parallel with results kept apart for a panel. On Claude Code use the plugin's ff:ff-review agent (read-only, loads review.md itself); on Codex use the ff_review agent that ff syncs into ~/.codex/agents/ (read-only by instruction only, so for a review that must be enforced read-only use ff review); on other hosts use whatever read-only sub-agent the host offers. With no sub-agents, review in this session, and write no independent review on the card. A member who is absent is noted, and the rest go on.

The lead is roles.reviewer in ~/.ff/config.json, and host or an unset value means the current model.

3. Decide

When reviewers disagree widely, the requirement is probably unclear: go back to the acceptance criteria instead of averaging or adding rounds. The lead reads the raw findings, applies the caps, and decides each one: block, fix now, defer, or reject with evidence. Other reviewers have no vote, and each of their findings gets a response. Do not rewrite their text. Check each finding against the source before acting. When you reject or defer a finding without high confidence, list it in your report to the user under a "Needs your look" item: what the issue is, where (file:line if known), and why you are unsure.

4. Write REVIEW.md

For contract and high, or when an accepted finding must not be raised again. Otherwise the report is enough. Append a dated section, keeping earlier ones:

## <date> <range>, <tier>, round <n>

Reviewers: <who, which model, who was absent>
Verdict: PASS or FAIL. FAIL while any BLOCKER or HIGH is open.

### Findings
| Severity | Family | Where | Decision | Why |

### Can be deleted
### Dropped
<count>

### Residual risk
<card from review.md, for contract and high>

### Known accepted

5. Fix

Unless the user asked for review only, fix what the lead accepted, and delete what "Can be deleted" lists when the lead agrees. Use a fix card that says: smallest fix, no other protection. Check the same pattern elsewhere for confirmed bugs. Do not sweep for hypothetical bypasses.

Round 2 onward: one reviewer reads the fix diff only. The lead supplies its adjudicated findings explicitly with --findings <path> so the reviewer checks each fix and any new problems introduced by the fix diff.

node <this skill's directory>/../../cli/ff.mjs review --base <ref> --risk <tier> --round <n> --findings <path>

Stop on the conditions in review.md. High tier has at most 3 rounds. The second appearance of a family ends patching for that family. At the limit, decide. Report the verdict and where REVIEW.md is, then continue with whatever the calling skill had left.

setup

Follow ../../playbook/default.md (relative to this skill's directory).

1. Detect

node <this skill's directory>/../../cli/ff.mjs doctor

If the tool is missing or fails, detect by hand. Read versions and model lists only. Do not open credential files or print secrets.

  • Single-model hosts: check for CLIs with claude --version, codex --version, grok --version, and opencode --version. Each CLI is usually one model family, and a second family means calling its CLI.
  • Multi-model hosts: read pi --list-models and opencode models and group by vendor. Another family needs only a different --model argument, so default the reviewer to a different family from the builder.

Judge family from the model name, and fall back to vendor if unclear. Two tiers from one vendor count as one family, because they share blind spots.

2. Ask one thing

Who leads reviews? The default is the current model, since it holds the full context. If the user is away, use the default and say so.

3. Assign roles

roles.builder runs unattended work, so it must be a headless command, not host. Use claude or codex when that CLI is installed, or a pi: or opencode: role. Work inside a session still happens in that session.

FamiliesBuilderreviewersecondReports say
1That family's CLIThe same CLI, as a clean processEmptyno independent-family review
2User's choice, default current modelThe other familyEmptyWho led
3 or moreAs aboveOne other familyA third familyWho led

The lead reads every reviewer and decides. Missing models downgrade the workflow and never block it.

roles.fallback is optional. It takes over only when the builder hits a provider limit, never a second attempt. roles.consult is optional: name the strongest model available, such as Fable, as an executor name or a pi: or opencode: role. It runs read-only and is asked only when the reviewer's diagnosis of a failed task is unclear, or when the diagnosis found a slip and the retry failed again, at most 2 times per run.

4. Write the file

Write ~/.ff/config.json. A project may override it in .ff/config.json. If the file exists, add missing keys and leave the user's values alone.

{
  "roles": { "builder": "claude", "reviewer": "codex", "second": "", "fallback": "", "consult": "" },
  "executors": {
    "<name>": { "cmd": "<headless command>", "profile": "generic" }
  },
  "review": { "panel": [] },
  "playbook": "~/.ff/my-rules.md"
}
  • claude and codex are built in, so they need no executors entry. Add one only for another tool, such as grok -p, and use its help to confirm flags. It must read the prompt from stdin and be able to write files without asking.
  • profile is generic, gpt, or claude, matching ../../playbook/executors/.
  • On a multi-model host, a role can name a model directly: pi:<vendor>/<model>:<effort>.
  • A Codex role can name a model family, such as codex:sol, and ff runs the newest model of that family Codex has listed. A full slug such as codex:gpt-6.2-sol pins one version. Plain codex uses the model in ~/.codex/config.toml. ff doctor shows what each family resolves to.
  • OpenCode roles use opencode:<provider>/<model> for builders, reviewers, and council advisers. Prompts stay in the run/review/council directory and travel through --file; --dir is the project root. The message asks the model to read through EOF using offsets when truncated and follow the file's final instructions. No real model is called during detection.
  • OpenCode reviews and council advisers select ff-review, defined for that child process through OPENCODE_CONFIG_CONTENT (OpenCode V1 agent configuration). Its permissions deny every tool except read, grep, glob, and list. No agent installation or user-config write is needed. This replaces inline config for that child process; ordinary user/project files still load. An unavailable agent marks the reviewer or adviser failed, with no review verdict. Builders keep their existing OpenCode permissions. See the OpenCode configuration source for the V1 format.
  • Reviewers and consults run read-only. claude, codex, pi:, and opencode: roles get this automatically. Other executors need reviewArgs.
  • Credentials never go in this file.

Create ~/.ff/my-rules.md only if the user has rules to add. Do not overwrite one.

5. Prepare the repository

Run node <this skill's directory>/../../cli/ff.mjs init to preview the folders, ignore lines, and rules-file block it would add, then init --apply if they fit. It only adds what is missing, keeps existing names such as temp-ignore/, and never rewrites a rules section; aligning older ones is the init skill's step 3.

6. Offer session model tiers

Sub-agents cost less and finish sooner on a model that fits the job. This is for work inside a session; roles above cover unattended runs.

Check what the user already has. Read file names and model or effort lines only.

  • Claude Code: ~/.claude/agents/*.md with a model: line, and a delegation section in ~/.claude/CLAUDE.md.
  • Codex: ~/.codex/agents/*.toml with model or model_reasoning_effort, and ~/.codex/AGENTS.md.
  • Pi has no sub-agents of its own, so only the delegation section applies, in ~/.pi/agent/AGENTS.md.

If tiers exist, report them and change nothing. Otherwise ask one question: lean toward lower cost, or toward quality? Then show the files and write them once the user agrees. Write only files that do not exist. Add the delegation section to the end of a rules file, and never rewrite what is there. Then record the file as holding the current Forge Flow rules: node <this skill's directory>/../../cli/ff.mjs init --rules --mark <file>. Aligning an older delegation section after an update is the init skill's job.

TierUse forClaude Code, lower costClaude Code, qualityCodex effort, lower costCodex effort, quality
ff-lightCounts, file checks, list comparisons, format conversion, simple searcheshaiku, lowhaiku, mediumlowmedium
ff-standardRoutine implementation, doc sync, summaries, reconciling sourcessonnet, mediumsonnet, highmediumhigh
ff-deepReviews of contract or high-risk changes, root causes, specsopus, highopus, xhighhighxhigh

Claude Code, ~/.claude/agents/ff-light.md, and the same for the other two without the two light-tier sentences:

---
name: ff-light
description: <the "Use for" cell>. Cheapest tier.
model: haiku
effort: low
---

Do only what the prompt asks, in the paths it names. Do not commit or push unless asked. Never print credentials. End with the result and the paths you changed. Read only the files and ranges the prompt names; if the task needs wide reading or judgment, stop and say it is beyond the light tier. Cite the source of each finding as file:line so the main session can check it.

Codex, ~/.codex/agents/ff-light.toml. Keep the user's model and set only the effort, unless the user names a smaller model for light work:

name = "ff_light"
description = "<the Use for cell>. Cheapest tier."
model_reasoning_effort = "low"
developer_instructions = """
Do only what the prompt asks, in the paths it names. Do not commit or push unless asked. Never print credentials. End with the result and the paths you changed. Read only the files and ranges the prompt names; if the task needs wide reading or judgment, stop and say it is beyond the light tier. Cite the source of each finding as file:line so the main session can check it.
"""

The delegation section, in the user's language:

## Delegation

- Keep planning, decisions, and the final check of results in this session.
- Mechanical checks and lookups go to ff-light, routine work to ff-standard, and reviews of contract or high-risk changes, root causes, and specs to ff-deep. When unsure, use ff-standard.
- A sub-agent's report is a claim. Read the diff and the output.

On Codex the names are ff_light, ff_standard, and ff_deep. On Pi, drop the tier names and keep the first and last lines.

7. Offer notifications and branch protection

If the user wants to hear when long work ends, show them the settings in the README's "Notifications" section. They fill in ~/.ff/notify.env themselves, because it holds credentials. Then run ff notify --test.

If this repository should not take direct commits on its main branch, run ff protect here. It applies to one repository, so run it in each one that needs it.

8. Report

List the tools found, the role assignment, the session tiers found or added, and any downgrade. Mention that third-party marketplaces may not auto-update, so the update skill exists for that.

update

Follow ../../playbook/default.md (relative to this skill's directory).

1. Run

node <this skill's directory>/../../cli/ff.mjs update

It finds the hosts with Forge Flow installed and runs each host's own update. One host failing does not stop the others. It fills in new config keys with defaults and leaves existing values alone.

If a run is in progress, mention it and continue. State files only gain fields, so old runs keep working.

2. Without the tool

If ff update is missing or fails, do it by hand for each host that has Forge Flow. Report a failure and move on to the next.

HostCommandsTakes effect
Claude Codeclaude plugin marketplace update, then claude plugin update ff@<marketplace>/reload-plugins or a new session
Codexcodex plugin marketplace upgrade, then codex plugin add ff@<marketplace>Restart Codex
Pipi update --extension <package source>/reload or a new session

Leave other plugins and marketplaces alone. For other hosts, tell the user to use that host's update entry.

3. Report

For each host: version before, version after, and whether a reload or restart is needed. Bad releases are undone by installing an earlier tag, not by rollback code here. If a host fails, give its error and the command to retry.

An update can change Forge Flow's rules, which project and user rules files keep in their own copy. After a reload, run ff init --rules (or ff doctor, line Rules version): when a file is behind, offer the init skill to align it. New sessions also say so on their own.

Agents 2

You are the read-only diagnostician that Forge Flow ships with its Claude Code plugin.

First read ${CLAUDE_PLUGIN_ROOT}/playbook/diagnose.md and follow it. It defines the failure classes, what evidence each one needs, and the closing line.

Input

The prompt gives you some of: the task card, the acceptance commands and their output, the failure evidence (test output, reviewer findings, a stack trace), and the attempt's file inventory with the path of its patch file. Read the hunks you need from the patch with Read, using further offsets for a long one. You may open the code the attempt touched and the tests it ran to confirm the cause.

Rules

  • Find the cause, not every possible improvement. One failure, one diagnosis.
  • Quote the evidence that supports the classification: the failing assertion, the missing binary, the contradiction between the task and the acceptance command.
  • Give a concrete fix: which file, which change, and roughly how large. A fix the next attempt can apply without re-investigating.
  • If the task or its acceptance is what is wrong, say what the task should have asked for instead.
  • Do not modify any file, do not run commands, and do not create files. Reading is the whole job.

Output

Write, in this order:

  1. What failed: one or two sentences.
  2. Evidence: the lines that show the cause, with file:line where there is a file.
  3. Fix: the concrete change for the next attempt, or what a person or the environment must supply.

The last line of your reply is exactly one of DIAGNOSIS: SLIP, DIAGNOSIS: ENVIRONMENT, DIAGNOSIS: SPEC, or DIAGNOSIS: UNCLEAR, as diagnose.md defines them. Nothing follows that line.

You are the read-only reviewer that Forge Flow ships with its Claude Code plugin.

First read ${CLAUDE_PLUGIN_ROOT}/playbook/review.md and follow it: the finding format, the six items, the severity caps, the required sections, and the stop conditions all come from that file. If the prompt names a REVIEW.md or a list of known-accepted items, do not raise those again.

Scope

Review only what the prompt gives you: a brief with a file inventory and the path of a patch file, a diff, or a list of files. For a patch file, read the hunks you need with Read, using further offsets for a long one, and read the surrounding code from the files. You may open the code a change touches, its callers, and the acceptance criteria, to confirm a scenario. Do not widen the scope to unrelated files, and do not report problems in code the change did not touch as blocking.

Rules

  • Find what would cause real loss. You are not proving the code perfect.
  • Every finding needs a real scenario, a reachable path, and a loss type. Say whether you reproduced it by reading the code path or only reasoned it out.
  • One entry per family of problem. Merge variants and count them.
  • Do not modify any file, do not run commands, and do not create files. Reading is the whole job.

Output

Write the three required sections in this order, even when a section is empty:

  1. Findings, ordered by severity, each with its severity, family, file:line, and the six items from review.md.
  2. Can be deleted: checks, branches, config, or tests that could go without adding loss.
  3. Dropped: how many candidates you considered and did not report.

Before the last line, write Not read: with the changed files you did not read, comma-separated, or Not read: none.

The last line of your reply is exactly VERDICT: PASS or VERDICT: FAIL. FAIL if any BLOCKER or HIGH remains. Nothing follows that line.

Sponsors

Details

Marketplace
pbvcity/Forge-Flow
Category
Community