forge-init
Initialize feature-forge configuration in the current project. Use when user runs forge-init or asks to set up forge for the first time. Creates forge.config.json with defaults. Do NOT trigger for general project initialization or setup tasks outside the forge pipeline.
- License 许可
- MIT
- 最近更新
- 2026-10-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- forge-init
- description
- Initialize feature-forge configuration in the current project. Use when user runs forge-init or asks to set up forge for the first time. Creates forge.config.json with defaults. Do NOT trigger for general project initialization or setup tasks outside the forge pipeline.
02 资源文件 2
- 参考文档references/preflight-and-self-heal.md11.8 KB
- 参考文档references/shared-conventions.md72.3 KB
03 SKILL.md 正文
Initialize Feature Forge
Run the initialization script to create forge.config.json with default settings:
R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
bash "$R/scripts/forge-init.sh"
After initialization, the config file will contain defaults for:
specsDir:./specsdocsDir:./docs/architecturebacklogDir:null(backlog lives alongside specs)gitCommitAfterStage:truecommitPrefix:forgestack:null(detected duringforge-2-tech)typeCheckCommand:null(set duringforge-2-tech)testCommand:null(set duringforge-2-tech)smokeCommand:null(optional end-to-end smoke that boots the wired app and drives one request; set it to enable impl-verify's runnability checkCHECK-I21— distinct fromtestCommand)autoInvokeNextStage:true(the navigator auto-starts the next stage after you confirm; setfalseto only print the command)contextWindowTokens:null(the navigator infers the context window; set to your model's window, e.g.1000000for a 1M-context model, for accurate context-usage advice)contextWarnThreshold:0.7(fraction of the window past which the navigator suggests a clean session)autoVerify:false(settrueto runforge-verifyautomatically after each authoring stage completes — in-stage, in the same session, before the exit block; it costs an extra clean-room verify per stage, so it trades a little time/tokens for catching errors early)autoVerifyStages:{}(per-stage overrides forautoVerify)autoFix:false(settrueto chainforge-fixafter an auto-verify finds issues)
If forge.config.json already exists, the script will not overwrite it.
Offer auto-verify
The template writes autoVerify: false. After the config is created (and only when the script
actually created it — skip this if it reported the file already exists), offer to turn
auto-verify on, then write the choice back into forge.config.json.
If the host's question mechanism is available, ask exactly one question:
Enable auto-verify? Verification runs in a clean-room subagent in-stage after each authoring stage completes — in the same session, before the exit block, so any fix decision keeps its context. It never needs a session clear and only returns a compact digest. Recommended: on. (Change later by editing
autoVerifyinforge.config.json.)
Options: Enable (recommended) / Leave off.
- On Enable: patch
"autoVerify": false→"autoVerify": truein the generatedforge.config.jsonin place, preserving formatting and every other key. - On Leave off: leave the config as written (
autoVerify: false).
This is the run's first question, so determine your rung before asking it, per the
Interaction Capability Ladder (references/shared-conventions.md) — read the rung from
doctor's interaction-mode record as that section directs; never judge it from your own tool
surface, which cannot see whether anyone is there to answer:
R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
python3 "$R/scripts/forge-session.py" doctor --json --check interaction-mode
At rung 1 or 2, ask (structured tool, or the same choice in plain prose — then wait for the
reply). At rung 3 this question's declared default is the no-write / no-proceed option — skip the
prompt, leave autoVerify: false, state the rung-3 default taken, and print the one-line note
Set "autoVerify": true in forge.config.json to verify automatically after each stage. — then
continue with the steps below; declining this edit never ends the skill. The same rung governs
every remaining step: never emit a question a rung-3 run cannot answer.
Preflight the install
Once the config exists, check the tooling this project's pipeline will lean on:
R="$(bash -c '[ -z "${FEATURE_FORGE_ROOT:-}" ] || [ -x "$FEATURE_FORGE_ROOT/scripts/forge-root.sh" ] || { echo "feature-forge: FEATURE_FORGE_ROOT=$FEATURE_FORGE_ROOT has no scripts/forge-root.sh" >&2; exit 2; }; for d in "${FEATURE_FORGE_ROOT:-}" "${CLAUDE_PLUGIN_ROOT:-}" "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge ./.agents/skills/feature-forge; do [ -x "$d/scripts/forge-root.sh" ] && exec "$d/scripts/forge-root.sh"; done')"
[ -n "$R" ] || { echo "feature-forge: cannot locate plugin root" >&2; exit 1; }
python3 "$R/scripts/forge-session.py" doctor --json \
--check plugin-root --check root-version-skew --check gh-available
Follow references/preflight-and-self-heal.md with that result: all ok/na → say nothing and
move on. Otherwise cluster and report. No check here is a stop for forge-init — report and
continue; a warn here never aborts initialization (the procedure returns statuses; the caller
owns its own gate). gh-available matters because the tooling-feedback step below tells agents
to file issues with gh issue create; when gh is missing or unauthenticated, say so once — its
remedies are global-install/network, so they are advise-only and nothing is executed. It
is one informational line, never a prompt: gh is optional (every stage degrades to manual
steps without it), and this check cannot return na, so a machine without gh must not be
interrogated about it on every init.
root-version-skew is reported the same way: a second install shadowing this one is worth
knowing about before the first stage runs.
plugin-root is reported the same way, advisory here despite its blocking severity. The
prelude above already exits 1 when the resolver fails, so below it the check warns only when the
resolved root is un-built canon (no .feature-forge-bundle.json — a repo checkout loaded
directly): its skills cannot read their shared references and will break mid-stage. Say so once
with the check's remedy.description (advise-only, network) and continue.
Root hygiene — tooling feedback
Offer the project-root Tooling feedback section, per references/shared-conventions.md
§ Root Hygiene (Tooling Feedback) — that block owns the protocol text, the copy commands, the
three-case analysis, and the never-overwrite rule; do not restate them here. In short: decide
which variants are missing first, ask once as a local-write only for those, and stay silent
about a file that already carries the section. AGENTS.md always; CLAUDE.md only on Claude,
read from the bundle's own agent field — never from tool availability. At rung 3 this step
writes nothing and says so (that block's declared default). This is what makes the specs/
hygiene files' "see the project-root AGENTS.md" pointer resolve.
After initialization, start the pipeline with forge-1-prd <feature-name>.
Host execution notes (Codex)
This skill was authored Claude-first; the body above refers to "the host's question mechanism", "the host's subagent mechanism", and "the host's background-execution mechanism". On Codex:
- User input: Codex has no structured question tool. Which rung you are on is not observable from inside the session — a
codex execrun looks exactly like an interactive one — so read it from the Interaction Capability Ladder'sinteraction-moderecord instead of judging it. Interactive session — ask the question directly and wait for the reply; never assume an answer. Non-interactive — don't wait: take the Interaction Capability Ladder's declared conservative default, state it in your output, and useno-default: abort — <question> requires a human answerfor an interview question with no sane default (references/shared-conventions.md). - Subagents: spawn a Codex subagent using the named custom agent under
.codex/agents/<name>.toml. Codex spawns a subagent only when explicitly asked; if the custom agent is unavailable, run that step inline yourself. - Background / monitoring (forge-5-loop): Codex cannot wake you when a background process prints or exits, so never end your turn while the loop runs. Launch it detached and supervise it from inside the turn with the
rauf loop waitloop — one bounded wait per shell call, print each card, decide from the status JSON — exactly asreferences/runner-contract.md(Steps 3b/3d) says for this host. The optional rauf Stop hook (rauf hook codex-stop; wire it withnpx @garygentry/feature-forge install -a codex --codex-stop-hook) holds the session open if it tries to end its turn while the loop still runs. Other long-lived commands: run them in your shell session and report progress as it arrives.
04 同仓库更多 Skills
alpha
A valid skill description.
alpha
暂无简介
alpha
This is a folded scalar description.
alpha
A valid skill description.
alpha
foo: bar
alpha
A valid description.