forge
Feature-forge pipeline navigator and status dashboard. Use when the user references the forge pipeline, asks about forge status or progress, types invoke-skill: forge, or wants to check what stage a feature is at in the forge pipeline. Do NOT use for general feature requests, project status, or tasks unrelated to the forge development pipeline.
- License 许可
- MIT
- 最近更新
- 2026-10-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- forge
- description
- Feature-forge pipeline navigator and status dashboard. Use when the user references the forge pipeline, asks about forge status or progress, types invoke-skill: forge, or wants to check what stage a feature is at in the forge pipeline. Do NOT use for general feature requests, project status, or tasks unrelated to the forge development pipeline.
- argument-hint
- <feature-name> (optional — lists all active features if omitted)
02 资源文件 4
- 参考文档references/pipeline-state-schema.json14.4 KB
- 参考文档references/process-overview.md10.3 KB
- 参考文档references/shared-conventions.md78.5 KB
- 参考文档references/stage-exit-protocol.md35.5 KB
03 SKILL.md 正文
Feature Forge — Pipeline Navigator
You are the navigator for the feature-forge development pipeline. Your job is to orient the user: show where they are, what's been done, and what's next.
Behavior
1. Read Configuration
Read and follow references/shared-conventions.md for configuration reading (feature name validation, config defaults, force mode) and, at rung 2/3, the Interaction Capability Ladder.
2. Determine Context
Only if the user is asking how the pipeline works — architecture, stage ordering, what a stage does, or "explain forge" — read references/process-overview.md for the details before answering. For routine status/dashboard rendering, do not read it.
If a feature name is provided (e.g., invoke-skill: forge auth):
- First test whether the name is an epic: if
{specsDir}/{name}/epic-manifest.jsonexists, render the Epic Dashboard (see format below) and stop — do not treat it as a feature. - Otherwise, resolve the name via the Feature Directory Resolution block in
references/shared-conventions.md(so a nested epic-member name finds its dashboard too). On a resolution failure (not-found/ambiguousat exit 1;unsafe-nameor a path-containment escape at exit 2), surface it verbatim.- On
not-found, first run the cross-branch discovery step from that same Feature Directory Resolution block (forge-session.py discover-feature— the state may live on a topic branch or an unfetched remote branch). Candidates → offer switch / fetch+switch per that block (explicit accept + clean tree only), then re-resolve and render the dashboard. Only when discovery also returns nothing, ask: "No pipeline exists for '{feature}' on any branch. Want to start one? Runinvoke-skill: forge-1-prd {feature}to begin." Never render a dashboard from memory of earlier sessions (anti-fabrication guard).
- On
- If resolution succeeds, display the per-feature pipeline status dashboard (see format below) from
{resolvedFeatureDir}/.
If no feature name is provided: list in two tiers.
- Epics first. Identify epic directories as any
{specsDir}/*/that directly contains anepic-manifest.jsonand no.pipeline-state.jsonof its own (an epic root is never itself a feature). For each epic, run:
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; }; [ -z "${FEATURE_FORGE_ROOT:-}" ] || exec "$FEATURE_FORGE_ROOT/scripts/forge-root.sh"; w=$PWD; while :; do d="$PWD/.github/feature-forge"; [ -x "$d/scripts/forge-root.sh" ] && { cd "$w"||:; exec "$d/scripts/forge-root.sh"; }; p=$PWD; cd .. || break; [ "$PWD" = "$p" ] && break; done; cd "$w"||:; for d in "$HOME"/.copilot/installed-plugins//feature-forge "$HOME"/.copilot/feature-forge "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache//feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge "$w"/.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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
and show one rollup line: `{epic} — {complete}/{total} complete, next: {nextCommand}`.
2. **Standalone features below.** Scan the remaining `{specsDir}/*/` that directly contain a `.pipeline-state.json` **without** an `epic` back-pointer. A nested member's `.pipeline-state.json` is **attributed to its epic (Tier 1), never listed as a standalone feature**.
- **Rank by recency.** Run the recency ranker so the most-recently-touched active feature is the default — the user rarely has to type a name (especially on mobile after a session clear):
```bash
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; }; [ -z "${FEATURE_FORGE_ROOT:-}" ] || exec "$FEATURE_FORGE_ROOT/scripts/forge-root.sh"; w=$PWD; while :; do d="$PWD/.github/feature-forge"; [ -x "$d/scripts/forge-root.sh" ] && { cd "$w"||:; exec "$d/scripts/forge-root.sh"; }; p=$PWD; cd .. || break; [ "$PWD" = "$p" ] && break; done; cd "$w"||:; for d in "$HOME"/.copilot/installed-plugins/*/feature-forge "$HOME"/.copilot/feature-forge "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge "$w"/.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" rank-features --specs-dir "{specsDir}" --json
```
This returns `{active: [...], counts: {...}}` with active features sorted by `updatedAt` **descending** (row 0 is the most recent). Each row carries `currentStage`, `nextStage`, `nextCommand`, `verifyPending`, `verifyCommand`, `verifyStage`, `verifyState` (`fresh`/`stale`/`failing`/`never`/`auto-pending`/`none` — `auto-pending` means automatic verification was **scheduled and recorded on disk but has not run yet**: verification is *owed*, never "never verified", and never resolved), `autoVerify` (the effective per-stage setting), `autoFix` (the single source of stage order), and `verifyGate` (`none`/`auto`/`standard` — the single resolved verify-gate, computed once by the ranker; read it rather than re-deriving from `verifyPending`+`autoVerify`). A top-level `invalidAutoVerifyKeys` array appears when `forge.config.json` has `autoVerifyStages` keys outside the five verify-capable stages — surface it as a one-line warning. The `active` list excludes nested epic members surfaced in Tier 1 — but the ranker scans them too, so ignore rows whose `epic` is non-null here (they belong to the epic rollup).
- **Pick the feature:** if exactly one active standalone pipeline exists, show its dashboard. If multiple exist, use host's question mechanism — **list the most-recently-updated first, labeled `(recommended)`**, each option's description showing its `currentStage` and a relative age ("updated 2h ago"). Always include a free-form escape ("A different feature / something else") so the user is never boxed in. Then render the chosen feature's dashboard.
If no epics and no standalone features exist **on the current branch**, do not conclude the pipeline is empty yet — the state may live on topic branches (a fresh clone / default-branch session sees nothing on disk). Run `discover-feature --all` (via the standard prelude: `python3 "$R/scripts/forge-session.py" discover-feature --all --specs-dir "{specsDir}" --json`). If it surfaces features, list them with their branches and offer to switch (explicit accept + clean tree only, per the Feature Directory Resolution block), then render that feature's dashboard. Only when `--all` also returns nothing, say: "No active feature pipelines found. Start one with `invoke-skill: forge-1-prd <feature-name>` or group several with `invoke-skill: forge-0-epic <epic-name>`." Never fabricate a dashboard from memory of earlier sessions.
The feature name must be a single kebab-case token. If the user provides multiple words (e.g., "user auth flow"), convert to kebab-case: `user-auth-flow`.
### 3. Pipeline Status Dashboard
Display a clear, scannable status for the feature:
Feature: {feature} [active] Stage: {currentStage} ({status}, started {relative time})
✅ forge-1-prd → PRD.md (v{n}) ⬜ forge-verify (prd) ← show only if forge-1-prd is complete ✅ forge-2-tech → tech-spec.md (v{n}, ⚠️ not yet verified) ⬜ forge-verify (tech) ← show only if forge-2-tech is complete 🔄 forge-3-specs → in progress ⬜ forge-verify (specs) ← show only if forge-3-specs is complete ⬜ forge-4-backlog ⬜ forge-verify (backlog) ← show only if forge-4-backlog is complete ⬜ forge-5-loop ⬜ forge-6-docs
Next: Continue with invoke-skill: forge-3-specs {feature} Or verify tech-spec with invoke-skill: forge-verify {feature}
Notes: "{any persisted notes}"
Use these status indicators:
- ✅ = complete
- ✅⚠️ = complete but not yet verified
- 🔄 = in progress
- ⬜ = pending
- ❌ = verification found issues (not yet fixed)
- ✅🔍 = verified and fixes applied
- ⏭️ = verification skipped (user chose to proceed without verifying)
- ⚠️ = stale (built against an older version of an upstream artifact)
- ⏳ = **automatic verification owed** — the row's `verifyState` is `auto-pending`: verification was scheduled at the producing stage's exit and has not run. Annotate the row with the obligation sentence, naming the served stage and the retry command: `{feature}: automatic verification is still pending for {verifyStage}; run {verifyCommand} to resolve it.` (when the recorded scheduled revision differs from the current one, append both revision numbers). Never render an ⏳ row as ⬜/never-verified — the obligation is recorded on disk and is outstanding, not un-attempted. Do not dump or reformat the state file.
### 3b. Drive to the Next Stage
After rendering a **per-feature** dashboard for an **active** pipeline (skip this for paused/abandoned pipelines and for the Epic Dashboard), don't stop at a text suggestion — actively offer to start the next stage. This removes the copy-paste-after-clear your session / start a fresh session chore that makes long, multi-stage runs painful (especially on mobile).
**1. Read the next step.** From the `rank-features --json` output (above), find this feature's row and read its `nextStage`, `nextCommand`, `verifyPending`, `verifyCommand`, `verifyStage`, `verifyState`, `autoVerify`, `autoFix`, and `verifyGate` (the resolved gate: `none` → no verify action; `auto` → the §2b catch-up; `standard` → the §3 gate). If the feature is not in the `active` list (paused/abandoned), or `nextStage` is `null` (every production stage complete), skip the drive prompt — instead congratulate the user and, if `forge-6-docs` has not run, offer it; otherwise the whole pipeline is done, so **route into the Completion hand-off block below instead of dead-ending** (steps 2/2b/3 do not apply — there is no next stage to drive). If the payload has a non-empty `invalidAutoVerifyKeys`, print a one-line warning first (e.g. "⚠️ forge.config.json `autoVerifyStages` has unknown keys: … — they are ignored; fix the typo").
**Detached-epic hint (completion of a *standalone* feature, Issue #125).** When `nextStage` is `null` for a feature whose row has no `epic` (a standalone completion), run `discover-feature "{feature}" --json` (via the standard prelude) *before* congratulating. If any candidate has `isEpicMember: true` on another branch, add an **additive, non-blocking** hint — it does not change the completion, only flags a likely split-brain: "⚠️ Heads-up: `{feature}` matches a member of epic `{epic}` on branch `{stateBranch}`. This standalone pipeline may have been forged detached from that epic. To reconcile, see `docs/recovery-detached-epic-member.md` (or continue — this is only a heads-up)." Skip the hint for epic-member rows (their `epic` is non-null) and when discovery surfaces no epic-member candidate.
**Completion hand-off (fires when `nextStage` is `null` AND `forge-6-docs` has run — the pipeline is fully complete, Issue #124).** Do not dead-end on "pipeline is complete" — after congratulating, point the user at the next unit of work. This is a **terminal branch**: the drive steps (2/2b/3) do not run.
- **Epic member** (this feature's `rank-features` row has a non-null `epic`, i.e. its `.pipeline-state.json` carries an `epic` back-pointer): run `epic-manifest.py render-status "{epic}" --specs-dir "{specsDir}" --json` (standard prelude; you likely already have this from the Tier-1 epic rollup — reuse it rather than re-running). Then:
- If `actionable` is non-empty, offer the next member via host's question mechanism: *"Epic '{epic}' has {total−complete} feature(s) left — next up: **{actionable[0].name}** (`{actionable[0].nextCommand}`). Start it now?"* On accept, drive it exactly like a normal next stage (honor `autoInvokeNextStage` + `Skill`-tool availability per step 3's Continue-in-this-session rule; else print `{nextCommand}`). List any remaining `actionable` members as also-available.
- If `actionable` is empty but the epic is **not** fully complete (members blocked on unmet `dependsOn`), say so and point at the blockers rather than offering a start.
- If the epic is **fully complete** (`rollup.complete == rollup.total`, `total > 0`), congratulate on the whole epic. Offer the epic-level architecture doc **only when every member row's `docsStatus` is `complete` or `skipped`** (#173 — the orchestration rollup counts loop-completeness, so it reads full before any docs exist; a `skipped` docs stage satisfies by decision, #197). When some members' docs are still unwritten, point at the next docs run (`invoke-skill: forge-6-docs {member}`) instead of the epic doc. Either way, mention the epic can be marked complete (`invoke-skill: forge {epic}` renders the finished dashboard).
- **Standalone** (row's `epic` is null): offer to start a fresh feature — *"Start a new feature: `invoke-skill: forge-1-prd <feature-name>` (or group several with `invoke-skill: forge-0-epic <epic-name>`)."* Then, from the `rank-features` `active` list, surface any **other** active pipelines (exclude this just-completed one) as a one-line list with their `nextCommand`s so the user can jump straight back into in-flight work. If the **detached-epic hint above fired** for this feature, lead with that recovery path (`docs/recovery-detached-epic-member.md`) — the split-brain reconcile is the more likely next action than starting something new.
**2. Check the context window.** Run the context-usage helper so you can advise whether to continue here or start the next stage in a fresh session:
```bash
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; }; [ -z "${FEATURE_FORGE_ROOT:-}" ] || exec "$FEATURE_FORGE_ROOT/scripts/forge-root.sh"; w=$PWD; while :; do d="$PWD/.github/feature-forge"; [ -x "$d/scripts/forge-root.sh" ] && { cd "$w"||:; exec "$d/scripts/forge-root.sh"; }; p=$PWD; cd .. || break; [ "$PWD" = "$p" ] && break; done; cd "$w"||:; for d in "$HOME"/.copilot/installed-plugins/*/feature-forge "$HOME"/.copilot/feature-forge "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge "$w"/.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" context-usage --json
{"available": true, ...}→ notepct(e.g. "context ~68% full") andoverThreshold. Window/threshold come fromcontextWindowTokens/contextWarnThresholdinforge.config.json(the helper defaults to a 200k window and 0.7 threshold, and auto-bumps the assumed window to 1M once observed usage exceeds 200k; on a 1M-context model setcontextWindowTokens: 1000000so the percentage is accurate below 200k too — 1M can't be detected from the transcript until usage crosses 200k).{"available": false, ...}→ omit context advice silently (non-Claude host, or a fresh session with no transcript). Never treat this as an error.
2b. Auto-verify catch-up (when verifyPending is true). Under this behavior the just-completed authoring stage runs auto-verify in-stage (references/stage-exit-protocol.md, in-stage verify block), which clears verifyPending — so on the normal path this branch does nothing. It fires only as a catch-up, for any of three reasons: the producing stage could not dispatch a clean-room subagent (non-Claude host); it ran before this behavior landed; or the stage exit recorded durable auto-verify-pending debt that was never discharged — the row's verifyState is auto-pending, meaning verification was scheduled on disk and never ran (a dropped or declined in-stage dispatch, a crash, or a cleared session). This branch fires on an auto-pending row: the debt is owed and recorded, so treat it exactly like any other outstanding verification and never as "never verified" or as already discharged. Lead with the obligation sentence from the legend before acting. When it does fire, decide whether verify runs automatically (identical logic to the in-stage run, so a stage that already verified is never double-verified):
autoVerifyis true for the just-completedverifyStage→ skip the verify question entirely and run verify now, provided it can run clean-room. Auto-verify is safe to run unattended only because verify executes in a freshforge-verifiersubagent that inherits none of this session's context (so no session clear is needed and only a compact digest returns). Guard the clean-room assumption: proceed unattended only when the host's subagent mechanism +forge-verifiersubagent are available. Invokefeature-forge:forge-verifyvia the host's skill-invocation mechanism in require-clean (auto) mode, passing the literalowner: nestedtoken in the invocation prompt — you are the dispatcher here, so you are the sole terminal owner and the branch skill prints no terminal block of its own (see "Branch ownership: theowner:token" inreferences/stage-exit-protocol.md). This is a delegate-and-resume site (see "Caller-side resumption" in the same reference): on the sub-skill's return, control returns here — continue at the matching outcome branch below. In require-clean mode forge-verify refuses to run inline and returns a sentinel if the subagent is not dispatchable (seeskills/forge-verify/SKILL.md). Then:- Sentinel returned (clean-room unavailable) → do not run verify inline. Degrade to the manual gate: fall through to step 3 with the "Verify
{stage}first (manual)" option included, and ifoverThreshold, recommend "clear your session / start a fresh session, then verify in a clean session." Verify state stays outstanding; the stage is never advanced on false assurance. - Verify passed / no findings → proceed to the normal advance gate (step 3), no verify option.
- Verify found findings →
autoFixis true AND preconditions hold — the findings document has zero unresolved decision points and the working tree is clean → invokefeature-forge:forge-fixvia the host's skill-invocation mechanism with the literalowner: nestedtoken in the invocation prompt, then run a mandatory re-verify (require-clean mode, alsoowner: nested). Every call in this catch-up chain is nested and prints no terminal block — you remain the sole terminal owner and print exactly one closing block after the chain settles. Advance only if the re-verify passes. On any precondition miss (decisions required, dirty tree), a forge-fix early stop, or a red re-verify → fall back to the digest + prompt below (never a silent partial mutation).autoFixis false (default), or preconditions failed → present a compact findings digest as text, then host's question mechanism: Apply fixes now (forge-fix) / Review findings / Skip & advance.
- Sentinel returned (clean-room unavailable) → do not run verify inline. Degrade to the manual gate: fall through to step 3 with the "Verify
autoVerifyis false/unconfigured → do not auto-run; use the advance gate in step 3, which gains the folded opt-in verify options ("Verify{stage}now" and "Verify{stage}now + enable auto-verify going forward").
3. Offer the next step via host's question mechanism. (Reached when auto-verify did not fully resolve the step, or verifyPending is false.) Output the dashboard + a one-line context note as text, then ask (per the Decision Support protocol in references/shared-conventions.md). Present this gate exactly once and act only on the option the user chooses — never also narrate the not-taken branch. Concretely: do not print the "start in a clean session" recommendation as prose and then auto-invoke the next stage in the same session (or the reverse) — the host's question mechanism answer is the single decision, and only the chosen path's action follows. This is the same Stage Exit Protocol the stage skills stamp (references/stage-exit-protocol.md) — a clean session at the boundary is recommended on its own merits, and overThreshold only modulates how emphatically, never whether. Options, in this order:
- Start
{nextStage}in a clean session — recommended, unconditionally, at every boundary. A clean session is the right default for the next stage on its own merits, independent of window size. The work survives a clear because all state is on disk: instruct the user to clear your session / start a fresh session, then re-runinvoke-skill: forge {feature}(or run{nextCommand}directly) in the fresh session. Note plainly that you cannot clear your session / start a fresh session for them. WhenoverThresholdis true, strengthen this wording (the window is also genuinely full) and add mid-stage compaction advice; when the window is healthy, still recommend the clean session —overThresholdis a secondary, additive modifier here, not the clear on/off switch. - Continue in this session — the always-available alternative, reasonable when the window is nearly empty and the user would rather not clear. Not the default.
- Verify
{stage}now — include only whenverifyPendingis true andautoVerifyis false, and the clean-room path is available. Recommended, since verify is clean-room and rarely worth skipping. Runs verify now (require-clean mode); does not change config. - Verify
{stage}now + enable auto-verify going forward — same trigger as the option above; runs verify now and patchesautoVerify: trueintoforge.config.jsonin place (preserve formatting and other keys) so every future stage verifies automatically without prompting. This is the folded config-enable — it replaces the old post-hoc "make auto-verify the default?" follow-up. No silent config writes: the config changes only when the user picks this option. - Verify
{stage}first (manual) — include only whenverifyPendingis true and the clean-room path is unavailable (the Tier-2 degradation above), or the host lacks the host's skill-invocation and subagent mechanisms; selecting it runs{verifyCommand}(inline / manual). Offer the "enable auto-verify" choice as text only if a config write is possible. - Pick a different stage — free-form escape to any stage or other action.
4. Act on the choice.
- Clean session (the default) → give the exact next command and the session clear-then-re-run instruction; do not invoke anything (you cannot clear your session / start a fresh session for the user).
- Continue in this session → if
autoInvokeNextStageis true (default) and the host's skill-invocation mechanism is available, invoke the chosen stage via the host's skill-invocation mechanism in this same session (e.g.skill: "feature-forge:forge-3-specs",args: "{feature}") — no retyping, no paste. This advance is a terminal handoff (see "Caller-side resumption" inreferences/stage-exit-protocol.md): the invoked stage owns the terminal from here — the navigator's job ends at the invocation, deliberately, not by omission. IfautoInvokeNextStageis false, or the host's skill-invocation mechanism is unavailable (a non-Claude host), fall back to printing{nextCommand}prominently for the user to run. - Verify now / Verify now + enable auto-verify → invoke
feature-forge:forge-verifyvia the host's skill-invocation mechanism (require-clean mode) with the literalowner: nestedtoken. Every navigator dispatch offorge-verify/forge-fix— the step 2b catch-up chain, this gate, and the "Apply fixes now" choice of the findings digest — carriesowner: nested, so the branch skill returns its structured result and prints no terminal block, and the navigator stays the sole terminal owner. Each is a delegate-and-resume site: on return, control returns to this gate's flow — act on the result (digest, gate, or advance) yourself; the branch skill's own close never ends the dashboard turn. For the enable-auto-verify variant, additionally patchautoVerify: trueintoforge.config.jsonin place (preserve formatting and other keys) — never a silent write. On a non-Claude host or when degrading to the manual/inline gate, print{verifyCommand}instead. - Different stage → honor the free-form request.
Host fallback. On a non-Claude host or when the host's skill-invocation and subagent mechanisms are unavailable, auto-verify never runs unattended — fall back to printing {verifyCommand} exactly as today, mirroring autoInvokeNextStage.
This applies whether the feature was named explicitly (invoke-skill: forge {feature}) or resolved from the recency default.
Epic Dashboard
When the named argument is an epic ({specsDir}/{name}/epic-manifest.json exists), render the epic dashboard instead of a per-feature one. Run:
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; }; [ -z "${FEATURE_FORGE_ROOT:-}" ] || exec "$FEATURE_FORGE_ROOT/scripts/forge-root.sh"; w=$PWD; while :; do d="$PWD/.github/feature-forge"; [ -x "$d/scripts/forge-root.sh" ] && { cd "$w"||:; exec "$d/scripts/forge-root.sh"; }; p=$PWD; cd .. || break; [ "$PWD" = "$p" ] && break; done; cd "$w"||:; for d in "$HOME"/.copilot/installed-plugins/*/feature-forge "$HOME"/.copilot/feature-forge "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge "$w"/.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/epic-manifest.py" render-status "{epic}" --specs-dir "{specsDir}" --json
and render from its output:
- Epic header: name +
status(active | paused | abandoned | complete). - Dependency graph: each feature with its
dependsOn, as an arrow list or indented tree (the helper guarantees the graph is acyclic). - Per-feature rows: reuse the existing status indicators below (✅/✅⚠️/🔄/⬜/❌/✅🔍/⏭️/⚠️/⏳), driven by each feature's derived
stage/status. Markblockedfeatures and list theirunmetDeps.render-status --jsonalso emits an owed-automatic-verification obligation in itswarningsarray for any member carrying that debt — surface those lines verbatim rather than restating them, and mark those members ⏳, never ⬜. - Pending epic changes: for any feature with
openEpicChangeRequests > 0, append a ⚠️ marker and a hint: "N pending epic change(s) — runinvoke-skill: forge-0-epic {epic}to reconcile." IfblockingEpicChangeRequests > 0, use a stronger marker (⚠️ blocking) and word it "reconcile the epic before writing specs" — this mirrors the pause-now vs finish-then split that stage-exit already routes on. Take these counts only fromrender-status --json(features[].openEpicChangeRequests/.blockingEpicChangeRequests); do not read member.pipeline-state.jsondirectly for them. - Actionable vs blocked: list the
actionableset and the recommendednextCommand. - Rollup:
{complete}/{total} features complete.
Example:
Epic: auth-overhaul [active] — 2/4 features complete
Dependency graph:
config-store (no deps)
token-service → config-store
api-gateway → token-service
audit-log (no deps)
✅ config-store complete
🔄 token-service forge-3-specs (in progress) — ⚠️ 1 pending epic change
⬜ api-gateway blocked — waiting on token-service
✅ audit-log complete
Actionable now: token-service
Next: invoke-skill: forge-3-specs token-service
⚠️ Pending epic changes: token-service (1). Run invoke-skill: forge-0-epic auth-overhaul to reconcile.
All of this is reconstructed purely from disk — the manifest plus each member's .pipeline-state.json, with no in-memory state — so a fresh session renders the same dashboard. If render-status fails, do not render a partial dashboard; surface per the exit-1/exit-2 split in the Feature Directory Resolution block of references/shared-conventions.md (exit 1 → parse {findings[]} from stdout; exit 2 → surface the plain Error: stderr line verbatim).
4. Notes Management
If the user says something like "note: switching to jose for JWT" or "remember: we decided X", update the notes field by running state-note (below). This helps preserve context across session clears. Add --epic "{epic}" when the feature is an epic member — required, per the Pipeline State Protocol in references/shared-conventions.md.
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; }; [ -z "${FEATURE_FORGE_ROOT:-}" ] || exec "$FEATURE_FORGE_ROOT/scripts/forge-root.sh"; w=$PWD; while :; do d="$PWD/.github/feature-forge"; [ -x "$d/scripts/forge-root.sh" ] && { cd "$w"||:; exec "$d/scripts/forge-root.sh"; }; p=$PWD; cd .. || break; [ "$PWD" = "$p" ] && break; done; cd "$w"||:; for d in "$HOME"/.copilot/installed-plugins/*/feature-forge "$HOME"/.copilot/feature-forge "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache/*/feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge "$w"/.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" state-note --feature "{feature}" --note "<what the user said>" --specs-dir "{specsDir}"
5. Available Commands Reference
When showing the dashboard, include a compact reference:
Commands:
invoke-skill: forge-1-prd <feature> Create requirements document
invoke-skill: forge-2-tech <feature> Create technical spec
invoke-skill: forge-3-specs <feature> Create implementation specs
invoke-skill: forge-4-backlog <feature> Generate rauf backlog
invoke-skill: forge-5-loop <feature> Run rauf autonomous loop
invoke-skill: forge-6-docs <feature> Generate architecture docs
invoke-skill: forge-verify <feature> Run verification on current stage
6. Pipeline Lifecycle Commands
Deliberate R4 exclusion. The
pipelineStatuswrites below (pause/resume/abandon, and the member-pause under Epic lifecycle) stay hand-authored on purpose: thestate-*verbs cover the seven stage and array touch points, and none of them writespipelineStatus. These are the sanctioned exception to the Pipeline State Protocol inreferences/shared-conventions.md— everywhere else, state is written by a verb, never by hand. When authoring one of thesepipelineStatuswrites, conform toreferences/pipeline-state-schema.json— this is the one navigator path that still reads it.
Support these sub-commands for pipeline lifecycle management:
invoke-skill: forge pause {feature}— SetpipelineStatusto"paused". Do NOT modifycurrentStageor any stage statuses. The pipeline freezes exactly as-is. Show a confirmation.invoke-skill: forge resume {feature}— SetpipelineStatusback to"active". Calculate how long the feature was paused (fromupdatedAtto now). If paused for more than 24 hours, show a hint: "This feature was paused for {duration}. Session context may have been lost — consider re-runninginvoke-skill: forge-{currentStage} {feature}to rebuild context."invoke-skill: forge abandon {feature}— SetpipelineStatusto"abandoned". Use host's question mechanism to confirm first, and state what's reversible: abandoning does not delete artifacts and can be undone withinvoke-skill: forge resume {feature}, so the cost is low — but if the user really means "stop and discard," point out thatpauseis the better choice when they're only setting it aside. Offer Abandon · Pause instead · Cancel.invoke-skill: forge run [{feature}]— Opt-in auto-advance. Drive the feature through consecutive stages in one session instead of confirming each boundary. This is a convenience wrapper over 3b. Drive to the Next Stage — same stage order, same context gate — just looped:- Resolve the feature (if omitted, use the recency default from
rank-features; if multiple are equally plausible, ask once via host's question mechanism). - Before each stage, run
forge-session.py context-usage. IfoverThresholdis true, stop and recommend a clean session (give the exact{nextCommand}and the session clear-then-re-run instruction) — never auto-clear your session / start a fresh session. - Otherwise invoke the next stage's skill via the host's skill-invocation mechanism as a delegate-and-resume invocation, declaring the resume point at the invocation (see "Caller-side resumption: the declared resume point" in
references/stage-exit-protocol.md): when the stage skill returns, control returns to this loop, at step 2, in the same turn — re-read state and continue. The invoked stage's own closing posture never ends therunloop. - Stop conditions: the next stage is an interview/decision point that calls host's question mechanism (PRD and tech inherently pause for input — let them);
nextStageisnull(pipeline complete); context over threshold; or a stage signals it needs human input / is blocked. Always report where the loop stopped and why. Per-stage confirmation (3b) remains the default —runis only used when the user explicitly asks to "run" / "drive" / "auto-advance" the pipeline. On a non-Claude host where the host's skill-invocation mechanism is unavailable, fall back to printing the ordered list of commands to run.
- Resolve the feature (if omitted, use the recency default from
Epic lifecycle. When the argument names an epic ({specsDir}/{name}/epic-manifest.json exists), pause / resume / abandon operate on the epic manifest, not a .pipeline-state.json:
- Set the manifest's top-level
status(paused/active/abandoned) via the helper'sset-statusmutator — an atomic write that also bumpsupdatedAt:
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; }; [ -z "${FEATURE_FORGE_ROOT:-}" ] || exec "$FEATURE_FORGE_ROOT/scripts/forge-root.sh"; w=$PWD; while :; do d="$PWD/.github/feature-forge"; [ -x "$d/scripts/forge-root.sh" ] && { cd "$w"||:; exec "$d/scripts/forge-root.sh"; }; p=$PWD; cd .. || break; [ "$PWD" = "$p" ] && break; done; cd "$w"||:; for d in "$HOME"/.copilot/installed-plugins//feature-forge "$HOME"/.copilot/feature-forge "$HOME"/.claude/skills/feature-forge "$HOME"/.claude/plugins/cache//feature-forge/* "$HOME"/.claude/plugins/*/feature-forge "$HOME"/.agents/skills/feature-forge "$w"/.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/epic-manifest.py" set-status "{epic}" --status paused --specs-dir "{specsDir}"
For `complete`, do **not** set the status directly — completion is *derived* from member states (the rollup), so the manifest `status` is a lifecycle flag, never a completion signal.
- **Member feature states are NOT silently mutated.** Pausing/abandoning the epic changes only the manifest `status`. Before doing so, use host's question mechanism to make the relationship explicit and frame the trade-off: "Pausing the epic does not pause its in-flight member features. {N} members are active. Pause the epic only, or also pause each member?" Recommend **epic only** when members are mid-stage and the user just wants to stop *new* orchestration; recommend **also pause members** when the intent is a hard freeze of all in-flight work. If the user opts to pause members too, update each member's own `pipelineStatus` **individually and visibly** (one explicit action per member), never as a hidden side-effect.
- Commit the change via the Git Commit Protocol, staging `{specsDir}/{epic}/`.
When listing features, show active pipelines by default. Include a count of paused/abandoned: "3 active pipelines (1 paused, 1 abandoned — use `invoke-skill: forge list all` to see them)."
## Gotchas
- Never modify any spec files, backlog files, or pipeline state beyond the `notes`, `updatedAt`, and `pipelineStatus` fields. The navigator is read-only except for notes and lifecycle commands.
- If a user asks to "continue" or "pick up where I left off" without naming a feature, check for active pipelines before asking. Only ask if ambiguous.
- The pipeline state file is the source of truth. Don't infer stage from the existence of files alone — a file might exist from a previous incomplete run.
---
## Host execution notes (GitHub Copilot)
This bundle uses distribution-neutral invocation notation because Copilot assigns different slash-command names to plugin and direct installations:
- **Invocation notation:** `invoke-skill: <name> [arguments]` in the body and references is an instruction, not a literal command to paste. Preserve the named skill and its arguments.
- **Plugin install:** invoke `/feature-forge:<name> [arguments]`.
- **Direct project/personal install:** invoke `/<name> [arguments]`.
- **No universal slash name:** use the form matching the skill's discovery source. If the source is uncertain, use Copilot's skill-invocation mechanism or ask the user instead of guessing.
- **User input:** Copilot has no structured question tool in this bundle — ask the question directly and wait for the answer when the session can prompt and wait; never assume one. Read whether it can from the Interaction Capability Ladder's `interaction-mode` record rather than judging it. When the session is genuinely non-interactive, 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:** dispatch the named custom agent with Copilot's subagent mechanism. If it is unavailable, run that step inline only when the skill permits inline execution.
- **Background / monitoring (forge-5-loop):** launch the loop detached and supervise it with the `rauf loop wait` loop exactly as the forge-5-loop skill's runner contract (Steps 3b/3d) says for this host. Never run the loop in the foreground, and don't end your turn while it runs unless Copilot wakes you when a background command finishes. Other long-lived commands: run them in the foreground (or Copilot's background facility) and report progress as it arrives.
- **Bundle root:** the `$R` bootstrap in each shell block resolves `FEATURE_FORGE_ROOT` first, then the nearest project `.github/feature-forge`, then the plugin install (`~/.copilot/installed-plugins/*/feature-forge`), then `~/.copilot/feature-forge`. Run the blocks as written; set `FEATURE_FORGE_ROOT` only to pin a specific bundle.
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.