SPEC Workflow Management

Quick Reference (30 seconds)

SPEC Workflow Orchestration - Comprehensive specification management using EARS format for systematic requirement definition and Plan-Run-Sync workflow integration.

Core Capabilities:

• EARS Format Specifications: Five requirement patterns for clarity

• Requirement Clarification: Four-step systematic process

• SPEC Document Templates: Standardized structure for consistency

• Plan-Run-Sync Integration: Seamless workflow connection

• Parallel Development: Git Worktree-based SPEC isolation

• Quality Gates: TRUST 5 framework validation

EARS Five Patterns:

• Ubiquitous: The system shall always perform action - Always active

• Event-Driven: WHEN event occurs THEN action executes - Trigger-response

• State-Driven: IF condition is true THEN action executes - Conditional behavior

• Unwanted: The system shall not perform action - Prohibition

• Optional: Where possible, provide feature - Nice-to-have

When to Use:

• 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/

Document Type Why Not SPEC Correct Location

Security Audit Analyzes existing code .moai/reports/security-audit-{DATE}/

Performance Report Documents current metrics .moai/reports/performance-{DATE}/

Dependency Analysis Reviews existing dependencies .moai/reports/dependency-review-{DATE}/

Architecture Overview Documents current state .moai/docs/architecture.md

API Reference Documents existing APIs .moai/docs/api-reference.md

Meeting Notes Records decisions made .moai/reports/meeting-{DATE}/

Retrospective Analyzes past work .moai/reports/retro-{DATE}/

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

For migration scenarios and validation scripts, see reference/migration-guide.md.

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