From forge
Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions. The entry point of the forge loop and its plan-grilling stage — use in contexts like "start a new task", "start with forge", "let's work on this", '새 작업 시작', 'forge로 시작', '이거 작업하자', '계획 다듬자', '이 계획 그릴링해줘'. Once an agreed plan is loaded into .forge/backlog/<slug>.md, fg-run picks it up and runs it. Always conducted as a conversation in this session (outside any workflow).
How this skill is triggered — by the user, by Claude, or both
Slash command
/forge:fg-askThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
<what-to-do>
Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
Ask the questions one at a time, waiting for feedback on each question before continuing.
If a question can be answered by exploring the codebase, explore the codebase instead.
During codebase exploration, also look for existing documentation:
Most repos have a single context:
/
├── .forge/
│ ├── CONTEXT.md
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
If a CONTEXT-MAP.md exists at the root, the repo has multiple contexts. The map points to where each one lives:
/
├── CONTEXT-MAP.md
├── .forge/
│ └── adr/ ← all ADRs live here (single location, every context)
├── src/
│ ├── ordering/
│ │ └── CONTEXT.md ← glossary stays next to its code
│ └── billing/
│ └── CONTEXT.md
Create files lazily — only when you have something to write. If no .forge/CONTEXT.md exists, create one when the first term is resolved. If no .forge/adr/ exists, create it when the first ADR is needed.
When the user uses a term that conflicts with the existing language in CONTEXT.md, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
When a term is resolved, update CONTEXT.md right there. Don't batch these up — capture them as they happen. Use the format in CONTEXT-FORMAT.md.
CONTEXT.md should be totally devoid of implementation details. Do not treat CONTEXT.md as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
Only offer to create an ADR when all three are true:
If any of the three is missing, skip the ADR. Use the format in ADR-FORMAT.md.
The original text ends above. What follows is the minimal glue that keeps the forge loop unbroken; the grilling method itself follows the original text above.
.forge/... path in this section is relative to the resolved forge root — .forge/ on the default branch, .forge/branch/<branch>/ (git-tracked) on any other branch. Resolve it per ${CLAUDE_PLUGIN_ROOT}/skills/fg-run/FORGE-ROOT.md (skill-relative ../fg-run/FORGE-ROOT.md) before reading or writing state — backlog, plan, CONTEXT.md, ADRs, and retros all live under that root. Two global exemptions stay at the top-level .forge/ regardless of branch: .forge/config.json (the tdd read below) and .forge/codebase/ (the map read below) — read both globally, never under the branch root (ADR-0011). Reads of the permanent fuel (CONTEXT.md, adr/, retro/) on a non-default branch overlay the branch root on top of the top-level .forge/ base — read both, branch wins on conflict; writes go to the branch root only (see FORGE-ROOT.md's read overlay)..forge/retro/ exists, read it as a starting point for grilling — pull each retro's "Do differently next time" and "Divergences" into your opening questions (which past traps could recur this time, which assumptions broke). Selection rule (when retros have piled up): first take those in the same area as this task (overlapping slug stem / domain terms), then up to the most recent 3–5. Don't read all of them. Retros are reference fuel for sharpening the plan, not a source of truth — the plan's source of truth comes only from CONTEXT.md and ADRs. Read the active adr/*.md files (per the read overlay above — the top-level base plus the branch root on a non-default branch) as that ADR source of truth; do NOT read adr/retired/ at either level — those are ADRs the fg-cleanup utility retired (superseded/no-longer-applies, ADR-0012), kept on disk for archaeology but deliberately out of the active grilling fuel (retired numbers still count for numbering — see ADR-FORMAT.md). If there are no retros or none are relevant, skip silently..forge/codebase/ exists (produced by the fg-map utility), read the documents relevant to this task before grilling — they are a structured map of the stack, architecture, conventions, and known concerns, so you grill against the map instead of re-exploring the whole codebase from scratch (this is what cuts context rot). Check each document's last_mapped_commit frontmatter against the current HEAD (git rev-parse HEAD): if the map is many commits behind (e.g. dozens), warn in one line — "the codebase map is stale (mapped at {sha}, now {n} commits back); consider re-running fg-map" — then proceed anyway (do not block). If .forge/codebase/ does not exist, skip silently; the map is optional fuel, not a prerequisite.deep-research skill, or Claude's web research). This is optional fuel, not a prerequisite (same standing as .forge/codebase/): if no such capability exists, skip silently and grill with the project docs + codebase as usual — never hard-depend on a specific external skill. Never auto-run it — research is slow and costly, so offer first ("this looks like it needs external research on X — run deep research before we grill?") and run only on agreement. It does not replace grilling: findings are reference fuel, the one-question-at-a-time conversational grilling still happens, and the web is a reference — the source of truth stays CONTEXT.md/ADRs, not the research. Fold conclusions into the plan (Source of truth / decisions); if the research drives a hard-to-reverse technology choice, record it as an ADR under the usual gate. Do not dump raw research into a new doc. (See .forge/adr/0006-fg-ask-optional-deep-research-fuel.md.)tdd from .forge/config.json (treat as off if the file doesn't exist — e.g. fg-tdd not set up). Use it as the default and ask once, early in grilling: "build this task test-first (TDD)? (default: )". The user's answer (or the default if they don't care) is recorded on the plan as <!-- tdd: on|off --> at Output time — fg-run reads it to run test-first when on. This sets execution mode only; it does not change how grilling itself is conducted.run.md whose STATUS.md reads status: executed but is not yet sealed, or any .forge/executed/*/STATUS.md reads status: executed (a parked task awaiting retro), the previous loop's verification/retro/seal is unfinished — easy to forget once the work felt done. Surface it in one line and ask (in the user's language): "⚠ the previous task <slug> is awaiting [verification / retro / sealing] — (a) finish it first, or (b) keep starting the new task?" (several parked → just give the count). On (a), invoke fg-next — it derives whether verification, retro, or seal is owed via fg-status's state machine, so do not reimplement that decision here — and do not start the new grilling now (the user re-triggers fg-ask after finishing). On (b), proceed below — the new plan stacks in the backlog and coexists, exactly as designed. If there is no such unfinished work, say nothing and proceed immediately — the common case, zero added latency. Note: an active slot with only plan.md and no run.md (a promoted-but-unrun plan, awaiting fg-run) does not trigger this — it is not a retro/seal debt and coexists normally; warning on it would just be noise for deliberate backlog stacking..forge/loop.md exists, an fg-loop drive is in flight or halted at a wall. Warn in one line: "⚠ a goal loop is halted at a wall () — (a) resume it via fg-loop, or (b) keep starting the new task? (a new plan is loaded as a non-member of the loop)". On (b) proceed normally — the new plan is safe from the unattended drive because fg-loop promotes only the slugs listed in loop.md's ## Tasks membership section (see ../fg-loop/SKILL.md §2); do not add the new plan to that list..forge/plan.md) and the backlog (.forge/backlog/) for an existing plan, and consult .forge/done/*/STATUS.md for what is already sealed. Resolve two things:
run.md — the "between fg-ask and fg-run" window where a requirement can still be added before execution). Be deterministic, not guess-based: name the pending plan(s) and ask in one line whether this request refines one of them or is a new task (list them if several). Ask only when a pending plan actually exists — say nothing on empty state (no noise on a fresh start). This removes the old ambiguity where re-invoking fg-ask would fold-or-fork at random.
task: number, no part: marker) that coexists — this is an independent task, not a split.forge-slug / task: / tdd markers.<base>-1ofM + <!-- part: N/M -->, per PLAN-FORMAT.md).run.md. That plan has already run; editing it would pollute fg-learn's "Plan vs actual" comparison. A requirement on already-run work is a new task or a post-failure re-grill, not an in-place edit — confirm explicitly before touching it.
If it is plainly a new task, proceed as is — the new plan stacks in the backlog and coexists with existing work..forge/backlog/<slug>.md (slug = kebab-case of the task title, -2 on collision; the directory is created lazily). Embed a <!-- forge-slug: <slug> --> comment on the plan's first line — a persistent identifier that lets retro and sealing pair up by the same slug even after the plan moves to the active slot. Also assign a stable task number and embed <!-- task: N --> next to it: scan the task: markers of every existing plan (in .forge/backlog/, the active slot, .forge/executed/, .forge/done/), take the maximum, add one (or 1 if none exist). This number is the task's identity for fg-status display and fg-run selection — it never changes once assigned (see PLAN-FORMAT.md). Numbering applies to formal loop tasks only, not the fg-quick lane. Also record the TDD choice from the start-of-grilling question as a <!-- tdd: on|off --> marker near the forge-slug line (default = tdd in .forge/config.json, off if absent); fg-run reads it to run test-first when on (see PLAN-FORMAT.md). The format follows the skeleton in PLAN-FORMAT.md (or ${CLAUDE_PLUGIN_ROOT}/skills/fg-run/PLAN-FORMAT.md) — sharpened terms → source-of-truth glossary, hard-to-reverse decisions → ADR links, agreed units of work → slices (+ observable completion criterion), things decided not to do this time → non-goals. Split a big task into several plans when either applies (see PLAN-FORMAT.md's splitting rule): (a) a point needs human confirmation midway — narrow the plan up to there and leave the rest as a separate backlog task; or (b) the agreed work is large and decomposes into chunks that are each independently shippable, verifiable, and sealable — write one part-plan per chunk rather than one giant plan. For a size split, give each part an ordered slug (<base>-1of3, <base>-2of3, …) and a <!-- part: N/M --> marker so fg-run shows them in order and completes them one at a time; each part must still stand as its own full loop (it is a soft order, not a hard dependency). If during grilling the task turns out trivial enough that a retro will likely have nothing to fold into the docs (a tiny, low-risk change), you may add a <!-- retro-hint: optional --> marker comment near the forge-slug line — a non-binding hint that lets fg-run lead with the "skip retro" option at its handoff. Omit it by default; the actual skip is fg-run's call, gated on the run's divergence. Likewise, if a task's importance relative to other backlog work is clear, you may add a <!-- priority: high|medium|low --> marker near the forge-slug line — fg-run sorts its selection menu (and the "Run all" order) by it (high → medium → low, no marker = medium). It only changes ordering, never auto-selects; omit it when unsure..forge/backlog/<slug>.md), plus any .forge/CONTEXT.md entry updated and any .forge/adr/NNNN-* added this session (only those actually touched). Say it conversationally — e.g. "I wrote the plan to .forge/backlog/<slug>.md (and updated CONTEXT.md / added ADR-NNNN); open them to review before we run." Then state the next step and stop — do not ask "shall I run it now?" and do not auto-invoke fg-run; chaining into the next stage is fg-next's job (ADR-0015). Tell them: the plan is in the backlog, and fg-run will pick it up (a selection menu if several wait, with "Run all" at the end), promote it, and run it. Give the trigger — "forge run" / "계획 실행" / /forge:fg-run, or fg-next to proceed in one step. Do not ask whether the task is big enough for a Dynamic Workflow vs. handling it directly — that is fg-run's call via its own cost estimate, not a grilling question..gitignore whitelist, and a non-default branch root is tracked whole (see FORGE-ROOT.md / ADR-0011).npx claudepluginhub gyuha/forge --plugin forgeGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.