SPEC workflow orchestration with EARS format requirements, acceptance criteria, and Plan-Run-Sync integration for MoAI-ADK development methodology. Use when creating SPEC documents, writing EARS requirements, defining acceptance criteria, planning features, or orchestrating the /moai plan phase. Do NOT use for implementation (use moai-workflow-ddd instead) or documentation generation (use moai-workflow-project instead).
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:
[Where ...][While ...][When ...] The <subject> shall <behavior> and a generalized <subject> (any noun, not only "the system")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.
IF/THEN deprecated callout: Authoring guidance previously used
IF <condition> THEN <action>to describe state-conditioned behavior. In GEARS that intent is expressed asWhen <condition-detected>(event-detected form). The lint engine emits aLegacyEARSKeywordwarning (non-strict) or error (moai spec lint --strict) on residualIF/THENin 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:
<subject> = skill)<subject> = agent)<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.
When to Use:
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
SPEC-First Development Philosophy:
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.
| Stage | Activity | |-------|----------| | 1 | User Input Analysis — parse natural-language feature description | | 2 | Requirement Clarification — 4-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 |
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 aLegacyEARSKeywordfinding for every residualIF/THENmodality.
This example chains all three GEARS modifiers (Where, While, When) and uses <subject> = "lint engine" rather than "the system".
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.
5-step systematic process:
See requirement clarification detailed workflow for assumption documentation templates and Five Whys application.
[NEEDS CLARIFICATION: <topic>] 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 questions3-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 codeProcessing:
[NEEDS CLARIFICATION] markers during auditPLAN (/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.
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.
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.
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).
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.
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.
| 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.
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).
| 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}/ |
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/.
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
<!-- moai:evolvable-start id="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. |
<!-- moai:evolvable-end --> <!-- moai:evolvable-start id="red-flags" -->.moai/specs/ directory.moai/specs/SPEC-XXX/spec.md with unique ID### Out of Scope — <topic> H3 sub-heading with a - bullet entry (satisfies the OutOfScopeRule lint)Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer