/moai-workflow-spec

name: moai-workflow-spec
description: >
  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.

license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Write, Edit, Bash(git:*), Bash(ls:*), Bash(wc:*), Bash(mkdir:*), Grep, Glob
user-invocable: false
metadata:
  version: "1.2.0"
  category: "workflow"
  status: "active"
  updated: "2026-01-08"
  modularized: "true"
  tags: "workflow, spec, ears, requirements, moai-adk, planning"
  author: "MoAI-ADK Team"

# MoAI Extension: Progressive Disclosure
progressive_disclosure:
  enabled: true
  level1_tokens: 100
  level2_tokens: 5000

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):

| 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).

> **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.

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 clar