skills.rest
Seung-zedd
Seung-zeddCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

moai-workflow-spec

Creates EARS and GEARS format SPEC documents with acceptance criteria for Plan-Run-Sync workflows.

Updated Aug 29, 2026
Search Tags:#workflow#planning#requirements#acceptance criteria#spec#ears#moai-adk
One-click install
npx skills add https://github.com/Seung-zedd/secure-file-upload --skill moai-workflow-spec-seung-zedd
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: moai-workflow-spec
Source: https://github.com/Seung-zedd/secure-file-upload/tree/main/.claude/skills/moai-workflow-spec
Command: npx skills add https://github.com/Seung-zedd/secure-file-upload --skill moai-workflow-spec-seung-zedd

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing unambiguous software requirements is hard: vague prose leads to misinterpretation, scope creep, and untestable acceptance criteria. This Skill structures requirement definition using the GEARS/EARS notation, a standardized 3-file SPEC format (spec.md, plan.md, acceptance.md), and a systematic clarification process so every requirement is testable before implementation begins. ## Core Features & Use Cases - GEARS/EARS Requirement Patterns: Authors requirements using five canonical patterns (Ubiquitous, Event-driven, State-driven, Capability gate, Unwanted) with a unified compound clause and generalized subjects, including lint guidance for deprecated IF/THEN syntax. - Requirement Clarification Workflow: Applies a 5-step process (assumption analysis, Five Whys root cause analysis, scope definition, constraint extraction, success criteria and test scenario generation) to eliminate ambiguity before coding. - Plan-Run-Sync Integration: Connects SPEC documents to the MoAI-ADK workflow, including Git Worktree parallel development, SPEC lifecycle management, metadata schema validation, and TRUST 5 quality gates. - Use Case: When planning a JWT authentication feature, use this Skill to produce a SPEC with EARS requirements, quantified success criteria (e.g., P95 < 200ms), and a full test scenario table covering normal, error, edge, and security cases. ## Quick Start Ask the AI to create a SPEC document for your feature using EARS format requirements and Given-When-Then acceptance criteria.

Frequently Asked Questions about moai-workflow-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write requirements in EARS format?▼

EARS uses five patterns: Ubiquitous ("The system shall X"), Event-Driven ("WHEN event THEN action"), State-Driven ("WHILE state, the system shall X"), Unwanted ("The system shall not X"), and Optional ("Where possible, provide X"). Pick the pattern based on whether the requirement is always active, triggered, state-dependent, prohibited, or nice-to-have.

What is the difference between GEARS and EARS notation?▼

GEARS is the canonical notation as of v3.0.0 that generalizes the EARS subject from "the system" to any noun and replaces the IF/THEN modality with "When <event-detected>". Legacy EARS SPECs remain valid during a 6-month backward-compatibility window, with lint warnings on residual IF/THEN.

What files must a SPEC directory contain?▼

Every SPEC directory under .moai/specs/SPEC-{ID}/ must contain three files: spec.md for EARS format requirements, plan.md for the implementation plan and milestones, and acceptance.md for Given-When-Then acceptance criteria. Missing files create incomplete requirements.

How do I handle unresolved questions in a SPEC plan?▼

Use [NEEDS CLARIFICATION: <topic>] markers, but only in plan.md and research.md, never in spec.md or acceptance.md. The plan-auditor flags unresolved markers, and all clarifications must be resolved through user questions before the Implementation Kickoff Approval gate.

When should a document not be placed in .moai/specs/?▼

Reports analyzing existing code (security audits, performance reviews, dependency analyses) belong in .moai/reports/, and documentation explaining how to use existing features belongs in .moai/docs/. The specs directory is exclusively for forward-looking feature definitions.

How do I run multiple SPECs in parallel?▼

Use Git Worktree-based isolation: create multiple SPECs with /moai plan, then run each SPEC in its own worktree session with /moai run. This provides independent working directories per SPEC, clear ownership boundaries, and reduced merge conflicts.

Related Skills

Explore More Software Engineering Skills→
sibukixxxsibukixxx

business-to-requirements

Transform vague business ideas into structured technical requirements and user stories.

Community
Advanced
GainInsightDevGainInsightDev

af-deliver-features

Implement features from approved mini-PRDs using TDD and generate pull requests.

Official
Advanced
kivo360kivo360
1

moai-foundation-ears

Automate EARS requirement authoring with five official patterns and TRUST 5 integration.

Community
Advanced
burgebjburgebj

octopus-quick

Execute small software changes with atomic commits and state tracking.

Community
Intermediate