artifact-validator

<purpose> Validate feature artifacts (spec.md, plan.md, tasks.md) for quality and consistency. Check API contracts and type definitions for breaking changes. Generate actionable reports with pass/fail gates. </purpose> <triggers> - User requests "validate", "check quality", "verify consistency" - Transitioning from specification to planning - Transitioning from planning to implementation - Before archiving a completed feature - `/orbit` offers validation option </triggers> <workflow> <step name="load"> Read all artifacts from `.spec/features/{feature}/`: - spec.md (user stories, acceptance criteria, frontmatter) - plan.md (technical design) - tasks.md (implementation tasks) - metrics.md (current status)

Also check architecture docs if they exist:

• .spec/architecture/product-requirements.md
• .spec/architecture/technical-design.md </step>

<step name="validate-spec"> Check specification quality:

Completeness:

• Has frontmatter with id, title, status, priority
• Has user stories with acceptance criteria
• Priority assigned (P1/P2/P3)
• No unresolved [CLARIFY] tags

Clarity:

• Acceptance criteria are testable
• No ambiguous language ("should", "might", "could")
• Technical constraints specified

Measurability:

• Success metrics defined
• Performance requirements if applicable </step>

<step name="validate-plan"> Check plan quality (if exists):

Coverage:

• Every user story referenced
• Architecture decisions documented
• Components identified with purposes

Feasibility:

• No impossible requirements
• Dependencies identified
• Risks acknowledged with mitigations </step>

<step name="validate-tasks"> Check task quality (if exists):

Structure:

• Tasks have IDs (T001, T002...)
• Dependencies specified [depends:X]
• Critical changes flagged [critical:type]
• Parallel groups defined

Consistency:

• Every plan component has tasks
• Dependencies are valid (no cycles)
• All critical patterns identified </step>

<step name="validate-consistency"> Check alignment between artifacts:

Spec → Plan:

• Every US has implementation approach
• Acceptance criteria map to components
• No plan items without spec backing (scope creep)

Plan → Tasks:

• Every component has tasks
• Task dependencies match plan phases
• Critical patterns from plan are tagged </step>

<step name="check-contracts"> If API/contract changes in plan or tasks:

1. Read existing contracts (openapi.yml, types.ts)
2. Compare to planned changes
3. Identify breaking changes:
   • Removed endpoints
   • Changed response types
   • New required fields
4. Flag for review </step>

<step name="report"> Update metrics.md with validation results. Output summary to conversation. </step> </workflow> <breaking-change-detection> ## Contract Validation

Check for breaking changes when tasks involve:

• openapi.yml / swagger.yml
• types.ts / interfaces.ts
• schema.prisma / database migrations
• *.proto (Protocol Buffers)
• *.graphql

Breaking change types:

Change	Type	Severity
Removed field	BREAKING	HIGH
Changed type	BREAKING	HIGH
New required field	BREAKING	HIGH
Removed endpoint	BREAKING	HIGH
Changed response	BREAKING	MEDIUM
New optional field	SAFE	LOW
New endpoint	SAFE	LOW

Report format:

⚠️ BREAKING CHANGES DETECTED

| Location | Change | Impact |
|----------|--------|--------|
| `User.email` | type: string → number | 12 files affected |
| `GET /users` | removed | 3 consumers |

Recommendation: Review and approve before implementation.

</breaking-change-detection>

<output_template>

Validation Report

Feature: {name} Phase: {current phase} Gate: {PASS | FAIL | WARNING}

Frontmatter

Field	Status
id	✓
status	✓
progress	✓

Specification Quality

Check	Status
User stories	✓
Acceptance criteria	✓
No [CLARIFY] tags	✗ (3 remain)
Testable criteria	✓

Plan Coverage

Check	Status
US → Plan	100%
Components defined	✓
Risks documented	✓

Task Consistency

Check	Status
Plan → Tasks	80%
Dependencies valid	✓
Critical tagged	✓
Parallel groups	✓

Contract Changes

Type	Count	Severity
Breaking	0	-
Safe	3	LOW

Issues

1. [HIGH] US1.2 has no implementation in plan
2. [MEDIUM] T003 missing dependency on T001
3. [LOW] Consider adding estimate to T005

Recommendation

{PROCEED | FIX_REQUIRED | MAJOR_REVISION}

Next Steps:

• {specific action to resolve issues} </output_template>

<quality_gate> PASS requires:

• Frontmatter complete and valid
• All user stories have acceptance criteria
• No unresolved [CLARIFY] tags
• 100% spec → plan coverage
• No HIGH severity issues
• No unacknowledged breaking changes

WARNING if:

• Coverage 90-99%
• MEDIUM severity issues present
• Breaking changes acknowledged

FAIL if any:

• Missing frontmatter fields
• Missing acceptance criteria
• Unresolved clarifications
• Coverage < 90%
• Any HIGH severity issue
• Unacknowledged breaking changes </quality_gate>