forge skills in detail

The long form of the README's "Skill catalog". It carries each skill's input, output, and next step, plus its triggers, behavior, and rationale ADRs. For the at-a-glance summary table, see the README.

Skill catalog (all six columns)

Skill	Stage	One-line role	Input	Output	Next
fg-ask	① Ask·plan	grill-with-docs verbatim — grills the plan against domain, terms, and decisions	User request	.forge/backlog/<slug>.md + CONTEXT/ADR	fg-run
fg-run	② Execute	Executes through the host adapter—Dynamic Workflow on Claude Code, collaboration/subagents on Codex, serial fallback when unavailable	.forge/backlog/, plan.md	Result + .forge/run.md + STATUS.md (or executed/)	fg-learn
fg-learn	③ Retro	Promotes learnings to docs (a mechanically checkable learning is promoted as an eval — a persistent regression check), surfaces the next inquiry	.forge/run.md, plan.md, executed/	.forge/retro/*.md + promotions	fg-done (re-grill via fg-ask if divergence was large)
fg-done	④ Done	Tidies up the cycle — confirms the retro, closes STATUS.md as done, archives, clears active state, seals the loop. The mechanical seal runs as a deterministic script (forge-done.sh/.js) (ADR-0030). all mode batch-seals every executed task (retros skipped, backlog untouched)	.forge/*	.forge/done/<date-slug>/	fg-ask / end
fg-map	Utility (outside the loop)	Maps the codebase into .forge/codebase/ with parallel subagents, so grilling reads a map instead of re-exploring the code (cuts context rot)	Codebase	.forge/codebase/*.md (7 documents)	— (consumed by fg-ask)
fg-quick	Lightweight lane (outside the loop)	For trivial tasks — grills lightly, then runs directly with no formal artifacts (no ADR/plan/retro); bails to fg-ask if it turns out non-trivial	User request	One entry in .forge/quick/LOG.md	— (self-contained)
fg-status	Reporter (outside the loop)	Read-only — surveys .forge/ and prints where every task stands plus the single next step you need; writes nothing and never auto-runs	.forge/* (read-only)	Printed report (no files)	— (suggests the next step)
fg-next	Orchestrator (outside the loop)	Derives the single next step via fg-status's state machine, announces it in one line, then runs that skill right away — it does not merely report; one-shot. fg-status reports, fg-next acts	.forge/* (itself read-only)	None — delegated to the invoked skill	— (invokes the next skill)
fg-loop	Orchestrator (outside the loop)	Goal-driven loop with bounded replan — pins stop checks, a fix-forward scope, and a cap, then drives run → UAT → skip retro → seal; a failed active task is repaired in place, a failing check with an empty slot generates a new plan	goal (inquiry), .forge/loop.md, backlog/	Sealed tasks + repaired-by in-place repairs / generated-by fix-forward plans	— (completion report; promote later via fg-learn)
fg-config	Settings (outside the loop)	Unified settings surface for the six .forge/config.json keys (simple·eco·tdd·driveCommit·driveCommitMessage·defaultBranch) — fg-config (no arg) shows the full settings table and offers changes via a menu, fg-config <key> <value> sets one. simple is auto-seal mode (after UAT, fg-run skips the retro and seals in the same turn; the verification gate stays inviolable), eco/tdd semantics are unchanged. Replaces the former per-key toggle skills (ADR 260905-212045)	<key> <value>/(none)	.forge/config.json	— (setting only)
fg-merge	Integrator (outside the loop)	Integrates a branch's forge root after a git merge — a deterministic script (forge-merge.sh/.js) moves time-ID ADRs as they are (on a collision, the next letter; no cascade renumbering), reassigns task numbers, and merges CONTEXT/retro/done/backlog, exiting nonzero on a structural conflict (usable as an AI-free CI gate). The core script is git-free (CI); fg-merge <branch> runs the git merge for you interactively (ADR 260717-10a); fg-merge to main commits, merges, integrates, and commits from the feature branch (ADR 261006-102435)	.forge/branch/<branch>/	Integrated .forge/ documents	— (integration step)
fg-cleanup	Retirer (outside the loop)	Retires stale/superseded ADRs out of the active decision set — proposes candidates with rationale and, on approval, moves each to .forge/adr/retired/<NNNN>-slug.md with a supersede/retire mark. Numbers never change, are never reused, and nothing is deleted. fg-ask stops reading retired/ as source of truth	.forge/adr/*.md	.forge/adr/retired/*	— (ADR upkeep)
fg-statusline	Setup utility (outside the loop)	Shows forge's loop progress in the statusline in one of two modes — method 1 (append) auto-wraps your existing statusline as a separate row below (a thin forge fragment, ADR-0017); method 2 (merge) installs a unified script that prints daleseo-style system info (model · directory · ⎇git · Context/size + gradient bar + $cost/±lines/elapsed) plus forge progress in semantic group brackets, with a compact/full density toggle (a command argument) (ADR-0029)	Existing settings.json	A statusline script in ~/.claude/ + the statusLine setting	— (terminal display)
fg-adversarial-review	Review utility (outside the loop)	Optional adversarial review between fg-run and fg-learn — records findings, and approved code defects become a fix-forward plan; seal the original task first to free the slot, then run the fix plan	active plan.md · run.md · working-tree diff · CONTEXT/ADR	.forge/review.md + (on approval) a fix-forward backlog plan	fg-learn → fg-done → fg-run
fg-doctor	Health check (outside the loop)	Read-only integrity check — a deterministic script (forge-doctor.sh/.js; exit 0/1/2 makes it an AI-free CI gate) surveys the .forge/ state contract (orphans · STATUS fields · slug pairing · half-sealed · an orphaned branch root = a forgotten fg-merge) and docs/manifest consistency (version synced across Claude/Codex manifests · README bilingual sync · the CLAUDE.md skill list · ADR-ID uniqueness across both formats), plus cross-reference integrity inside skill bodies (§N self-references — a partial guard for the empty pointers a conditional split leaves behind), reporting each violation with severity and a fix hint; writes nothing and never auto-fixes	.forge/* · manifests · README · CLAUDE.md (read-only)	Printed report (no files)	— (fix via fg-quick/fg-ask)
fg-help	Help reporter (outside the loop)	Read-only usage help — /forge:fg-help (no argument) prints an overview of every forge skill grouped by the loop's four stages plus the outside-the-loop utilities; /forge:fg-help <command> prints a 4-line detail for one skill (what · when · trigger · next step). It reads each skills/*/SKILL.md frontmatter description as the single source (zero copies) and renders it in the user's language via the LLM — no deterministic twin, because a script cannot translate (this is what sets it apart from fg-status/fg-doctor). Writes nothing, never auto-runs	skills/*/SKILL.md — Glob path pinned to the plugin's skills/ (read-only)	Printed report (no files)	— (docs utility)
fg-drop	Discard utility (outside the loop)	Discards incomplete work — a selection UI sized to one/few/many items; a goal loop is deleted or archived whole, loop.md plus its members' incomplete state (done and non-members untouched); removes forge state only	.forge/* (unsealed)	Hard delete or .forge/dropped/<slug>/	— (self-contained)
fg-agents	Generator utility (outside the loop)	Conversational grilling mines the project domain to derive roles, then writes standard .claude/agents/<role>.md cards (each description carrying a "when to use" → fg-run maps slice↔role automatically). Reads active ADRs as fuel so cards reflect the project's decisions lightly. Cards load at session start, so a restart is required after generating them (ADR-0024). Graceful · optional	.forge/codebase/ · CONTEXT.md · active .forge/adr/ (optional fuel)	.claude/agents/<role>.md cards	— (fg-run uses them after a restart)
fg-showme	Visual utility (outside the loop)	Browser-based visual companion (engine re-checked against v6.3.0 — no upstream change to port) — obra/superpowers v6.1.1 Visual Companion, vendored with MIT attribution. A zero-dependency Node server shows HTML the agent pushes (mockups, diagrams, visual A/B comparisons) live in a browser tab and takes the user's clicks and text input back as events (JSONL) that the agent reads as answers. On an event_wake host, a required confirm button on choice screens wakes the agent directly with no terminal turn; on other hosts, confirmation needs one subsequent terminal turn (exploratory clicks do not wake it), and fg-ask offers it just-in-time once when a visual question arrives (no re-offer if declined). This skill is the standalone entry point (ADR 260719-224442 · 260730-224259 · 260805-005436)	HTML the agent pushes	Top-level .forge/showme/<session>/ on every branch (ephemeral · global exemption) + click events (JSONL)	— (shut down with fg-showme stop)
fg-agenda	Planning utility (outside the loop)	Decision queue — the place where a decision not yet made lives. Settles the destination with you first, grills breadth-first to surface what must be decided, and keeps it in a single file, .forge/agenda.md (destination · decided · open questions · fog · out of scope), then resolves questions one at a time using fg-ask's method and deletes itself when no open question is left. The agent surfaces them; the human gives every answer (pillar 1)	A loose idea (open) or an existing .forge/agenda.md (working)	.forge/agenda.md + any conditional ADR a resolution produced (a decision that becomes buildable goes to fg-ask as a backlog plan)	— (next question in the same conversation by default; fg-ask once it is buildable)
fg-security	Audit utility (outside the loop)	Security audit of a codebase — vendored cloudflare methodology; artefacts outside the repo; severity-gated findings become fix-forward plans	the whole codebase + prior runs' findings.json (repeat runs skip known findings and target gaps)	~/security-audit-skill/<repo>/run-N/ (REPORT.md, FINDINGS-DETAIL.md, findings.json — outside the repo) + .forge/backlog/*.md on approval	fg-run (runs the approved fix-forward plans) — never a seal gate
fg-debug	Diagnosis utility (outside the loop)	Conversational diagnosis discipline for hard bugs — vendored diagnosing-bugs (MIT); builds a red-capable feedback loop, reproduces and minimises, ranks hypotheses; diagnosis only (the fix belongs to the loop)	a bug report + the project working tree	active failure: return to fg-run; independent diagnosis: fg-quick if trivial, approved .forge/backlog/*.md if non-trivial; red commands count as evals only when durable, raw captures stay outside the repo with cleanup on every exit	fg-run (returns an active failure or runs the approved fix plan)

The handoff table — the shared shape of every next-step guidance

The next-step guidance a skill emits at the end renders as a fixed four-row handoff table (Just did · Next step · How to start · Alternative). It fixes, with a shape, the problem of the next step being buried mid-paragraph (the pain was findability, not length), and it applies always, regardless of the eco gate — ADR 260805-231104.

• The table renders in the user's language. The canonical row labels are English (Just did · Next step · How to start · Alternative) — those are the names used to refer to a cell, since skill documents are written in English — and they are translated into the user's language on screen. Only paths, .forge/ fields, and /commands are verbatim; natural-language triggers are not verbatim — the cell is filled with whichever of the skill's registered Korean/English triggers matches the user's language.

• Applies at 15 points — the loop's four stages (fg-ask · fg-run · fg-learn · fg-done) plus the eleven utilities that have a real next step to point at (fg-status · fg-next · fg-loop · fg-quick · fg-map · fg-doctor · fg-agenda · fg-adversarial-review · fg-agents · fg-security · fg-debug).

• Excluded at 7 points — fg-config · fg-statusline are toggles and setup, so they have nothing to point at and their one-line body is shorter than any table. fg-cleanup · fg-drop · fg-showme · fg-help emit no next-step guidance in the first place. fg-merge is excluded on the narrowest rationale — what it emits are git-state recovery instructions ("resolve the conflicts → git commit → run fg-merge again"), not a loop handoff.

• The table is not a menu. The statement form is unchanged (ADR-0015) — it is never emitted via AskUserQuestion, the Alternative row is not a question asking you to choose, and the skill states and stops. Chaining is still fg-next's job.

• A conditional next step is filled by a precedence rule. Pin one branch into the row and push the rest into Alternative, and the table ends up instructing the user to do the very thing the skill just advised against (fg-run's and fg-learn's divergence rules are the examples).

• In an unattended drive the delegated skill renders no table — fg-next all and fg-loop suppress it and render only at their own step (a wall or completion). If a delegated "run fg-learn" instruction leaks to the user, the drive stalls (DRIVE.md).

• It is a different thing from the eco summary table — that one answers what was done (its axis is slices, and only when eco: true), this one what comes next. Where both render, each drops the row the other owns.

The single definition is skills/fg-next/HANDOFF.md, and all 15 points reference it (no copy-pasting — the same convention as skills/fg-run/FORGE-ROOT.md and skills/fg-next/DRIVE.md).

Explaining forge — how forge explains its own vocabulary (always)

forge output used to assume its reader knows its vocabulary — verified: failed, unsealed tail, "pillar 1", wall: stalled-waiting are a cipher to anyone who has not read the docs. So all 22 SKILL.md files carry an always-on **Explaining forge** rule next to their **Language** rule. It is independent of the eco gate — ADR 260824-134246.

• Three rules — ① gloss a forge-specific term at its first use in a message (a few words, not a paragraph), ② put the purpose before the mechanism, ③ lead with the answer and close on what it means for the user.
• Keeping it out of eco is the load-bearing decision. eco defaults to false, and the people who most need a gloss — those who just installed forge — are exactly the ones least likely to have turned eco on. Bundling it into eco would deliver the discipline backwards. This is a deliberately different call from ADR-0014's bundling of caveman into eco, and the difference is that caveman saves tokens (axis: cost) while this one lands meaning (axis: quality).
• It divides labour with ECO.md's terse rules — terseness governs form (length, padding), this rule governs vocabulary. A gloss is not filler, so terseness never deletes one. eco off = full prose with glosses; eco on = terse prose with glosses — the glosses are invariant across both.
• Adapted in concept from eli5 by dreambigou (MIT) — not a code vendoring (no files copied). Its audience tables (24 rows of ages, grades, relationships, job roles) were dropped: no forge output is ever read by a five-year-old, a spouse, or a designer, so there is no audience axis left to keep — the variation is between fluency levels, not between people.
• Inlined rather than given a single-definition doc — the rule is three sentences on one line, so a reference line would be about as long as the rule itself (HANDOFF.md and ECO.md earn a file; three lines do not). The cost, 22-way duplication drift, is held by fg-doctor check B17 — it requires the single definition of the canonical body (scripts/explaining-forge.rule.txt) verbatim, by containment, in all 22 files, so a heading kept over a deleted, truncated, weakened or negated body is caught too. Because it is containment and not equality, fg-ask's deliberate superset (one appended sentence) passes with no exception list. Severity is warning — the same rubric as its prose-drift siblings (B12/B13/B15/B16), since a missing style paragraph does not break the release. It applies only inside the forge repo (a user project's own skills would be a false positive, so the scope keys on the top-level manifest name — a nested "author": {"name": "forge"} cannot trigger it).

Loop skills (the four stages)

fg-ask — ① Ask·plan

fg-ask is the loop's entry point — it owns both inquiry/classification and grilling (the former separate fg-plan stage was folded into fg-ask). It triggers on utterances like "start with forge", "new task", "let's work on this", "refine the plan".

On entry it closes the unsealed tail (STEP 0). If you come to start a new task while the previous one is still unsealed, the branch depends on how much judgment is left — if none (verification is at a sealable value and the retro is resolved, or only the retro is outstanding and run.md's divergence is negligible), it seals without asking, reports it in one line, and continues the grilling in the same turn. If judgment remains (high divergence · verified: pending · verified: failed · a halted goal loop) it asks as before, but it holds on to your new request and returns to that spot once the tail is closed — the demand to "finish that, then type fg-ask again" has been dropped (that was the thing breaking the flow). The reach is the active slot only, one task: parked tasks in .forge/executed/ are not a forgotten tail but a deliberate wait, so it reports the count only and touches nothing (that is fg-done all/fg-learn's job). The verification gate (ADR-0009) is inviolable, and fg-ask never performs a UAT itself (ADR 260727-201115).

fg-run — ② Execute

Execution uses the active host adapter: a Dynamic Workflow on Claude Code, bounded collaboration/subagents on Codex, and a serial fallback when delegation is unavailable. Selection, state transitions, UAT, and run recording are shared.

Runs the plan (.forge/plan.md, or a waiting plan in .forge/backlog/) as a Claude Code Dynamic Workflow. If the backlog holds exactly one unexecuted plan it runs immediately with no confirmation question. For 2–3 it uses an AskUserQuestion selection menu (with "Run all" as the last option); for 4 or more, a priority-ordered numbered text list plus an all input — so candidates are never truncated by the tool's four-option ceiling. Only the chosen task is promoted into the active slot and run. It triggers on "forge run", "run the plan", "run this as a workflow" (the older "forge execute" remains an alias). It will not run when there is no plan to run, and it warns before re-running a plan that already ran.

If the project has domain agents (.claude/agents/, e.g. generated by fg-agents), the workflow dispatches the role matching each slice as an agentType — the mapping comes from the "when to use" in each role card's description. Without them the behavior is 100% identical to before (the default workflow subagents, graceful). Note that .claude/agents/ is loaded once at session start, so a card created mid-session is only callable after a restart; and when eco is on, agentType dispatches also get the sonnet cap and the ECO.md injection, though an explicit model: on the role card wins (ADR-0024).

fg-learn — ③ Retro

After execution it classifies the learnings and promotes them to CONTEXT.md, ADRs, and the retro log (.forge/retro), then surfaces the next inquiry. As a fourth destination, a mechanically checkable learning is promoted as an eval — a persistent regression check living in the project's own test suite (in a repo with no suite, an equivalent executable landing spot) (ADR 260906-171420). It triggers on "forge learn", "let's do a retro", "write up this task". It is always conversational and respects the promotion discipline.

fg-done — ④ Done

Tidies up what the cycle left behind — confirms the retro, marks STATUS.md done, archives the task, and empties the active .forge state to close the loop. It triggers on "task complete", "seal it", "wrap this up" ("tidy up the task" and "forge complete" are recognized as aliases; note that "forge cleanup" now routes to the separate ADR-retirement skill). Emptying the active state is what blocks the same plan from re-running.

The mechanical seal (pre-checks · gate enforcement · closing STATUS.md · archiving · clearing the slot) is handled in one shot by the deterministic script forge-done.sh/.js, and the skill only routes on its exit code — making it the script-backed skill that follows fg-status (ADR-0020). This script is the single seal primitive shared by all three seal paths — interactive fg-done, fg-done all, and fg-next all (delegated) — and unlike the read-only fg-status it moves files, so it is gate-first and non-destructive (it touches nothing until the verification and retro gates pass, refusing with a reason instead) and is protected by behavior + parity tests (ADR-0030).

When you seal with an explicit single /fg-done, it renders a seal summary on screen right after closing — "the requirement + what was done" reconstructed from the archived plan, run, STATUS, and retro (requirement / what was done / a retro chapter only when a retro file exists / verification, docs, and archive metadata). It is not saved to a file, and the seal script does not touch it — it is judgment-layer prose. Conversely, batch/unattended paths keep the current terse notice — fg-done all, fg-next (one-shot, whether via autochain or a direct fg-done delegation, and all), and fg-loop — because the point there is keeping the flow, and after an autochain the retro has just finished, so the summary would be redundant. The rationale for this asymmetry is ADR-0032.

The all argument (fg-done all, "seal all") is a seal-only batch mode — it unconditionally skips the retro of every already-executed task (the active slot plus everything in .forge/executed/) and seals each into its own done/. It is the seal-only cousin of fg-next all, and it does not promote or run unexecuted backlog tasks (that is the only difference). The verification gate (ADR-0009) is inviolable, so it seals only sealable verified: values, routes failed to an fg-run repair, and for pending repeats per task the same seal-time UAT as the single path. Just before sealing it shows the included/excluded lists once, takes a single go-ahead, and then seals everything without a per-task question. The skipped retros stay auditable as retro: skipped (fg-done all — …), and the learnings are preserved in run.md (ADR-0023).

Outside-the-loop utilities (18)

fg-map

fg-map is not a loop stage — it is an on-demand utility you run when the codebase has changed enough that the map is stale, triggered by utterances like "analyze the codebase", "map the codebase". If a map already exists, the normal path is an Update (a diff increment against the last_mapped_commit stamp — it edits the 7 documents in place, so the cost is proportional to the amount of change, not to the size of the codebase); if the stamp is missing or is not an ancestor of HEAD (a rebase or force-push), it falls back to a full Refresh without asking (ADR 260801-020258).

fg-quick

fg-quick is also outside the loop — a lightweight lane for trivial work (typos, small renames, version bumps) that still grills, but lightly, then runs directly with no formal artifacts (no ADR/plan/retro) and records one line in .forge/quick/LOG.md. If the grilling reveals the task is non-trivial, it bails to fg-ask (the formal loop). It triggers on utterances like "forge quick", "quick task", "just do this quickly".

fg-status

fg-status is also an outside-the-loop, read-only reporter — run it any time to see where every task stands (active slot · backlog · awaiting retro · done history · quick-lane log) plus the single next step you need; it writes nothing and never auto-runs. It triggers on utterances like "forge status", "where am I", "how far did I get".

fg-next

fg-next is fg-status's acting sibling, also outside the loop — it derives the same single next step (by reusing fg-status's state machine, not reimplementing it), announces it in one line, and then runs that skill right away — it does not stop at reporting and does not wait for a separate approval. It is one-shot (a single step; from there the invoked skill's own handoff takes over) and writes nothing itself, delegating every action to that skill — the sole exception being when the retro (fg-learn) finishes normally with no re-grilling recommendation, in which case it chains straight through to the seal (fg-done) in the same invocation (ADR-0026). It is the cold-re-entry entry point for "I can't remember where I left off, just do the next thing." In all mode (fg-next all) it drives tasks one at a time to completion until the backlog is empty — it auto-advances through the linear mechanical steps and always auto-skips the retro (regardless of divergence), but halts at the conversational walls (failed/unverifiable UAT · a genuine fork · empty state) and hands back to the human. It is the momentum superset that extends fg-run's "Run all" through verify → done (ADR-0010). Continuity in an unattended drive rests on two axes — continuing within the turn (not treating a delegated skill's statement-form stop as a turn boundary, and proceeding to the next step immediately — best-effort) and /goal fallback (the primary path is forge's own shipped Stop hook — the drive writes a drive.md marker and the hook returns exit 2 to prevent the turn from ending, so no user action is needed; bounds 30 min / 50 blocked stops. The paste-ready /goal line is offered only when the hook may not be live, and without either the drive runs one cycle and stops — that is expected, re-trigger to resume) — and this shared discipline is defined once in skills/fg-next/DRIVE.md and shared with fg-loop (ADR-0028). It triggers on utterances like "forge next", "next step", "keep going", "fg-next all", "run all the remaining steps".

fg-loop

fg-loop all also leaves the retros behind. By default fg-loop skips each verified task's retro and seals. Started as /fg-loop all <goal>, it records retro: auto in loop.md and, just before each seal, writes a retro log from that task's plan, run, and repair record only (marked <!-- auto-retro: fg-loop all -->), then seals. A resume with a bare /fg-loop keeps the same mode. The auto retro neither promotes to nor proposes changes for CONTEXT or ADRs; its STATUS reads "auto, promotion unreviewed", which makes it a candidate for fg-learn's batch promotion (ADR 261010-230950).

A resume is not authorization to clear a blocker. When loop.md retains a wall:, fg-loop first checks prior approvals and relevant changes or evidence. If nothing changed, it does not rerun the same checks or repeat /goal; it names the decision or evidence still needed. It records an already-approved scope change and continues in the same turn. An explicit recheck request authorizes diagnostics only, not broader repairs or a verification waiver, and failing observations remain separate from actual repair attempts.

fg-loop is the third lane, goal-driven, also outside the loop — an initial conversational inquiry pins a machine-verifiable stop condition (a check the agent can actually run — "the AI thinks it is satisfied" does not count), an approved fix-forward replan scope, and a replan cap (3 rounds by default) into .forge/loop.md, loads the initial backlog plans, and then drives the entire task loop (run → UAT → always auto-skip the retro → seal, reusing fg-next all's machinery by reference) until every check passes. A failing stop check with an empty active slot becomes a normal PLAN-FORMAT plan marked generated-by: fg-loop, whereas verified: failed does not produce a separate backlog plan — after checking cap, scope, and safety first, it repairs the same active task in place with a repaired-by: fg-loop marker and re-runs it through fg-run's failed branch. That distinction keeps the one-active-slot contract intact while leaving verified: failed an automatic fix-forward case. At the walls — unverifiable UAT · a genuine fork (including an out-of-scope fix) · cap exhausted · the same check making no progress twice in a row · tension (a regression ping-pong where a fix-forward breaks a check that already passed) · safety (an irreversible action class, even inside the approved scope) · stalled-waiting (a wait stuck at ×2 with unchanged evidence) · blocked-health (a check command that cannot even run — a missing tool or credential) · budget-exhausted (the declared token ceiling is reached, or the pre-flight estimate says the remaining budget cannot cover the observed per-task average) — it halts and hands back to the human; when the goal is met it reports a summary and deletes loop.md. This is a deliberate, bounded relaxation of pillar 1 (ADR-0016); the retro learnings remain in the archived run.md for a human to promote in bulk later via fg-learn. loop.md persists a per-check progress ledger (## Check progress — result · ×N consecutive no-progress · regressed: ×N (pass→fail regression count) · last-evidence · attempted slug · reflection) and a wall: field: Reflexion (verbalizing the failure and injecting it into the next fix-forward — persistence is mandatory because fg-loop resumes statelessly) makes the next fix-forward try something different rather than repeating the same approach, the no-progress wall is decided from the ledger's ×N≥2 rather than in-session memory, and fg-status reads these fields to report why it halted (rather than a bare "resume") (two 2026-06-18 amendments to ADR-0016). reflection is volatile working memory inside the drive, not a retro. A check may declare evidence: external (off by default), and a declared check that has not passed is unconditionally waiting — not a failure and not a wall, so it consumes no replan-round, creates no fix-forward, and simply ends the turn without asking the human for anything (a re-trigger resumes once the evidence arrives). The price of limiting the verdict to a declaration is that "a red CI" and "an unfinished CI" cannot be told apart, so declared external checks are excluded from automatic repair — which makes the cap that promotes a consecutive waiting ×2 with unchanged evidence into a stalled-waiting wall the only safeguard against waiting forever. Before running the first check of a drive it derives each check command's executable and confirms it exists (a blocked-health wall if absent), and only for cases pre-derivation cannot catch — a tool behind a pipe, a missing credential — does it promote conservatively after the fact (when ambiguous, treat it as an ordinary failure — the asymmetry exists because misclassifying a failure as an environment problem hides real bugs). waiting ×N was absorbed into the existing ledger rather than a new field, and evidence: external into the existing check section, avoiding consumer ripple (a LoopX concept adaptation — quota and scheduling were not adopted because forge has no competition between multiple goals; ADR-0016 amended 2026-08-09). The spend ceiling is the one deliberate exception: two top-level fields (budget-tokens and budget-spent · since:) — spend belongs to no single check, so the ledger was never its home, and its structural twins are replan-round/replan-cap. The deterministic twin forge-loop-spend.sh/.js sums the raw four usage fields across the session transcript and every subagents/ transcript as a delta since since:, and is called once per task boundary, yielding overrun (exit 3), predicted overrun (exit 4) and unmeasurable (exit 5) in one go, handing the verdict back as an exit code (two calls was a bug: the first advanced since:, so the second re-counted the interval). When a ceiling is declared but cannot be measured — transcript root missing, since: not a timestamp, ceiling value unparseable — it halts at a blocked-health wall instead of quietly reporting zero spend; failing to tell "nothing spent yet" from "cannot measure" is what silently voided the ceiling. Counting cache reads is the whole point: they are the context re-sent on every iteration, and replan-cap bounds only rounds, so it cannot see that growth. What the number is, though, is token throughput for the whole project while the loop is alive — not this drive's billed cost: a safety bound rather than an accounting ledger, where over-counting is the safe direction (ADR-0016 amended 2026-08-20). The ceiling is asked by extending §1's existing cap question (none is a valid answer and bypasses everything) and no default is invented (that waits on measured drives). It consumes no replan-round and creates no fix-forward, and the only way out is the human raising budget-tokens (budget-spent is never reset). Unlike the other walls, its absence from fg-next all is a scope decision, not a structural impossibility — that lane also drives unattended, but has no contract file to hold a ceiling (ADR-0016 amended 2026-08-19, GitHub issue #12). It triggers on utterances like "forge loop", "start a loop", "repeat until the condition is met".

Per-task commit on an unattended drive (opt-in). When driveCommit in .forge/config.json is on (strict boolean, default false), fg-next all and fg-loop commit locally at each seal, leaving a per-task rollback point — because when several tasks seal with nobody watching, there is nothing to roll back to. Commit only; a drive never pushes (rollback is complete at the local commit, and pushing only removes reversibility). The key discipline is that staging is never inferred: the drive commits only if git status --porcelain is empty at entry (then git add -A is exactly what this task changed), and otherwise makes no commits for that drive and says so in one line. Nothing to commit is a state, not a failure, so it continues silently; a refusal (pre-commit hook, detached HEAD, mid-merge) halts at the existing fork (commit rejected — <reason>) wall — no tenth wall is minted. The default message is {title} (forge task #{task} · {slug}), overridable via driveCommitMessage (placeholders are exactly {title} · {slug} · {task}; an unknown one falls back to the default and warns). Single definition: skills/fg-next/DRIVE.md Part 3; rationale: ADR 260901-213128.

fg-config

fg-config is also outside the loop — the single entry point for the six .forge/config.json keys (simple·eco·tdd·driveCommit·driveCommitMessage·defaultBranch) (fg-config with no argument = the full settings table + a change menu · fg-config <key> = one key · fg-config <key> <value> = set it). It replaces the former per-key toggle skills and absorbs their old triggers like "eco on" and "turn TDD on" (ADR 260905-212045).

simple — auto-seal mode (new, ADR 260905-212045). With simple: true, fg-run unconditionally skips the retro after UAT (verification) and chains into the seal in the same turn (the verification gate stays inviolable). For the flow comparison table, the diagram, and when to turn it on or off, see the config modes guide.

tdd — the test-first default (ADR-0008, semantics unchanged). fg-ask asks "TDD for this task?" per task with this setting as the default answer, and when the plan's tdd marker is on, fg-run runs test-first.

eco — eco mode (semantics unchanged). Binary on/off; turning it on activates three efficiency behaviors under the single principle "waste nothing in the forge loop" (ADR-0014 (eco subagent model tiering) as amended, and ADR 260730-230321).

1. Model cap (cost savings). fg-run caps its delegated Dynamic Workflow subagents at sonnet — downward only (it never raises a tier; if already at or below sonnet, inheritance stands), an explicit user model instruction wins, and the main session model is untouched. Since a skill cannot change the session model (which is why automatic per-stage model switching is impossible — the premise of ADR-0014), design (fg-ask) and completion (fg-done) run on whatever model you chose, and the result is a two-tier split of powerful = main session · ordinary = delegated execution. fg-map is deliberately out of scope (map quality is grilling fuel, so the risk outweighs the savings).
2. The Eco laziness-first discipline (code and plan complexity savings). The embedded restraint discipline (skills/fg-config/ECO.md — "the best code is the code you didn't write") applies in three places: (a) the six-rung ladder (YAGNI → stdlib → native → existing dependency → one-liner → minimal code) and its core constraints are prepended to fg-run's every delegated subagent prompt, (b) it is woven into fg-ask grilling as a quiet YAGNI lens ("is this really needed? what is the minimal version? does an existing mechanism cover it?"), and (c) the current session adopts the discipline every time it observes eco: true — it fires not only on the toggle but on any main-session eco read (a no-arg check that stays on, a direct fg-run, an fg-ask handoff), making it state-based (the model is still untouched; note that at the very start of a fresh session where no skill has run there is no session-start hook, so self-adoption is impossible — the first skill that reads eco picks it up). Trust-boundary validation, data-loss prevention, security, accessibility, and explicit requests are never simplified, and non-trivial logic keeps one runnable check. This discipline is not a standalone skill but part of eco (no separate toggle), borrowed and adapted from DietrichGebert's Ponytail (credited in the README). On top of that, ECO.md also carries output prose compression (terser execution and reporting prose — code, commands, and errors stay verbatim; grilling questions, generated documents, and explicitly requested explanations are exempt; borrowed from JuliusBrussee's caveman), saving communication tokens (ADR-0014's second amendment).
3. The eco summary table (reading-effort savings). At the points where a task ends — fg-run's single-task handoff, fg-done's explicit single seal, and the batch/unattended paths (Run all, fg-done all, fg-next's delegated seal, fg-next all, fg-loop) — it replaces the prose handoff (replaces, not adds — appending would make the text longer, defeating the purpose): a one-line header (title · #task · verified · divergence) + ▸ Request (the plan's Goal, one line) + ▸ Done (a slice table: # · slice · result · vs plan) + ▸ Next (the next step and its trigger, one line). Batch paths use a table with one row per task. It is a rule of shape born from the evidence that #2's compression, being a style instruction, left no visible sign of compliance and in practice fell short; and to guarantee the table's raw material, fg-run always records a one-line result per slice in run.md (regardless of eco — so the table still holds when the task is sealed in a later session). The verification state (verified:) is the information that decides whether the task can be sealed, so it is never dropped from the header (ADR-0009). Narration during execution is untouched so you can still see where things got stuck; grilling, retros, generated documents (plan/run/retro/CONTEXT/ADR), and fg-quick are exempt; and with eco: false the prose stays exactly as before. The shape is defined in ECO.md alone, and fg-run, fg-done, and DRIVE.md only reference it (ADR 260730-230321, GitHub issue #7).

driveCommit/driveCommitMessage · defaultBranch — the per-task local commit on unattended drives and its message template (see the fg-loop section above, ADR 260901-213128), and the default branch for forge-root resolution (ADR-0011).

It triggers on utterances like "forge config", "settings", "simple mode", "eco on/off", "eco mode", "tdd on/off".

fg-merge

fg-merge is the integration utility for branch isolation, also outside the loop — after you git merge a feature branch, it folds that branch's .forge/branch/<branch>/ into the default branch's .forge/. The mechanical integration is performed by a deterministic script (forge-merge.sh/.js, dual dispatch): it moves the branch's time-based ADRs as they are (an exact ID collision is resolved locally by taking the next free letter — no cascade renumbering, so cross-references never break), reassigns only the task: numbers of incoming done/ + backlog/ plans through a map that avoids collisions with the target, then merges CONTEXT, retro, done, and backlog and removes the branch folder. Being a script, it can also serve as a CI gate with no AI involved (nonzero exit on a structural conflict), and it stops to ask a human only on genuine conflicts — a term redefinition (a term is a **name**: entry and ## X is a group subheading, so two glossaries sharing ## Language is not a conflict) · an incoming NNNN collision · an unrecognized CONTEXT format (if there are only ## headings and zero **term**: entries, term-level merging would silently do nothing, so halting is safer than a no-op merge) — while semantic ADR contradictions are outside the script's scope and belong to PR review. The core script never runs git itself, so it is usable AI-free in CI, and as an interactive convenience fg-merge <branch> runs the git merge for you first (skill layer only · default branch only · stops in place on a conflict — ADR 260717-10a). The third mode, fg-merge to main, goes the other way: run from the finished feature branch, it chains commit your work → check out the default branch → git merge → integrate → commit the integration. Before step 1 it runs the script's --gate-only (judges only the in-flight gate, moves nothing) to stop on unfinished forge work, asks for confirmation once just before committing, and — though it is the only mode that commits — never pushes or deletes the branch (ADR 261006-102435). It triggers on utterances like "forge merge", "fg-merge <branch>", "fg-merge to main", "integrate the branch" (ADR-0011). For the team's merge ritual, conflict ownership, and CI gate usage, see team-workflow.md.

fg-cleanup

fg-cleanup is the ADR retirement utility, also outside the loop — it retires stale or superseded ADRs out of the active decision set: it proposes retirement candidates with rationale and, once a human approves, moves each ADR to .forge/adr/retired/<NNNN>-slug.md with a one-line Superseded by ADR-NNNN / Retired (reason) mark. Numbers never change and are never reused, and nothing is deleted (the "why" stays on disk). fg-ask does not read retired/ as source of truth, so a retired decision drops out of grilling fuel. Retirement is human-approved on principle, never automatic, and sealing a task is fg-done's job, not this skill's. It triggers on utterances like "forge cleanup", "tidy up the ADRs", "retire ADRs", "clear out the old ADRs" (ADR-0012).

fg-statusline

This is a Claude Code UI utility. On Codex it does not edit settings and directs the user to $fg-status.

fg-statusline is a one-off setup utility, also outside the loop — it shows your current position in the forge loop in the terminal statusline, in one of two installation modes (ADR-0029). Both modes share the same thin fragment for the forge progress row; they differ in what else they show and in who owns the command.

• Method 1 (append/wrap) — installs the thin forge-only fragment (scripts/forge-statusline.sh/.js) at a stable path, which reads .forge/ and prints up to 2 rows in semantic group brackets [...] — the first row is the goal-loop indicator [🔁 rN/cap] (when present) followed by the forge group [⚒ #N slug · colored ✔ ask → ● run → ○ learn → ○ done · flag] (only the current stage is highlighted · done is decorative · the verified flag sits at the end of the pipeline), and the second row is the queue + mode group [📋 N queued · 📝 M awaiting retro · ✗ K failed · ♻️ · 🧪] (📝 counts only parks that can be retro'd; a verified: failed park is tallied separately as ✗, since it is blocked from both retro and seal and needs fg-run recovery — the same split the SessionStart hook reports. 🧪 = the plan's <!-- tdd: on --> · ♻️ = top-level config eco: true — lit only during real activity, excluded when idle); when idle it prints nothing. The separator defaults to · (FORGE_SL_SEP) and it is uncolored, so method 1's append character is preserved. Claude Code allows only one statusLine, so it auto-wraps your existing command and appends forge as a separate row below (the original is preserved). It is a thin reader that draws no system information whatsoever (ADR-0017; only the group brackets and emoji indicators come from the ADR-0029 amendment).
• Method 2 (merge) — a forge-owned unified script (the scripts/forge-statusline-full.sh/.js twins) prints daleseo-style system information and forge progress in group brackets from a single script. full (4 rows): [model|reasoning effort] [directory|⎇git(↑N ↓N +!?)] [⏱|$cost|±lines] / [dynamic emoji Context/size gradient bar N% | 5h … | 7d …] / the forge group / the queue + mode group. compact (2 rows): system + bar on one row, plus a single forge group (the session group is dropped). Density is stored as a positional argument on the command (compact/full, defaulting to full), so there is no new config key. The separator is | (delegated to the fragment as FORGE_SL_SEP=|), and colors and gradients are live-tunable. The forge portion is delegated to the fragment so the stage logic is reused (no triple duplication · parity tests), and when forge is idle only the forge group disappears while the system rows remain.

The installation decision: with an existing statusline you choose 1 or 2; with none, 2 is automatic; on Windows with an existing one, only 2 (method 1's wrapper is bash-only). When method 2 replaces an existing statusline, it preserves the original and tells you how to restore it. The mode is detected from the wired command path and the density from that command's positional argument (neither adds a config key — installing method 2 asks about density once and pins it as an argument, and a refresh preserves the existing density). In either mode the source of truth for the next step is still fg-status, and after a forge update you refresh the script by running the skill again. It triggers on utterances like "forge statusline", "status bar", "set up the statusline" (ADR-0017 · ADR-0029).

fg-adversarial-review

fg-adversarial-review is an optional review utility, also outside the loop — it runs a deliberately hostile second look between fg-run and fg-learn, before the seal. The reviewer takes the attacker's, the opponent's stance, starting from "assume this result is wrong and find the evidence", and fans out six lenses — failure points · hidden assumptions · misread requirements · security/performance/data loss · unexpected misuse · weak or unverified reasoning — as parallel Dynamic Workflow subagents (no human input is needed during execution, so it does not violate pillar 1). Findings are recorded in .forge/review.md, and at the handoff a human judges each one — a code defect becomes (after approval) a fix-forward backlog plan (generated-by: fg-adversarial-review), but because the original task occupies the active slot, the original task is sealed first through fg-learn → fg-done before fg-run picks up the fix plan. Design and requirement defects go back to fg-ask re-grilling, and accepted findings feed the retro. It is purely optional and never a seal gate (the gates are verified: and the retro only), and fg-next all / fg-loop always skip it because judging findings is a human's job. It triggers on utterances like "adversarial review", "red team this", "find the holes" (ADR-0018).

fg-doctor

fg-doctor is a read-only integrity health check, also outside the loop — harness engineering's init.sh health check applied to forge. Where fg-status reports how far you have got, fg-doctor reports whether the state is healthy: it surveys the .forge/ state contract (an orphaned run.md · corrupted STATUS fields · a plan↔STATUS↔retro slug pairing mismatch · a half-sealed done/ · backlog markers and task-number uniqueness) and the persistent documents/manifests (the version synced in 4 places · JSON validity · skill name frontmatter · skill-count consistency · the completeness of CLAUDE.md's skill list · README bilingual sync · ADR numbering and cross-references), classifies each violation as error/warning/info, and prints an actionable fix hint per item. It writes nothing and never auto-fixes — a human fixes things with fg-quick (trivial) or fg-ask (non-trivial), and no other skill calls it automatically. It triggers on utterances like "forge doctor", "integrity check", "state check", "health check", "check forge state" (ADR-0019).

fg-help

fg-help is a read-only usage reporter, also outside the loop — it answers forge's third read-only question: where fg-status reports how far you have got (progress + next step) and fg-doctor whether the state is healthy (integrity), fg-help reports how you use these skills (usage). /forge:fg-help (no argument) prints an overview of every forge fg-* skill grouped by the loop's four stages (fg-ask → fg-run → fg-learn → fg-done) plus the outside-the-loop utilities; /forge:fg-help <command> prints a 4-line detail for one skill (what · when · trigger · next step). The single source of usage text is the frontmatter description of each of the plugin's skills/*/SKILL.md, read by pinning Glob's path argument to this skill's parent directory (a ${...} pattern is matched literally and a ../ pattern resolves against the user's working directory — both silently return zero files) — no copies are kept (no fifth sync surface), so a new skill appears automatically without editing fg-help. The glob targets forge skills only (other plugins' skills are excluded — forge cannot vouch for the quality of their descriptions). It has no deterministic script twin — its core job is rendering an English source description in the user's language, and a script cannot translate (this is what sets it apart from the script-backed fg-status/fg-doctor). fg-status cross-references it for a lost user ("for usage, /forge:fg-help"). It writes nothing, never auto-runs, and like fg-cleanup and fg-drop it emits no handoff table, keeping its prose. It triggers on utterances like "forge help", "fg-help", "help", "usage", "how do I use forge" (ADR 260814-104534).

fg-drop

fg-drop is the discard utility, also outside the loop — it removes incomplete (unsealed) work you no longer want: backlog plans, the active slot, awaiting-retro tasks in executed/, and a halted goal loop.md (a sealed done/ is not a target — that is fg-done's territory). It first presents the incomplete items with a per-item risk level (for one item, a drop/cancel pair; for 2–4, checkboxes; for 5 or more, a numbered text list). A separate follow-up question then lets you choose between a hard delete (the default, leaving no trace) and archiving to .forge/dropped/<slug>/. A confirmation gate blocks the irreversible delete once more and warns that code already changed by an executed task is not reverted — fg-drop removes forge state only and never touches git or your code. A halted goal loop is dropped only as a whole, with no per-member exclusion (so that no loop.md membership re-sync logic has to exist). .forge/dropped/ is ephemeral (gitignored), so fg-doctor tolerates it and fg-status ignores it. It triggers on utterances like "forge drop", "fg-drop", "throw this task away", "cancel this task", "delete the plan", "clear the backlog", "drop task", "discard plan" (ADR-0021).

fg-agents

Its current generated output is Claude Code's .claude/agents/<role>.md. Codex-native project-role materialization is not yet supported.

fg-agents is a generator utility, also outside the loop — it creates the project's domain agents. Conversational grilling (pillar 1, outside the workflow) mines the kinds of work that recur in the project and can be separated out, derives roles from them, and writes standard Claude Code subagent definitions, .claude/agents/<role>.md (role cards), itself. Each card's description must carry a "when to use" — fg-run's workflow builder uses that description to map the plan's work slices to roles automatically (ADR-0024 chose automatic mapping over mapping markers on the plan side). If a .forge/codebase/ map, CONTEXT.md, or active .forge/adr/ exist, it reads them as grilling fuel; if not, it explores directly or proceeds from your explanation alone (graceful · no hard dependency). Since ADRs are the project's documented decisions, it reflects relevant ones lightly in the card's system prompt (as prose, not by mechanically citing numbers) so the card is aligned with the project rather than generic — it does not read retired/ (ADR-0012), and on a non-default branch it uses the read-overlay (ADR-0011), identical to fg-ask's ADR reading discipline. Only the subset of roles a human approves becomes cards, and if there is no good seam, zero is an honest result (no forcing roles into existence — the same restraint as fg-cleanup). The key constraint (ADR-0024): .claude/agents/ is loaded once at session start, so cards created mid-session are not picked up dynamically — a card generated by fg-agents is only loaded and dispatched as an agentType by fg-run after you restart the session. The operating flow is generate → restart → use, and the restart is a one-time project-setup cost. Generated cards are project assets rather than forge .forge/ state, so you commit them to git (the skill does not run git itself). The loop skills point at fg-agents: fg-ask (during grilling) and fg-run (during execution) mention it narrowly and as an offer, once, when a specialized role looks repeatedly useful and no matching card exists (never an automatic invocation, and the restart gate is stated) — isomorphic to fg-agents' own "a role must earn its keep" restraint. It triggers on utterances like "forge agents", "create domain agents", "set up an agent team", "create project agents", "domain agents", "agent roles" (ADR-0024).

fg-showme

fg-showme is the visual companion utility, also outside the loop — obra/superpowers v6.1.1's Visual Companion, vendored with MIT attribution and re-checked against v6.3.0: the five engine files differ only by forge's own modifications (branding/telemetry removed, paths), and upstream shipped no visual-companion change in v6.2.0 or v6.3.0, so there is nothing to port. The name follows the user-side act (show me) rather than the medium (visual) — rationale and rejected alternatives: ADR 260831-140943. A zero-dependency Node server (scripts/server.cjs and 4 other files) shows HTML the agent pushes (mockups, diagrams, visual A/B comparisons) live in a browser tab and takes the user's clicks and text input back as events (JSONL) that the agent reads back. The browser is not display-only but a secondary answer channel — on a choice question a click stands as the answer, a screen can carry a text input box, and answers from both channels are merged, with a one-line follow-up only when they contradict. Choice screens carry a required confirm button, and on an event_wake host a confirm click resumes the conversation directly with no terminal turn, while other hosts require one subsequent terminal turn (exploratory clicks do not wake it); pillar 1 stays intact with its rationale relocated — not because resumption is a terminal turn, but because the browser is not a Dynamic Workflow runtime input (ADR 260730-224259 · 260805-005436). Session files live in top-level .forge/showme/<session>/ on every branch (ephemeral) — a global exemption like .forge/config.json and .forge/codebase/, never moved to the branch root. There is structurally no path into git: start-server.sh writes a self-ignoring .forge/showme/.gitignore (a single *; the user's own root .gitignore is never edited), the session directory is deleted on stop — and the whole .forge/showme/ goes with the last session — and dead sessions left by a crash or the idle timeout are swept at the next start (ADR 260719-224442, amended 2026-09-02). It has session-key URL authentication, survives a server restart and browser reconnection, and auto-shuts down after 4 hours idle; there is no telemetry and no remote resource. fg-ask integration: fg-ask decides before grilling starts whether the task touches a visual surface, or carries enough structure that explaining it will want a picture (the decision point), and offers the companion just-in-time, only once, when a visual question or explanation actually first arrives (the offer point — a standalone message, with no re-offer if declined). The offer is not tied to questions alone — it also fires when you are about to explain something structural (a flow with branches, a state machine, a multi-axis comparison), with a text flow diagram as the boundary: if A → B → C carries it, write that in the terminal. The reason the decision and the offer are separated is that combining them meant the offer never fired at all. If you accept, fg-ask uses ../fg-showme/VISUAL.md and scripts/ directly as file references (the same single-definition convention as ECO.md and FORGE-ROOT.md — no copy-pasting) and shuts the server down at Output (the handoff). The frame theme comes from DESIGN.md at the repo root (the Anthropic/Claude design system — cream canvas #faf9f5, coral #cc785c, editorial serif display). The design lives entirely in 25 CSS variables in scripts/frame-template.html and screen content uses its classes, so every screen an agent pushes inherits the theme automatically. The light theme is a faithful transcription of claude.com's live values, so six pairs land under WCAG AA (the lowest is white on coral at 3.28:1) — a recorded decision favouring brand fidelity, with the full list in a comment in the file; the dark theme passes everywhere (lowest 5.47:1). The server uses no network, so no web font is fetched and the display face is approximated with a system serif stack. The vendored files keep their upstream form but are not byte-for-byte: branding and theme adjustments are recorded in each file's header (ADR 260719-224442 §1). This skill is itself the standalone entry point — fg-showme to start, fg-showme stop to stop. It triggers on utterances like "forge visual", "visual companion", "show me visually", "show me a mockup", "show it in the browser", "compare them on screen" (ADR 260719-224442).

fg-agenda

fg-agenda is the decision queue, also outside the loop — it gives forge a place where a decision not yet made lives. Everything forge produces is a build artifact (plan.md's Work slices) and an ADR records a decision already made, so a large piece of work still in fog either gets forced into a prematurely-complete plan or its decisions scatter across conversation and retro prose and vanish. fg-agenda fills that gap with a single file, .forge/agenda.md — five sections: destination · decided · open questions · what is not yet clear (fog) · out of scope — with one active agenda (the same shape as the one-active-slot discipline), located at the resolved forge root (branch-scoped — treated like loop.md, not a global exemption). When no open question is left it deletes agenda.md (following fg-loop's precedent of deleting loop.md when the goal is met) — the persistent trace is the ADRs and backlog plans the agenda produced, so no new archive was invented.

The boundary of autonomy is this skill's identity: the agent finds out what must be decided, and the human gives every answer. The agent's part is mining open decisions with breadth-first grilling · distinguishing fog from questions (the test is can I state the question precisely right now, not can I answer it) · ordering "what can be answered now" to the top · picking the next question · promoting fog and ruling things out of scope; the human's part is setting the destination and giving every answer. The agent never answers its own question — if it did, the agenda's "decided" would be the agent's guess rather than a decision, and pillar 1 would break. The two modes are split by whether agenda.md exists: open (no agenda) settles the destination with the human first, grills breadth-first, writes the agenda, and then stops — it resolves no question at all, and if no fog surfaces it creates no agenda and points at fg-ask instead. work (an agenda exists) picks one question (if you do not name one, the first line under open questions = the frontier), resolves it with fg-ask's grilling method, writes the answer as one line under ## Decided, writes an ADR too if it clears the three conditions, and re-charts by adding new questions, promoting fog that has become clear, and moving things out of scope.

The agenda owns decisions only — the moment a decision becomes buildable, that line leaves the agenda and becomes an ordinary backlog plan loaded by fg-ask (without this line the agenda becomes a second backlog, and fg-next and fg-run no longer know which to look at). It creates no dependency edges and no blocking (reading a single file top to bottom is the frontier), no ticket-type classification (research/prototype/grilling/task are the names of resolvers, and forge already has all of them — conditional deep research · fg-showme · fg-ask · fg-quick), and no scripts. The grilling method references fg-ask's single definition rather than copying it, and only the output differs (an agenda line + a conditional ADR, not a backlog plan). It is not wired into fg-next/fg-status's next-step chain — that chain belongs to the one task in progress, while the agenda is a parallel planning surface, so fg-status reports it in one line only. It is the mirror image of its sibling utility fg-loop: loop.md is a machine-verifiable stop condition + an unattended drive, agenda.md a judgment stop condition + HITL — the same shape of contract file, opposite in nature. The concept is an adaptation of Wayfinder from mattpocock/skills (MIT) and is a concept adaptation, not code vendoring (no files copied, and the name is forge's own vocabulary — in forge, "map" already belongs to fg-map). It triggers on utterances like "forge agenda", "agenda", "decision queue", "sort out what I need to decide" (ADR 260805-201313).

fg-security

fg-security is a codebase security audit, outside the loop — and the methodology is not forge's. cloudflare/security-audit-skill is vendored here under MIT: AUDIT.md plus nine attack-class playbooks (ATTACK-CLASSES, WEB-PROTOCOL-AND-AUTH, CLIENT-SIDE, AI-AND-LLM, MEMORY-SAFETY-AND-BINARY and more), report-schema.json and validate-findings.cjs, all kept byte-for-byte with upstream so a future diff stays cheap (only the entry file is renamed to AUDIT.md, because forge auto-discovers skills at skills/<name>/SKILL.md and the upstream name would collide — while nesting it risks being mis-discovered as a second skill). It is a multi-phase, multi-agent audit: recon → parallel attack-class hunting → independent validation → report, and upstream itself notes that "the best single run finds roughly half the total vulnerabilities", so repeat runs are recommended.

forge adds exactly three things. ① Findings enter the loop instead of stopping at a report — the artefacts themselves stay at upstream's default ~/security-audit-skill/<repo>/run-<N>/, i.e. outside the repo. The initial design used a top-level .forge/security/, and a pre-seal adversarial review demolished that guarantee: "the existing .forge/* exclusion covers it" is true only in forge's own repo, forge never writes a .gitignore into a user's project, and the ADR itself names the intended use as "the user's other projects that forge drives" — precisely the repos least likely to carry that rule. An in-repo path cannot be made safe by construction; an out-of-repo path has no commit path at all. The cost, stated plainly: artefacts do not travel with a clone, a teammate cannot read them, and a home directory is easy to forget (so the handoff always names the full run path). Two traps surfaced along the way: a "global exemption" (ADR-0011) is about branch namespacing, not git-tracking — two existing exemptions are global and tracked — and !.forge/branch/ tracks a non-default branch's forge root whole. ② Only findings past a severity gate become fix-forward backlog plans, and only with your approval — CRITICAL and HIGH are each offered (grouped when several share one code path or one fix), MEDIUM is offered with grouping recommended, and LOW/INFO stay in the report with no plan. That is the same promotion bar forge applies everywhere (retro promotion, the ADR three-condition gate, CONTEXT.md terms), and it is what keeps a real audit — 5 to 20 findings — from flooding the backlog and making the one-active-slot discipline meaningless. Each plan carries a <!-- generated-by: fg-security --> marker and the next monotonic task: number, and its Definition of Done is "the vulnerability no longer reproduces" — upstream records the data flow for MEDIUM+ findings in FINDINGS-DETAIL.md, and that reproduction path is what fills ADR-0009's verification gate. ③ In the unattended lanes (fg-next all, fg-loop) it is always skipped, like the retro — judging which findings are real and worth fixing is human work.

It never blocks a seal (the gates stay verified: and the retro). It triggers on utterances like "forge security", "security audit", "audit this codebase for vulnerabilities" (ADR 260820-215004).

fg-debug

fg-debug is a conversational diagnosis discipline for hard bugs, outside the loop — and the methodology is not forge's. diagnosing-bugs in mattpocock/skills is vendored here under MIT: the entry file (renamed to DIAGNOSE.md, because forge auto-discovers skills at skills/<name>/SKILL.md and the upstream name would collide) and scripts/hitl-loop.template.sh are kept byte-for-byte with upstream (the fg-security precedent — a future diff stays cheap). The spine of the discipline is Phases 1–4: first build a red-capable feedback loop (preferring a failing test at the correct seam), then reproduce, minimise, and rank hypotheses — there is no new .forge/ state, and only confirmed secret-scrubbed fixtures and persistent tests may remain in the project working tree.

What forge adds is a boundary. fg-debug only diagnoses and decides from invocation state before fix size — diagnosing an active verified: failed task returns to the existing fg-run fix-and-re-run path even when the fix is trivial. Only an independent diagnosis branches to fg-quick when trivial or, when non-trivial, to a human-approved fix-forward plan carrying <!-- generated-by: fg-debug -->. A Phase 1 red command counts as an eval only when it is itself a persistent regression check. A one-shot curl, trace, or HITL command instead requires a persistent-check slice in the plan, or a recorded reason why persistence is not mechanically possible. Only confirmed secret-scrubbed fixtures and tests may remain in the working tree; raw traces, HARs, and logs stay in a temporary location outside it, and every exit — including success, inconclusive diagnosis, and fg-quick handoff — cleans temporary instrumentation and artefacts. Being conversational, it is always skipped in the unattended lanes (fg-next all, fg-loop), like the retro.

It never blocks a seal (the gates stay verified: and the retro). It triggers on utterances like "debug this", "hunt this bug", "why is this broken/slow" (ADR 260907-140655).