Moai Workflow Spec

---
name: moai-workflow-spec
description: SPEC workflow orchestration with EARS format, requirement clarification, and Plan-Run-Sync integration for MoAI-ADK development methodology
version: 1.0.0
category: workflow
tags:
 - workflow
 - spec
 - ears
 - requirements
 - moai-adk
 - planning
updated: 2025-12-07
status: active
author: MoAI-ADK Team
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
---

# 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:
```bash
# 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

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:
```markdown
## 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):
```markdown
## 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**:
```markdown
# 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):
```markdown
## Requirements

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

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

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

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

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

**Constraints Section**:
```markdown
## 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**:
```markdown
## 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**:
```markdown
## 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**:
```bash
# 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**:
```bash
# 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](advanced-patterns.md): Custom SPEC templates, validation automation
- [Reference Guide](reference.md): SPEC metadata schema, integration examples
- [Examples](examples.md): 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

### 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:
```bash
# 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:
```bash
# 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.1.0 (Philosopher Framework Integration)
Last Updated: 2025-12-19
Integration Status: Complete - Full Plan-Run-Sync workflow with Assumption Analysis support