Back to Details

moai-workflow-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SPEC Workflow Management

SPEC工作流管理

Quick Reference (30 seconds)

快速参考（30秒）

SPEC Workflow Orchestration - Comprehensive specification management using EARS format for systematic requirement definition and Plan-Run-Sync workflow integration.
Core Capabilities:
  • EARS Format Specifications: Five requirement patterns for clarity
  • Requirement Clarification: Four-step systematic process
  • SPEC Document Templates: Standardized structure for consistency
  • Plan-Run-Sync Integration: Seamless workflow connection
  • Parallel Development: Git Worktree-based SPEC isolation
  • Quality Gates: TRUST 5 framework validation
EARS Five Patterns:
  • Ubiquitous: The system shall always perform action - Always active
  • Event-Driven: WHEN event occurs THEN action executes - Trigger-response
  • State-Driven: IF condition is true THEN action executes - Conditional behavior
  • Unwanted: The system shall not perform action - Prohibition
  • Optional: Where possible, provide feature - Nice-to-have
When to Use:
  • Feature planning and requirement definition
  • SPEC document creation and maintenance
  • Parallel feature development coordination
  • Quality assurance and validation planning
Quick Commands:
  • Create new SPEC: /moai:1-plan "user authentication system"
  • Create parallel SPECs with Worktrees: /moai:1-plan "login feature" "signup feature" --worktree
  • Create SPEC with new branch: /moai:1-plan "payment processing" --branch
  • Update existing SPEC: /moai:1-plan SPEC-001 "add OAuth support"
SPEC工作流编排 - 采用EARS格式进行系统化需求定义，并集成Plan-Run-Sync工作流的综合规格管理。
核心能力：
  • EARS格式规格：五种需求模式，确保清晰性
  • 需求澄清：四步系统化流程
  • SPEC文档模板：标准化结构，保证一致性
  • Plan-Run-Sync集成：无缝工作流衔接
  • 并行开发：基于Git Worktree的SPEC隔离机制
  • 质量闸门：TRUST 5框架验证
EARS五种模式：
  • 通用型（Ubiquitous）：系统应始终执行某操作 - 持续生效
  • 事件驱动型（Event-Driven）：当事件发生时，执行对应操作 - 触发-响应机制
  • 状态驱动型（State-Driven）：若条件成立，则执行对应操作 - 条件性行为
  • 禁止型（Unwanted）：系统不得执行某操作 - 禁令要求
  • 可选型（Optional）：尽可能提供某功能 - 锦上添花的特性
适用场景：
  • 功能规划与需求定义
  • SPEC文档创建与维护
  • 并行功能开发协调
  • 质量保证与验证规划
快速命令：
  • 创建新SPEC：/moai:1-plan "用户认证系统"
  • 使用Worktree创建并行SPEC：/moai:1-plan "登录功能" "注册功能" --worktree
  • 创建带新分支的SPEC：/moai:1-plan "支付处理" --branch
  • 更新现有SPEC：/moai:1-plan SPEC-001 "添加OAuth支持"

Implementation Guide (5 minutes)

实施指南（5分钟）

Core Concepts

核心概念

SPEC-First Development Philosophy:
  • EARS format ensures unambiguous requirements
  • Requirement clarification prevents scope creep
  • Systematic validation through test scenarios
  • Integration with DDD workflow for implementation
  • Quality gates enforce completion criteria
  • Constitution reference ensures project-wide consistency
SPEC优先开发理念：
  • EARS格式确保需求无歧义
  • 需求澄清防止范围蔓延
  • 通过测试场景进行系统化验证
  • 与DDD工作流集成以实现落地
  • 质量闸门强制完成标准
  • 参考项目章程确保全项目一致性

Constitution Reference (SDD 2025 Standard)

章程参考（SDD 2025标准）

Constitution defines the project DNA that all SPECs must respect. Before creating any SPEC, verify alignment with project constitution defined in 
.moai/project/tech.md
.
Constitution Components:
  • Technology Stack: Required versions and frameworks
  • Naming Conventions: Variable, function, and file naming standards
  • Forbidden Libraries: Libraries explicitly prohibited with alternatives
  • Architectural Patterns: Layering rules and dependency directions
  • Security Standards: Authentication patterns and encryption requirements
  • Logging Standards: Log format and structured logging requirements
Constitution Verification:
  • All SPEC technology choices must align with Constitution stack versions
  • No SPEC may introduce forbidden libraries or patterns
  • SPEC must follow naming conventions defined in Constitution
  • SPEC must respect architectural boundaries and layering
WHY: Constitution prevents architectural drift and ensures maintainability IMPACT: SPECs aligned with Constitution reduce integration conflicts significantly
章程定义了所有SPEC必须遵循的项目核心准则。创建任何SPEC前，需验证其是否与
.moai/project/tech.md
中定义的项目章程保持一致。
章程组成部分：
  • 技术栈：要求的版本与框架
  • 命名规范：变量、函数与文件的命名标准
  • 禁用库：明确禁止使用的库及替代方案
  • 架构模式：分层规则与依赖方向
  • 安全标准：认证模式与加密要求
  • 日志标准：日志格式与结构化日志要求
章程验证规则：
  • 所有SPEC的技术选型必须与章程中的栈版本对齐
  • 任何SPEC不得引入禁用库或模式
  • SPEC必须遵循章程定义的命名规范
  • SPEC必须尊重架构边界与分层原则
原因：章程可防止架构漂移，确保可维护性 影响：与章程对齐的SPEC可显著减少集成冲突

SPEC Workflow Stages

SPEC工作流阶段

Stage 1 - User Input Analysis: Parse natural language feature description Stage 2 - Requirement Clarification: Four-step systematic process Stage 3 - EARS Pattern Application: Structure requirements using five patterns Stage 4 - Success Criteria Definition: Establish completion metrics Stage 5 - Test Scenario Generation: Create verification test cases Stage 6 - SPEC Document Generation: Produce standardized markdown output
阶段1 - 用户输入分析：解析自然语言描述的功能需求 阶段2 - 需求澄清：执行四步系统化流程 阶段3 - EARS模式应用：采用五种模式结构化需求 阶段4 - 成功标准定义：确立完成指标 阶段5 - 测试场景生成：创建验证用例 阶段6 - SPEC文档生成：生成标准化Markdown输出

EARS Format Deep Dive

EARS格式深度解析

Ubiquitous Requirements - Always Active:
  • Use case: System-wide quality attributes
  • Examples: Logging, input validation, error handling
  • Test strategy: Include in all feature test suites as common verification
Event-Driven Requirements - Trigger-Response:
  • Use case: User interactions and inter-system communication
  • Examples: Button clicks, file uploads, payment completions
  • Test strategy: Event simulation with expected response verification
State-Driven Requirements - Conditional Behavior:
  • Use case: Access control, state machines, conditional business logic
  • Examples: Account status checks, inventory verification, permission checks
  • Test strategy: State setup with conditional behavior verification
Unwanted Requirements - Prohibited Actions:
  • Use case: Security vulnerabilities, data integrity protection
  • Examples: No plaintext passwords, no unauthorized access, no PII in logs
  • Test strategy: Negative test cases with prohibited behavior verification
Optional Requirements - Enhancement Features:
  • Use case: MVP scope definition, feature prioritization
  • Examples: OAuth login, dark mode, offline mode
  • Test strategy: Conditional test execution based on implementation status
通用型需求 - 持续生效：
  • 用例：全系统质量属性
  • 示例：日志记录、输入验证、错误处理
  • 测试策略：作为通用验证项纳入所有功能测试套件
事件驱动型需求 - 触发-响应：
  • 用例：用户交互与系统间通信
  • 示例：按钮点击、文件上传、支付完成
  • 测试策略：模拟事件并验证预期响应
状态驱动型需求 - 条件性行为：
  • 用例：访问控制、状态机、条件业务逻辑
  • 示例：账户状态检查、库存验证、权限校验
  • 测试策略：设置状态并验证条件性行为
禁止型需求 - 禁止操作：
  • 用例：安全漏洞防护、数据完整性保障
  • 示例：不得存储明文密码、禁止未授权访问、日志中不得包含PII
  • 测试策略：通过负面测试用例验证禁止行为
可选型需求 - 增强功能：
  • 用例：MVP范围定义、功能优先级排序
  • 示例：OAuth登录、深色模式、离线模式
  • 测试策略：根据实现状态条件执行测试

Requirement Clarification Process

需求澄清流程

Step 0 - Assumption Analysis (Philosopher Framework):
Before defining scope, surface and validate underlying assumptions using AskUserQuestion.
Assumption Categories:
  • Technical Assumptions: Technology capabilities, API availability, performance characteristics
  • Business Assumptions: User behavior, market requirements, timeline feasibility
  • Team Assumptions: Skill availability, resource allocation, knowledge gaps
  • Integration Assumptions: Third-party service reliability, compatibility expectations
Assumption Documentation:
  • Assumption Statement: Clear description of what is assumed
  • Confidence Level: High, Medium, or Low based on evidence
  • Evidence Basis: What supports this assumption
  • Risk if Wrong: Consequence if assumption proves false
  • Validation Method: How to verify before committing significant effort
Step 0.5 - Root Cause Analysis:
For feature requests or problem-driven SPECs, apply Five Whys:
  • Surface Problem: What is the user observing or requesting?
  • First Why: What immediate need drives this request?
  • Second Why: What underlying problem creates that need?
  • Third Why: What systemic factor contributes?
  • Root Cause: What fundamental issue must the solution adddess?
Step 1 - Scope Definition:
  • Identify supported authentication methods
  • Define validation rules and constraints
  • Determine failure handling strategy
  • Establish session management approach
Step 2 - Constraint Extraction:
  • Performance Requirements: Response time targets
  • Security Requirements: OWASP compliance, encryption standards
  • Compatibility Requirements: Supported browsers and devices
  • Scalability Requirements: Concurrent user targets
Step 3 - Success Criteria Definition:
  • Test Coverage: Minimum percentage target
  • Response Time: Percentile targets (P50, P95, P99)
  • Functional Completion: All normal scenarios pass verification
  • Quality Gates: Zero linter warnings, zero security vulnerabilities
Step 4 - Test Scenario Creation:
  • Normal Cases: Valid inputs with expected outputs
  • Error Cases: Invalid inputs with error handling
  • Edge Cases: Boundary conditions and corner cases
  • Security Cases: Injection attacks, privilege escalation attempts
步骤0 - 假设分析（Philosopher框架）：
在定义范围前，使用AskUserQuestion工具梳理并验证潜在假设。
假设类别：
  • 技术假设：技术能力、API可用性、性能特征
  • 业务假设：用户行为、市场需求、时间线可行性
  • 团队假设：技能可用性、资源分配、知识缺口
  • 集成假设：第三方服务可靠性、兼容性预期
假设文档化：
  • 假设陈述：清晰描述假设内容
  • 置信度：基于证据分为高、中、低
  • 证据依据：支持该假设的依据
  • 错误风险：假设不成立时的后果
  • 验证方法：在投入大量精力前如何验证假设
步骤0.5 - 根因分析：
对于功能请求或问题驱动的SPEC，应用五问法：
  • 表面问题：用户观察到或请求的内容是什么？
  • 第一问：驱动该请求的直接需求是什么？
  • 第二问：产生该需求的潜在问题是什么？
  • 第三问：哪些系统性因素导致了这个问题？
  • 根因：解决方案必须解决的根本问题是什么？
步骤1 - 范围定义：
  • 识别支持的认证方式
  • 定义验证规则与约束
  • 确定失败处理策略
  • 确立会话管理方案
步骤2 - 约束提取：
  • 性能要求：响应时间目标
  • 安全要求：OWASP合规、加密标准
  • 兼容性要求：支持的浏览器与设备
  • 可扩展性要求：并发用户目标
步骤3 - 成功标准定义：
  • 测试覆盖率：最低百分比目标
  • 响应时间：分位数目标（P50、P95、P99）
  • 功能完成度：所有正常场景通过验证
  • 质量闸门：零代码检查警告、零安全漏洞
步骤4 - 测试场景创建：
  • 正常用例：有效输入与预期输出
  • 错误用例：无效输入与错误处理
  • 边缘用例：边界条件与极端场景
  • 安全用例：注入攻击、权限提升尝试

Plan-Run-Sync Workflow Integration

Plan-Run-Sync工作流集成

PLAN Phase (/moai:1-plan):
  • manager-spec agent analyzes user input
  • EARS format requirements generation
  • Requirement clarification with user interaction
  • SPEC document creation in .moai/specs/ directory
  • Git branch creation (optional --branch flag)
  • Git Worktree setup (optional --worktree flag)
RUN Phase (/moai:2-run):
  • manager-ddd agent loads SPEC document
  • ANALYZE-PRESERVE-IMPROVE DDD cycle execution
  • moai-workflow-testing skill reference for test patterns
  • Domain Expert agent delegation (expert-backend, expert-frontend, etc.)
  • Quality validation through manager-quality agent
SYNC Phase (/moai:3-sync):
  • manager-docs agent synchronizes documentation
  • API documentation generation from SPEC
  • README and architecture document updates
  • CHANGELOG entry creation
  • Version control commit with SPEC reference
PLAN阶段（/moai:1-plan）：
  • manager-spec代理分析用户输入
  • 生成EARS格式需求
  • 与用户交互完成需求澄清
  • 在.moai/specs/目录创建SPEC文档
  • 创建Git分支（可选--branch参数）
  • 设置Git Worktree（可选--worktree参数）
RUN阶段（/moai:2-run）：
  • manager-ddd代理加载SPEC文档
  • 执行ANALYZE-PRESERVE-IMPROVE DDD循环
  • 参考moai-workflow-testing技能获取测试模式
  • 委派给领域专家代理（expert-backend、expert-frontend等）
  • 通过manager-quality代理进行质量验证
SYNC阶段（/moai:3-sync）：
  • manager-docs代理同步文档
  • 从SPEC生成API文档
  • 更新README与架构文档
  • 创建CHANGELOG条目
  • 提交版本控制并关联SPEC引用

Parallel Development with Git Worktree

基于Git Worktree的并行开发

Worktree Concept:
  • Independent working directories for multiple branches
  • Each SPEC gets isolated development environment
  • No branch switching needed for parallel work
  • Reduced merge conflicts through feature isolation
Worktree Creation:
  • Command /moai:1-plan "login feature" "signup feature" --worktree creates multiple SPECs
  • Result creates project-worktrees directory with SPEC-specific subdirectories
Worktree Benefits:
  • Parallel Development: Multiple features developed simultaneously
  • Team Collaboration: Clear ownership boundaries per SPEC
  • Dependency Isolation: Different library versions per feature
  • Risk Reduction: Unstable code does not affect other features
Worktree概念：
  • 多分支的独立工作目录
  • 每个SPEC对应独立的开发环境
  • 并行工作无需切换分支
  • 通过功能隔离减少合并冲突
Worktree创建：
  • 命令/moai:1-plan "登录功能" "注册功能" --worktree可创建多个SPEC
  • 结果会在project-worktrees目录下生成SPEC专属子目录
Worktree优势：
  • 并行开发：同时开发多个功能
  • 团队协作：每个SPEC有清晰的所有权边界
  • 依赖隔离：不同功能可使用不同版本的库
  • 风险降低：不稳定代码不会影响其他功能

Advanced Implementation (10+ minutes)

高级实施（10+分钟）

For advanced patterns including SPEC templates, validation automation, and workflow optimization, see:
  • Advanced Patterns: Custom SPEC templates, validation automation
  • Reference Guide: SPEC metadata schema, integration examples
  • Examples: Real-world SPEC documents, workflow scenarios
如需了解包括SPEC模板、验证自动化与工作流优化在内的高级模式，请参考：
  • 高级模式：自定义SPEC模板、验证自动化
  • 参考指南：SPEC元数据 schema、集成示例
  • 示例：真实世界的SPEC文档、工作流场景

Resources

资源

SPEC File Organization

SPEC文件组织

Directory Structure (Standard 3-File Format):
  • .moai/specs/SPEC-{ID}/: SPEC document directory containing 3 required files
    • spec.md: EARS format specification (Environment, Assumptions, Requirements, Specifications)
    • plan.md: Implementation plan, milestones, technical approach
    • acceptance.md: Detailed acceptance criteria, test scenarios (Given-When-Then format)
  • .moai/memory/: Session state files (last-session-state.json)
  • .moai/docs/: Generated documentation (api-documentation.md)
[HARD] Required File Set: Every SPEC directory MUST contain all 3 files (spec.md, plan.md, acceptance.md) WHY: Complete SPEC structure ensures traceability, implementation guidance, and quality validation IMPACT: Missing files create incomplete requirements and prevent proper workflow execution
目录结构（标准3文件格式）：
  • .moai/specs/SPEC-{ID}/：包含3个必填文件的SPEC文档目录
    • spec.md：EARS格式规格（环境、假设、需求、规范）
    • plan.md：实施计划、里程碑、技术方案
    • acceptance.md：详细验收标准、测试场景（Given-When-Then格式）
  • .moai/memory/：会话状态文件（last-session-state.json）
  • .moai/docs/：生成的文档（api-documentation.md）
[硬性要求] 必填文件集： 每个SPEC目录必须包含全部3个文件（spec.md、plan.md、acceptance.md） 原因：完整的SPEC结构确保可追溯性、实施指导与质量验证 影响：缺失文件会导致需求不完整，无法正常执行工作流

SPEC Metadata Schema

SPEC元数据Schema

Required Fields:
  • SPEC ID: Sequential number (SPEC-001, SPEC-002, etc.)
  • Title: Feature name in English
  • Created: ISO 8601 timestamp
  • Status: Planned, In Progress, Completed, Blocked
  • Priority: High, Medium, Low
  • Assigned: Agent responsible for implementation
Optional Fields:
  • Related SPECs: Dependencies and related features
  • Epic: Parent feature group
  • Estimated Effort: Time estimate in hours or story points
  • Labels: Tags for categorization
必填字段：
  • SPEC ID：序列号（如SPEC-001、SPEC-002等）
  • 标题：英文功能名称
  • 创建时间：ISO 8601时间戳
  • 状态：计划中、进行中、已完成、受阻
  • 优先级：高、中、低
  • 负责人：负责实施的代理
可选字段：
  • 关联SPEC：依赖与相关功能
  • 史诗：父功能组
  • 预估工作量：小时或故事点
  • 标签：分类标签

SPEC Lifecycle Management (SDD 2025 Standard)

SPEC生命周期管理（SDD 2025标准）

Lifecycle Level Field:
Level 1 - spec-first:
  • Description: SPEC written before implementation, discarded after completion
  • Use Case: One-time features, prototypes, experiments
  • Maintenance Policy: No maintenance required after implementation
Level 2 - spec-anchored:
  • Description: SPEC maintained alongside implementation for evolution
  • Use Case: Core features, API contracts, integration points
  • Maintenance Policy: Quarterly review, update when implementation changes
Level 3 - spec-as-source:
  • Description: SPEC is the single source of truth; only SPEC is edited by humans
  • Use Case: Critical systems, regulated environments, code generation workflows
  • Maintenance Policy: SPEC changes trigger implementation regeneration
Lifecycle Transition Rules:
  • spec-first to spec-anchored: When feature becomes production-critical
  • spec-anchored to spec-as-source: When compliance or regeneration workflow required
  • Downgrade allowed but requires explicit justification in SPEC history
生命周期等级：
Level 1 - spec-first：
  • 描述：在实施前编写SPEC，完成后丢弃
  • 用例：一次性功能、原型、实验
  • 维护策略：实施完成后无需维护
Level 2 - spec-anchored：
  • 描述：SPEC与实施同步维护以适应演进
  • 用例：核心功能、API契约、集成点
  • 维护策略：季度评审，实施变更时更新
Level 3 - spec-as-source：
  • 描述：SPEC是唯一可信源；仅人类编辑SPEC
  • 用例：关键系统、受监管环境、代码生成工作流
  • 维护策略：SPEC变更触发实施重生成
生命周期转换规则：
  • spec-first转spec-anchored：当功能成为生产关键功能时
  • spec-anchored转spec-as-source：当需要合规或重生成工作流时
  • 允许降级，但需在SPEC历史中提供明确理由

Quality Metrics

质量指标

SPEC Quality Indicators:
  • Requirement Clarity: All EARS patterns used appropriately
  • Test Coverage: All requirements have corresponding test scenarios
  • Constraint Completeness: Technical and business constraints defined
  • Success Criteria Measurability: Quantifiable completion metrics
Validation Checklist:
  • All EARS requirements testable
  • No ambiguous language (should, might, usually)
  • All error cases documented
  • Performance targets quantified
  • Security requirements OWASP-compliant
SPEC质量指标：
  • 需求清晰度：所有EARS模式使用恰当
  • 测试覆盖率：所有需求都有对应的测试场景
  • 约束完整性：技术与业务约束已定义
  • 成功标准可衡量性：量化的完成指标
验证清单：
  • 所有EARS需求可测试
  • 无模糊语言（如should、might、usually）
  • 所有错误场景已文档化
  • 性能目标已量化
  • 安全要求符合OWASP标准

Works Well With

兼容组件

  • moai-foundation-core: SPEC-First DDD methodology and TRUST 5 framework
  • moai-workflow-testing: DDD implementation and test automation
  • moai-workflow-project: Project initialization and configuration
  • moai-workflow-worktree: Git Worktree management for parallel development
  • manager-spec: SPEC creation and requirement analysis agent
  • manager-ddd: DDD implementation based on SPEC requirements
  • manager-quality: TRUST 5 quality validation and gate enforcement
  • moai-foundation-core：SPEC优先DDD方法论与TRUST 5框架
  • moai-workflow-testing：DDD实施与测试自动化
  • moai-workflow-project：项目初始化与配置
  • moai-workflow-worktree：Git Worktree并行开发管理
  • manager-spec：SPEC创建与需求分析代理
  • manager-ddd：基于SPEC需求的DDD实施
  • manager-quality：TRUST 5质量验证与闸门强制

Integration Examples

集成示例

Sequential Workflow:
  • Step 1 PLAN: /moai:1-plan "user authentication system"
  • Step 2 RUN: /moai:2-run SPEC-001
  • Step 3 SYNC: /moai:3-sync SPEC-001
Parallel Workflow:
  • Create multiple SPECs: /moai:1-plan "backend API" "frontend UI" "database schema" --worktree
  • Session 1: /moai:2-run SPEC-001 (backend API)
  • Session 2: /moai:2-run SPEC-002 (frontend UI)
  • Session 3: /moai:2-run SPEC-003 (database schema)
顺序工作流：
  • 步骤1 PLAN：/moai:1-plan "用户认证系统"
  • 步骤2 RUN：/moai:2-run SPEC-001
  • 步骤3 SYNC：/moai:3-sync SPEC-001
并行工作流：
  • 创建多个SPEC：/moai:1-plan "后端API" "前端UI" "数据库 schema" --worktree
  • 会话1：/moai:2-run SPEC-001（后端API）
  • 会话2：/moai:2-run SPEC-002（前端UI）
  • 会话3：/moai:2-run SPEC-003（数据库 schema）

Token Management

令牌管理

Session Strategy:
  • PLAN phase uses approximately 30% of session tokens
  • RUN phase uses approximately 60% of session tokens
  • SYNC phase uses approximately 10% of session tokens
Context Optimization:
  • SPEC document persists in .moai/specs/ directory
  • Session memory in .moai/memory/ for cross-session context
  • Minimal context transfer through SPEC ID reference
  • Agent delegation reduces token overhead
会话策略：
  • PLAN阶段约占会话令牌的30%
  • RUN阶段约占会话令牌的60%
  • SYNC阶段约占会话令牌的10%
上下文优化：
  • SPEC文档持久化在.moai/specs/目录
  • .moai/memory/中的会话内存用于跨会话上下文
  • 通过SPEC ID引用实现最小化上下文传递
  • 代理委派减少令牌开销

SPEC Scope and Classification (NEW)

SPEC范围与分类（新增）

What Belongs in .moai/specs/

.moai/specs/目录的内容范围

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: Describes what WILL be built
  • Actionable: Contains implementation guidance
  • Testable: Includes acceptance criteria
  • Structured: Uses EARS format patterns
.moai/specs/
目录仅用于存放定义待实现功能的SPEC文档。
有效SPEC内容：
  • EARS格式的功能需求
  • 包含里程碑的实施计划
  • 带Given/When/Then场景的验收标准
  • 新功能的技术规格
  • 带明确交付物的用户故事
SPEC特征：
  • 前瞻性：描述将要构建的内容
  • 可执行：包含实施指导
  • 可测试：包含验收标准
  • 结构化：采用EARS格式模式

What Does NOT Belong in .moai/specs/

.moai/specs/目录的排除内容

Document TypeWhy Not SPECCorrect Location
Security AuditAnalyzes existing code
.moai/reports/security-audit-{DATE}/
Performance ReportDocuments current metrics
.moai/reports/performance-{DATE}/
Dependency AnalysisReviews existing dependencies
.moai/reports/dependency-review-{DATE}/
Architecture OverviewDocuments current state
.moai/docs/architecture.md
API ReferenceDocuments existing APIs
.moai/docs/api-reference.md
Meeting NotesRecords decisions made
.moai/reports/meeting-{DATE}/
RetrospectiveAnalyzes past work
.moai/reports/retro-{DATE}/
文档类型不属于SPEC的原因正确存放位置
安全审计报告分析现有代码
.moai/reports/security-audit-{DATE}/
性能报告记录当前指标
.moai/reports/performance-{DATE}/
依赖分析报告评审现有依赖
.moai/reports/dependency-review-{DATE}/
架构概述记录当前状态
.moai/docs/architecture.md
API参考文档记录现有API
.moai/docs/api-reference.md
会议纪要记录已做出的决策
.moai/reports/meeting-{DATE}/
回顾总结分析过往工作
.moai/reports/retro-{DATE}/

Exclusion Rules

排除规则

[HARD] Report vs SPEC Distinction:
Reports analyze what EXISTS → 
.moai/reports/
SPECs define what will be BUILT → 
.moai/specs/
[HARD] Documentation vs SPEC Distinction:
Documentation explains HOW TO USE → 
.moai/docs/
SPECs define WHAT TO BUILD → 
.moai/specs/
[硬性要求] 报告与SPEC的区别：
报告分析已存在的内容 → 
.moai/reports/
SPEC定义将要构建的内容 → 
.moai/specs/
[硬性要求] 文档与SPEC的区别：
文档解释如何使用 → 
.moai/docs/
SPEC定义要构建什么 → 
.moai/specs/

Migration Guide for Legacy Files

遗留文件迁移指南

Scenario 1: Flat SPEC File → Directory Conversion

场景1：扁平SPEC文件 → 目录结构转换

Problem: 
.moai/specs/SPEC-AUTH-001.md
exists as single file
Solution Steps:
  1. Create directory: 
    mkdir -p .moai/specs/SPEC-AUTH-001/
  2. Move content: 
    mv .moai/specs/SPEC-AUTH-001.md .moai/specs/SPEC-AUTH-001/spec.md
  3. Create missing files:
    • Extract implementation plan → 
      plan.md
    • Extract acceptance criteria → 
      acceptance.md
  4. Verify structure: All 3 files present
  5. Commit: 
    git add . && git commit -m "refactor(spec): Convert SPEC-AUTH-001 to directory structure"
Validation Command:
bash
undefined
问题：
.moai/specs/SPEC-AUTH-001.md
为单个文件
解决步骤：
  1. 创建目录：
    mkdir -p .moai/specs/SPEC-AUTH-001/
  2. 移动内容：
    mv .moai/specs/SPEC-AUTH-001.md .moai/specs/SPEC-AUTH-001/spec.md
  3. 创建缺失文件：
    • 提取实施计划 → 
      plan.md
    • 提取验收标准 → 
      acceptance.md
  4. 验证结构：确认3个文件均存在
  5. 提交：
    git add . && git commit -m "refactor(spec): Convert SPEC-AUTH-001 to directory structure"
验证命令：
bash
undefined

Check for flat SPEC files (should return empty)

检查扁平SPEC文件（应返回空）

find .moai/specs -maxdepth 1 -name "SPEC-*.md" -type f
undefined
find .moai/specs -maxdepth 1 -name "SPEC-*.md" -type f
undefined

Scenario 2: Unnumbered SPEC ID → Number Assignment

场景2：无编号SPEC ID → 分配编号

Problem: 
SPEC-REDESIGN
or 
SPEC-SDK-INTEGRATION
without number
Solution Steps:
  1. Find next available number:
    bash
    ls -d .moai/specs/SPEC-*-[0-9][0-9][0-9] 2>/dev/null | sort -t- -k3 -n | tail -1
  2. Assign number: 
    SPEC-REDESIGN
    → 
    SPEC-REDESIGN-001
  3. Rename directory:
    bash
    mv .moai/specs/SPEC-REDESIGN .moai/specs/SPEC-REDESIGN-001
  4. Update internal references in spec.md frontmatter
  5. Commit: 
    git commit -m "refactor(spec): Assign number to SPEC-REDESIGN → SPEC-REDESIGN-001"
问题：
SPEC-REDESIGN
或
SPEC-SDK-INTEGRATION
无编号
解决步骤：
  1. 查找下一个可用编号：
    bash
    ls -d .moai/specs/SPEC-*-[0-9][0-9][0-9] 2>/dev/null | sort -t- -k3 -n | tail -1
  2. 分配编号：
    SPEC-REDESIGN
    → 
    SPEC-REDESIGN-001
  3. 重命名目录：
    bash
    mv .moai/specs/SPEC-REDESIGN .moai/specs/SPEC-REDESIGN-001
  4. 更新spec.md前置元数据中的内部引用
  5. 提交：
    git commit -m "refactor(spec): Assign number to SPEC-REDESIGN → SPEC-REDESIGN-001"

Scenario 3: Report in SPEC Directory → Separation

场景3：SPEC目录中的报告 → 分离

Problem: Analysis/audit document in 
.moai/specs/
Solution Steps:
  1. Identify document type from content
  2. Create reports directory:
    bash
    mkdir -p .moai/reports/security-audit-2025-01/
  3. Move content:
    bash
    mv .moai/specs/SPEC-SECURITY-AUDIT/* .moai/reports/security-audit-2025-01/
rmdir .moai/specs/SPEC-SECURITY-AUDIT
  4. Rename main file to report.md if needed
  5. Commit: 
    git commit -m "refactor: Move security audit from specs to reports"
问题：分析/审计文档存放在
.moai/specs/
中
解决步骤：
  1. 根据内容识别文档类型
  2. 创建报告目录：
    bash
    mkdir -p .moai/reports/security-audit-2025-01/
  3. 移动内容：
    bash
    mv .moai/specs/SPEC-SECURITY-AUDIT/* .moai/reports/security-audit-2025-01/
rmdir .moai/specs/SPEC-SECURITY-AUDIT
  4. 必要时将主文件重命名为report.md
  5. 提交：
    git commit -m "refactor: Move security audit from specs to reports"

Scenario 4: Duplicate SPEC ID → Resolution

场景4：重复SPEC ID → 解决

Problem: Two directories with same SPEC ID
Solution Steps:
  1. Compare creation dates:
    bash
    ls -la .moai/specs/ | grep SPEC-AUTH-001
  2. Determine which is canonical (usually older one)
  3. Renumber newer one to next available:
    bash
    mv .moai/specs/SPEC-AUTH-001-duplicate .moai/specs/SPEC-AUTH-002
  4. Update internal references
  5. Commit: 
    git commit -m "fix(spec): Resolve duplicate SPEC-AUTH-001 → SPEC-AUTH-002"
问题：两个目录使用相同的SPEC ID
解决步骤：
  1. 比较创建日期：
    bash
    ls -la .moai/specs/ | grep SPEC-AUTH-001
  2. 确定规范版本（通常为较旧的版本）
  3. 将较新的版本重命名为下一个可用编号：
    bash
    mv .moai/specs/SPEC-AUTH-001-duplicate .moai/specs/SPEC-AUTH-002
  4. 更新内部引用
  5. 提交：
    git commit -m "fix(spec): Resolve duplicate SPEC-AUTH-001 → SPEC-AUTH-002"

Validation Script

验证脚本

Run this script to identify SPEC organization issues:
bash
#!/bin/bash
运行以下脚本识别SPEC组织问题：
bash
#!/bin/bash

SPEC Organization Validator

SPEC组织验证工具

echo "=== SPEC Organization Check ==="
echo "=== SPEC组织检查 ==="

Check 1: Flat files in specs root

检查1：specs根目录下的扁平文件

echo -e "\n[Check 1] Flat SPEC files (should be empty):" find .moai/specs -maxdepth 1 -name "SPEC-*.md" -type f
echo -e "\n[检查1] 扁平SPEC文件（应返回空）：" find .moai/specs -maxdepth 1 -name "SPEC-*.md" -type f

Check 2: Directories without required files

检查2：缺失必填文件的目录

echo -e "\n[Check 2] SPEC directories missing required files:" for dir in .moai/specs/SPEC-*/; do if [ -d "$dir" ]; then missing="" [ ! -f "${dir}spec.md" ] && missing="${missing}spec.md " [ ! -f "${dir}plan.md" ] && missing="${missing}plan.md " [ ! -f "${dir}acceptance.md" ] && missing="${missing}acceptance.md " [ -n "$missing" ] && echo "$dir: Missing $missing" fi done
echo -e "\n[检查2] 缺失必填文件的SPEC目录：" for dir in .moai/specs/SPEC-*/; do if [ -d "$dir" ]; then missing="" [ ! -f "${dir}spec.md" ] && missing="${missing}spec.md " [ ! -f "${dir}plan.md" ] && missing="${missing}plan.md " [ ! -f "${dir}acceptance.md" ] && missing="${missing}acceptance.md " [ -n "$missing" ] && echo "$dir: 缺失 $missing" fi done

Check 3: SPECs without numbers

检查3：无正确编号的SPEC

echo -e "\n[Check 3] SPECs without proper numbering:" ls -d .moai/specs/SPEC-*/ 2>/dev/null | grep -v -E 'SPEC-[A-Z]+-[0-9]{3}'
echo -e "\n[检查3] 未正确编号的SPEC：" ls -d .moai/specs/SPEC-*/ 2>/dev/null | grep -v -E 'SPEC-[A-Z]+-[0-9]{3}'

Check 4: Potential reports in specs

检查4：specs目录中可能存在的报告

echo -e "\n[Check 4] Potential reports in specs (check manually):" grep -l -r "findings|recommendations|audit|analysis" .moai/specs/*/spec.md 2>/dev/null
echo -e "\n=== Check Complete ==="

---

Version: 1.3.0 (SDD 2025 Standard Integration + SPEC Scope Classification)
Last Updated: 2026-01-21
Integration Status: Complete - Full Plan-Run-Sync workflow with SDD 2025 features and Migration Guide
echo -e "\n[检查4] specs目录中可能存在的报告（需手动检查）：" grep -l -r "findings|recommendations|audit|analysis" .moai/specs/*/spec.md 2>/dev/null
echo -e "\n=== 检查完成 ==="

---

版本：1.3.0（集成SDD 2025标准 + SPEC范围分类）
最后更新：2026-01-21
集成状态：完成 - 完整的Plan-Run-Sync工作流，包含SDD 2025特性与迁移指南