forge-bootstrap
Scaffold a brand-new empty repository to a pipeline-ready, green baseline (structure, toolchain, passing lint+test, forge.config.json), then optionally chain into the pipeline. Use when the user runs /feature-forge:forge-bootstrap or asks to bootstrap/scaffold a new empty project for forge. Do NOT trigger on a non-empty repo (that is forge-init), or for general project setup outside the forge pipeline.
- License 许可
- MIT
- 最近更新
- 2026-10-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- forge-bootstrap
- metadata
- { "argument-hint": "[--mode-b] [--here|<target-dir>]" }
- description
- Scaffold a brand-new empty repository to a pipeline-ready, green baseline (structure, toolchain, passing lint+test, forge.config.json), then optionally chain into the pipeline. Use when the user runs /feature-forge:forge-bootstrap or asks to bootstrap/scaffold a new empty project for forge. Do NOT trigger on a non-empty repo (that is forge-init), or for general project setup outside the forge pipeline.
- disable-model-invocation
- true
02 资源文件 28
- 参考文档references/templates/ci/github-actions.yml172 B
- 参考文档references/templates/generic/gitignore28 B
- 脚本references/templates/generic/run.sh87 B
- 脚本references/templates/generic/test.sh315 B
- 参考文档references/templates/go/gitignore47 B
- 参考文档references/templates/go/go.mod24 B
- 脚本references/templates/go/main_test.go193 B
- 脚本references/templates/go/main.go197 B
- 参考文档references/templates/hygiene/AGENTS.md2.1 KB
- 参考文档references/templates/hygiene/CLAUDE.md2.3 KB
- 参考文档references/templates/hygiene/README.md178 B
- 许可证references/templates/licenses/Apache-2.0/LICENSE10.7 KB
- 许可证references/templates/licenses/MIT/LICENSE1.0 KB
- 参考文档references/templates/python/gitignore105 B
- 参考文档references/templates/python/pyproject.toml452 B
- 脚本references/templates/python/src/{{PKG}}/__init__.py85 B
- 脚本references/templates/python/src/{{PKG}}/main.py240 B
- 脚本references/templates/python/tests/test_smoke.py201 B
- 参考文档references/templates/rust/Cargo.toml197 B
- 参考文档references/templates/rust/gitignore42 B
- 脚本references/templates/rust/src/lib.rs176 B
- 脚本references/templates/rust/src/main.rs82 B
- 脚本references/templates/rust/tests/smoke.rs113 B
- 参考文档references/templates/typescript/gitignore56 B
- 参考文档references/templates/typescript/package.json283 B
- 脚本references/templates/typescript/src/index.ts139 B
- 脚本references/templates/typescript/test/smoke.test.ts177 B
- 参考文档references/templates/typescript/tsconfig.json317 B
03 SKILL.md 正文
Bootstrap a Greenfield Repo
Take a brand-new, empty repository to a pipeline-ready, green baseline — a
scaffolded stack, a valid forge.config.json, and a passing lint+test — then optionally
chain into the pipeline (Mode B). You own the conversation and decisions only; every
mechanic (the greenfield gate, git init, scaffolding, the config write, the toolchain
probe, the commit) is delegated to the helper scripts/forge-bootstrap.py. Never inline
file generation, template contents, the config field list, or the greenfield allow-list —
they live in the helper and templates, referenced here, never duplicated.
<target-dir> below is the project being bootstrapped (default ., or the argument) — it is
distinct from $R, the plugin root. Drive control flow off the helper's exit codes and
JSON: 0 = ok, 1 = actionable findings, 2 = usage/IO or verify
toolchain-missing.
Host adaptation (conversational fallback)
If the {{ASK_TOOL}} is available, ask the interview questions through it. If it is
not available (a non-Claude host such as Codex), emit the same questions as a single
numbered text list — each line one question with its options in brackets and the default
marked — then stop and wait for a single text reply. Parse the reply positionally
(answer N → question N); re-prompt only the unparseable items. The question content (text,
options, defaults) and the conditional gating (Q4 skipped for go/rust/generic; Q6a only for
monorepo; Q8 only after a verified-green baseline) are identical across both paths — only
the rendering changes. Never assume answers; always wait for the reply. At rung 3
(genuinely non-interactive — Interaction Capability Ladder, references/shared-conventions.md),
this interview has no sane unattended default: no-default: abort — the bootstrap interview requires a human answer.
Emit any context as plain text, then route all questions through {{ASK_TOOL}} (or the fallback) — never as inline prose questions, which stall the session.
Flow (Mode A — default)
1. Portable-root prelude → locate $R
2. check → gate + recovery detection
├─ eligible:false (exit 1) → Greenfield refusal — STOP
└─ resumeMarker != null → Resume / restart / cancel
3. Interview → assemble the Answers payload
4. scaffold --answers <json> → git init if absent; compose templates; write config;
track artifacts into the sentinel
5. verify → toolchain probe + lint/test per member
├─ toolchainPresent:false (2) → Missing toolchain: scaffold-anyway-unverified vs abort
├─ green:false (exit 1) → Not-green: surface failures, offer fix/abort
└─ green:true (exit 0) → proceed
6. commit [--stage-only per Q9] → stage exact tracked list; single baseline commit;
remove the sentinel before staging
7. Completion summary / Mode B hand-off
Step 1 — locate the helper
Every bash invocation begins with the byte-identical portable-root prelude, then calls the
helper. Pass --specs-dir ./specs (the default) so the gate allow-lists the specs directory.
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-bootstrap.py" check "<target-dir>" --json --specs-dir ./specs
Never hardcode a plugin path or a ~/.claude/... path — always go through $R.
Step 2 — gate (check)
Read CheckResult{eligible, disqualifying[], resumeMarker}.
-
eligible:false(exit 1) → Greenfield refusal. Name every path indisqualifying[]verbatim, then direct the user to the right tool — runforge-init, thenforge-1-prd. Touch no files and STOP (the gate is read-only).This repo is not empty — forge-bootstrap only scaffolds a brand-new project. Disqualifying files found: - package.json - src/index.ts To set forge up on an existing project, run: /feature-forge:forge-init Then start the pipeline with: /feature-forge:forge-1-prd <feature> -
resumeMarker != null→ Partial-state detected. A.forge-bootstrap.jsonsentinel from this tool's own prior run exists — do not treat it as a refusal. Surface the prior run'sstartedAtandartifactsWritten[], then ask resume / restart / cancel:- Resume — reuse the sentinel's mirrored
answers(no re-interview), re-runscaffold(idempotent — the helper skips already-recorded files), continue from step 5. - Restart — discard the partial: delete the recorded
artifactsWritten[]tree + the.forge-bootstrap.jsonsentinel (a skill-orchestration step — the helper has no clean subcommand), then run the interview andscaffoldfresh. - Cancel — stop without changes.
You perform no cleanup yourself; you only render the choice and dispatch the subcommand.
- Resume — reuse the sentinel's mirrored
Step 3 — interview
Ask exactly these, in order. Resolved answers become the Answers payload handed to
scaffold --answers.
| # | Question | Default / seed rule | Options |
|---|---|---|---|
| Q1 | Project name? | default = target directory basename (confirm) | free-text, pre-filled |
| Q2 | One-line purpose? | no default; seeds README + config | free-text |
| Q3 | Language / stack? | required | typescript / python / go / rust / generic |
| Q4 | Package manager? | only when the stack has a choice — TS: npm/pnpm/yarn, Python: uv/poetry/pip; skipped for go/rust/generic |
the stack's options |
| Q5 | License? | detect & pre-select from a pre-existing LICENSE (see gating); else default MIT. The helper keeps an existing LICENSE (REQ-SCAF-09) |
MIT / Apache-2.0 / none |
| Q6 | Single package or monorepo? | default single |
single / monorepo |
| Q6a | (monorepo only) member count, then per-member name + stack | no default; one member each (mixed-language allowed) | loop |
| Q7 | Chain into the pipeline now (Mode B)? | default no |
no, scaffold only / yes, chain in |
| Q8 | (Mode B only) First build: feature or epic? | asked only after a verified-green baseline | feature / epic |
| Q9 | Commit the baseline, or leave it staged? | default commit |
commit / stage only |
Gating: Q4 is asked only when the chosen stack has a package-manager choice; Q6a only when
Q6 = monorepo (each member gets a path like packages/<name>; a single package is one
member with path = "."); Q7 may be asked up-front, but Q8 / Mode B launch are gated on a
verified-green, committed baseline (see below). You may also offer an optional
"generate a CI workflow (lint+test)?" question, setting Answers.ci.
License detect-and-seed (Q5, REQ-SCAF-09): when a LICENSE already exists in the target
(an allowed-meta file the gate let through), read its first lines and pre-select the
matching Q5 default — "MIT License" → MIT, "Apache License" → Apache-2.0, otherwise
keep the default and note the unrecognized license. The helper never overwrites the existing
LICENSE; this only seeds the interview default. Also set Answers.author from
git config user.name (fallback: the project name) and Answers.host to claude when
running on a Claude host (so the helper emits CLAUDE.md alongside AGENTS.md), else leave
it null.
Assemble the payload. Build one Answers JSON object — projectName, purpose,
layout, license, members[], modeB, modeBTarget, ci, commitStyle, author,
host — and pass it verbatim to scaffold --answers '<json>'. Invent no fields beyond that
schema. Two fields come from your runtime, not the interview: author from git config user.name (else the project name; it is the LICENSE copyright holder), and host —
"claude" when you are running as Claude, else "codex"/"other". Use your own runtime
identity, never a capability proxy: do not infer "claude" from {{ASK_TOOL}}
availability alone — Pi's compatibility extension registers it too, so an available
question tool does not prove you are Claude specifically (host never implies, and is
never implied by, a capability; Interaction Capability Ladder,
references/shared-conventions.md). host drives the
host-conditional agent file: the helper always emits AGENTS.md and adds CLAUDE.md only
when host == "claude".
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-bootstrap.py" scaffold "<target-dir>" --json --answers '<Answers JSON>'
Step 5 — verify
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-bootstrap.py" verify "<target-dir>" --json --answers '<Answers JSON>'
Read VerifyResult{green, toolchainPresent, lint[], test[]}.
toolchainPresent:false(exit 2) → Missing toolchain. Warn, naming which stack's toolchain is missing. Ask scaffold-anyway (unverified) vs abort. If scaffold-anyway, proceed to commit and mark the baseline unverified in the summary — never claim green you could not verify. If abort, stop; the sentinel stays in-progress for a later resume. An unverified baseline disqualifies Mode B (no override).green:falsewithtoolchainPresent:true(exit 1) → Not-green. Surface the failingCommandOutcomeentries (command + member) verbatim; offer abort or retry-after-investigation. Do not silently proceed to a "green" summary.green:true(exit 0) → proceed to commit.
Step 6 — commit
Invoke commit (or commit --stage-only, per Q9). Helper-owned: it stages the exact
tracked list (never git add -A/--force/--no-verify), makes a single baseline commit,
and removes the sentinel before staging so it never enters history. Read
CommitResult{committed, commitHash, staged[]}. On commit failure, surface the error and
leave the sentinel in-progress (resumable) — do not declare success.
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-bootstrap.py" commit "<target-dir>" --json --answers '<Answers JSON>' [--stage-only]
Completion summary
Render the human-facing summary from the helper's JSON (VerifyResult + CommitResult). State:
created artifacts (from CommitResult.staged[], including any kept pre-existing meta file);
resolved stack(s) (single, or each monorepo member's name + stack); the verification
verdict — green or unverified (never "green" for an unverified baseline); the commit
state (with commitHash, or staged-only); and the exact next command. In Mode B, launch
the next stage instead of printing the command.
Bootstrap complete — pipeline-ready baseline.
Stack: python (uv)
Created: pyproject.toml, src/acme_svc/..., tests/test_smoke.py, .gitignore,
README.md, LICENSE, AGENTS.md, CLAUDE.md, forge.config.json
Kept: (none — README/LICENSE generated fresh)
Verification: green (mypy ✓ pytest ✓)
Commit: baseline committed (a1b2c3d)
Next step: /feature-forge:forge-1-prd <feature>
Unverified variant:
Verification: UNVERIFIED — toolchain not found on this machine; lint+test were not run.
Install the toolchain and re-run verify before relying on the baseline.
Mode B hand-off (opt-in)
Mode B is opt-in (Q7; default Mode A) and agent-driven — it hands skill-to-skill to the next pipeline stage, not through the helper.
Gate: launch the next stage only after both a verified-green baseline
(VerifyResult.green == true) and a successful commit (CommitResult.committed == true).
If the baseline is unverified or not-green, you MUST NOT launch the next stage and MUST NOT
even ask Q8 — fall back to the Mode A summary with the next command printed. There is no
"launch anyway on red" path.
When the gate passes:
- Ask Q8 — feature vs epic — if not already resolved.
- Feature: invoke
forge-1-prd <feature>skill-to-skill, seeding<feature>from a confirmed, kebab-cased name. - Epic: invoke
forge-0-epic <epic>skill-to-skill. Seed the epic name and initial decomposition from the project name + purpose (Q1/Q2), propose it, let the user edit/approve, then launch. - Launch that stage instead of printing its command.
Mode B auto-launches only the immediate next stage; every subsequent pipeline stage stays a normal, user-driven step. The hand-off is always skill-to-skill, never via the helper.
The four terminal outcomes
Every run ends in exactly one explicit, actionable outcome — make it explicit in your output; no run ends silently:
- Success —
commitexit 0 + green (or unverified-but-proceeded) → completion summary, or Mode B launch. - Greenfield refusal —
checkeligible:false→ namedisqualifying[], point toforge-init+forge-1-prd, touch nothing. - Missing toolchain —
verifytoolchainPresent:false(exit 2) → scaffold-anyway-unverified vs abort; mark unverified. - Partial-state detected —
checkresumeMarker != null→ resume / restart / cancel.
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.