Spec Workflow

Spec Workflow

Use this skill to turn unclear work into implementable, reviewable specs before code changes.

When To Use

• New feature, new page/flow, cross-module change, integration, architecture/design task, or migration.
• Acceptance criteria, UI/UX behavior, API contracts, permissions, or rollout expectations are unclear.
• The user asks to define, review, confirm, or refine requirements before implementation.

When To Skip

• Small bug fix with clear scope.
• One-file documentation/config update.
• User provided exact implementation details and no behavior is ambiguous.

Before You Start — Refresh design references（每次開工先執行）

在讀取 references/ 下任何 PM spec 或 prototype 之前，先把它們更新到遠端最新，確保對到的是最新設計：

# 逐個把 submodule 更新到遠端最新（一個失敗不連坐其他）
git config -f .gitmodules --get-regexp '^submodule\..*\.path$' | awk '{print $2}' | while read -r m; do
  git submodule update --init --remote "$m" || echo "FAILED: $m"
  git -C "$m" submodule update --init --recursive || echo "FAILED (nested): $m"
done

# 驗收（必跑）：確認上面沒有 FAILED，且每個 submodule 都有 SHA
git submodule status

不要圖快改用 git submodule update --init --recursive --remote references。 --remote 需要知道要追哪個分支，.gitmodules 沒設 branch 時會 fallback 到該 clone 的 origin/HEAD；巢狀 submodule 常常沒有 origin/HEAD，會噴 fatal: Unable to find refs/remotes/origin/HEAD revision in submodule path ...，而 git 遇到這個是直接中止整趟迭代——排在後面的 submodule 靜默沒被更新，你會拿舊 spec 開工。

跑完不要再補一條不帶 --remote 的 git submodule update。 那條的語意是「把每個 submodule reset 回父 repo 記錄的 pin」，會把剛才 --remote 的成果整個倒退回去。巢狀 submodule 已經由上面 git -C "$m" ... 那行補齊了。

驗收怎麼看：git submodule status 的 + 前綴代表 checkout 已超前父 repo 的 pin（--remote 生效）；沒有 + 代表 pin 本來就是最新——兩者都正常。- 前綴才是沒初始化。

註：--remote 會把 submodule checkout 到遠端最新，父 repo 的 pin 會顯示為已變更。這個 pin bump commit 進 feature 分支完全無妨、也不影響開發——references/ 只是背景參考（不被 app 編譯，實作以 distill 進 requirements/ 的內容為準），且 CI 未開 submodules: true。因此就讓 pin 始終浮到最新、bump 自然留在分支即可，不必刻意避免 commit。

Repository Convention Discovery

Before writing specs, inspect the repo source of truth:

• AGENTS.md, docs/spec-driven-development.md, requirements/_index.md, requirements/README.md.
• requirements/requests/_index.md and requirements/tasks/_index.md.
• profiles/README.md, profiles/<framework_profile>/README.md when framework-specific work is involved.
• references/ only for background context; do not implement directly from references.

Required Spec Content

• Meta: ID, status, priority, spec mode, related request/reference links.
• 1) Requirements: background, goal, in scope, out of scope, known context, open questions/decisions, EARS acceptance criteria.
• 2) Design: UI/UX decisions, component structure, data dependencies, API contracts, auth/permission, acceptance test matrix, test plan.
• 3) Implementation Tasks: reviewable tasks mapped to acceptance criteria.
• 4) Execution Log / Change Log: spec creation, decisions, status changes, implementation notes, verification results.

Readiness Gate

Do not implement until all pass:

• Blocking questions are answered.
• Scope and non-goals are explicit.
• UI/UX behavior, form validation, error states, and loading states are defined where relevant.
• API/data/security/operational behavior is defined where relevant.
• Each R# acceptance criterion maps to at least one implementation task and one verification case.
• No conflicting source documents remain unresolved.
• User confirms readiness when the change affects behavior, contracts, data, deployment, or prototype fidelity.

Use status flow draft -> ready -> in-progress -> done. Do not use in_progress, and do not move ready to in-progress without explicit implementation instruction.

Deviation Protocol

If implementation needs to differ from an approved spec:

1. Stop the deviating part of the work.
2. Explain the proposed deviation, reason, impact, and risk.
3. Get explicit confirmation.
4. Update the spec/tasks/verification notes.
5. Resume only after the change is accepted.

Done Gate

• Acceptance criteria are satisfied.
• Verification commands/checks are run or explicitly documented as not runnable.
• Generated/config/deployment artifacts are updated when required.
• No unapproved spec deviations remain.
• requirements/tasks/_index.md and the task spec Meta status are synchronized when task status changes.
• .agents/skills/clean-code or equivalent self-review is applied to changed application code before marking the task done.