AGENT SKILL

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

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 in disqualifying[] verbatim, then direct the user to the right tool — run forge-init, then forge-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.json sentinel from this tool's own prior run exists — do not treat it as a refusal. Surface the prior run's startedAt and artifactsWritten[], then ask resume / restart / cancel:

    • Resume — reuse the sentinel's mirrored answers (no re-interview), re-run scaffold (idempotent — the helper skips already-recorded files), continue from step 5.
    • Restart — discard the partial: delete the recorded artifactsWritten[] tree + the .forge-bootstrap.json sentinel (a skill-orchestration step — the helper has no clean subcommand), then run the interview and scaffold fresh.
    • Cancel — stop without changes.

    You perform no cleanup yourself; you only render the choice and dispatch the subcommand.

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:false with toolchainPresent:true (exit 1) → Not-green. Surface the failing CommandOutcome entries (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:

  1. Ask Q8 — feature vs epic — if not already resolved.
  2. Feature: invoke forge-1-prd <feature> skill-to-skill, seeding <feature> from a confirmed, kebab-cased name.
  3. 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.
  4. 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 — commit exit 0 + green (or unverified-but-proceeded) → completion summary, or Mode B launch.
  • Greenfield refusal — check eligible:false → name disqualifying[], point to forge-init + forge-1-prd, touch nothing.
  • Missing toolchain — verify toolchainPresent:false (exit 2) → scaffold-anyway-unverified vs abort; mark unverified.
  • Partial-state detected — check resumeMarker != null → resume / restart / cancel.

04 同仓库更多 Skills