forge 发布智能体工程工作流插件，支持 Claude Code、Codex、opencode 和 Pi

An agent-engineering workflow plugin for Claude Code, Codex, opencode, and Pi — one task through a single cycle of ask·plan → execute → retro → done. A loop-style workflow plugin built from twenty-two shared fg- skills — four that form the loop, plus eighteen utilities outside it.

한국어

The full docs below are also published as a docs site — sidebar navigation, search, dark mode — at gyuha.com/forge/docs/en (Korean: gyuha.com/forge/docs).

Planning happens as grill-with-docs-style conversational grilling. Execution uses the active host adapter—a Claude Code Dynamic Workflow, Codex collaboration/subagents, or sequential execution on opencode/Pi—then the retro feeds learnings back into project docs (CONTEXT.md · ADRs · retro log · evals — machine-checkable learnings promoted into the project's own test suite), and the done step seals the task so the same task never runs twice.

The workflow and .forge/ state contract exist once. Claude Code, Codex, opencode, and Pi use the same skills/ and deterministic scripts; only interaction, delegation, hooks, and host UI are adapted. See Using forge with Codex, Using forge with opencode, and Using forge with Pi for each support matrix and its known limits.

Sealing prepares a complete archive before removing source files, and recovery enforces the same verification and retro gates. Branch integration discovers nested branch names at any depth. Mapping follows the active host's delegation capabilities, and Windows hook dispatch preserves the hook's exit code.

Quick start — you mostly only need three

Twenty-two skills look like a lot, but day to day you drive with three:

fg-ask   →   fg-run   →   fg-next
 (plan)       (execute)     (auto-continue: verify → retro/seal)

• fg-ask — start every task here. It grills the plan with you, one question at a time.
• fg-run — runs the plan through the active host's execution adapter.
• fg-next — does the one next step for you (verify → retro or seal). Run it again to keep moving.

Use /forge:fg-* in Claude Code, $fg-* in Codex, the skill name in opencode, and /skill:fg-* in Pi; natural-language triggers work on all four.

Even shorter — plan once, then let it drive itself to completion:

/fg-ask   →   /fg-next all     (execute → verify → seal, looped until it needs you)

When you lose track: /fg-status just shows where you are; /fg-next just does the next thing. Tiny one-off change (typo, version bump)? /fg-quick. To ship the result: type 배포 (deploy).

Everything else in the catalog below is optional scaffolding — reach for it only when a specific need comes up. If you remember just one line: /fg-ask then keep calling /fg-next (or /fg-next all).

Choosing a lane — observe, assist, then run unattended

The three driving skills form a trust ladder — the same graduated-autonomy idea as loop engineering's L1→L2→L3 rollout (report → assisted → unattended). Start low, move up as you trust the loop on a given task:

• L1 — observe (/fg-status): read-only. It just shows where every task stands and the single next step. Nothing runs. Use it to see the board before deciding.
• L2 — assisted (/fg-next): does the one next step and stops. You stay in the seat between steps — review, then call it again. Best when you want to watch each transition.
• L3 — unattended (/fg-loop or /fg-next all): drives whole task loops to completion. /fg-next all drains a human-grilled backlog until it's empty; /fg-loop converges on a machine-verifiable goal, generating bounded fix-forward work along the way. Both halt at the walls (failed/unverifiable verification, a genuine fork, no progress; /fg-loop additionally at a check-tension oscillation, a safety/irreversible action, a stalled wait, or a check command that cannot execute) and hand back with full context. /fg-loop also distinguishes waiting on external evidence (CI, a deploy) from failure — it asks nothing of you and simply resumes on the next trigger. Optionally (driveCommit in .forge/config.json, off by default) each seal also leaves a local commit, so an unattended run has a rollback point per task — commit only, never push; a refused commit is a wall.
  • Running L3 unattended needs no user action — forge ships its own Stop hook (ADR-0028, amended 2026-08-22). A turn ends when the model stops calling tools, and the only mechanism that can prevent that is a Stop hook — which is why /goal used to be required. Now the drive writes a drive.md marker at entry and forge's own hook returns exit 2 while it lives, so the drive crosses turn boundaries (a background workflow finishing, a pause) on its own until it's done or hits a wall. Deleting that marker is how the drive says "I may stop" — it is deleted at every wall, at the terminal state, and before any pause only you can end (a workflow script approval always needs you). Two bounds — 30 minutes and 50 blocked stops — keep a drive that died or looped from wedging the session, and every failure path in the hook allows stopping. /goal remains as the fallback: hooks load at session start, so a session that predates installing or updating forge has none, and there the old behavior holds (one cycle, then re-issue the trigger).

Rule of thumb: grill the plan with /fg-ask first — that human judgment is L1 and is never automated — then pick the lowest lane you're comfortable with. /fg-loop is L3 for a goal you can pin to runnable checks (grep/test/build); /fg-next all is L3 for a queue you've already grilled.

Which one holds the work — fg-ask, fg-loop, fg-agenda

Three skills hold work that outlives a single step, and they are easy to confuse because all three open with a conversation. What differs is what that conversation pins down:

fg-agenda sits upstream of the plan · fg-ask makes the plan · fg-loop drives past it.

The selection test — what can you produce right now?

• I can name the work slices, even roughly → fg-ask. This is the default; the other two are exceptions.
• I can express "done" as commands that pass or fail → fg-loop.
• I can do neither, and the honest answer to "what first?" is "I don't even know what has to be decided" → fg-agenda.

They chain rather than compete — an agenda resolves one question at a time by grilling, and the moment a decision makes something buildable it leaves for the backlog:

fg-agenda ──one question──▶ (fg-ask's grilling) ──▶ a line under "Decided"
    └──a decision became buildable──▶ fg-ask ──▶ backlog ──▶ fg-run ──▶ …
                                                    └── or let fg-loop / fg-next all drive it

fg-agenda defers to fg-ask on its own: if the breadth-first pass surfaces no fog, it writes no agenda and points at fg-ask — so reach for it only when the way genuinely isn't visible yet. And fg-loop is the mirror image of fg-agenda: unattended with a machine stop condition, versus human-answered with a judgment one. That is why they are two skills and not one.

Use cases — typical flows

Reach for the right sequence by situation. The everyday and unattended rows point back to the sections above rather than repeating them.

First-time setup is the one sequence Quick start skips: on a fresh project, map the code and (optionally) generate domain agents before your first fg-ask — fg-agents cards load only at session start, so restart once after generating them (ADR-0024).

Skill catalog

The four loop stages, then the eighteen utilities outside the loop:

Per-skill detail — input/output/next, triggers, and the rationale ADRs — is in docs/skills.md (Korean). fg-ask is the loop's entry point (it triggers on "start with forge", "new task", "refine the plan"); the utilities are on-demand, each triggered by its own utterances.

Overall flow

When one skill finishes, it states the way to the next as a fixed four-row handoff table — what was just done · next step · how to start · alternative — at each of the 15 points that have a real next step (the other seven are toggles and utilities with nothing to point at, and keep their prose). The next step then sits in the same place every time instead of being buried mid-paragraph: the pain this fixes is findability, not length (ADR 260805-231104). It is a different thing from the eco summary table, which answers what was done; this one answers what comes next, and it renders whether eco is on or off. The statement form is unchanged — the table is text output, never a menu: no "shall I continue?", and chaining into the next stage is still fg-next's job (ADR-0015, amended 2026-06-15 — fg-run's old four-way menu was dropped because it re-triggered on the unchanged active-slot state and looped). This holds for every handoff, including fg-run's single-task end: default retro via fg-learn, skip+seal via fg-done only when divergence is low, re-grill via fg-ask when it is high — stated, then stop. After fg-done seals a task, the loop restarts at fg-ask only as a new task — the same task never runs again. Two utilities tend this fuel from outside the loop: fg-map writes the codebase map fg-ask reads, and fg-cleanup curates the ADR set fg-ask reads.

fg-ask ───▶ fg-run ───▶ fg-learn ───▶ fg-done
① ask/plan      ② execute       ③ retro       ④ done
(grilling·      (Dynamic WF)    (reflect      (seal·
 conversational)                 into docs)    re-run guard)

How it phrases anything is a separate always-on rule. Every skill carries an **Explaining forge** paragraph next to its language rule: gloss a forge-specific term the first time it appears in a message, put the purpose before the mechanism, and lead with the answer. It is not gated on eco — the installers who most need a gloss are the ones least likely to have turned eco on — and it governs vocabulary while eco's terse rules govern form, so terseness never deletes a gloss. A fg-doctor check compares each skill's copy against a single canonical definition, so the rule cannot quietly drift out of one of them (ADR 260824-134246).

Skill authors can consult the optional situational output examples when reviewing a specific skill’s output. They illustrate context restoration, numbered procedures, and grouping without dropping information. Routine skill execution does not require reading them; existing handoffs and output rules still apply.

A detailed flow diagram (loop ↔ document artifacts) is in docs/state-contract.md (Korean).

Install

Claude Code

In a Claude Code session, add the GitHub marketplace, then install the plugin.

/plugin marketplace add gyuha/forge
/plugin install forge@forge

To install from a local clone instead (e.g. while developing), pass the path to the repo root:

/plugin marketplace add /path/to/forge
/plugin install forge@forge

Notes:

• The GitHub install pulls the repo's default branch (main) — to test a change via install, it must be pushed to main first.
• Skills are auto-discovered from skills/<name>/SKILL.md; no extra configuration is needed.
• To update later, run /plugin marketplace update forge, and to remove, /plugin uninstall forge@forge.

Codex

Forge ships .codex-plugin/plugin.json; install the repository as a local Codex plugin from your Codex plugin/marketplace UI, then start a fresh task so its shared skills and reviewed hooks load. Invoke skills as $fg-ask, $fg-run, $fg-next, and so on. Codex and Claude Code consume the same skills/ and .forge/ state; only the host adapters differ. The Codex adapter does not currently install a persistent statusline—use $fg-status instead.

Codex currently supports the core loop, state utilities, serial fallback, parallel bounded subagents, and SessionStart notices. fg-next all/fg-loop unattended continuation and Codex-native fg-agents are limited; use them under supervision. Full details: Codex guide.

Pi

Pi loads the same 22 skills from a local forge checkout: run pi install /absolute/path/to/forge, then start a fresh Pi session and invoke /skill:fg-ask, /skill:fg-run, or /skill:fg-status. It discovers the package’s skills/ directory without a separate manifest or extension. Use a checkout containing the Pi support changes.

Basic support uses text choices and sequential execution. fg-next all and fg-loop run within the current turn and resume when invoked again; Pi hooks, a statusline, and custom subagents are not included. Installation, capability limits, and verification scope: Pi guide.

opencode

opencode needs no forge-specific manifest — skills load by SKILL.md discovery alone. But a forge installed with /plugin install lands in the ~/.claude/plugins/cache/… plugin cache, which opencode does not scan, so you have to link it once into a discovery path such as ~/.config/opencode/skills/ — if your other skills appear in opencode but forge does not, this is why. It is two lines (git clone + ln -s); the procedure and its caveats (linking the version-pinned cache path silently leaves you on an old version) are in the guide below. Invoke skills by name (fg-ask, fg-run, fg-next, …).

Every capability in hosts/opencode/capabilities.json is currently false, which is the contract's observation rule applied literally rather than a claim that opencode cannot do these things: the core loop and state utilities work, while parallel delegation, role dispatch, SessionStart notices, the statusline, and unattended driving fall back (fg-next all/fg-loop are turn-bounded — they run as far as one turn allows and resume on re-trigger). Full details: opencode guide.

After installing, start with fg-ask (/forge:fg-ask on Claude Code, $fg-ask on Codex, fg-ask on opencode, /skill:fg-ask on Pi), or an utterance like "start with forge".

Shared state and directories

State is passed through files so the flow continues even when stages are invoked independently. A single .forge/ directory holds everything — both the volatile loop state and the git-tracked permanent docs (the .gitignore excludes .forge/ by default and whitelists only the permanent docs). The active slot is always exactly one — one plan.md = one run.md = one seal. On a non-default branch the whole forge root moves to .forge/branch/<branch>/ (git-tracked) so parallel branches never collide (ADR-0011).

The full directory layout, the .gitignore pattern, branch isolation, the retro-skip rule (ADR-0002), and the verification-before-seal gate (ADR-0009) are documented in docs/state-contract.md (Korean).

And it is closed at the next question. When you start a new task while a previous one sits unsealed, fg-ask's STEP 0 decides by how much judgment is left: none (verification is sealable and the retro is resolved, or only the retro is owed and the run barely diverged) → it seals without asking, reports one line, and keeps grilling in the same turn; judgment remains (high divergence, verified: pending/failed, a halted goal loop) → it asks, but holds your request and returns to it once the tail is closed — you never have to re-trigger fg-ask. Its reach is the active slot only; tasks parked in executed/ are a deliberate wait, not part of the tail, so they are reported and left alone (ADR 260727-201115).

Forgetting to seal is caught at session entry. forge ships two hooks (hooks/hooks.json, installed with the plugin — no settings edit). The first, at SessionStart, checks for an unsealed tail — a task that ran but was never sealed, a task parked awaiting retro, or a halted goal loop — and, only then, injects a short notice so the agent tells you about it before starting new work. It never runs or seals on its own initiative before you answer — fg-ask's STEP 0 auto-close is the one approved exception — so the decision stays yours. A clean repo, or one with only a backlog waiting, gets nothing at all. The second, at Stop, is what lets an unattended drive cross turn boundaries without /goal — it blocks only while a drive's drive.md marker is live and inside its bounds, so a session that is not driving is untouched (ADR-0028). Because hooks load at session start, a newly installed or edited hook applies from the next session (ADR 260727-201031).

How git and branches are operated with forge — the git-abstinence model, the commit points, and a feature-branch walkthrough with git CLI — is in docs/git-workflow.md (Korean).

The two pillars

1. Grilling (planning) is conversational, outside the execution workflow. Delegated execution — a Dynamic Workflow or Codex subagents — cannot take user input mid-run, so question-by-question grilling uses the active host's interactive input and never runs inside parallel agent execution.
2. Docs are the loop's fuel, not its by-product. Terms sharpened in planning become the standard for execution, and retro learnings become the starting point of the next plan.

forge vs. other harnesses

Legend: ✓ explicitly supported · △ something similar exists but differs in form/rigor · — not found in public docs (not claimed absent)

forge's strengths

• Docs are the loop's fuel, not a byproduct — ADRs are created only when all three gate conditions hold, which structurally prevents doc bloat.
• No seal without verification — pending/failed/skipped(reason)/n-a(reason) are honestly distinguished so an unverified task can never quietly become "done."
• Unattended automation still stops itself at human-defined walls (failed verification, an unresolvable fork, tension/oscillation ping-pong, safety-class actions, a stalled wait on external evidence, a check command blocked by a missing tool or credential).
• Sealing means the loop really ends — a sealed task is structurally blocked from ever re-running.
• Zero runtime infrastructure — no DB or server; install through the host's plugin or skill-loading mechanism.
• Instead of a fixed roster of specialists, forge interviews the project to find which roles actually recur, and generates agent cards only for those.
• Honest trade-off: forge supports Claude Code, Codex, opencode, and Pi, while some host-native extras remain asymmetric (fg-statusline and current fg-agents output are Claude-oriented; Codex unattended continuation is limited, and every opencode capability is still unobserved so it falls back throughout; Pi basic support is sequential and turn-bounded). The shared state and workflow rules stay identical instead of being duplicated.

What forge doesn't do

• Cross-model benchmarking — GStack has it (/codex, gstack-model-benchmark), forge doesn't (deliberate: model choice is Claude Code's own domain, not forge's).
• Browser automation, iOS QA, design generation — GStack has these (/browse, /ios-qa, /design-*), forge doesn't (deliberate: forge stays scoped to the plan→execute→retro→done loop, not the whole SDLC).
• Team-shared, searchable knowledge base across projects — GStack's GBrain (Supabase-backed) does this; forge's .forge/ is scoped to a single repo.
• Always-on, unconditional TDD enforcement — Superpowers deletes code written before tests; forge's TDD is an opt-in toggle a project can choose not to use.
• Automatic per-task git worktree isolation — Superpowers creates one automatically; forge isolates state per branch (ADR-0011) but doesn't automate worktree creation itself.
• Scored quality gate on planning documents — GStack's /spec blocks below a 7/10 Codex score; forge's ADR gate is qualitative (three conditions), not numeric.

Credits

The grilling/documentation pattern of fg-ask (including the verbatim original) and CONTEXT-FORMAT.md/ADR-FORMAT.md are inherited from grill-with-docs in mattpocock/skills.

The code-simplicity discipline used by eco mode (fg-config's eco key) — the laziness-first decision ladder embedded in skills/fg-config/ECO.md and injected into fg-run subagents / fg-ask grilling — is adapted from the Ponytail skill by DietrichGebert.

The terse-communication output rules in the same ECO.md — compressing execution/reporting prose to save context while keeping code/errors verbatim and leaving grilling questions and generated docs in full — are adapted from the caveman skill by JuliusBrussee.

The always-on **Explaining forge** rule carried by every SKILL.md — gloss a forge-specific term on first use, purpose before mechanism, lead with the answer — is adapted in concept from the eli5 skill by dreambigou (MIT). No code was vendored: only the vocabulary-calibration rules were taken, its audience tables were dropped (forge output has one reader), and it is deliberately not part of eco — the installers who most need a gloss are the ones least likely to have eco on. It governs vocabulary while ECO.md's terse rules govern form, so terseness never deletes a gloss (ADR 260824-134246).

The situational output examples adapt numbered procedures, context restoration, and grouped lists from ayghri/i-have-adhd (MIT). These are forge-specific examples, not a vendored skill or a claim of measured output improvement.

The landing page (docs/index.html) was built with the Visual Companion of Superpowers by Jesse Vincent (obra) — its browser-preview design tool that lays out mockup, layout, and color options before the page is coded.

The security-audit methodology behind fg-security is cloudflare/security-audit-skill, vendored under MIT — its entry file plus nine attack-class playbooks, report-schema.json and validate-findings.cjs live in skills/fg-security/, with the licence copy at skills/fg-security/LICENSE. Only the entry file was renamed (SKILL.md → AUDIT.md, so it does not collide with forge's own skill-discovery path); the other eleven files are kept byte-for-byte with upstream so a future diff stays cheap. forge adds only the loop integration — a severity gate, fix-forward plans on approval, and keeping artefacts outside the repo.

The bug-diagnosis discipline behind fg-debug is diagnosing-bugs in mattpocock/skills, vendored under MIT — its entry file and scripts/hitl-loop.template.sh live in skills/fg-debug/, with the licence copy at skills/fg-debug/LICENSE. Only the entry file was renamed (SKILL.md → DIAGNOSE.md, so it does not collide with forge's own skill-discovery path); the files are kept byte-for-byte with upstream so a future diff stays cheap. forge adds only the loop integration — diagnosis only, with routing decided by state before fix size: an active verified: failed task returns to fg-run's fix-and-re-run path even when the fix is trivial; only an independent diagnosis goes to fg-quick when trivial or to a human-approved fix-forward plan when non-trivial. Its Phase 1 red command counts as the plan's persistent eval only when it is itself durable; otherwise the plan adds a persistent regression check or records why that is not mechanically possible. Only secret-scrubbed fixtures and tests may remain in the working tree; raw captures stay outside it, and every exit cleans temporary instrumentation and artefacts.