Moai Workflow Spec

• Feature planning and requirement definition
• SPEC document creation and maintenance
• Parallel feature development coordination
• Quality assurance and validation planning

Quick Commands:

• Create new SPEC: /moai:1-plan "user authentication system"
• Create parallel SPECs with Worktrees: /moai:1-plan "login feature" "signup feature" --worktree
• Create SPEC with new branch: /moai:1-plan "payment processing" --branch
• Update existing SPEC: /moai:1-plan SPEC-001 "add OAuth support"

Implementation Guide (5 minutes)

Core Concepts

SPEC-First Development Philosophy:

• EARS format ensures unambiguous requirements
• Requirement clarification prevents scope creep
• Systematic validation through test scenarios
• Integration with DDD workflow for implementation
• Quality gates enforce completion criteria
• Constitution reference ensures project-wide consistency

Constitution Reference (SDD 2025 Standard)

Constitution defines the project DNA that all SPECs must respect. Before creating any SPEC, verify alignment with project constitution defined in .moai/project/tech.md.

Constitution Components:

• Technology Stack: Required versions and frameworks
• Naming Conventions: Variable, function, and file naming standards
• Forbidden Libraries: Libraries explicitly prohibited with alternatives
• Architectural Patterns: Layering rules and dependency directions
• Security Standards: Authentication patterns and encryption requirements
• Logging Standards: Log format and structured logging requirements

Constitution Verification:

• All SPEC technology choices must align with Constitution stack versions
• No SPEC may introduce forbidden libraries or patterns
• SPEC must follow naming conventions defined in Constitution
• SPEC must respect architectural boundaries and layering

WHY: Constitution prevents architectural drift and ensures maintainability IMPACT: SPECs aligned with Constitution reduce integration conflicts significantly

SPEC Workflow Stages

Stage 1 - User Input Analysis: Parse natural language feature description Stage 2 - Requirement Clarification: Four-step systematic process Stage 3 - EARS Pattern Application: Structure requirements using five patterns Stage 4 - Success Criteria Definition: Establish completion metrics Stage 5 - Test Scenario Generation: Create verification test cases Stage 6 - SPEC Document Generation: Produce standardized markdown output

EARS Format Deep Dive

Ubiquitous Requirements - Always Active:

• Use case: System-wide quality attributes
• Examples: Logging, input validation, error handling
• Test strategy: Include in all feature test suites as common verification

Event-Driven Requirements - Trigger-Response:

• Use case: User interactions and inter-system communication
• Examples: Button clicks, file uploads, payment completions
• Test strategy: Event simulation with expected response verification

State-Driven Requirements - Conditional Behavior:

• Use case: Access control, state machines, conditional business logic
• Examples: Account status checks, inventory verification, permission checks
• Test strategy: State setup with conditional behavior verification

Unwanted Requirements - Prohibited Actions:

• Use case: Security vulnerabilities, data integrity protection
• Examples: No plaintext passwords, no unauthorized access, no PII in logs
• Test strategy: Negative test cases with prohibited behavior verification

Optional Requirements - Enhancement Features:

• Use case: MVP scope definition, feature prioritization
• Examples: OAuth login, dark mode, offline mode
• Test strategy: Conditional test execution based on implementation status

Requirement Clarification Process

Step 0 - Assumption Analysis (Philosopher Framework):

Before defining scope, surface and validate underlying assumptions using AskUserQuestion.

Assumption Categories:

• Technical Assumptions: Technology capabilities, API availability, performance characteristics
• Business Assumptions: User behavior, market requirements, timeline feasibility
• Team Assumptions: Skill availability, resource allocation, knowledge gaps
• Integration Assumptions: Third-party service reliability, compatibility expectations

Assumption Documentation:

• Assumption Statement: Clear description of what is assumed
• Confidence Level: High, Medium, or Low based on evidence
• Evidence Basis: What supports this assumption
• Risk if Wrong: Consequence if assumption proves false
• Validation Method: How to verify before committing significant effort

Step 0.5 - Root Cause Analysis:

For feature requests or problem-driven SPECs, apply Five Whys:

• Surface Problem: What is the user observing or requesting?
• First Why: What immediate need drives this request?
• Second Why: What underlying problem creates that need?
• Third Why: What systemic factor contributes?
• Root Cause: What fundamental issue must the solution adddess?

Step 1 - Scope Definition:

• Identify supported authentication methods
• Define validation rules and constraints
• Determine failure handling strategy
• Establish session management approach

Step 2 - Constraint Extraction:

• Performance Requirements: Response time targets
• Security Requirements: OWASP compliance, encryption standards
• Compatibility Requirements: Supported browsers and devices
• Scalability Requirements: Concurrent user targets

Step 3 - Success Criteria Definition:

• Test Coverage: Minimum percentage target
• Response Time: Percentile targets (P50, P95, P99)
• Functional Completion: All normal scenarios pass verification
• Quality Gates: Zero linter warnings, zero security vulnerabilities

Step 4 - Test Scenario Creation:

• Normal Cases: Valid inputs with expected outputs
• Error Cases: Invalid inputs with error handling
• Edge Cases: Boundary conditions and corner cases
• Security Cases: Injection attacks, privilege escalation attempts

Plan-Run-Sync Workflow Integration

PLAN Phase (/moai:1-plan):

• manager-spec agent analyzes user input
• EARS format requirements generation
• Requirement clarification with user interaction
• SPEC document creation in .moai/specs/ directory
• Git branch creation (optional --branch flag)
• Git Worktree setup (optional --worktree flag)

RUN Phase (/moai:2-run):

• manager-ddd agent loads SPEC document
• ANALYZE-PRESERVE-IMPROVE DDD cycle execution
• moai-workflow-testing skill reference for test patterns
• Domain Expert agent delegation (expert-backend, expert-frontend, etc.)
• Quality validation through manager-quality agent

SYNC Phase (/moai:3-sync):

• manager-docs agent synchronizes documentation
• API documentation generation from SPEC
• README and architecture document updates
• CHANGELOG entry creation
• Version control commit with SPEC reference

Parallel Development with Git Worktree

Worktree Concept:

• Independent working directories for multiple branches
• Each SPEC gets isolated development environment
• No branch switching needed for parallel work
• Reduced merge conflicts through feature isolation

Worktree Creation:

• Command /moai:1-plan "login feature" "signup feature" --worktree creates multiple SPECs
• Result creates project-worktrees directory with SPEC-specific subdirectories

Worktree Benefits:

• Parallel Development: Multiple features developed simultaneously
• Team Collaboration: Clear ownership boundaries per SPEC
• Dependency Isolation: Different library versions per feature
• Risk Reduction: Unstable code does not affect other features

Advanced Implementation (10+ minutes)

For advanced patterns including SPEC templates, validation automation, and workflow optimization, see:

• Advanced Patterns: Custom SPEC templates, validation automation
• Reference Guide: SPEC metadata schema, integration examples
• Examples: Real-world SPEC documents, workflow scenarios

Resources

SPEC File Organization

Directory Structure (Standard 3-File Format):

• .moai/specs/SPEC-{ID}/: SPEC document directory containing 3 required files
  • spec.md: EARS format specification (Environment, Assumptions, Requirements, Specifications)
  • plan.md: Implementation plan, milestones, technical approach
  • acceptance.md: Detailed acceptance criteria, test scenarios (Given-When-Then format)
• .moai/state/: Session state files (last-session-state.json)
• .moai/docs/: Generated documentation (api-documentation.md)

[HARD] Required File Set: Every SPEC directory MUST contain all 3 files (spec.md, plan.md, acceptance.md) WHY: Complete SPEC structure ensures traceability, implementation guidance, and quality validation IMPACT: Missing files create incomplete requirements and prevent proper workflow execution

SPEC Metadata Schema

Required Fields:

• SPEC ID: Sequential number (SPEC-001, SPEC-002, etc.)
• Title: Feature name in English
• Created: ISO 8601 timestamp
• Status: Planned, In Progress, Completed, Blocked
• Priority: High, Medium, Low
• Assigned: Agent responsible for implementation

Optional Fields:

• Related SPECs: Dependencies and related features
• Epic: Parent feature group
• Estimated Effort: Time estimate in hours or story points
• Labels: Tags for categorization

SPEC Lifecycle Management (SDD 2025 Standard)

Lifecycle Level Field:

Level 1 - spec-first:

• Description: SPEC written before implementation, discarded after completion
• Use Case: One-time features, prototypes, experiments
• Maintenance Policy: No maintenance required after implementation

Level 2 - spec-anchored:

• Description: SPEC maintained alongside implementation for evolution
• Use Case: Core features, API contracts, integration points
• Maintenance Policy: Quarterly review, update when implementation changes

Level 3 - spec-as-source:

• Description: SPEC is the single source of truth; only SPEC is edited by humans
• Use Case: Critical systems, regulated environments, code generation workflows
• Maintenance Policy: SPEC changes trigger implementation regeneration

Lifecycle Transition Rules:

• spec-first to spec-anchored: When feature becomes production-critical
• spec-anchored to spec-as-source: When compliance or regeneration workflow required
• Downgrade allowed but requires explicit justification in SPEC history

Quality Metrics

SPEC Quality Indicators:

• Requirement Clarity: All EARS patterns used appropriately
• Test Coverage: All requirements have corresponding test scenarios
• Constraint Completeness: Technical and business constraints defined
• Success Criteria Measurability: Quantifiable completion metrics

Validation Checklist:

• All EARS requirements testable
• No ambiguous language (should, might, usually)
• All error cases documented
• Performance targets quantified
• Security requirements OWASP-compliant

Works Well With

• moai-foundation-core: SPEC-First DDD methodology and TRUST 5 framework
• moai-workflow-testing: DDD implementation and test automation
• moai-workflow-project: Project initialization and configuration
• moai-workflow-worktree: Git Worktree management for parallel development
• manager-spec: SPEC creation and requirement analysis agent
• manager-ddd: DDD implementation based on SPEC requirements
• manager-quality: TRUST 5 quality validation and gate enforcement

Integration Examples

Sequential Workflow:

• Step 1 PLAN: /moai:1-plan "user authentication system"
• Step 2 RUN: /moai:2-run SPEC-001
• Step 3 SYNC: /moai:3-sync SPEC-001

Parallel Workflow:

• Create multiple SPECs: /moai:1-plan "backend API" "frontend UI" "database schema" --worktree
• Session 1: /moai:2-run SPEC-001 (backend API)
• Session 2: /moai:2-run SPEC-002 (frontend UI)
• Session 3: /moai:2-run SPEC-003 (database schema)

Token Management

Session Strategy:

• PLAN phase uses approximately 30% of session tokens
• RUN phase uses approximately 60% of session tokens
• SYNC phase uses approximately 10% of session tokens

Context Optimization:

• SPEC document persists in .moai/specs/ directory
• Session state in .moai/state/ for cross-session context
• Minimal context transfer through SPEC ID reference
• Agent delegation reduces token overhead

SPEC Scope and Classification (NEW)

What Belongs in .moai/specs/

The .moai/specs/ directory is EXCLUSIVELY for SPEC documents that define features to be implemented.

Valid SPEC Content:

• Feature requirements in EARS format
• Implementation plans with milestones
• Acceptance criteria with Given/When/Then scenarios
• Technical specifications for new functionality
• User stories with clear deliverables

SPEC Characteristics:

• Forward-looking: Describes what WILL be built
• Actionable: Contains implementation guidance
• Testable: Includes acceptance criteria
• Structured: Uses EARS format patterns

What Does NOT Belong in .moai/specs/

Exclusion Rules

[HARD] Report vs SPEC Distinction:

Reports analyze what EXISTS → .moai/reports/ SPECs define what will be BUILT → .moai/specs/

[HARD] Documentation vs SPEC Distinction:

Documentation explains HOW TO USE → .moai/docs/ SPECs define WHAT TO BUILD → .moai/specs/

Migration Guide for Legacy Files

Scenario 1: Flat SPEC File → Directory Conversion

Problem: .moai/specs/SPEC-AUTH-001.md exists as single file

Solution Steps:

1. Create directory: mkdir -p .moai/specs/SPEC-AUTH-001/
2. Move content: mv .moai/specs/SPEC-AUTH-001.md .moai/specs/SPEC-AUTH-001/spec.md
3. Create missing files:
   • Extract implementation plan → plan.md
   • Extract acceptance criteria → acceptance.md
4. Verify structure: All 3 files present
5. Commit: git add . && git commit -m "refactor(spec): Convert SPEC-AUTH-001 to directory structure"

Validation Command:

# Check for flat SPEC files (should return empty)
find .moai/specs -maxdepth 1 -name "SPEC-*.md" -type f

Scenario 2: Unnumbered SPEC ID → Number Assignment

Problem: SPEC-REDESIGN or SPEC-SDK-INTEGRATION without number

Solution Steps:

1. Find next available number:

   ls -d .moai/specs/SPEC-*-[0-9][0-9][0-9] 2>/dev/null | sort -t- -k3 -n | tail -1
   

2. Assign number: SPEC-REDESIGN → SPEC-REDESIGN-001
3. Rename directory:

   mv .moai/specs/SPEC-REDESIGN .moai/specs/SPEC-REDESIGN-001
   

4. Update internal references in spec.md frontmatter
5. Commit: git commit -m "refactor(spec): Assign number to SPEC-REDESIGN → SPEC-REDESIGN-001"

Scenario 3: Report in SPEC Directory → Separation

Problem: Analysis/audit document in .moai/specs/

Solution Steps:

1. Identify document type from content
2. Create reports directory:

   mkdir -p .moai/reports/security-audit-2025-01/
   

3. Move content:

   mv .moai/specs/SPEC-SECURITY-AUDIT/* .moai/reports/security-audit-2025-01/
   rmdir .moai/specs/SPEC-SECURITY-AUDIT
   

4. Rename main file to report.md if needed
5. Commit: git commit -m "refactor: Move security audit from specs to reports"

Scenario 4: Duplicate SPEC ID → Resolution

Problem: Two directories with same SPEC ID

Solution Steps:

1. Compare creation dates:

   ls -la .moai/specs/ | grep SPEC-AUTH-001
   

2. Determine which is canonical (usually older one)
3. Renumber newer one to next available:

   mv .moai/specs/SPEC-AUTH-001-duplicate .moai/specs/SPEC-AUTH-002
   

4. Update internal references
5. Commit: git commit -m "fix(spec): Resolve duplicate SPEC-AUTH-001 → SPEC-AUTH-002"

Validation Script

Run this script to identify SPEC organization issues:

#!/bin/bash
# SPEC Organization Validator

echo "=== SPEC Organization Check ==="

# Check 1: Flat files in specs root
echo -e "\n[Check 1] Flat SPEC files (should be empty):"
find .moai/specs -maxdepth 1 -name "SPEC-*.md" -type f

# Check 2: Directories without required files
echo -e "\n[Check 2] SPEC directories missing required files:"
for dir in .moai/specs/SPEC-*/; do
  if [ -d "$dir" ]; then
    missing=""
    [ ! -f "${dir}spec.md" ] && missing="${missing}spec.md "
    [ ! -f "${dir}plan.md" ] && missing="${missing}plan.md "
    [ ! -f "${dir}acceptance.md" ] && missing="${missing}acceptance.md "
    [ -n "$missing" ] && echo "$dir: Missing $missing"
  fi
done

# Check 3: SPECs without numbers
echo -e "\n[Check 3] SPECs without proper numbering:"
ls -d .moai/specs/SPEC-*/ 2>/dev/null | grep -v -E 'SPEC-[A-Z]+-[0-9]{3}'

# Check 4: Potential reports in specs
echo -e "\n[Check 4] Potential reports in specs (check manually):"
grep -l -r "findings\|recommendations\|audit\|analysis" .moai/specs/*/spec.md 2>/dev/null

echo -e "\n=== Check Complete ==="

Version: 1.3.0 (SDD 2025 Standard Integration + SPEC Scope Classification) Last Updated: 2026-01-21 Integration Status: Complete - Full Plan-Run-Sync workflow with SDD 2025 features and Migration Guide