| name | spec-anchor-prelude |
| description | Use BEFORE invoking any superpowers process skill (brainstorming, writing-plans, executing-plans, systematic-debugging) in a project that contains anchor.yaml or .specanchor/. Loads the project's Spec Landscape (Global/Module Spec + Available Commands + Active Tasks) into context so subsequent design/plan work stays anchored. Skip ONLY when the working directory has no anchor.yaml and no .specanchor/ subdir. |
Spec Anchor Prelude
One purpose: Before any creative or planning skill runs, materialize the project's Spec Landscape so design/plan decisions are made inside the team's pre-compiled spec context, not in the void.
This skill is the bridge between the superpowers process layer (brainstorming → writing-plans → executing-plans) and the spec-anchor context control plane (Spec / Decision / Evidence).
When to invoke
Invoke this skill before any of these:
superpowers:brainstormingsuperpowers:writing-planssuperpowers:executing-planssuperpowers:subagent-driven-developmentsuperpowers:systematic-debugging (when the bug touches multiple modules)
Skip only when:
- Working directory has no
anchor.yaml and no .specanchor/ subdir
- Task is a pure non-coding chat (e.g., "explain regex")
What this skill does
A single, deterministic 4-step prelude. No interactive questions.
Step 1 — Locate spec-anchor
SA_DIR=""
if [[ -f scripts/specanchor-boot.sh ]]; then
SA_DIR="$PWD"
elif [[ -d "$HOME/.claude/plugins/cache" ]]; then
SA_DIR=$(find "$HOME/.claude/plugins/cache" -name "specanchor-boot.sh" -path "*spec-anchor*" 2>/dev/null | head -1 | xargs dirname | xargs dirname)
fi
[[ -z "$SA_DIR" ]] && { echo "spec-anchor not installed — Skill prelude SKIPPED"; exit 0; }
Step 2 — Run boot, capture Spec Landscape
SPECANCHOR_SKILL_DIR="$SA_DIR" bash "$SA_DIR/scripts/specanchor-boot.sh" --format=summary
Read the output for:
- Landscape Readiness — 🟢/🟡/🔴 status
- Global Specs — files and line counts
- Active Tasks — task_name + status + RIPER phase + writing_protocol (schema-aware：fluid schema 不显示 phase)
- Available Commands — internal IDs for routing
- Available Modules — what modules already have specs
Step 3 — Decide workflow intensity
Status 语义：Active Tasks 段会列出所有未归档 task。本表中 "in-progress" 严格指 status: in_progress（不含 review / draft / done 未归档）。其他状态作为信号但不阻断。
| Landscape Readiness | status == in_progress | Recommendation |
|---|
| 🟢 READY | 0 | Proceed to superpowers skill with full context；如有 review / draft 状态 task 仅向用户报告其存在 |
| 🟢 READY | ≥1 | Stop. Read the in-progress task spec(s) first. Confirm with user whether to continue existing work or start new. |
| 🟡 ATTENTION | any | Surface attention reasons to user. Proceed only after acknowledgement. |
| 🔴 NOT_READY | any | Block. Run specanchor_init / specanchor_global first. Do NOT invoke any process skill. |
Implementation hint：用 --format=json 取 active_tasks[] 然后 filter(t.status=="in_progress") 比解析 text 输出更可靠。
Step 4 — Hand off with explicit context
Before invoking the chosen superpowers skill, announce in one sentence:
Spec Landscape: 🟢 READY · 3 globals · N modules fresh · M in-progress task(s) · Available commands loaded.
Then invoke superpowers:brainstorming (or whichever was requested).
Hard rules
- Never skip step 3 reading active task specs when Landscape Readiness shows them.
- Never propose architectural decisions without referencing at least one of: Global Spec, Module Spec, or related Task Spec.
- Never invent business rules that aren't in the loaded specs — instead, ask the user or create a new Task Spec via
specanchor_task.
Why this exists (rationale)
superpowers process skills (brainstorming, writing-plans, etc.) are project-agnostic — they ask great questions but don't know your team's conventions, in-progress work, or already-decided trade-offs. Without spec-anchor in the loop, agents repeatedly re-derive context from scratch.
spec-anchor compiles that knowledge into .specanchor/ ahead of time. This prelude skill makes sure the superpowers process always starts with that compiled context loaded — turning "vibe coding from prompt" into "spec-anchored design".
Anti-patterns
| Anti-pattern | Why it's wrong |
|---|
| "Just brainstorm first, we'll check spec later" | Late-bound spec check produces re-work; superpowers skills make decisions during brainstorm |
| "The project is too small to need spec-anchor" | If anchor.yaml exists, the team has decided to use it — respect that |
Calling specanchor-boot.sh manually without reading the output | Loading bytes ≠ loading context. Read and reason about Active Tasks, Available Modules. |
Skipping when .specanchor/ exists but anchor.yaml doesn't | .specanchor/ alone is a valid spec-anchor configuration (legacy compat) |
Composability
This skill outputs Spec Landscape Loaded: <summary> and then chains into the requested process skill. It is intentionally short (≤200 lines) and side-effect-free except for reading files and one boot script invocation.
Reference
- spec-anchor full agent contract:
references/agents/agent-contract.md (7 steps; this skill executes step 1)
- spec-anchor command quickref:
references/commands-quickref.md
- Why three context categories: spec-anchor
WHY.md §"三类 Context"
- Dogfood validation (2026-05-20 11:05 CST): 在 spec-anchor 自身仓库实测——
boot --format=json snapshot 返回 9 active tasks，其中 1 个 status: in_progress → 触发 STOP 判定正确；fluid schema task 在 text 模式不显示 phase，JSON 模式保留 phase 字段且值为空字符串。
- Status 语义辨析背景：详见
references/concepts/capability-drift.md Capability Drift 概念，以及 references/schemas/sdd-riper-one/template.md §6.3 落地点。
