SPEC workflow orchestration with EARS format requirements, acceptance criteria, and Plan-Run-Sync integration for MoAI-ADK development. Use when creating SPEC documents or defining acceptance criteria.
SPEC workflow orchestration with EARS format requirements, acceptance criteria, and Plan-Run-Sync integration for MoAI-ADK development. Use when creating SPEC documents or defining acceptance criteria.
when_to_use
Use for SPEC workflow orchestration: EARS-format requirements, acceptance criteria, user stories, requirements gathering, planning, and Plan-Run-Sync integration for MoAI-ADK development.
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
<subject> may be any noun: system, component, service, agent, function, artifact
Event-driven
"When , the shall "
"WHEN , the system shall "
Unchanged trigger semantics
State-driven
"While , the shall "
"WHILE , the system shall "
Unchanged — promoted as a first-class pattern
Capability gate
"Where <capability / feature flag / static config>, the shall "
"WHERE , the system shall "
Reframed — represents capability gate / feature flag / static config (no longer "Optional")
Event-detected (replaces IF/THEN)
"When , the shall "
IF <condition> THEN <action>[DEPRECATED — use WHEN ]
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.
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):
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.
Test Scenario Generation — create verification test cases
6
SPEC Document Generation — produce standardized markdown
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>.
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.
[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
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.yamlconstitution.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.
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.)
Full schema at .claude/rules/moai/development/spec-frontmatter-schema.md (SSOT).
SPEC Lifecycle Management
Three lifecycle levels:
Level
Description
Maintenance
spec-first
SPEC discarded after implementation
None
spec-anchored
SPEC maintained alongside implementation
Quarterly review
spec-as-source
SPEC is single source of truth, only SPEC edited by humans
Changes regenerate impl
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
Phase
Token Budget
PLAN
~30%
RUN
~60%
SYNC
~10%
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/
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}/
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
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
Rationalization
Reality
"The SPEC is obvious, I can skip EARS format"
EARS exists because obvious requirements are the first to be misinterpreted. The format forces disambiguation.
"Acceptance criteria are redundant with the requirements"
Requirements describe intent. Acceptance criteria describe observable evidence. Both are needed.
"I will refine the SPEC during implementation"
Late refinement means wasted implementation. SPEC is the cheap place to change your mind.
"Research is a nice-to-have, not a blocker"
Skipping research produces SPECs that conflict with existing code. research.md prevents rework.
"Annotation cycle is just user friction"
Annotation catches misunderstandings before code is written. It is the cheapest feedback loop in the pipeline.
"This SPEC is small, I do not need a separate file"
Every SPEC is a persistent contract. In-message SPECs cannot be referenced by /moai run SPEC-XXX.
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)
