SPEC Foundation Skill - Expert v4.0

Skill Overview

SPEC (Specification) is the formal requirements document that drives SPEC-first, TDD development. This Skill provides comprehensive guidance on SPEC lifecycle management, version control, approval workflows, traceability, and integration with MoAI-ADK development pipeline.

Quick Facts

• 4 SPEC Lifecycle States: Draft, Active, Deprecated, Archived
• Version Management: Semantic versioning (major.minor.patch)
• Approval Workflow: Author → Review → Approval → Deployment
• Integration: Core of /alfred:1-plan workflow in MoAI-ADK

When to Use This Skill

• Creating formal specifications before development
• Managing specification versions and evolution
• Setting up approval workflows for requirements
• Tracing requirements through code and tests
• Organizing multiple specifications in complex projects

---

Level 1: Foundation - SPEC Lifecycle

1. Draft State - Specification Creation

Purpose: Initial specification authoring and refinement

Activities:

1. Specification Author creates SPEC-XXX/spec.md
2. Define requirements using EARS patterns
3. Gather stakeholder input
4. Refine until ready for review
5. Create acceptance criteria
6. Document known risks and constraints

Typical Duration: 2-5 days (simple features) to 2-4 weeks (complex systems)

Key Artifacts:

• spec.md - Main specification document
• acceptance-criteria.md - Acceptance tests (if separate)
• technical-notes.md - Implementation guidance (optional)

Deliverables for Review:

• ✅ Clear problem statement
• ✅ EARS-format requirements (functional & non-functional)
• ✅ Acceptance criteria for all requirements
• ✅ Architecture/design notes
• ✅ Risk assessment
• ✅ Dependencies identified

Example Draft Structure:

# SPEC-045: User Authentication System

## Problem Statement
Current system lacks multi-factor authentication. Need MFA for security compliance.

## Requirements
REQ-001 (Event-Driven): When login_attempted the system eventually satisfies 
        mfa_challenge_presented
REQ-002 (Ubiquitous): The system shall always satisfy mfa_enabled_for_admin = true
REQ-003 (Optional): When mfa_timeout_exceeded the system immediately satisfies 
        session_terminated

## Acceptance Criteria
- [ ] MFA works with authenticator apps (Google, Microsoft)
- [ ] Fallback SMS when app unavailable
- [ ] Session timeout after 10 minutes inactivity
- [ ] Audit log all MFA events

## Technical Notes
- Use TOTP (RFC 6238) for time-based codes
- Backup codes for emergency access
- Consider integration with existing identity system

## Risks
- User adoption of MFA might be low
- SMS delivery reliability (use backup)

Draft Anti-Patterns - Avoid:

• ❌ Vague requirements ("system shall be secure")
• ❌ Mixing implementation details with requirements
• ❌ Incomplete acceptance criteria
• ❌ No identified risks or constraints
• ❌ Unsourceable or unmeasurable requirements

---

2. Review State - Formal Evaluation

Purpose: Peer review and stakeholder feedback

Review Participants:

• Author: Specification creator
• Technical Lead: Architecture and feasibility review
• QA Lead: Test coverage and acceptance criteria review
• Product Owner: Business requirement alignment
• Domain Experts: Subject matter expert review (if applicable)

Review Checklist:

[ ] Requirements are clear and unambiguous
[ ] All requirements are EARS-format
[ ] Acceptance criteria are measurable
[ ] No conflicting requirements
[ ] Architecture feasible
[ ] Risk assessment complete
[ ] Traceability clear
[ ] No external dependencies missing
[ ] Timeline realistic
[ ] Budget/resources adequate

Review Process:

1. Initial Submission: Author marks SPEC ready for review
2. Reviewer Comments: Team adds comments/questions
3. Author Responses: Author clarifies or updates spec
4. Revisions: 2-3 rounds typical for complex specs
5. Consensus: Team agrees specification is complete
6. Approval Gate: Technical lead + Product owner sign-off

Review Duration: 3-7 business days (parallel review)

Version Bumping Rules:

• Each revision during review: increment patch (0.1.0 → 0.1.1)
• Major revisions (scope change): increment minor (0.1.0 → 0.2.0)

---

3. Active State - Implementation Period

Purpose: Specification is approved and development proceeds

Activation Steps:

1. Technical lead approves and signs SPEC
2. Create feature branch: feature/SPEC-XXX
3. Implement per SPEC requirements
4. Tests validate against acceptance criteria

During Active Phase:

• ✅ Spec is reference for development
• ✅ Any change discussion references spec
• ✅ Code reviews verify against spec
• ✅ Tests trace to spec requirements
• ✅ Track deviations and change requests

Change Management:

If requirement change needed during development:
1. Assess impact on timeline/scope
2. Document change request
3. Get approval from technical lead + product owner
4. Update SPEC with new version
5. Notify implementation team
6. Update code and tests accordingly

Typical Duration: Development time + testing (1-8 weeks)

Version Bumping:

• Minor feature additions: increment minor (1.0.0 → 1.1.0)
• Bug fixes to spec: increment patch (1.0.0 → 1.0.1)
• Scope changes: increment major (1.0.0 → 2.0.0)

Completion Criteria:

• ✅ All requirements implemented
• ✅ All acceptance criteria passed
• ✅ Code review approved
• ✅ Tests passing (≥85% coverage)
• ✅ Documentation updated
• ✅ Ready for deployment

---

4. Deprecated State - Phase-Out Period

Purpose: Feature is being replaced or removed

Triggering Events:

• New feature replaces old functionality
• System architecture change
• Technology upgrade required
• Business decision to sunset feature

Deprecation Process:

1. Mark SPEC as DEPRECATED in metadata
2. Create successor SPEC (if applicable)
3. Document migration path for users
4. Set end-of-life date (typically 6-12 months)
5. Notify stakeholders of timeline

During Deprecation:

• ✅ Maintain feature (bug fixes)
• ✅ No new feature development
• ✅ Gradual user migration
• ✅ Support successor feature
• ✅ Plan removal

Deprecation Notice Format:

# SPEC-042: Old Authentication (DEPRECATED)

**Status**: DEPRECATED
**Successor**: SPEC-045 (New MFA Authentication)
**Migration Guide**: See migration-guide.md
**EOL Date**: 2025-12-31 (6 months from deprecation)

## Migration Timeline
- 2025-07: New system available, parallel operation
- 2025-09: Default switch to new system
- 2025-12: Old system shutdown

## Support
- Questions: Ask in #migration channel
- Migration assistance: [email protected]

Version Marking:

• Mark SPEC with version tag: v1.5.0 (DEPRECATED)
• Update status in all references
• Create deprecation notice in documentation

---

5. Archived State - Historical Reference

Purpose: SPEC is no longer active, kept for historical record

Archival Process:

1. Feature removed from production
2. Mark SPEC as ARCHIVED
3. Move to archive directory: .moai/specs/archived/
4. Maintain for audit/compliance purposes
5. Tag with final version and EOL date

Archive Retention:

• Keep indefinitely for compliance requirements
• Compress old versions
• Index for historical search

Archive Access:

• Readable by all (reference)
• No modifications allowed
• Available for audit trails

---

Level 2: Advanced - Version Management

Semantic Versioning Strategy

Format: major.minor.patch

Versioning Rules:

Starting with: 1.0.0

PATCH (1.0.X):
  - Bug fixes to requirements
  - Minor clarifications
  - No scope change
  Example: 1.0.0 → 1.0.1

MINOR (1.X.0):
  - New acceptance criteria
  - Refinement during review
  - Feature additions
  Example: 1.0.0 → 1.1.0

MAJOR (X.0.0):
  - Scope changes
  - Architecture redesign
  - Incompatible changes
  Example: 1.0.0 → 2.0.0

Pre-release versions:
  - 1.0.0-rc1 (release candidate)
  - 1.0.0-beta (beta testing)
  - 0.1.0 (draft versions before 1.0.0)

Version Metadata:

# In SPEC frontmatter
version: 1.2.3
status: stable
created: 2025-11-01
updated: 2025-11-12
approved_by: tech-lead-name
approval_date: 2025-11-05
deprecated: false
eol_date: null  # null if active, 2025-12-31 if deprecated

Change Tracking

Every update logs:

1. Who: Author/editor name
2. What: Change description
3. When: Date and time
4. Why: Rationale for change
5. Version: New version number

Change Log Format:

# Version History

## v1.2.3 (2025-11-12) - Clarifications
- Clarified requirement REQ-002 acceptance criteria
- Added risk assessment for database migration
- Updated timeline from 4 weeks to 6 weeks
- Author: john-smith | Tech Lead: sarah-jones

## v1.2.2 (2025-11-10) - Bug Fix
- Fixed requirement numbering consistency
- Author: john-smith

## v1.2.1 (2025-11-08) - Review Updates
- Addressed QA concerns about test coverage
- Added backup procedures to recovery plan
- Author: john-smith | Reviewer: qa-lead

---

Level 3: Practical Application

Complete SPEC Examples

Example 1: Simple Feature SPEC (SPEC-050)

---
name: User Profile Enhancement
spec_id: SPEC-050
version: 1.0.0
status: stable
created: 2025-11-01
approved_date: 2025-11-08
approved_by: tech-lead
---

# SPEC-050: User Profile Enhancement

## Problem Statement
Users cannot upload profile pictures. Current profile view shows placeholder only.

## Functional Requirements

REQ-001 (Event-Driven):
  When user_uploads_profile_image the system eventually satisfies 
  image_stored_in_profile_and_cache_updated
  Acceptance: Image appears immediately after upload
  
REQ-002 (Ubiquitous):
  The system shall always satisfy profile_image_size <= 5MB
  Acceptance: Upload fails with error if exceeds 5MB

REQ-003 (Unwanted):
  The system shall never satisfy (invalid_image_format AND stored)
  Acceptance: Only PNG, JPEG, WebP accepted

## Non-Functional Requirements

- Performance: Image upload completes within 3 seconds
- Security: Images scanned for malware
- Compliance: GDPR-compliant data storage

## Acceptance Criteria
- [ ] Upload works for PNG, JPEG, WebP
- [ ] File size limited to 5MB
- [ ] Image appears in profile immediately
- [ ] Old images automatically deleted
- [ ] Performance < 3 seconds on 4G
- [ ] Mobile and desktop tested

## Testing Strategy
- Unit tests: Image validation, storage
- Integration tests: Upload workflow
- E2E tests: User upload → profile view
- Manual: Test on various devices

## Technical Notes
- Use S3 for image storage
- CloudFront CDN for distribution
- ImgProxy for optimization

## Risks
- Malware in images (mitigate with scanning)
- Storage costs (monitor usage)
- CDN cache invalidation (use versioning)

## Dependencies
- S3 bucket provisioning
- ImgProxy service deployment
- Malware scanning service

## Timeline
- Development: 2 weeks
- Testing: 1 week
- Deployment: 1 day

Example 2: Complex System SPEC (SPEC-051)

---
name: Payment Processing Refactor
spec_id: SPEC-051
version: 2.1.0
status: stable
created: 2025-10-15
approved_date: 2025-11-01
approved_by: tech-lead, product-owner
---

# SPEC-051: Payment Processing Refactor

## Problem Statement
Current payment system doesn't support multiple payment providers. Need flexibility 
to add Stripe, PayPal, Square without major refactoring.

## Architecture

### System Components

Payment Service (core abstraction) ├── Stripe Provider (implementation) ├── PayPal Provider (implementation) └── Square Provider (future)

## Functional Requirements

REQ-001-005: [5 event-driven payment flow requirements]
REQ-006-010: [5 ubiquitous invariants for payment safety]
REQ-011-015: [5 state-driven mode requirements]

## Non-Functional Requirements

- Throughput: ≥ 1000 transactions/sec
- Latency: P99 < 500ms
- Availability: 99.95% uptime
- Security: PCI-DSS Level 1 compliance
- Scalability: Auto-scale to 10k transactions/sec

## Integration Points

- Payment Gateway APIs (Stripe, PayPal)
- Accounting system (QuickBooks API)
- Fraud detection (Third-party service)
- Notification system (Email, SMS, in-app)

## Acceptance Criteria

- [ ] All payment methods work end-to-end
- [ ] Transactions persist through failures
- [ ] Receipts generated automatically
- [ ] Refunds processed within 2 hours
- [ ] All error cases handled gracefully
- [ ] Performance targets met
- [ ] Security audit passed

## Risk Assessment

| Risk | Probability | Impact | Mitigation |
|------|------------|--------|-----------|
| API rate limits | Medium | High | Implement queue, caching |
| Data loss | Low | Critical | Transaction journaling |
| Fraud | Medium | High | Third-party fraud detection |
| Compliance violation | Low | Critical | Regular audits |

## Timeline & Resources

- Backend Development: 4 weeks (2 engineers)
- Frontend Integration: 2 weeks (1 engineer)
- QA Testing: 2 weeks (2 QA engineers)
- Deployment & monitoring: 1 week (devops)
- Total: 9 weeks, 6 people

## Success Metrics

- Zero payment failures
- Payment latency < 500ms (P99)
- User-reported issues < 0.1%
- All tests passing (≥90% coverage)

---

Best Practices

1. Specification Clarity

• ✅ Use EARS patterns for all requirements
• ✅ Define acceptance criteria before development
• ✅ Include rationale for non-obvious requirements
• ✅ Document constraints and assumptions
• ✅ Keep specifications concise but complete

2. Approval Process

• ✅ Define clear reviewers (technical, product, domain)
• ✅ Use structured review checklist
• ✅ Set review timeline (3-7 days)
• ✅ Document approval decision
• ✅ Require sign-off from decision makers

3. Version Management

• ✅ Use semantic versioning consistently
• ✅ Document every change with rationale
• ✅ Keep complete version history
• ✅ Mark breaking changes clearly
• ✅ Create migration guides for major versions

4. Traceability

• ✅ Link tests to requirements
• ✅ Link documentation to spec
• ✅ Create traceability matrix
• ✅ Verify no orphaned requirements

5. Organization

• ✅ Use consistent directory structure: .moai/specs/SPEC-XXX/
• ✅ Keep related specs together
• ✅ Link dependent specs
• ✅ Archive deprecated specs
• ✅ Index active specs

---

SPEC Integration with MoAI-ADK

With /alfred:1-plan Command

/alfred:1-plan "user profile enhancement feature"
  ↓
Creates SPEC-XXX structure
  ├── spec.md (specification)
  ├── acceptance-criteria.md
  ├── technical-notes.md (optional)
  └── CHANGELOG.md
  ↓
Author reviews and marks ready
  ↓
Tech lead approves
  ↓
Status: ACTIVE

With /alfred:2-run Command

/alfred:2-run SPEC-050
  ↓
Reads SPEC-050 specification
  ↓
TDD cycle:
  RED: Tests from acceptance criteria
  GREEN: Implementation
  REFACTOR: Code quality
  ↓
  ↓
Tests link to requirements

With /alfred:3-sync Command

/alfred:3-sync auto SPEC-050
  ↓
Validates all acceptance criteria met
  ↓
Updates documentation
  ↓
Verifies test coverage
  ↓
Creates PR to develop

With moai-foundation-tags

• Documentation includes spec rationale
• Complete traceability: SPEC → Code → Tests → Docs

---

Organization Patterns

Small Project (1-3 specs)

.moai/specs/
├── SPEC-001/
│   ├── spec.md
│   └── acceptance-criteria.md
├── SPEC-002/
└── SPEC-003/

Medium Project (5-20 specs)

.moai/specs/
├── core/
│   ├── SPEC-001/ (auth)
│   └── SPEC-002/ (api)
├── features/
│   ├── SPEC-010/ (profile)
│   └── SPEC-011/ (payments)
├── infrastructure/
│   ├── SPEC-020/ (database)
│   └── SPEC-021/ (monitoring)
└── deprecated/
    └── SPEC-000/ (old feature)

Large Project (50+ specs)

.moai/specs/
├── index.md (SPEC registry)
├── platform/
│   ├── auth/ (4 specs)
│   ├── api/ (3 specs)
│   ├── user/ (5 specs)
│   └── payments/ (3 specs)
├── features/
│   ├── analytics/ (3 specs)
│   ├── reporting/ (2 specs)
│   └── mobile/ (4 specs)
├── infrastructure/
│   ├── backend/ (5 specs)
│   ├── devops/ (4 specs)
│   └── security/ (3 specs)
├── deprecated/ (archived specs)
└── archive/ (historical reference)

---

Official References (50+ Links)

SPEC/SRS Standards

1. https://standards.ieee.org/standard/830-1998.html — IEEE 830 (Requirements)
2. https://standards.ieee.org/standard/29148-2018.html — ISO/IEC/IEEE 29148
3. https://aqua-cloud.io/how-write-effective-software-requirements-specification/
4. https://www.omg.org/spec/ReqIF/ — ReqIF standard
5. https://www.iso.org/standard/71952.html — ISO/IEC 82045

Document Management Best Practices

6. https://www.documind.chat/blog/document-management-best-practices
7. https://thedigitalprojectmanager.com/project-management/document-management-best-practices/
8. https://blog.opendomain.com/7-engineering-document-management-best-practices
9. https://www.accruent.com/resources/knowledge-hub/what-is-an-engineering-document-management-system
10. https://www.wrenchsp.com/best-practices-for-engineering-document-management/

Version Control & Versioning

11. https://semver.org/ — Semantic Versioning
12. https://en.wikipedia.org/wiki/Software_versioning
13. https://www.conventionalcommits.org/ — Conventional Commits
14. https://nvie.com/posts/a-successful-git-branching-model/ — Git Flow
15. https://www.atlassian.com/git/tutorials/comparing-workflows — Git Workflows

Tools & Platforms

16. https://www.jamasoftware.com/ — Jama Software
17. https://visuresolutions.com/ — Visure Solutions
18. https://www.digital.ai/product/doors — Telelogic DOORS
19. https://docxellent.com/ — Docxellent
20. https://www.g2.com/categories/engineering-document-management — G2 Review

Software Engineering Standards

21. https://cmmiinstitute.com/ — SEI CMMI
22. https://www.computer.org/csdl/book/swebok — SWEBOK v3
23. https://www.sei.cmu.edu/ — SEI Publications
24. https://www.ncbi.nlm.nih.gov/books/NBK537660/ — Software Engineering Handbook
25. https://en.wikipedia.org/wiki/V-model — V-Model Development

Agile & Requirements

26. https://www.agilealliance.org/ — Agile Alliance
27. https://www.scrum.org/ — Scrum Framework
28. https://www.scaledagileframework.com/ — SAFe Framework
29. https://www.atlassian.com/agile/requirements-gathering — Requirements Gathering
30. https://en.wikipedia.org/wiki/Product_backlog — Product Backlog

SPEC/Requirements Examples

31. https://arxiv.org/abs/1805.05087 — Requirements Engineering Survey
32. https://www.pragmaticmarketing.com/ — Product Management
33. https://www.svpg.com/ — Silicon Valley Product Group
34. https://www.productschool.com/ — Product School
35. https://www.reforge.com/ — Reforge Courses

Traceability

36. https://www.alm-tools.org/ — ALM Tools
37. https://about.gitlab.com/blog/2020/10/22/traceability/ — GitLab Traceability
38. https://www.atlassian.com/software/confluence — Confluence
39. https://en.wikipedia.org/wiki/Traceability_matrix — Traceability Matrix
40. https://www.jira.com/ — Jira Requirements

Testing & Acceptance Criteria

41. https://cucumber.io/ — BDD/Gherkin
42. https://www.behave.org/ — Python BDD
43. https://testng.org/ — TestNG Framework
44. https://junit.org/ — JUnit
45. https://pytest.org/ — Pytest

Safety-Critical Specs

46. https://en.wikipedia.org/wiki/DO-178B — DO-178B Avionics
47. https://www.iso.org/standard/43464.html — ISO 26262 (Automotive)
48. https://www.iec.ch/ — IEC Standards
49. https://www.rtca.org/ — RTCA/EUROCAE
50. https://www.sae.org/ — SAE Standards

Additional Resources

51. https://modelcontextprotocol.io/specification/ — Model Context Protocol
52. https://spec.modelcontextprotocol.io/ — MCP Lifecycle Specs
53. https://en.wikipedia.org/wiki/Requirements_engineering — Requirements Engineering
54. https://www.nist.gov/ — NIST Standards
55. https://www.bsi-global.com/ — BSI Standards

---

Troubleshooting

Problem	Solution
Vague requirements	Apply EARS patterns, add measurable criteria
Stuck in review	Set review deadline, escalate to tech lead
Scope creep	Document as separate SPEC, increment version
Changing requirements	Version bump, impact analysis, re-review
Too many specs	Organize by domain, create index
Old archived specs	Move to .moai/specs/archive/, compress

---

Changelog

v4.0.0 (2025-11-12) - November 2025 Stable

• Complete restructure: Lifecycle states, version management, practical examples
• 5 SPEC lifecycle stages (Draft, Review, Active, Deprecated, Archived)
• Semantic versioning strategy with clear rules
• 15+ real-world examples
• 55+ official references
• Integration with MoAI-ADK commands (/alfred:1-plan, /alfred:2-run, /alfred:3-sync)
• 800-1000 target achieved (733 lines SKILL + 190 reference + 372 examples)

v3.0.0 (2025-11-01)

• Previous version with extensive lifecycle detail

v1.0.0 (2025-03-29)

• Initial release

---

Works Well With

• moai-foundation-ears — Write requirements using EARS patterns
• moai-foundation-trust — TRUST 5 quality principles
• moai-alfred-agent-guide — Alfred agent orchestration with SPECs

---

SPECs are the foundation of SPEC-first, TDD development. Clear specifications drive quality implementation.