Imported from qxbyte/skills (spec-mode/SKILL.md). Install upstream with npx skills add qxbyte/skills --skill spec-mode. Copyright stays with the author.

Spec Mode

File-first specification-driven workflow for CLI agents (Codex, Claude Code). Generated Markdown documents are the source of truth; coding starts only after requirements, design, and tasks are confirmed.

Activation Guard

This skill is opt-in only. Activate only when the user's current message contains one of:

• /spec, /spec-mode, /spec-continue, /spec-status, /spec-end
• /spec -h, /spec-mode -h
• /spec --set-vault, /spec --set-root, /spec --detect-vault, /spec --vault-status
• 使用 spec 模式 / 启用 spec 模式 / 用 spec 模式 / use spec mode

Hard rules:

1. /spec and /spec-mode always activate the spec workflow — even when the requested work is to inspect or modify the spec-mode skill itself.
2. Command compliance: when any spec command is triggered, follow the corresponding workflow exactly. Do not skip phases, phase gates, or confirmation steps for any reason. Commands are absolute; the assistant's judgment cannot override a command.
3. Persistent session exception: if a persistent spec-mode session is active for the current conversation, route follow-up messages through this skill until the user runs /spec-end.

Do not activate for ordinary coding, planning, requirements, design, task lists, bugfixes, implementation, or documentation requests. In those cases, work normally — do not create spec folders.

⛔ Iron Rules — Top of Mind

These rules are checked at every turn of every spec-mode session. Never violate them. Never defer them. If the user pushes back, acknowledge — then comply with the rule first, discuss after.

1. ⛔ Document-first. Any change to requirements / design / tasks discussed in chat MUST be written to the corresponding spec document in the same turn, before further discussion or implementation. Verbal-only changes are invisible to the next session and silently drift from the persisted spec.

2. ⛔ Post-/spec-continue sync — 非常重要. After /spec-continue you are resuming an already-landed spec. Every subsequent adjustment to requirements or design — even a single clarifying sentence from the user — MUST be reflected in requirements.md / bugfix.md / design.md / tasks.md and (for requirements changes) acceptance-checklist.md, in the same turn. Do not wait for "later", do not batch into "next round", do not say "I'll update it after the code". Write now. The user said it → write it. The next session can only see what was persisted; chat is ephemeral.

3. ⛔ acceptance-checklist follow-mode. requirements.md or bugfix.md modified → rewrite acceptance-checklist.md in the same turn, derived from the new SHALL statements. Failure surfaces as spec_lint.py WARNING and ⚠ 落后于 requirements.md on next /spec-continue.

4. ⛔ Write-before-verify-lock. Before any Edit/Write on a spec document, call python3 scripts/spec_session.py verify-lock <spec-dir> --session <id>. Returns evicted → stop work immediately and tell the user the spec was taken over by another session.

5. ⛔ Phase gate compliance. No skipping confirmation steps. No auto-selecting at gates. No "this seems simple, let's skip ahead". Commands are absolute; the assistant's judgment cannot override them.

6. ⛔ Forced writes. Every config / document mutation must be persisted on the spot. When a write fails (IOError / permission / lock_lost), abort the operation — never continue with in-memory unpersisted state.

These rules trigger detectable signals (lint, /spec-continue ⚠ markers, verify-lock exit codes). Treat any of those signals as a regression on your part, not a tool quirk.

Command Entry

/spec <requirement or path> [extras]            ← one-shot workflow
/spec-mode <requirement or path> [extras]
/spec --persist <requirement or path>           ← persistent session (shows footer)
/spec-continue [spec-slug]                       ← resume / switch; multi-window aware
/spec-status                                     ← show current session status
/spec-end                                        ← end persistent session (docs preserved)

/spec --set-vault <vault-path>                   ← set Obsidian vault → vault/spec-in/<os>-<user>/specs
/spec --set-root <dir>                           ← set any directory as spec root
/spec --detect-vault                             ← detect installed Obsidian vaults
/spec --vault-status                             ← show current root + obsolete-location warnings

/spec -h | /spec-mode -h                         ← help (output references/help-output.md verbatim, stop)

--set-vault / --set-root may be run at any time (no need to /spec-end first); the new value is written to ~/.config/spec-mode/config.json immediately and used by all subsequent commands.

If the text after /spec is an existing file path, read it as the requirement source; otherwise treat it as the requirement description.

Sub-flag Dispatch (execute and stop — do NOT trigger spec workflow)

For any of the dispatch flags above (the first five rows), do not run intake, do not create a spec folder, do not enter Plan-mode. Just execute the indicated script and stop.

Optional spec name prefix. If the requirement starts with <名称>：<内容> (full-width ：) or <名称>: <内容> (ASCII : followed by a space), split on the first colon:

• The part before the colon is the spec folder name hint. Agent derives a semantic English slug from the hint and passes spec_init.py --name <slug> --requirement-name "<原名称>". The original hint is preserved as the displayed requirementName in .config.json.
• The part after the colon is the requirement source text.
• Skip the split if the prefix looks like a path (contains / or \), a URL, or no colon appears in the first ~30 chars.
• No colon → whole text is the requirement; agent infers the slug from the requirement content as before.

Pre-requirements Clarification (Plan-mode)

Before generating requirements.md / bugfix.md, evaluate whether the user's requirement is unambiguous enough to translate into EARS SHALL statements without invention.

• Clear enough → proceed to workflow selection and document generation.
• Real ambiguity affecting scope, behavior, UX, data, validation, or acceptance → enter clarification dialogue first. Phase stays in intake. Do not write any spec document yet.

Clarification dialogue protocol:

1. Output the questions using Template B (开放式澄清问答) in references/prompts.md. Each question is labeled 【阻塞】 or 【可延后】. Aim for ≤5 blocking items per round.
2. End the turn. Wait for the user's reply.
3. After the user answers, parse the response and run the 澄清完成 selector (Template A in references/prompts.md):
   • 进入下一阶段 → proceed to workflow selection and document generation. Carry resolved answers into the document; unresolved items go to the 待确认问题 section.
   • 继续澄清 → ask the next round of questions using Template B again.
4. Never invent missing scope, business rules, UI behavior, data fields, or acceptance criteria.

This is the spec-mode equivalent of agent "Plan mode": converge on intent through dialogue before any file is written.

→ 详见 references/prompts.md（所有 prompt 输出模板、统一选择器命令、措辞禁忌）

Document Root Resolution (Iron Law)

Three-tier resolution. No project fallback, no home fallback.

1. --root argument or SPEC_MODE_ROOT env (highest)
2. ~/.config/spec-mode/config.json → obsidianRoot (set via --set-vault/--set-root; written automatically on first Obsidian detection)
3. Auto-detect Obsidian vault → <vault>/spec-in/<os>-<user>/specs (and persist to config)

All three miss → hard stop, output guidance and exit:

未检测到 Obsidian vault，且未配置 spec 根目录。请选择以下方式之一：
  1. 安装 Obsidian 后重试（推荐）
  2. /spec --set-vault <vault路径>
  3. /spec --set-root <自定义目录>

/spec and /spec-continue use the same resolution. Never create <project>/specs or ~/new project/specs.

→ 详见 references/obsidian.md（vault 检测、目录树、多 vault 选择）

Sessions: One-shot vs Persistent

Every /spec creates permanent documents (requirements.md, design.md, tasks.md, acceptance-checklist.md, .config.json). They can always be reopened via /spec-continue.

Persistent-mode footer (exact format, shown only in persistent mode):

─── spec-mode ─── spec: <slug> | session: <sessionId> | phase: <phase> | /spec-end 退出

When in read-only mode (see references/lock-protocol.md), append | [只读] before /spec-end 退出.

sessionId resolution: $TERM_SESSION_ID → $SPEC_SESSION_ID → "default". Each window must use a distinct sessionId for parallel work.

State files:

• <spec-dir>/.config.json — per-spec identity, lifecycle, lock, sessions, iteration round
• <document-root>/.active-spec-mode.json — v2 window index keyed by sessionId (slug-only, no absolute paths)

Multi-Window + Lock (Iron Law)

Different agent windows may work on different specs in parallel. The same spec is held by at most one session at a time via a write lock in its .config.json.

Before any spec document write, perform three checks:

1. specId: active-pointer.specId == .config.json.specId
2. boundary: spec_dir is inside documentRoot (spec_session.ensure_within_root)
3. lock: python3 scripts/spec_session.py verify-lock <spec-dir> --session <id> returns ok

Any failure → refuse the write, surface the error, do not silently continue.

/spec-continue <slug> on a locked spec must offer three options to the user: 强制接管 / 只读查看 / 取消. Never auto-evict without user choice.

Heartbeat: agent must call python3 scripts/spec_session.py heartbeat <spec-dir> before every Edit/Write on a spec document. Stale lock threshold: 30 minutes (SPEC_MODE_LOCK_STALE_SECONDS to override).

→ 详见 references/lock-protocol.md（5 个 lock 子命令、接管协议、只读模式、被驱逐窗口行为）

Phase Gates

Phase order (no skipping confirmations):

1. requirements (or bugfix)
2. Confirm
3. design
4. Confirm
5. tasks
6. Confirm
7. Ask whether to execute tasks
8. Code → validate → accept
9. (post-acceptance) iteration

Confirmation protocol — for every phase boundary, in the same response:

1. Show the document path, summary, key changes, unresolved questions
2. Show confirmation options via scripts/spec_choice.py. In a non-interactive shell (Claude Code Bash, CI) the script prints the option block + AWAITING_USER_CHOICE sentinel on stdout and exits 0 — relay the stdout block to the user verbatim and end the turn. Never re-run the script to "retry" the prompt.
3. End the turn. Never proceed in the same response.

Auto-selecting a default at a phase gate is never acceptable.

→ 详见 references/workflow.md §Phase Gates（完整 9 步、spec_choice.py 调用范本） → 详见 references/iteration.md（iteration 阶段、子循环、文档累积规则）

Document-first Discipline

Spec documents are the sole persistent memory. Any change not written to a document is invisible to the next session. See also Iron Rules #1, #2, #3, #6 at the top of this file.

Iron rules (apply from the moment a persistent session is active, and apply equally — and especially — after /spec-continue):

1. Requirement change → update requirements.md / bugfix.md first, then continue
2. Design decision → update design.md first, then implementation
3. Task status change → update tasks.md immediately when a task starts ([~]), completes ([x]), or is blocked
4. New task or sub-task → append to tasks.md before starting it
5. requirements.md / bugfix.md modified → must rewrite acceptance-checklist.md in the same turn (跟随式生成；不写则下次 /spec-continue 显示 ⚠ 落后于 requirements.md)
6. Write-before-verify: before any Edit/Write on a spec document, call spec_session.py verify-lock. EVICTED → stop work and tell the user.
7. Post-/spec-continue sync (非常重要): after /spec-continue, the spec docs are already landed. Any further requirement/design adjustment from the user (including verbal-only "顺便改一下…") MUST be applied to the landed requirements.md / design.md / tasks.md / acceptance-checklist.md in the same turn it is raised, before any code action. Never leave a chat-only change unwritten between turns — the next session will lose it. If multiple docs are affected by one change, update all of them in the same turn.

These writes are non-negotiable. If the user asks to skip writing and proceed, acknowledge — then write first, proceed second. Writes are forced: if a write fails (IOError/permission), abort the operation; never continue with in-memory unpersisted state.

→ 详见 references/workflow.md §1.1（自然语言路由表）

Workflow Selection

Classify the request before creating documents:

• Feature, behavior-first → Requirements-first (recommended default)
• Feature, architecture-first → Technical Design first
• Bug / regression / failing test → Bugfix

Use scripts/spec_choice.py when the workflow matters and is unclear. In non-interactive shells the script outputs the option block + AWAITING_USER_CHOICE sentinel and exits 0 — relay stdout to the user and end the turn. Never silently choose for the user.

Output Language

All user-facing output (summaries, questions, confirmations, status, errors) — Chinese.

Exceptions (English / original form):

• Technical terms, command names, file paths, code identifiers
• Content inside code blocks
• Skill's own rule files (SKILL.md, references/)

If the user's requirement is in English, generated spec documents may use English; other agent output (summaries, confirmations) stays Chinese.

Helper Scripts

• scripts/spec_init.py — create spec directory; requires --name <slug> (agent generates the semantic slug)
• scripts/spec_session.py — start / continue / status / end / list / list-specs / load / acquire / release / heartbeat / verify-lock / iterate
• scripts/spec_vault.py — detect / set --vault / set --root / get
• scripts/spec_lint.py — validate spec files (now also lock-field + checklist-staleness checks)
• scripts/spec_status.py — task-progress view (thin wrapper over spec_session.py load --json)
• scripts/spec_choice.py — selector. TTY → curses ↑/↓ + Enter. Non-TTY (Claude Code Bash, CI) → prints option block + AWAITING_USER_CHOICE sentinel on stdout, exits 0; agent relays to user and ends turn.

Help Output

When /spec -h / /spec-mode -h is triggered, output exactly references/help-output.md and stop.

References

• references/workflow.md — full phase protocol, interactive selector commands, /spec-continue context loading, EARS examples
• references/prompts.md — unified prompt templates (selector usage, clarification format, list view, forbidden phrasings)
• references/iteration.md — iteration phase, sub-loop, document accumulation rules
• references/lock-protocol.md — lock mechanism, takeover, read-only mode, eviction
• references/obsidian.md — vault detection, directory tree, config.json lifecycle
• references/templates.md — document templates and style conventions
• references/help-output.md — verbatim help text