メニュー
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.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/modu-ai/moai-adk --skill moai-workflow-specコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SOC 職業分類に基づく
SKILL.md を表示中
| 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"} |
| progressive_disclosure | {"enabled":true,"level1_tokens":100,"level2_tokens":5000} |
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 shall " | "The system shall " | <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 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: ] 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
| 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/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)