Moai Workflow Spec

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:    "시스템은 항상 [동작]해야 한다" - Always perform
Event-Driven:  "WHEN [이벤트] THEN [동작]" - Trigger-response
State-Driven:  "IF [조건] THEN [동작]" - Conditional behavior
Unwanted:      "시스템은 [동작]하지 않아야 한다" - Prohibition
Optional:      "가능하면 [동작]을 제공한다" - 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 TDD 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 (extended with Constitution section).

Constitution Components:

• Technology Stack: Required versions and frameworks (e.g., Python 3.13+, FastAPI 0.118+)
• Naming Conventions: Variable, function, and file naming standards
• Forbidden Libraries: Libraries explicitly prohibited (with alternatives)
• Architectural Patterns: Layering rules, dependency directions
• Security Standards: Authentication patterns, encryption requirements
• Logging Standards: Log format, structured logging requirements

Constitution Verification Checklist:

• All SPEC technology choices align with Constitution stack versions
• No SPEC introduces forbidden libraries or patterns
• SPEC follows naming conventions defined in Constitution
• SPEC respects architectural boundaries and layering

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

SPEC Workflow Stages:

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

EARS Format Deep Dive

Ubiquitous Requirements - Always Active:

• Pattern: "시스템은 항상 [동작]해야 한다"
• 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:

• Pattern: "WHEN [이벤트]가 발생하면 THEN [동작]한다"
• Use Case: User interactions and inter-system communication
• Examples:
  • "WHEN 사용자가 로그인 버튼을 클릭하면 THEN 인증을 시도한다"
  • "WHEN 파일이 업로드되면 THEN 바이러스 스캔을 실행한다"
  • "WHEN 결제가 완료되면 THEN 영수증을 발송한다"
• Test Strategy: Event simulation with expected response verification

State-Driven Requirements - Conditional Behavior:

• Pattern: "IF [조건]이면 THEN [동작]한다"
• Use Case: Access control, state machines, conditional business logic
• Examples:
  • "IF 계정이 활성 상태이면 THEN 로그인을 허용한다"
  • "IF 재고가 있으면 THEN 주문을 처리한다"
  • "IF 관리자 권한이면 THEN 삭제를 허용한다"
• Test Strategy: State setup with conditional behavior verification

Unwanted Requirements - Prohibited Actions:

• Pattern: "시스템은 [동작]하지 않아야 한다"
• Use Case: Security vulnerabilities, data integrity protection
• Examples:
  • "시스템은 평문 비밀번호를 저장하지 않아야 한다"
  • "시스템은 인증되지 않은 접근을 허용하지 않아야 한다"
  • "시스템은 민감 정보를 로그에 기록하지 않아야 한다"
• Test Strategy: Negative test cases with prohibited behavior verification

Optional Requirements - Enhancement Features:

• Pattern: "가능하면 [동작]을 제공한다"
• Use Case: MVP scope definition, feature prioritization
• Examples:
  • "가능하면 OAuth 로그인을 제공한다"
  • "가능하면 다크 모드를 지원한다"
  • "가능하면 오프라인 모드를 제공한다"
• Test Strategy: Conditional test execution based on implementation status

Requirement Clarification Process

Step 0: Assumption Analysis (Philosopher Framework) [NEW]

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

Assumption Categories to Examine:

• 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 Format:

• 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

Example Assumption Analysis:

## Assumptions Declared

| # | Assumption | Confidence | Risk if Wrong |
|---|-----------|------------|---------------|
| 1 | Users have stable internet | Medium | Need offline mode |
| 2 | OAuth provider maintains API compatibility | High | Migration needed |
| 3 | Team familiar with JWT patterns | Low | Training required |

Use AskUserQuestion to verify critical assumptions before proceeding to scope definition.

Step 0.5: Root Cause Analysis [NEW]

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 address?

Alternative Approaches Section (SPEC Document):

## Approaches Considered

| Approach | Pros | Cons | Selected |
|----------|------|------|----------|
| Option A | ... | ... | Yes |
| Option B | ... | ... | No - higher complexity |
| Option C | ... | ... | No - vendor lock-in |

Step 1: Scope Definition

• Identify supported authentication methods (email/password, OAuth, SSO)
• Define password complexity rules and validation
• Determine login failure handling strategy
• Establish session management approach

Step 2: Constraint Extraction

• Performance Requirements: Response time targets (e.g., 500ms P95)
• Security Requirements: OWASP compliance, encryption standards
• Compatibility Requirements: Supported browsers, mobile devices
• Scalability Requirements: Concurrent user targets

Step 3: Success Criteria Definition

• Test Coverage: Minimum 85% code coverage target
• Response Time: P50 < 50ms, P95 < 200ms, P99 < 500ms
• 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

SPEC Document Structure

Header Section:

# SPEC-001: User Authentication System

Created: 2025-12-07
Status: Planned
Priority: High
Assigned: manager-tdd
Related SPECs: SPEC-002 (User Registration)

Requirements Section (EARS Format):

## Requirements

### Ubiquitous
- 시스템은 항상 로그인 시도를 로깅해야 한다
- 시스템은 항상 비밀번호를 해싱하여 저장해야 한다

### Event-Driven
- WHEN 사용자가 로그인 버튼을 클릭하면 THEN 자격증명을 검증한다
- WHEN 로그인이 성공하면 THEN JWT 토큰을 발급한다

### State-Driven
- IF 계정이 활성 상태이면 THEN 로그인을 허용한다
- IF 로그인 실패 횟수가 5회 이상이면 THEN 계정을 일시 잠금한다

### Unwanted
- 시스템은 평문 비밀번호를 로그에 기록하지 않아야 한다
- 시스템은 토큰 없이 보호된 리소스 접근을 허용하지 않아야 한다

### Optional
- 가능하면 OAuth 2.0 소셜 로그인을 제공한다
- 가능하면 이중 인증(2FA)을 지원한다

Constraints Section:

## Constraints

Technical Constraints:
- Backend: Node.js 20+, Express.js framework
- Database: PostgreSQL 15+ for user credentials
- Authentication: JWT with RS256 algorithm
- Password Hashing: bcrypt with salt rounds 12

Business Constraints:
- Session timeout: 24 hours for standard users, 1 hour for admin
- Password complexity: Minimum 8 characters, mixed case, numbers, symbols
- Login attempt limit: 5 failures trigger 15-minute account lockout

Success Criteria Section:

## Success Criteria

Functional Criteria:
- All EARS requirements implemented and verified
- Test coverage >= 85% for authentication module
- All test scenarios pass with expected results

Performance Criteria:
- Login response time P95 < 200ms
- Token generation time < 50ms
- Password hashing time < 500ms

Security Criteria:
- OWASP Authentication Cheat Sheet compliance
- No SQL injection vulnerabilities (verified by SQLMap)
- No XSS vulnerabilities (verified by OWASP ZAP)

Test Scenarios Section:

## Test Scenarios

| ID | Category | Scenario | Input | Expected | Status |
|---|---|---|---|---|---|
| TC-1 | Normal | Valid login | email+password | JWT token, 200 | Pending |
| TC-2 | Error | Invalid password | wrong password | 401 error | Pending |
| TC-3 | Error | Nonexistent user | unknown email | 401 error | Pending |
| TC-4 | Edge | Empty password | empty string | 400 error | Pending |
| TC-5 | Security | SQL injection | ' OR '1'='1 | 400 error, blocked | Pending |
| TC-6 | State | Locked account | valid credentials | 403 error | Pending |
| TC-7 | Performance | Concurrent logins | 100 requests/sec | < 200ms P95 | Pending |

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-tdd agent loads SPEC document
• RED-GREEN-REFACTOR TDD 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 Process:

# Command creates two SPECs with Worktrees
/moai:1-plan "login feature" "signup feature" --worktree

# Result directory structure:
# /project                    (main branch)
# /project-worktrees/SPEC-001 (login feature branch)
# /project-worktrees/SPEC-002 (signup feature branch)

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 doesn't affect other features

Worktree Cleanup:

# After feature completion and merge
git worktree remove /project-worktrees/SPEC-001
git branch -d SPEC-001-login-feature

Advanced Implementation (10+ minutes)

For advanced patterns including SPEC templates, quality validation, 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:

.moai/
├── specs/
│   ├── SPEC-001-user-authentication.md
│   ├── SPEC-002-user-registration.md
│   └── SPEC-003-password-reset.md
├── memory/
│   └── last-session-state.json
└── docs/
    └── api-documentation.md

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 (NEW):

SPEC maturity follows three levels based on SDD 2025 best practices:

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
• Recommended For: Quick iterations, exploratory development

Level 2 - spec-anchored:

• Description: SPEC maintained alongside implementation for evolution and maintenance
• Use Case: Core features, API contracts, integration points
• Maintenance Policy: Quarterly review, update when implementation changes
• Recommended For: Production features requiring long-term maintenance

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
• Recommended For: High-reliability systems, compliance-required features

SPEC Document Header with Lifecycle:

---
id: SPEC-AUTH-001
version: "1.0.0"
status: "planned"
created: "2025-12-19"
updated: "2025-12-19"
author: "developer"
priority: "high"
lifecycle_level: "spec-anchored"
maintenance_policy: "quarterly_review"
---

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

Spec Drift Prevention:

• For spec-anchored and spec-as-source levels, /moai:3-sync validates SPEC-implementation alignment
• Drift detection triggers warning before documentation sync
• Manual override requires explicit acknowledgment

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 TDD methodology and TRUST 5 framework
• moai-workflow-testing: TDD implementation and test automation
• moai-workflow-project: Project initialization and configuration
• moai-worktree: Git Worktree management for parallel development
• manager-spec: SPEC creation and requirement analysis agent
• manager-tdd: TDD implementation based on SPEC requirements
• manager-quality: TRUST 5 quality validation and gate enforcement

Integration Examples

Sequential Workflow:

# Step 1: Plan - Create SPEC
/moai:1-plan "user authentication system"

# Step 2: Run - Implement with TDD
/moai:2-run SPEC-001

# Step 3: Sync - Update documentation
/moai:3-sync SPEC-001

Parallel Workflow:

# Create multiple SPECs with Worktrees
/moai:1-plan "backend API" "frontend UI" "database schema" --worktree

# Parallel implementation in separate sessions
# 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: Requirements analysis and SPEC generation (~30% tokens)
• Clear context: /clear command after SPEC document saved
• RUN phase: Fresh session for TDD implementation (~60% tokens)
• SYNC phase: Documentation update in final session (~10% tokens)

Context Optimization:

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

Version: 1.2.0 (SDD 2025 Standard Integration) Last Updated: 2025-12-19 Integration Status: Complete - Full Plan-Run-Sync workflow with SDD 2025 features (Constitution, Tasks Decomposition, Lifecycle Management)