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 per the lint engine's backward-compatibility policy to keep pre-v3 SPECs (those authored before GEARS became canonical) 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):

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.

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)

Pre-v3 SPECs (those authored before GEARS became canonical) 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):

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:

/moai:1-plan "user authentication system"                   # Create new SPEC
/moai:1-plan "login" "signup"                              # 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

GEARS Format (current)

GEARS (Generalized EARS) is the canonical SPEC notation as of v3.0.0. It preserves Ubiquitous / When (event-driven) / While (state-driven) and reframes Where as a capability gate. The legacy IF/THEN modality is replaced by When <event-detected>.

GEARS notation is exhaustively described in docs-site GEARS notation reference and the canonical GEARS migration policy record.

Compound clause example (with non-"the system" subject):

Where the project is initialized While strict mode is active When a SPEC author runs moai spec lint, the lint engine shall emit a LegacyEARSKeyword finding for every residual IF/THEN modality.

This example chains all three GEARS modifiers (Where, While, When) and uses <subject> = "lint engine" rather than "the system".

EARS Format (legacy — 6-month backward-compatibility window)

Five patterns cover all requirement types. Each pattern has a specific use case and test strategy. Pre-v3 SPECs (those authored before GEARS became canonical) continue to use EARS notation and remain valid per the lint engine's backward-compatibility policy.

See EARS deep dive with examples per pattern for use cases, examples, and test strategies for Ubiquitous, Event-Driven, State-Driven, Unwanted, and Optional requirements.

Requirement Clarification Process

5-step systematic process:

• Step 0: Assumption Analysis (Philosopher Framework) — surface technical, business, team, integration assumptions
• Step 0.5: Root Cause Analysis (Five Whys) — surface problem to root cause for problem-driven SPECs
• Step 1: Scope Definition — supported methods, validation rules, failure handling, session management
• Step 2: Constraint Extraction — performance, security, compatibility, scalability
• Step 3: Success Criteria — coverage targets, response time percentiles, functional completion, quality gates
• Step 4: Test Scenario Creation — normal, error, edge, security cases

See requirement clarification detailed workflow for assumption documentation templates and Five Whys application.

[NEEDS CLARIFICATION] Marker Convention

[NEEDS CLARIFICATION: ] markers identify unresolved questions in plan.md and research.md that MUST be settled before Implementation Kickoff Approval (plan→run HUMAN GATE).

Placement: ONLY in plan.md and research.md (NEVER in spec.md or acceptance.md).

Format:

• [NEEDS CLARIFICATION: <specific topic>] — inline marker for open questions
• Each marker MUST be addressable via orchestrator AskUserQuestion before run-phase entry
• plan-auditor detects unclarified markers and flags as "clarification gate" finding

3-Layer Distinction:

• [NEEDS CLARIFICATION: <topic>] — plan/research artifact blocker (user Q required)
• TODO — code-level implementation debt (no user Q needed)
• @MX:TODO — code-level annotation for untested/incomplete code

Processing:

• plan-auditor scans for [NEEDS CLARIFICATION] markers during audit
• If any remain, plan-auditor recommends resolution before Implementation Kickoff Approval
• Orchestrator runs AskUserQuestion rounds to resolve each marked topic
• Implementation Kickoff Approval (mandatory human gate) proceeds only after all clarifications are resolved

Plan-Run-Sync Workflow Integration

PLAN (/moai:1-plan): manager-spec analyzes input → EARS requirements → clarification → SPEC creation in .moai/specs/ → optional --branch.

RUN (/moai:2-run): manager-develop loads SPEC → ANALYZE-PRESERVE-IMPROVE (DDD) or RED-GREEN-REFACTOR (TDD) per quality.yaml constitution.development_mode → moai-workflow-testing reference → per-spawn Agent(general-purpose) domain delegation → quality-gate validation (Stop hook / /moai gate).

SYNC (/moai:3-sync): manager-docs synchronizes documentation → API docs from SPEC → README and architecture updates → CHANGELOG → version control commit.

Parallel Development with Git Worktree

Worktree provides isolated working directories per SPEC for parallel development without branch switching. Benefits: parallel development, clear ownership boundaries, dependency isolation, risk reduction.

See worktree workflow patterns for creation commands and team collaboration examples.

Resources

SPEC File Organization

Standard 3-File Format:

• .moai/specs/SPEC-{ID}/spec.md — EARS format specification
• .moai/specs/SPEC-{ID}/plan.md — implementation plan, milestones, technical approach
• .moai/specs/SPEC-{ID}/acceptance.md — acceptance criteria, Given-When-Then scenarios

[HARD] Every SPEC directory MUST contain all 3 files. Missing files create incomplete requirements.

State files: .moai/state/last-session-state.json. Generated docs: .moai/docs/api-documentation.md.

SPEC Metadata Schema

Canonical 12 required fields (enforced by the SPEC frontmatter lint rule): id, title, version, status, created, updated, author, priority, phase, module, lifecycle, tags.

Status enum (8 values): draft → in-progress → implemented → completed | superseded | archived | rejected. (planned is retained in the enum as legacy-optional — NOT in the active flow; no agent authors a draft → planned transition. See .claude/rules/moai/development/spec-frontmatter-schema.md § Status Enum.)

Optional fields: issue_number, depends_on, lint.skip, bc_id, tier (S/M/L LEAN tier).

Full schema at .claude/rules/moai/development/spec-frontmatter-schema.md (SSOT).

SPEC Lifecycle Management

Three lifecycle levels:

Transitions: spec-first → spec-anchored when production-critical, spec-anchored → spec-as-source when compliance or regeneration workflow required. Downgrade requires explicit justification.

Quality Metrics

SPEC Quality Indicators: requirement clarity (all EARS patterns used), test coverage (all requirements have scenarios), constraint completeness, success criteria measurability.

Validation Checklist: All EARS requirements testable, no ambiguous language ("should", "might", "usually"), all error cases documented, performance targets quantified, security requirements OWASP-compliant.

Token Management

Context Optimization: SPEC document persists in .moai/specs/. Session state in .moai/state/. Minimal context transfer through SPEC ID reference. Agent delegation reduces token overhead.

SPEC Scope and Classification

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 (what WILL be built), actionable, testable, structured (EARS).

What Does NOT Belong in .moai/specs/

Out of Scope Classification Rules

These routing rules decide what is out of scope for a SPEC document (and where it belongs instead). When authoring a SPEC's own exclusions section, express each excluded item as a ### Out of Scope — <topic> H3 sub-heading with - bullets so the section satisfies the OutOfScopeRule lint.

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

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

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-develop: DDD/TDD implementation based on SPEC requirements
• /moai gate skill (or sync-phase-quality-gate.sh Stop hook): TRUST 5 quality validation and gate enforcement (former manager-quality role)

For migration scenarios and validation scripts: references/migration-guide.md.

Version: 1.3.1 (skill body compression pass) Last Updated: 2026-05-23 Integration Status: Complete - Plan-Run-Sync workflow with SDD 2025 features

Common Rationalizations

Red Flags

• Requirements written in imperative prose instead of EARS (WHEN X, SHALL Y)
• Acceptance criteria phrased as subjective judgments ("feels fast", "looks clean")
• SPEC document missing research.md sibling when modifying existing code
• Annotation cycle skipped or reduced to a single-turn "looks good"
• Requirements use "should" where they mean "shall" (optional vs mandatory ambiguity)
• SPEC-ID not registered in .moai/specs/ directory

Verification

• SPEC file exists at .moai/specs/SPEC-XXX/spec.md with unique ID
• Every requirement uses EARS keywords (WHEN, WHILE, WHERE, IF, SHALL)
• Every acceptance criterion is observable (test output, file existence, metric threshold)
• research.md exists when the SPEC touches existing code
• Annotation cycle completed with explicit user approval marker
• SPEC references existing SPEC-IDs it depends on or supersedes
• Out of Scope section present to prevent scope creep — at least one ### Out of Scope — <topic> H3 sub-heading with a - bullet entry (satisfies the OutOfScopeRule lint)