archive
goalforge-internal — use entry commands; do not auto-trigger Archive a completed goalforge feature to its terminal `archived` status, optionally recording that it supersedes a prior feature. Fail-closed: REFUSES unless the feature is `status: completed` (cannot archive draft/ready/active). On `--supersedes <old>` writes the `supersedes`/`superseded_by` relationship edges on both features and archives the old one too, verifying both slugs exist first. A `--relocate` mode reconciles a STRANDED archived feature — one already `status: archived` but still physically at the active plans root (status set out-of-band, never moved) — by moving it into `_archived/` (move-only, no frontmatter edit; requires status: archived). Runs the strict validator gate and an ensure-committed check. TRIGGER: 'archive feature', 'archive completed feature', 'feature B supersedes A', 'migration archive', 'relocate stranded archived feature', 'reconcile archived plan at active root'. Human-gated / on-demand — NOT part of the sdd chain.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- archive
- metadata
- { "version": "1.4.0", "skill-kind": "preference" }
- description
- goalforge-internal — use entry commands; do not auto-trigger Archive a completed goalforge feature to its terminal `archived` status, optionally recording that it supersedes a prior feature. Fail-closed: REFUSES unless the feature is `status: completed` (cannot archive draft/ready/active). On `--supersedes <old>` writes the `supersedes`/`superseded_by` relationship edges on both features and archives the old one too, verifying both slugs exist first. A `--relocate` mode reconciles a STRANDED archived feature — one already `status: archived` but still physically at the active plans root (status set out-of-band, never moved) — by moving it into `_archived/` (move-only, no frontmatter edit; requires status: archived). Runs the strict validator gate and an ensure-committed check. TRIGGER: 'archive feature', 'archive completed feature', 'feature B supersedes A', 'migration archive', 'relocate stranded archived feature', 'reconcile archived plan at active root'. Human-gated / on-demand — NOT part of the sdd chain.
03 SKILL.md 正文
goalforge-archive
Drives a feature to its terminal archived status — the historical-record end
state. Two modes: a plain archive of one completed feature, and a
supersession archive that also records supersedes/superseded_by edges
between a replacing feature and the one it replaced.
completed → archived is explicit user action only — it is never automatic.
goalforge-verify advances a feature to completed (last-WP rule) and then offers
archival; this skill performs it on request.
Schema reference: ${CLAUDE_PLUGIN_ROOT}/references/schema.md.
Archive-consumer contract (what an archived slug guarantees to edge consumers):
${CLAUDE_PLUGIN_ROOT}/references/archive-contract.md.
Plans root
<feature> (and --supersedes <old>) name folders inside <PLANS_ROOT>/.
Resolve <PLANS_ROOT> per ${CLAUDE_PLUGIN_ROOT}/references/schema.md
§PLANS_ROOT resolution: env SDD_PLANS_DIR → project git-root plans/ →
global ~/.claude/plans/.
Inputs
<feature>— the feature slug to archive (required).--supersedes <old>— optional; the prior feature slug that<feature>replaces.--relocate— optional; reconcile a stranded archived feature (move-only). Mutually exclusive with--supersedes. See Relocate mode below.--strict-refs— optional; escalate the reference-gate (Step 4b) from WARN to REFUSE (exit 6) when inbound path references to the feature would dangle after the move. Recommended for interactive archival. Composes with all modes.
Relocate mode (stranded archived → _archived/)
A feature can end up status: archived but still physically at the active plans
root — its status was set out-of-band (a reconciliation pass, a hand edit) and the
folder was never moved into _archived/. The default gate cannot fix this: it
fail-closes on status: completed, and a stranded feature is already archived,
so it REFUSES. --relocate is the dedicated handler:
bash ${CLAUDE_PLUGIN_ROOT}/scripts/goalforge-archive.sh <feature> --relocate \
[--plans-root <PLANS_ROOT>]
- Inverse gate: requires
status: archived(REFUSE with exit 3 if the feature iscompleted/active/ready/draft— use the plain mode forcompleted). - Move-only: writes no frontmatter (the feature is already archived); it
validates the feature scoped (
--feature --strict) then moves<feature>/into_archived/<feature>/. Destination collision → exit 4 (HALT, no overwrite). --supersedesis rejected here (exit 2) — supersession is a completing-archival concern, not a relocation.
The orchestrator commits the rename (git tracks edit-free moves as a clean rename),
then runs the Step-5 ensure-clean on the new _archived/<feature>/ path.
Step 1 — Fail-closed precondition (REFUSE unless completed)
Read <PLANS_ROOT>/<feature>/overview.md. Inspect the status: frontmatter
field. The skill proceeds ONLY when status: completed.
If status: is anything else (draft, ready, active, or already
archived), the skill MUST:
- Print the offending status.
- Refuse to archive and halt — make no edits.
A feature must reach completed (all sibling WPs verified, via goalforge-verify's
last-WP rule) before it can be archived. There is no path that archives a
draft, ready, or active feature.
When --supersedes <old> is given, additionally verify both slugs resolve
to an existing <PLANS_ROOT>/<slug>/overview.md before writing anything. If
either is missing, refuse and report the missing slug. (The <old> feature is
not required to be completed — a superseded feature is being retired.)
Step 1.5 — Terminal integration confirmation before archive (soft gate)
The primary cross-WP integration review runs at the last-WP→completed
transition in goalforge-verify (role integration-review). This step is the
terminal confirmation of that review — the last point before the work becomes
a permanent historical record — not the sole integration tier and not a re-run
from scratch.
- Confirm the goalforge-verify integration review ran and its findings are resolved
(read the feature
findings.md). If it did run and is clean, this is a quick confirmation. If it is missing or has open findings, dispatch thereviewskill /code-reviewerover the feature's full diff (git diffacross all WP commits) and resolve findings first — archive must not be the only place integration is checked, but it is the backstop when the upstream review was skipped. - Human-judgment, not a mechanical gate (interactive). This step adds no
script check and never auto-blocks; the human decides whether findings are
resolved. (L2 user-decision —
[[review-agent-before-archive]].) - Autopilot (
SDD_AUTONOMY=unattended): PARK, do not silently no-op. With no human to judge, if the confirmation cannot be made cleanly (review missing or findings open), write the blocker to the featurefindings.mdand stop for human pickup — never skip the integration check and proceed to archive.
Steps 2–4 — Mechanical core (delegated to goalforge-archive.sh)
The frontmatter edit, physical move, and validator gate are performed
deterministically by a script — ${CLAUDE_PLUGIN_ROOT}/scripts/goalforge-archive.sh
— so the same logic is drivable unattended (the goalforge-archive-batch.sh loop). The
script is the single source of truth for these mechanics; this skill is the
human front door (the Step-1 gate presentation, the refusal templates below, and
the Step-6 report).
bash ${CLAUDE_PLUGIN_ROOT}/scripts/goalforge-archive.sh <feature> \
[--supersedes <old>] [--plans-root <PLANS_ROOT>]
What the script does (and its contract):
- Re-enforces the Step-1 gate (refuses unless
status: completed; under--supersedes, verifies both slugs exist). Exit 3 = refused. - Edits frontmatter (targeted, minimal-diff):
<feature>→status: archivedupdated: <today>. Under--supersedes, also writes the inverse edges —supersedes: [[<old>]]on<feature>andsuperseded_by: [[<feature>]]on<old>(merged into any existingrelationships:list, never clobbered) — and flips<old>tostatus: archivedtoo.
- Validates each edited feature scoped —
--feature <slug> --strict— BEFORE the move. The validator still WALKS the whole tree (so cross-featuresupersedes/superseded_by/depends_onedges resolve), but only the archived feature's own errors gate, so a tree that legitimately carries deferred drift in unrelated features never blocks the archive. Exit 5 if it fails. - Moves
<feature>/(and<old>/under--supersedes) into_archived/AFTER the edit+validate, so git records the edit + rename in one commit. Exit 4 if the destination already exists (HALT, no overwrite).
The script does not commit and does not run ensure-committed — Step 5 does that after the orchestrator commits. On a non-zero exit, present the matching refusal template and HALT.
Step 4b — Reference-gate (warn; REFUSE under --strict-refs)
Between the validator gate and the physical move, the script scans for inbound
path references to the feature — refs that use the active <slug>/ path (a
cross-cited findings.md/playbook, a fixture, a frontmatter locator:) and will
dangle after the folder moves to _archived/<slug>/. This is the gate that
was missing when a blind archive of a cross-cited WP findings.md broke ~12 links
and had to be reverted.
- What is flagged: only path references (
<slug>/…) from OUTSIDE the feature's own folder and outside_archived/, across<PLANS_ROOT>and the siblingdocs/. The search isgrep -F(literal) so a slug with regex chars is safe. - What is NOT flagged: relationship wikilinks
[[<slug>]]— those are graph edges, and an archived target is meant to stay resolvable (edges survive archiving and resolve terminal). Scope of that claim: verified forgoalforge-validate.sh, which re-adds archived slugs to its name index. Every other consumer is required to conform to${CLAUDE_PLUGIN_ROOT}/references/archive-contract.md— conformance is not verified here, so a consumer bug shows up as a dangling edge, not as a reason to refuse the archive. - Behavior: WARN by default (prints the offending refs + the relocate-then-move
remedy, exit 0 — non-blocking so the unattended
goalforge-archive-batch.shloop is unchanged). Under--strict-refsit REFUSES with exit 6. The remedy in both cases: relocate the cross-cited artifact to a stable home and repoint every reference (or re-point them to_archived/<slug>/) BEFORE archiving.
Step 5 — Ensure-clean (after the orchestrator commits)
This skill does not commit. After the orchestrator commits the archival
edits (including the physical move), confirm the feature path(s) carry no
uncommitted artifacts — using the new _archived/ paths (the originals no
longer exist):
bash ${CLAUDE_PLUGIN_ROOT}/scripts/goalforge-ensure-committed.sh <PLANS_ROOT>/_archived/<feature>
# and, under --supersedes:
bash ${CLAUDE_PLUGIN_ROOT}/scripts/goalforge-ensure-committed.sh <PLANS_ROOT>/_archived/<old>
On non-zero, report the dirty paths and HALT (do not declare done). The check is
path-scoped (unrelated dirt elsewhere never false-blocks) and branch-agnostic:
in the dotfiles repo the working branch is master, so the commit lands on
master directly — no feature branch, no push. Elsewhere, normal branch rules
apply.
Step 6 — Report
Archived: <PLANS_ROOT>/_archived/<feature>/overview.md (status: archived, moved from <feature>/)
[Supersedes: <old> — <old> archived + moved to _archived/<old>/]
Validator: PASS (goalforge-validate --strict)
Working tree: clean under _archived/<feature>/ [and _archived/<old>/]
Not in the chain
goalforge-archive is NOT wired into chain.yaml. Archival is a terminal,
human-gated decision invoked on demand — never an automated chain step.
Files read / written
| File | Access |
|---|---|
<feature>/overview.md |
read (status: gate) + write (status: archived, updated:, optional supersedes edge) |
<feature>/ (directory) |
moved to _archived/<feature>/ after frontmatter edit |
<old>/overview.md |
(--supersedes only) read (existence) + write (status: archived, updated:, superseded_by edge) |
<old>/ (directory) |
(--supersedes only) moved to _archived/<old>/ after frontmatter edit |
State transition
feature: completed → archived + moved to _archived/<feature>/ (explicit user action only — this skill)
feature: completed → archived + moved to _archived/<feature>/
<old> → archived + moved to _archived/<old>/ (--supersedes, both features)
completed is the only valid source state. archived is terminal. The physical
move to _archived/ is part of the same atomic user-action: frontmatter edit
then folder move, committed together.
Refusal template
When the precondition is not met, output:
goalforge-archive REFUSED — precondition not satisfied:
Feature: <feature>
status: <offending-status> (required: completed)
A feature must be `completed` (all WPs verified via goalforge-verify) before it can be
archived. Cannot archive a draft/ready/active feature.
When a --supersedes slug is missing:
goalforge-archive REFUSED — supersedes target not found:
Missing: <PLANS_ROOT>/<old>/overview.md
Check the <old> slug spelling, or confirm the feature exists.
Gotchas
- Reference-gate flags PATH refs, not wikilinks. Step 4b greps for
<slug>/(literal,grep -F) from outside the feature + outside_archived/. A[[<slug>]]relationship edge is NOT a path ref and is correctly ignored — the archived target stays resolvable per${CLAUDE_PLUGIN_ROOT}/references/archive-contract.md(validator-verified; other consumers conform to the contract rather than being guaranteed by this skill). Only refs that point INTO the feature's files (a cross-citedfindings.md, a frontmatterlocator:) dangle after the move. WARN by default keeps the unattended batch loop working;--strict-refsmakes it a hard gate (exit 6). Do NOT "fix" a flagged ref by deleting it — relocate the artifact and repoint. - The status gate is fail-closed on exactly
completed—active,ready,draft, and an already-archivedfeature all REFUSE in the default mode. There is no "force archive"; advance the feature tocompletedviagoalforge-verify's last-WP rule first. The one exception is--relocate, whose gate is the inverse (status: archivedrequired) and which only moves a stranded archived feature into_archived/— it never flips a non-archived status. - Feature terminal status is
archived(reached fromcompleted, which is the mandatory pre-archive feature status — see the gate above); the WP terminal status isverified, witharchivedas a second WP terminal set only by explicit out-of-band edit, never by a transition edge and never by any goalforge script. Never writestatus: verifiedto a feature overview, and neverstatus: completedto a WP — the enums do not overlap at the terminal end, witharchivedas the one deliberate exception (legal on both). A WP atarchivedis dep-satisfying:goalforge-frontier.shandgoalforge-validate.shtreat it exactly asverifiedwhen resolving a sibling'sdepends_on. --supersedesarchives BOTH features:<feature>(the replacing one, alreadycompleted) AND<old>(the replaced one, retired regardless of its prior status). Forgetting that<old>also flips toarchivedleaves a half-written relationship with one live and one archived side.supersedesandsuperseded_byare inverse edges and BOTH must be written (one per feature) — writing only one side leaves the graph navigable from a single direction and the validator's cross-feature check sees only half the relationship.- The validator gate runs over the WHOLE
<PLANS_ROOT>, not<PLANS_ROOT>/<feature>— a single-feature walk cannot resolve a cross-featuresupersedestarget and would either skip the check or false-dangle. Always pass the plans root. - Merge new edges into the existing
relationships:list; never replace it. A feature may already carryrelated_to/depends_onedges that must survive. - The ensure-committed check is path-scoped and branch-agnostic: it passes on
master(the dotfiles exception) and never false-blocks on dirt outside the feature path. It is NOT a substitute for the commit itself — the orchestrator commits; this skill only verifies cleanliness afterward. - The physical move happens AFTER the frontmatter edits so git tracks the rename correctly (edit + move in one commit). Moving first, then editing, creates a confusing two-step git history where the file appears at the old path in one commit and the new path in the next.
- After the physical move,
goalforge-ensure-committed.shmust be called on<PLANS_ROOT>/_archived/<feature>, NOT on the original path (which no longer exists after the move). goalforge-validate.sh --strict <PLANS_ROOT>must walk_archived/to resolve cross-featuresupersedes/superseded_byedges — pass<PLANS_ROOT>(not<PLANS_ROOT>/<feature>) so the validator sees both sides, including features that have already been moved into_archived/.
04 同仓库更多 Skills
wayfind
goalforge-internal — use entry commands; do not auto-trigger Chart a foggy, multi-session effort into a decision map BEFORE goalforge-capture — when the work is too big to spec yet, spans multiple sessions, and needs a decision map before anyone can write a real spec. Triggers: "chart this foggy effort", "multi-session decision map", "too big to spec yet", "map the unknowns before we plan". Establishes <PLANS_ROOT>/<effort>/wayfind/ (map.md pointer-index + one-decision-per-ticket files), drives a frontier-computed work loop across sessions, and graduates the converged map into goalforge-capture. SKIP when the effort is one session and already clear — a single well-understood feature goes straight to goalforge-capture with no map. SKIP for a bounded one-off edit, and for anything already past spec (that is the SDD chain, not wayfind).
verify
goalforge-internal — use entry commands; do not auto-trigger Verify a work package at `status: implemented`: gate A deterministic (lint, typecheck, verification.command, diff ⊆ owned_files), gate B one fresh-context review of the WP diff, gate C goal judge plus one second opinion. Advances `implemented → verified` — the sole authority for that edge. TRIGGER: /verify <wp-path>, or when the chain reaches the verify step.
spec
goalforge-internal — use entry commands; do not auto-trigger Run a design pass on a captured feature and propose the spec document, or propose a revision of an approved spec when a learning falsifies it (the respec edge). Reads plans/<feature>/overview.md, optionally invokes personas or architect for a multi-lens review, writes plans/<feature>/spec.md from the feature-spec template as the proposal (draft → spec), and ratifies it on spec → ready. HUMAN-GATED: spec → ready needs explicit user approval. Trigger: the user asks to spec, design, or elaborate on a feature that already has an overview.md (status: draft), or a feature sits at status: spec with a proposal awaiting ratification.
run
goalforge-internal — use entry commands; do not auto-trigger Chain driver for the goalforge stages: capture → spec → decompose → harden → execute → verify. Reads the target's on-disk `status:` and enters the one step that status admits; supports --dry-run. Use it to drive a feature end-to-end; for a single stage, use the entry command for that stage.
redecompose
goalforge-internal — use entry commands; do not auto-trigger Reconcile a proposed re-decomposition against a partially-executed feature's verified WPs. Calls goalforge-reconcile-diff.sh to produce a 5-bucket diff, then routes: same → untouched (no-op), changed+new → status: spec and onto the harden frontier via goalforge-transition.sh, dropped-verified → supersede in place (ledger row, never delete), ambiguous (slug changed, goal matches a verified WP) → judgment/human — never auto-rename or auto-supersede. Logs goal mutations via goalforge-goal-changelog.sh. Idempotent: re-run on unchanged decomposition is a byte-identical no-op. TRIGGER: /goalforge-redecompose <feature-dir> --learning '<text>' or when goalforge-run loops back on a learning event.
prototype
goalforge-internal — use entry commands; do not auto-trigger Throwaway spike answering exactly ONE design question with runnable code — logic branch (pure logic module + interactive terminal harness, LOGIC.md), UI branch (several radically different variations, UI.md), or perf branch (benchmark study of rival implementations with a scaling curve, PERF.md). Keep the answer, delete the code. Use when an open question is of kind "how should it behave / which approach wins / how should it look / is it fast enough, does it scale, is the optimization worth it" and more interviewing or reading will not settle it — a spike will. Entry points: handoff mode `prototype` (cross-session dispatch seam), goalforge-harden open-question routing, idea-refine, or the user saying "spike this" / "quick prototype to check" / "benchmark this". Refuses to start without a single question AND explicit success criteria.