moai-workflow-spec

# SPEC Workflow Management

## Quick Reference

SPEC Workflow Orchestration using GEARS notation (current) — backed by the EARS legacy backward-compatibility window — for systematic requirement definition and Plan-Run-Sync workflow integration.

Lint behavior canonicalized per the GEARS migration policy.

Core Capabilities:

- GEARS-Format Specifications (current): Five requirement patterns with the unified compound clause `[Where ...][While ...][When ...] The <subject> shall <behavior>` and a generalized `<subject>` (any noun, not only "the system")
- EARS Legacy Reference: All EARS patterns preserved for 6 months from v3.0.0 release to keep the 88 pre-v3 SPECs readable
- Requirement Clarification: Four-step systematic process with assumption analysis
- SPEC Document Templates: Standardized 3-file structure (spec.md / plan.md / acceptance.md)
- Plan-Run-Sync Integration: Seamless workflow connection
- Parallel Development: Git Worktree-based SPEC isolation
- Quality Gates: TRUST 5 framework validation

GEARS Five Patterns (current notation):

| Pattern | GEARS form (current) | EARS form (legacy) | Notes |
|---------|----------------------|--------------------|-------|
| Ubiquitous | "The <subject> shall <behavior>" | "The system shall <behavior>" | `<subject>` may be any noun: system, component, service, agent, function, artifact |
| Event-driven | "**When** <event-detected>, the <subject> shall <behavior>" | "WHEN <event>, the system shall <action>" | Unchanged trigger semantics |
| State-driven | "**While** <state>, the <subject> shall <behavior>" | "WHILE <state>, the system shall <action>" | Unchanged — promoted as a first-class pattern |
| Capability gate | "**Where** <capability / feature flag / static config>, the <subject> shall <behavior>" | "WHERE <feature exists>, the system shall <action>" | Reframed — represents capability gate / feature flag / static config (no longer "Optional") |
| Event-detected (replaces IF/THEN) | "**When** <undesired-condition-detected>, the <subject> shall <response>" | `IF <condition> THEN <action>` **[DEPRECATED — use WHEN <event-detected>]** | The `IF/THEN` modality was removed; describe the same intent as a detected event |

Unified compound clause: `**Where** <precondition> **While** <state> **When** <event> the <subject> shall <behavior>` — any subset of the three modifiers may chain.

See [GEARS notation reference](https://adk.mo.ai.kr/en/workflow-commands/moai-plan/#gears-notation) — 4-locale (en / ko / ja / zh).

> **IF/THEN deprecated callout**: Authoring guidance previously used `IF <condition> THEN <action>` to describe state-conditioned behavior. In GEARS that intent is expressed as `When <condition-detected>` (event-detected form). The lint engine emits a `LegacyEARSKeyword` warning (non-strict) or error (`moai spec lint --strict`) on residual `IF/THEN` in new SPECs. The 6-month backward-compatibility window remains active for legacy SPECs.

Generalized subject substitution: GEARS replaces the hardcoded "the system" subject with `<subject>`, which may be any noun. Authors writing NEW SPECs MAY use the generalized form. Examples of valid non-"the system" subjects:

- "The skill shall present GEARS as the primary notation." (Ubiquitous, `<subject>` = skill)
- "The agent shall return a blocker report instead of prompting the user." (Ubiquitous, `<subject>` = agent)
- "**When** a SPEC author opens the file, the component shall display the deprecation banner." (Event-driven, `<subject>` = component)

The 88 existing SPECs keep "The system" as the default subject for readability; existing readers do not need to relearn the canonical phrase.

EARS Five Patterns (legacy — 6-month backward-compatibility window):

| Pattern | Format | Use |
|---------|--------|-----|
| Ubiquitous | "The system shall always X" | Always active |
| Event-Driven | "WHEN event THEN action" | Trigger-response |
| State-Driven | "WHILE state, the system shall ..." | Conditional behavior (use `WHILE`, not legacy `IF/THEN`) |
| Unwanted | "The system shall not X" | Prohibition |
| Optional | "Where possible, provide X" | Nice-to-have |

The legacy `IF/THEN` modality is replaced by GEARS `When <event-detected>` — see callout above.

When to Use:

- Feature planning and requirement definition
- SPEC document creation and maintenance
- Parallel feature development coordination
- Quality assurance and validation planning
- Requirements gathering from user story narratives

Quick Commands:

```bash
/moai:1-plan "user authentication system"                   # Create new SPEC
/moai:1-plan "login" "signup" --worktree                    # Parallel SPECs
/moai:1-plan "payment processing" --branch                  # New branch
/moai:1-plan SPEC-001 "add OAuth support"                   # Update existing
```

---

## Implementation Guide

### 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 `.moai/project/tech.md`.

Constitution Components: Technology Stack, Naming Conventions, Forbidden Libraries, Architectural Patterns, Security Standards, Logging Standards.

Constitution Verification: All SPEC technology choices align with Constitution stack versions, no forbidden libraries, naming conventions respected, architectural boundaries preserved.

WHY: Constitution prevents architectural drift and ensures maintainability.

### SPEC Workflow Stages

| Stage | Activity |
|-------|----------|
| 1 | User Input Analysis — parse natural-language feature description |
| 2 | Requirement Clarification — 4-step systematic process |
| 3 | EARS