ai-sdlc-sdd: Spec Driven Development

Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. Before producing the final artifact, confirm required inputs, target audience, missing facts, output format, and constraints when they are unclear. Do not invent missing information. Ask concise clarification questions when required inputs are absent.

0. Skill Card

Skill name:
```
ai-sdlc-sdd
```
Primary audience: Dev
Supporting audience: BA, QA, PM
Audience tags: Dev, BA, QA, PM
SDLC stage: Repository SDD workflow
Purpose: Create, update, validate, and enforce the AI SDLC SDD package for medium and large changes before implementation expands.
Output: SDD package, Markdown execution plan, TOON machine plan, validation status, task alignment, and implementation handoff

0.1 Required Inputs

Medium or large change request.
Affected systems, APIs, packages, or artifacts.
Existing spec folder or proposed feature name if available.

0.2 Clarification Rules

Ask concise questions before finalizing when role, artifact, requirements, scope, audience, or constraints are unclear.
If optional information is missing, mark it as
```
TBD
```
,
```
Not provided
```
, or
```
Assumption
```
instead of inventing it.
Separate confirmed facts from assumptions and open questions.
Do not proceed to downstream synthesis when a required upstream artifact or decision is missing.

0.2.1 Flow Mode Flags

Support two explicit execution flags:
```
--quick-flow
```
and
```
--full-flow
```
.
If both flags are supplied,
```
--full-flow
```
takes precedence because it is the stricter mode.
```
--quick-flow
```
: move fast, make high-quality progress with available context, avoid clarification questions unless continuing would create material product, security, compliance, data-loss, or irreversible implementation risk.
In
```
--quick-flow
```
, use documented assumptions, recommended defaults, existing repository patterns, and the nearest available artifact evidence; record important assumptions and decisions in
```
decision-log.md
```
.
In
```
--quick-flow
```
, run only focused checks that are directly relevant, cheap, and likely to catch regressions for the requested work; report any skipped broader checks as residual risk.
```
--full-flow
```
: ask concise clarification questions when inputs, scope, ownership, acceptance criteria, or decisions are unclear; do not silently assume material requirements.
In
```
--full-flow
```
, verify upstream and downstream artifacts, decision-log entries, traceability links, acceptance criteria, and validation evidence before finalizing.
In
```
--full-flow
```
, SDD must consume upstream refinement context from
```
specs-refiniment/<feature-name>/
```
; missing or incomplete delivery-spec or QA-readiness context blocks implementation SDD handoff.
In
```
--full-flow
```
, run or recommend the skill-appropriate gates, reviews, scripts, and validation commands needed for end-to-end confidence; document any blocked verification explicitly.
When neither flag is supplied, follow the skill default rules and choose the least risky behavior for the request size and domain.

0.3 Output Rules

Keep output structured with headings and bullets.
Make findings, gaps, risks, and blockers explicit.
Tie recommendations to evidence from the provided artifact, repository,
```
specs-refiniment/<feature-name>/<file.md>
```
workspace, or user context.
Include role ownership when the output creates follow-up work for BA, QA, Dev, PM, or Delivery.
Return progress, completion, validation, and handoff summaries directly in the Codex response.

Before the final response, emit the

ai-sdlc-handoff/v1

contract with

result

blockers

next_required

, and

next_optional

; every action includes

reason

command

, and

expected_artifact

Do not create
```
summary.txt
```
,
```
*-summary.txt
```
, or another standalone summary file unless the user explicitly requests one.
Keep durable writes limited to the canonical lifecycle artifacts, decision log, human-readable index, and
```
_ai_sdlc
```
machine files.
Let shared helpers migrate legacy paths on the next write; never overwrite or manually merge divergent legacy and canonical files.

0.4 Artifact Routing

Maintain a feature decision log whenever this skill records, resolves, changes, or depends on a product, delivery, QA, security, validation, branching, implementation, or rollout decision.
For PM, BA, QA, Delivery, discovery, planning, refinement, and readiness work, write decisions to
```
specs-refiniment/<feature-name>/decision-log.md
```
.
For developer implementation SDD work, write decisions to
```
specs/<feature-name>/decision-log.md
```
.
Each decision-log entry must include date, decision, context or evidence, options considered when relevant, owner, status, and links to affected artifacts, tasks, tests, or validation evidence.

Use this exact decision-log structure:

markdown

# Decision Log

| ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

Use
```
specs/
```
only for developer implementation SDD packages and repo-governance artifacts.
Do not place PM, BA, QA, Delivery, discovery, planning, refinement, or readiness outputs in
```
specs/
```
; those belong at
```
specs-refiniment/<feature-name>/<file.md>
```
.
When consuming
```
specs-refiniment/<feature-name>/<file.md>
```
, treat it as upstream refinement context and create or update
```
specs/
```
only when implementation work is explicitly in scope.

0.5 Feature State Machine

Maintain feature lifecycle state in TOON at

specs-refiniment/<feature-name>/_ai_sdlc/state.toon

for refinement work and

specs/<feature-name>/_ai_sdlc/state.toon

for implementation work.

Before executing this skill for a feature, check the state machine with

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

When this skill starts durable work, mark it in progress with
```
begin
```
; when the skill's required artifact or review is complete, mark it done with
```
complete
```
and include
```
--artifacts <path>
```
plus
```
--decision-ref DEC-###
```
when a decision was involved.
In
```
--full-flow
```
, do not proceed when predecessor stages are incomplete, another lifecycle skill is active, or the state file reports a blocker.
In
```
--quick-flow
```
, a predecessor skip is allowed only when continuing is low risk and the command includes
```
--assumption "..."
```
or
```
--decision-ref DEC-###
```
; record the same assumption or decision in
```
decision-log.md
```
.

Use

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

to emit compact LLM-readable state before choosing the next skill.

The state machine is feature-scoped: do not reuse a
```
state.toon
```
across unrelated feature folders.

0.6 Artifact Metadata And Metatags

Every Markdown artifact generated or updated by this skill must start with an
```
artifact_metadata
```
YAML frontmatter block before the first visible heading.

Use schema

ai-sdlc-artifact-metadata/v1

and keep these fields current:

feature

artifact

path

workspace

skill

flow_mode

state_file

decision_log

status

owner

created_at

updated_at

trace_ids

related_artifacts

validation

, and

metatags

```
metatags
```
must include at minimum
```
ai-sdlc
```
, the workspace (
```
refinement
```
or
```
implementation
```
), this skill name, the artifact type or filename stem, and a lifecycle/status tag such as
```
draft
```
,
```
review
```
,
```
approved
```
, or
```
validated
```
.
When
```
--quick-flow
```
is active, set
```
flow_mode: quick
```
, keep assumptions visible in the body, and add tags for major defaults or unresolved risk only when they help retrieval.
When
```
--full-flow
```
is active, set
```
flow_mode: full
```
, keep blockers and validation evidence reflected in
```
status
```
,
```
validation
```
,
```
trace_ids
```
, and
```
related_artifacts
```
.
Update metadata whenever the artifact path, status, owner, trace links, validation evidence, related artifacts, or decision references change.
Metadata is an index for routing, retrieval, and traceability; it does not replace the artifact body,
```
decision-log.md
```
, or
```
state.toon
```
.

0.7 Specs Index

Before searching across feature folders, inspect the compact LLM index first:
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
for refinement work or
```
specs/_ai_sdlc/specs-index.toon
```
for implementation work.
Use the human-readable index at
```
specs-refiniment/specs-index.md
```
or
```
specs/specs-index.md
```
when reporting feature coverage, artifact inventory, or handoff status to people.

After this skill creates or materially updates an artifact, refresh the matching workspace index with

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

In
```
--quick-flow
```
, rely on
```
specs-index.toon
```
to choose the smallest relevant artifact set before opening files.
In
```
--full-flow
```
, verify the updated artifact appears in both
```
specs-index.toon
```
and
```
specs-index.md
```
before final handoff.
The specs index summarizes artifact metadata and state; it does not replace reading the selected source artifacts when details, approvals, or validation evidence matter.

References

Use
```
scripts/analyze_spec.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/check_checklist.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/check_clarify.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/resolve_active_spec.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/sdd_status.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/sdd_context.py
```
before broad SDD reads; inspect its exact AC/TC/task/decision anchors and follow only the reported
```
next_reads
```
ranges.
Use
```
scripts/spec_helpers.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/validate_spec.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/plan_links.py
```
to emit, write, or validate the required
```
_ai_sdlc/plan.toon
```
machine plan plus
```
plan.md
```
execution plan and cross-artifact trace map.

Use

scripts/sdd_artifact_scaffold.py

to write

requirements.md

design.md

test-cases.md

qa.md

, and

tasks.md

one stdin section at a time.

Use
```
scripts/check_refinement_context.py
```
in
```
--full-flow
```
before SDD handoff to ensure upstream refinement delivery and QA readiness are complete.

Script Usage

Use SDD scripts as ordered gates for implementation work; pass the same flow flag supplied to the skill.

Resolve active spec when the target is unclear:

python3 skills/ai-sdlc-sdd/scripts/resolve_active_spec.py --quick-flow --files <changed-file>...

python3 skills/ai-sdlc-sdd/scripts/resolve_active_spec.py --full-flow <spec-or-folder>

Check workflow state for people with

python3 skills/ai-sdlc-sdd/scripts/sdd_status.py --spec specs/<feature-name> --quick-flow

; agents add

--format toon

, and full-flow remains required before handoff.

Build bounded implementation context:

python3 skills/ai-sdlc-sdd/scripts/sdd_context.py specs/<feature-name> --quick-flow

; use

--cache-context

only when cross-session reuse is useful.

Write one artifact section:

python3 skills/ai-sdlc-sdd/scripts/sdd_artifact_scaffold.py specs/<feature-name> --artifact <requirements|design|test-cases|qa|tasks> --section "<section>" --quick-flow

; provide only the section body on stdin.

Repeat section writes and then replace
```
--section ...
```
with
```
--finalize
```
; the AI must not create a temporary content file or directly edit the generated Markdown artifact.
Add a decision with
```
--decision-row
```
and one nine-cell Markdown table row on stdin;
```
--artifact
```
is not required for this action.

Validate structure:

python3 skills/ai-sdlc-sdd/scripts/validate_spec.py specs/<feature-name> --quick-flow

Create or refresh the execution plan pair:

python3 skills/ai-sdlc-sdd/scripts/plan_links.py specs/<feature-name> --write --quick-flow|--full-flow

Emit compact machine plan only:

python3 skills/ai-sdlc-sdd/scripts/plan_links.py specs/<feature-name> --emit-toon --quick-flow|--full-flow

Validate the execution plan links:

python3 skills/ai-sdlc-sdd/scripts/plan_links.py specs/<feature-name> --check --quick-flow|--full-flow

Full-flow upstream gate:

python3 skills/ai-sdlc-sdd/scripts/check_refinement_context.py specs/<feature-name> --full-flow

Full-flow pre-implementation gates, in order:

check_refinement_context.py

check_clarify.py

check_checklist.py

plan_links.py --check

analyze_spec.py

, then

validate_spec.py

, each with

specs/<feature-name> --full-flow

Use quick flow for fast structural confidence; use full flow before expanding implementation tasks, handoff, review, or commit prep.

Purpose

Create, update, validate, and enforce the AI SDLC SDD package for medium and large changes before implementation expands.

Inputs

Read
```
AGENTS.md
```
for change classification and repository workflow rules.
Collect the user request, affected systems, and likely spec name.
Search existing
```
specs/
```
folders for a matching active or historical spec.
Use
```
$ai-sdlc-ba
```
,
```
$ai-sdlc-test-cases
```
, and
```
$ai-sdlc-qa
```
when those phases are incomplete.

--full-flow

, read

specs-refiniment/_ai_sdlc/specs-index.toon

, upstream

state.toon

delivery-spec.md

qa-readiness.md

, and

decision-log.md

before finalizing implementation SDD.

Read existing code only after the spec intent and affected surface are clear enough to avoid scope drift.

Steps

Classify the change as small, medium, or large using
```
AGENTS.md
```
.
Use the small-change path only for typo fixes, tiny bug fixes, test-only fixes, log text changes, or other no-contract changes.
For medium or large work, find a matching
```
specs/NNN-short-name/
```
folder or create the next numbered folder.
Treat the full folder name as the canonical delivery ID; do not rely on the numeric prefix alone.
Add or update
```
specs/spec-registry.md
```
for tracked governance or delivery-critical work.

Ensure these files exist before implementation:

```
requirements.md
```
```
design.md
```
```
test-cases.md
```
```
qa.md
```
```
tasks.md
```
```
_ai_sdlc/plan.toon
```
```
plan.md
```

Write requirements before design; write design before implementation tasks.

Run the clarify gate after requirements are current:

bash

python3 skills/ai-sdlc-sdd/scripts/check_clarify.py specs/NNN-feature-name

Record implementation traceability, source artifact links, or documented no-ticket exceptions in
```
requirements.md
```
.
Derive test cases before writing tests.
Derive QA acceptance and regression scope before final validation.
Write task entries with explicit
```
Output:
```
and
```
Refs:
```
metadata for new or updated active specs.
Write
```
_ai_sdlc/plan.toon
```
as the required compact machine plan linking SDD artifacts, AC IDs, TC IDs, task IDs, dependencies, decisions, task status, and validation order.
Write
```
plan.md
```
as the required human-readable execution plan and cross-artifact trace map generated from the same links; when
```
_ai_sdlc/plan.toon
```
marks a task
```
done
```
,
```
closed
```
,
```
complete
```
,
```
completed
```
, or
```
validated
```
, mark that task closed in
```
plan.md
```
.
Run the checklist gate before implementation tasks expand:

bash

python3 skills/ai-sdlc-sdd/scripts/check_checklist.py specs/NNN-feature-name

Implement only tasks described in
```
tasks.md
```
and sequenced in
```
_ai_sdlc/plan.toon
```
/
```
plan.md
```
.
Mark task status complete in
```
_ai_sdlc/plan.toon
```
and task checkboxes complete only after code, docs, or validation actually satisfy the task; then refresh
```
plan.md
```
.
Run the analyze gate before implementation handoff or commit prep:

bash

python3 skills/ai-sdlc-sdd/scripts/analyze_spec.py specs/NNN-feature-name

Validate the active spec:

bash

python3 skills/ai-sdlc-sdd/scripts/validate_spec.py specs/NNN-feature-name

Use workflow-state status when the next phase is unclear:

bash

python3 skills/ai-sdlc-sdd/scripts/sdd_status.py --spec specs/NNN-feature-name

Report compliance, completed tasks, validation, and open risks.

Output Spec

Use this completion report:

text

SDD compliance:
- Spec: specs/NNN-feature-name
- Change size: small | medium | large
- Requirements: updated | unchanged with reason
- Design: updated | unchanged with reason
- Test cases: updated | unchanged with reason
- QA: updated | unchanged with reason
- Tasks: completed task numbers and remaining task numbers
- Plan: `_ai_sdlc/plan.toon` and `plan.md` updated | unchanged with reason
- Validation: command -> outcome
- Scope control: no drift | drift and spec update
- Residual risk: none | concrete issue

Quality gate:

Pass when the SDD package exists, required sections are populated,
```
_ai_sdlc/plan.toon
```
links AC/TC/TASK/DEC status and dependencies,
```
plan.md
```
reflects those links for humans, tasks match implementation, and the validator passes.
Fail when code starts before missing spec artifacts are created, when implementation exceeds
```
tasks.md
```
, when the clarify/checklist/analyze gates fail, or when task checkboxes are marked complete without evidence.

Examples

Spec folder shape:

text

specs/177-skill-instruction-upgrade/
  requirements.md
  design.md
  test-cases.md
  qa.md
  tasks.md
  _ai_sdlc/plan.toon
  plan.md

Completion report sample:

text

SDD compliance:
- Spec: specs/177-skill-instruction-upgrade
- Change size: medium
- Requirements: updated
- Design: updated
- Test cases: updated
- QA: updated
- Tasks: 1-10 completed
- Plan: _ai_sdlc/plan.toon and plan.md updated
- Validation: python3 skills/ai-sdlc-sdd/scripts/validate_spec.py specs/177-skill-instruction-upgrade -> passed
- Scope control: no drift
- Residual risk: none

Invalid counter-example:

text

Implemented feature; will write spec later.

Reject this for medium and large work because the spec is the source of truth.

Edge Cases

Reuse an existing active spec when its requirements clearly match the user request.
Create a new spec when an existing completed or archived spec is only historically related.
Add
```
TODO(dm): exact question
```
when a required decision cannot be discovered and guessing would affect scope, contract, security, or rollout.

Use

Assumptions

Open Questions

, and

Decision Status

sections in

requirements.md

for clarify-gate evidence.

Update the spec first when code and spec conflict during an active change.
Treat unlisted historical numbered specs as
```
unclassified
```
until
```
specs/spec-registry.md
```
says otherwise.
Do not treat scaffolded historical
```
qa.md
```
or
```
test-cases.md
```
files with unresolved TODOs as validated evidence.
Treat missing
```
_ai_sdlc/plan.toon
```
or
```
plan.md
```
as a structural SDD failure, even in quick flow.

When

_ai_sdlc/plan.toon

and

plan.md

disagree, trust

_ai_sdlc/plan.toon

for machine task status and regenerate

plan.md

with

plan_links.py --write

In full flow, treat missing upstream refinement delivery or QA readiness as a blocker unless the predecessor is explicitly skipped with a decision reference.

Scope Boundary

Do not replace BA, test-case, QA, review, security, validation, or commit-prep skills; route to them when their phase is needed.
Do not implement major features without requirements, design, test cases, QA, tasks, and plan.
Do not run broad validation by default; use
```
$ai-sdlc-validation
```
for command selection.

ai-sdlc-sdd

NPX Install

Tags

SKILL.md Content

ai-sdlc-sdd: Spec Driven Development

0. Skill Card

0.1 Required Inputs

0.2 Clarification Rules

0.2.1 Flow Mode Flags

0.3 Output Rules

0.4 Artifact Routing

0.5 Feature State Machine

0.6 Artifact Metadata And Metatags

0.7 Specs Index

References

Script Usage

Purpose

Inputs

Steps

Output Spec

Examples

Edge Cases

Scope Boundary