# Spec Workflow

> Use when medium-to-large work needs requirements, design, task planning, readiness checks, and implementation governance before coding. Language-neutral.

- Skill: `asgard-ai-platform/spec-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add asgard-ai-platform/spec-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asgard-ai-platform/spec-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: asgard-ai-platform (https://skillmd.com/u/asgard-ai-platform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/asgard-ai-platform/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 之前，先把它們更新到遠端最新，確保對到的是最新設計：

```bash
git submodule update --init --recursive --remote references
```

註：`--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.