菜单
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命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Harness learning subsystem coordinator. Produces Tier 4 auto-update proposal payloads consumed by the orchestrator (which surfaces them via AskUserQuestion) and orchestrates Apply/Rollback flows. Triggers when harness learning proposals are pending or learning lifecycle management is needed.
DEPRECATED — legacy 7-Phase meta-harness. Redirects to the v4 harness Builder (/moai:harness <natural-language request>) which replaces the static 7-Phase workflow with an orchestrator-direct 4-phase Builder (ANALYZE / PLAN / GENERATE / ACTIVATE) + a manifest-driven dynamic-workflow Runner. Retained as the redirect source for backward-compat invocation paths; the 7-Phase body below is preserved as historical reference, NOT for new harness creation.
MoAI unified orchestrator for autonomous development. Routes natural language or subcommands (plan, run, sync, project, fix, loop, mx, feedback, review, clean, codemaps, gate, e2e, harness, goal, todo) to specialized agents.
基于 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)