AGENT SKILL

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

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: ./specs
  • docsDir: ./docs/architecture
  • backlogDir: null (backlog lives alongside specs)
  • gitCommitAfterStage: true
  • commitPrefix: forge
  • stack: null (detected during forge-2-tech)
  • typeCheckCommand: null (set during forge-2-tech)
  • testCommand: null (set during forge-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 check CHECK-I21 — distinct from testCommand)
  • autoInvokeNextStage: true (the navigator auto-starts the next stage after you confirm; set false to only print the command)
  • contextWindowTokens: null (the navigator infers the context window; set to your model's window, e.g. 1000000 for 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 (set true to run forge-verify automatically 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 for autoVerify)
  • autoFix: false (set true to chain forge-fix after 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 autoVerify in forge.config.json.)

Options: Enable (recommended) / Leave off.

  • On Enable: patch "autoVerify": false → "autoVerify": true in the generated forge.config.json in 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 exec run looks exactly like an interactive one — so read it from the Interaction Capability Ladder's interaction-mode record 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 use no-default: abort — <question> requires a human answer for 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 wait loop — one bounded wait per shell call, print each card, decide from the status JSON — exactly as references/runner-contract.md (Steps 3b/3d) says for this host. The optional rauf Stop hook (rauf hook codex-stop; wire it with npx @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