maestro-flow 0.1.0

package/templates/cli/prompts/documentation-swagger-api.txt

@@ -0,0 +1,266 @@
+生成符合 RESTful 规范的完整 Swagger/OpenAPI API 文档。
+
+## 核心检查清单 ⚡
+□ 严格遵循 RESTful API 设计规范
+□ 每个接口必须包含：功能描述、请求方法、URL路径、参数说明
+□ 必须包含全局 Security 配置（Authorization Bearer Token）
+□ 使用中文命名目录，保持层级清晰
+□ 每个字段需注明：类型、是否必填、示例值、说明
+□ 包含成功和失败的响应示例
+□ 标注接口版本和最后更新时间
+
+## OpenAPI 规范结构
+
+### 1. 文档信息 (info)
+```yaml
+openapi: 3.0.3
+info:
+  title: {项目名称} API
+  description: |
+    {项目描述}
+    
+    ## 认证方式
+    所有需要认证的接口必须在请求头中携带 Bearer Token：
+    ```
+    Authorization: Bearer <your-token>
+    ```
+  version: "1.0.0"
+  contact:
+    name: API 支持
+    email: api-support@example.com
+  license:
+    name: MIT
+```
+
+### 2. 服务器配置 (servers)
+```yaml
+servers:
+  - url: https://api.example.com/v1
+    description: 生产环境
+  - url: https://staging-api.example.com/v1
+    description: 测试环境
+  - url: http://localhost:3000/v1
+    description: 开发环境
+```
+
+### 3. 全局安全配置 (security)
+```yaml
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        JWT Token 认证
+        
+        获取方式：调用 POST /auth/login 接口
+        有效期：24小时
+        刷新：调用 POST /auth/refresh 接口
+
+security:
+  - bearerAuth: []
+```
+
+### 4. 接口路径规范 (paths)
+```yaml
+paths:
+  /users:
+    get:
+      tags:
+        - 用户管理
+      summary: 获取用户列表
+      description: |
+        分页获取系统用户列表，支持按状态、角色筛选。
+        
+        **适用环境**: 开发、测试、生产
+        **前置条件**: 需要管理员权限
+      operationId: listUsers
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: page
+          in: query
+          required: false
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+          description: 页码（从1开始）
+          example: 1
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            default: 20
+            minimum: 1
+            maximum: 100
+          description: 每页数量
+          example: 20
+      responses:
+        '200':
+          description: 成功获取用户列表
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserListResponse'
+              example:
+                code: 0
+                message: success
+                data:
+                  items:
+                    - id: "usr_123"
+                      email: "user@example.com"
+                      name: "张三"
+                  total: 100
+                  page: 1
+                  limit: 20
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+        '403':
+          $ref: '#/components/responses/ForbiddenError'
+```
+
+### 5. 数据模型规范 (schemas)
+```yaml
+components:
+  schemas:
+    # 基础响应结构
+    BaseResponse:
+      type: object
+      required:
+        - code
+        - message
+        - timestamp
+      properties:
+        code:
+          type: integer
+          description: 业务状态码，0表示成功
+          example: 0
+        message:
+          type: string
+          description: 响应消息
+          example: success
+        timestamp:
+          type: string
+          format: date-time
+          description: 响应时间戳
+          example: "2025-01-01T12:00:00Z"
+    
+    # 错误响应
+    ErrorResponse:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+          description: 错误码
+          example: "AUTH_001"
+        message:
+          type: string
+          description: 错误信息
+          example: "Token 无效或已过期"
+        details:
+          type: object
+          description: 错误详情
+          additionalProperties: true
+```
+
+### 6. 统一响应定义 (responses)
+```yaml
+components:
+  responses:
+    UnauthorizedError:
+      description: 认证失败
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            code: "AUTH_001"
+            message: "Token 无效或已过期"
+    ForbiddenError:
+      description: 权限不足
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            code: "AUTH_003"
+            message: "权限不足，需要管理员角色"
+    NotFoundError:
+      description: 资源不存在
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            code: "BIZ_002"
+            message: "资源不存在"
+    ValidationError:
+      description: 参数验证失败
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            code: "PARAM_001"
+            message: "参数格式错误"
+            details:
+              field: "email"
+              reason: "邮箱格式不正确"
+```
+
+## 接口文档必填项
+
+每个接口必须包含：
+
+1. **基本信息**
+   - tags: 所属模块（中文）
+   - summary: 一句话描述
+   - description: 详细说明（含适用环境、前置条件）
+   - operationId: 唯一操作标识
+
+2. **安全配置**
+   - security: 认证要求
+
+3. **参数定义**
+   - name: 参数名
+   - in: 位置 (path/query/header/cookie)
+   - required: 是否必填
+   - schema: 类型定义（含 default, minimum, maximum）
+   - description: 参数说明
+   - example: 示例值
+
+4. **响应定义**
+   - 200: 成功响应（含完整示例）
+   - 400: 参数错误
+   - 401: 认证失败
+   - 403: 权限不足
+   - 404: 资源不存在（如适用）
+   - 500: 服务器错误
+
+5. **版本信息**
+   - x-version: 接口版本
+   - x-updated: 最后更新时间
+
+## 错误码规范
+
+| 前缀 | 类别 | HTTP状态码 | 说明 |
+|------|------|------------|------|
+| AUTH_ | 认证错误 | 401/403 | 身份验证相关 |
+| PARAM_ | 参数错误 | 400 | 请求参数验证 |
+| BIZ_ | 业务错误 | 409/422 | 业务逻辑相关 |
+| SYS_ | 系统错误 | 500/503 | 服务器异常 |
+
+## RESTful 设计规范
+
+1. **URL 命名**: 使用复数名词，小写，连字符分隔
+2. **HTTP 方法**: GET(查询)、POST(创建)、PUT(更新)、DELETE(删除)、PATCH(部分更新)
+3. **状态码**: 正确使用 2xx/3xx/4xx/5xx
+4. **分页**: 使用 page/limit 或 offset/limit
+5. **筛选**: 使用查询参数
+6. **版本**: URL 路径 (/v1/) 或 请求头

package/templates/cli/prompts/memory-document-module-structure.txt

@@ -0,0 +1,165 @@
+Create or update CLAUDE.md documentation using unified module/file template.
+
+## ⚠️ FILE NAMING RULE (CRITICAL)
+- Target file: MUST be named exactly `CLAUDE.md` in the current directory
+- NEVER create files like `ToolSidebar.CLAUDE.md` or `[filename].CLAUDE.md`
+- ALWAYS use the fixed name: `CLAUDE.md`
+
+## CORE CHECKLIST ⚡
+□ MUST create/update file named exactly 'CLAUDE.md' (not variants)
+□ MUST include all 6 sections: Purpose, Structure, Components, Dependencies, Integration, Implementation
+□ For code files: Document all public/exported APIs with complete parameter details
+□ For folders: Reference subdirectory CLAUDE.md files instead of duplicating
+□ Provide method signatures with parameter types, descriptions, defaults, and return values
+□ Distinguish internal dependencies from external libraries
+□ Apply RULES template requirements exactly as specified
+
+## DOCUMENTATION REQUIREMENTS
+
+### Analysis Strategy
+- **Folders/Modules**: Analyze directory structure, sub-modules, and architectural patterns
+- **Code Files**: Analyze classes, functions, interfaces, and implementation details
+
+### Required Sections (ALL 6 MUST BE INCLUDED)
+
+#### 1. Purpose and Scope
+- Clear description of what this module/file does
+- Main responsibilities and boundaries
+- Role within the larger system
+
+#### 2. Structure Overview
+**For Folders**: Directory organization, sub-module categorization, architectural layout
+**For Code Files**: File organization (imports, exports), class hierarchy, function grouping
+
+#### 3. Key Components
+**For Folders**: Sub-modules, major components, entry points, public interfaces
+**For Code Files**:
+- Core classes with descriptions and responsibilities
+- Key methods with complete signatures:
+  ```
+  methodName(param1: Type1, param2: Type2): ReturnType
+  - Purpose: [what it does]
+  - Parameters:
+    • param1 (Type1): [description] [default: value]
+    • param2 (Type2): [description] [optional]
+  - Returns: (ReturnType) [description]
+  - Throws: [exception types and conditions]
+  - Example: [usage example for complex methods]
+  ```
+- Important interfaces/types
+- Exported APIs
+
+#### 4. Dependencies
+**Internal Dependencies**: Other modules/files within project (with purpose)
+**External Dependencies**: Third-party libraries and frameworks (with purpose, version constraints if critical)
+
+#### 5. Integration Points
+- How this connects to other parts
+- Public APIs or interfaces exposed
+- Data flow patterns (input → processing → output)
+- Event handling or callbacks
+- Extension points for customization
+
+#### 6. Implementation Notes
+- Key design patterns used (e.g., Singleton, Factory, Observer)
+- Important technical decisions and rationale
+- Configuration requirements or environment variables
+- Performance considerations
+- Security considerations if applicable
+- Known limitations or caveats
+
+## OUTPUT REQUIREMENTS
+
+### File Naming (CRITICAL)
+- **Output file**: MUST be named exactly `CLAUDE.md` in the current directory
+- **Examples of WRONG naming**: `ToolSidebar.CLAUDE.md`, `index.CLAUDE.md`, `utils.CLAUDE.md`
+- **Correct naming**: `CLAUDE.md` (always, for all directories)
+
+### Template Structure
+```markdown
+# [Module/File Name]
+
+## Purpose and Scope
+[Clear description of responsibilities and role]
+
+## Structure Overview
+[Directory structure for modules OR File organization for code files]
+
+## Key Components
+### [Component/Class Name]
+- Description: [Brief description]
+- Responsibilities: [What it does]
+- Key Methods:
+  #### `methodName(param1: Type1, param2?: Type2): ReturnType`
+  - Purpose: [what this method does]
+  - Parameters:
+    • param1 (Type1): [description]
+    • param2 (Type2): [description] [optional] [default: value]
+  - Returns: (ReturnType) [description]
+  - Throws: [exceptions if applicable]
+
+## Dependencies
+### Internal Dependencies
+- `[module/file path]` - [purpose]
+
+### External Dependencies
+- `[library name]` - [purpose and usage]
+
+## Integration Points
+### Public APIs
+- `[API/function signature]` - [description]
+
+### Data Flow
+[How data flows through this module/file]
+
+## Implementation Notes
+### Design Patterns
+- [Pattern name]: [Usage and rationale]
+
+### Technical Decisions
+- [Decision]: [Rationale]
+
+### Considerations
+- Performance: [notes]
+- Security: [notes]
+- Limitations: [notes]
+```
+
+### Documentation Style
+- **Concise but complete** - Focus on "what" and "why", not detailed "how"
+- **Code signatures** for key APIs - Include all parameter details
+- **Parameters**: Name, type, description, optional/default indicators, constraints
+- **Return values**: Type, description, special conditions (null, undefined, empty)
+- **Evidence-based** - Reference related documentation when appropriate
+- **Examples** for complex methods - Show usage patterns
+
+### Content Restrictions (STRICTLY AVOID)
+- ❌ Duplicating content from other CLAUDE.md files (reference instead)
+- ❌ Overly detailed code explanations (code should be self-documenting)
+- ❌ Complete code listings (use signatures and descriptions)
+- ❌ Version-specific details unless critical
+- ❌ Documenting every single function (focus on public/exported APIs)
+
+### Method Documentation Rules
+- **Public/Exported methods**: MUST document with full parameter details
+- **Private/Internal methods**: Only document if complex or critical
+- **Parameters**: MUST include type, description, constraints, defaults
+- **Return values**: MUST document type and description
+- **Exceptions**: Document all thrown errors
+
+### Special Instructions
+- If analyzing folder with existing subdirectory CLAUDE.md files → reference them
+- For code files → prioritize exported/public APIs
+- Keep dependency lists focused on direct dependencies (not transitive)
+- Update existing CLAUDE.md files rather than creating duplicate sections
+
+## VERIFICATION CHECKLIST ✓
+□ Output file is named exactly 'CLAUDE.md' (not [filename].CLAUDE.md)
+□ All 6 required sections included (Purpose, Structure, Components, Dependencies, Integration, Implementation)
+□ All public/exported APIs documented with complete signatures
+□ Parameters documented with types, descriptions, and defaults
+□ References used instead of duplicating subdirectory documentation
+□ Internal vs external dependencies clearly distinguished
+□ Examples provided for non-trivial methods
+
+Focus: Comprehensive yet concise documentation covering all essential aspects without redundancy.

package/templates/cli/prompts/planning-breakdown-task-steps.txt

@@ -0,0 +1,30 @@
+Create detailed task breakdown and implementation planning.
+
+## CORE CHECKLIST ⚡
+□ Break down tasks into manageable subtasks (3-8 hours each)
+□ Identify all dependencies and execution sequence
+□ Provide realistic effort estimates with buffer
+□ Document risks for each task
+
+## REQUIRED ANALYSIS
+1. Break down complex tasks into manageable subtasks
+2. Identify dependencies and execution sequence requirements
+3. Estimate effort and resource requirements for each task
+4. Map task relationships and critical path analysis
+5. Document risks and mitigation strategies
+
+## OUTPUT REQUIREMENTS
+- Hierarchical task breakdown with specific deliverables
+- Dependency mapping and execution sequence
+- Effort estimation with confidence levels
+- Resource allocation and skill requirements
+- Risk assessment and mitigation plans for each task
+
+## VERIFICATION CHECKLIST ✓
+□ All tasks broken down to manageable size (3-8 hours)
+□ Dependencies mapped and critical path identified
+□ Effort estimates realistic with buffer included
+□ Every task has clear deliverable defined
+□ Risks documented with mitigation strategies
+
+Focus: Actionable task planning with clear deliverables, dependencies, and realistic timelines.

package/templates/cli/prompts/planning-design-component-spec.txt

@@ -0,0 +1,28 @@
+Guide component implementation and development patterns.
+
+## CORE CHECKLIST ⚡
+□ Define component interface and API requirements clearly
+□ Identify reusable patterns and composition strategies
+□ Plan state management and data flow before implementation
+□ Design a comprehensive testing and validation approach
+
+## REQUIRED ANALYSIS
+1. Define component interface and API requirements
+2. Identify reusable patterns and composition strategies
+3. Plan state management and data flow implementation
+4. Design component testing and validation approach
+5. Document integration points and usage examples
+
+## OUTPUT REQUIREMENTS
+- Component specification with clear interface definition
+- Implementation patterns and best practices
+- State management strategy and data flow design
+- Testing approach and validation criteria
+
+## VERIFICATION CHECKLIST ✓
+□ Component specification includes a clear interface definition
+□ Reusable implementation patterns and best practices are documented
+□ State management and data flow design is clear and robust
+□ A thorough testing and validation approach is defined
+
+Focus: Reusable, maintainable component design with clear usage patterns.

package/templates/cli/prompts/planning-evaluate-concept-feasibility.txt

@@ -0,0 +1,127 @@
+Conduct comprehensive concept evaluation to assess feasibility, identify risks, and provide optimization recommendations.
+
+## CORE CHECKLIST ⚡
+□ Evaluate all 6 dimensions: Conceptual, Architectural, Technical, Resource, Risk, Dependency
+□ Provide quantified assessment scores (1-5 scale)
+□ Classify risks by severity (LOW/MEDIUM/HIGH/CRITICAL)
+□ Include specific, actionable recommendations
+□ Integrate session context and existing patterns
+
+## EVALUATION DIMENSIONS
+
+### 1. Conceptual Integrity
+- Design Coherence: Logical component connections
+- Requirement Completeness: All requirements identified
+- Scope Clarity: Defined and bounded scope
+- Success Criteria: Measurable metrics established
+
+### 2. Architectural Soundness
+- System Integration: Fit with existing architecture
+- Design Patterns: Appropriate pattern usage
+- Modularity: Maintainable structure
+- Scalability: Future requirement capacity
+
+### 3. Technical Feasibility
+- Implementation Complexity: Difficulty level assessment
+- Technology Maturity: Stable, supported technologies
+- Skill Requirements: Team expertise availability
+- Infrastructure Needs: Required changes/additions
+
+### 4. Resource Assessment
+- Development Time: Realistic estimation
+- Team Resources: Size and skill composition
+- Budget Impact: Financial implications
+- Opportunity Cost: Delayed initiatives
+
+### 5. Risk Identification
+- Technical Risks: Limitations, complexity, unknowns
+- Business Risks: Market timing, adoption, impact
+- Integration Risks: Compatibility challenges
+- Resource Risks: Availability, skills, timeline
+
+### 6. Dependency Analysis
+- External Dependencies: Third-party services/tools
+- Internal Dependencies: Systems, teams, resources
+- Temporal Dependencies: Sequence and timing
+- Critical Path: Essential blocking dependencies
+
+## ASSESSMENT METHODOLOGY
+
+**Scoring Scale** (1-5):
+- 5 - Excellent: Minimal risk, well-defined, highly feasible
+- 4 - Good: Low risk, mostly clear, feasible
+- 3 - Average: Moderate risk, needs clarification
+- 2 - Poor: High risk, major changes required
+- 1 - Critical: Very high risk, fundamental problems
+
+**Risk Levels**:
+- LOW: Minor issues, easily addressable
+- MEDIUM: Manageable challenges
+- HIGH: Significant concerns, major mitigation needed
+- CRITICAL: Fundamental viability threats
+
+**Optimization Priorities**:
+- CRITICAL: Must address before planning
+- IMPORTANT: Should address for optimal outcomes
+- OPTIONAL: Nice-to-have improvements
+
+## OUTPUT REQUIREMENTS
+
+### Evaluation Summary
+```markdown
+## Overall Assessment
+- Feasibility Score: X/5
+- Risk Level: LOW/MEDIUM/HIGH/CRITICAL
+- Recommendation: PROCEED/PROCEED_WITH_MODIFICATIONS/RECONSIDER/REJECT
+
+## Dimension Scores
+- Conceptual Integrity: X/5
+- Architectural Soundness: X/5
+- Technical Feasibility: X/5
+- Resource Assessment: X/5
+- Risk Profile: X/5
+- Dependency Complexity: X/5
+```
+
+### Detailed Analysis
+For each dimension:
+1. Assessment: Current state evaluation
+2. Strengths: What works well
+3. Concerns: Issues and risks
+4. Recommendations: Specific improvements
+
+### Risk Matrix
+| Risk Category | Level | Impact | Mitigation Strategy |
+|---------------|-------|--------|---------------------|
+| Technical     | HIGH  | Delays | Proof of concept    |
+| Resource      | MED   | Budget | Phased approach     |
+
+### Optimization Roadmap
+1. CRITICAL: [Issue] - [Recommendation] - [Impact]
+2. IMPORTANT: [Issue] - [Recommendation] - [Impact]
+3. OPTIONAL: [Issue] - [Recommendation] - [Impact]
+
+## CONTEXT INTEGRATION
+
+**Session Memory**: Reference current conversation, decisions, patterns from session history
+**Existing Patterns**: Identify similar implementations, evaluate success/failure, leverage proven approaches
+**Architectural Alignment**: Ensure consistency, consider evolution, apply standards
+**Business Context**: Strategic fit, user impact, competitive advantage, timeline alignment
+
+## PROJECT TYPE CONSIDERATIONS
+
+**Innovation Projects**: Higher risk tolerance, learning focus, phased approach
+**Critical Business**: Lower risk tolerance, reliability focus, comprehensive mitigation
+**Integration Projects**: Compatibility focus, minimal disruption, rollback strategies
+**Greenfield Projects**: Architectural innovation, scalability, technology standardization
+
+## VERIFICATION CHECKLIST ✓
+□ All 6 evaluation dimensions thoroughly assessed with scores
+□ Risk matrix completed with mitigation strategies
+□ Optimization recommendations prioritized (CRITICAL/IMPORTANT/OPTIONAL)
+□ Integration with existing systems evaluated
+□ Resource requirements and timeline implications identified
+□ Success criteria and validation metrics defined
+□ Next steps and decision points outlined
+
+Focus: Actionable insights to improve concept quality and reduce implementation risks.