ajbcoding/moai-foundation-specs

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.