maestro-flow 0.5.31 → 0.5.33

package/.claude/skills/skill-generator/specs/execution-modes.md

@@ -0,0 +1,399 @@
+# Execution Modes Specification
+
+Detailed specification definitions for two Skill execution modes.
+
+---
+
+## Mode Overview
+
+| Feature | Sequential (Fixed Order) | Autonomous (Dynamic) |
+|---------|--------------------------|----------------------|
+| Execution Order | Fixed (numeric prefix) | Dynamic (orchestrator decision) |
+| Phase Dependencies | Strong dependencies | Weak/no dependencies |
+| State Management | Implicit (phase output) | Explicit (state file) |
+| Use Cases | Pipeline tasks | Interactive tasks |
+| Complexity | Low | Medium-High |
+| Extensibility | Insert sub-phases | Add new actions |
+
+---
+
+## Mode 1: Sequential (Fixed Order Mode)
+
+### Definition
+
+Phases execute linearly in fixed order, with each phase's output serving as input to the next phase.
+
+### Directory Structure
+
+```
+phases/
+├── 01-{first-step}.md
+├── 02-{second-step}.md
+├── 02.5-{sub-step}.md      # Optional: sub-phase
+├── 03-{third-step}.md
+└── ...
+```
+
+### Execution Flow
+
+```
+┌─────────┐     ┌─────────┐     ┌─────────┐
+│Phase 01 │────▶│Phase 02 │────▶│Phase 03 │────▶ ...
+└─────────┘     └─────────┘     └─────────┘
+     │               │               │
+     ▼               ▼               ▼
+  output1.json   output2.md      output3.md
+```
+
+### Phase File Specification
+
+```markdown
+# Phase N: {Phase Name}
+
+{One-sentence description}
+
+## Objective
+
+{Detailed objective}
+
+## Input
+
+- Dependencies: {Previous phase output}
+- Configuration: {Configuration file}
+
+## Execution Steps
+
+### Step 1: {Step}
+{Execution code or description}
+
+### Step 2: {Step}
+{Execution code or description}
+
+## Output
+
+- **File**: `{Output file}`
+- **Format**: {JSON/Markdown}
+
+## Next Phase
+
+→ [Phase N+1: xxx](0N+1-xxx.md)
+```
+
+### Applicable Scenarios
+
+- **Document Generation**: Collect → Analyze → Assemble → Optimize
+- **Code Analysis**: Scan → Parse → Report
+- **Data Processing**: Extract → Transform → Load
+
+### Advantages
+
+- Clear logic, easy to understand
+- Simple debugging, can validate phase by phase
+- Predictable output
+
+### Disadvantages
+
+- Low flexibility
+- Difficult to handle branching logic
+- Limited user interaction
+
+---
+
+## Mode 2: Autonomous (Dynamic Mode)
+
+### Definition
+
+No fixed execution order. The orchestrator dynamically selects the next action based on current state.
+
+### Directory Structure
+
+```
+phases/
+├── orchestrator.md          # Orchestrator: core decision logic
+├── state-schema.md          # State structure definition
+└── actions/                 # Independent actions (no order)
+    ├── action-{a}.md
+    ├── action-{b}.md
+    ├── action-{c}.md
+    └── ...
+```
+
+### Core Components
+
+#### 1. Orchestrator
+
+```markdown
+# Orchestrator
+
+## Role
+
+Select and execute the next action based on current state.
+
+## State Reading
+
+Read state file: `{workDir}/state.json`
+
+## Decision Logic
+
+```javascript
+function selectNextAction(state) {
+  // 1. Check termination conditions
+  if (state.status === 'completed') return null;
+  if (state.error_count > MAX_RETRIES) return 'action-abort';
+
+  // 2. Select action based on state
+  if (!state.initialized) return 'action-init';
+  if (state.pending_items.length > 0) return 'action-process';
+  if (state.needs_review) return 'action-review';
+
+  // 3. Default action
+  return 'action-complete';
+}
+```
+
+## Execution Loop
+
+```
+while (true) {
+  state = readState();
+  action = selectNextAction(state);
+  if (!action) break;
+
+  result = executeAction(action, state);
+  updateState(result);
+}
+```
+```
+
+#### 2. State Schema
+
+```markdown
+# State Schema
+
+## State File
+
+Location: `{workDir}/state.json`
+
+## Structure Definition
+
+```typescript
+interface SkillState {
+  // Metadata
+  skill_name: string;
+  started_at: string;
+  updated_at: string;
+
+  // Execution state
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  current_action: string | null;
+  completed_actions: string[];
+
+  // Business data
+  context: Record<string, any>;
+  pending_items: any[];
+  results: Record<string, any>;
+
+  // Error tracking
+  errors: Array<{
+    action: string;
+    message: string;
+    timestamp: string;
+  }>;
+  error_count: number;
+}
+```
+
+## Initial State
+
+```json
+{
+  "skill_name": "{skill-name}",
+  "started_at": "{ISO8601}",
+  "updated_at": "{ISO8601}",
+  "status": "pending",
+  "current_action": null,
+  "completed_actions": [],
+  "context": {},
+  "pending_items": [],
+  "results": {},
+  "errors": [],
+  "error_count": 0
+}
+```
+```
+
+#### 3. Action
+
+```markdown
+# Action: {action-name}
+
+## Purpose
+
+{Action purpose}
+
+## Preconditions
+
+- [ ] Condition 1
+- [ ] Condition 2
+
+## Execution
+
+{Execution logic}
+
+## State Updates
+
+```javascript
+return {
+  completed_actions: [...state.completed_actions, 'action-name'],
+  results: {
+    ...state.results,
+    action_name: { /* result */ }
+  },
+  // Other state updates
+};
+```
+
+## Next Actions (Hints)
+
+- On success: `action-{next}`
+- On failure: `action-retry` or `action-abort`
+```
+
+### Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Orchestrator Loop                           │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │                                                          │    │
+│  │   ┌──────────┐     ┌──────────┐     ┌──────────┐        │    │
+│  │   │ Read     │────▶│ Select   │────▶│ Execute  │        │    │
+│  │   │ State    │     │ Action   │     │ Action   │        │    │
+│  │   └──────────┘     └──────────┘     └──────────┘        │    │
+│  │        ▲                                  │              │    │
+│  │        │                                  ▼              │    │
+│  │        │           ┌──────────┐                         │    │
+│  │        └───────────│ Update   │◀────────────────────────┘    │
+│  │                    │ State    │                              │
+│  │                    └──────────┘                              │
+│  │                                                          │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                              │                                   │
+│                              ▼                                   │
+│                    ┌──────────────────┐                         │
+│                    │ Termination?     │                         │
+│                    │ - completed      │                         │
+│                    │ - max_retries    │                         │
+│                    │ - user_abort     │                         │
+│                    └──────────────────┘                         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Action Catalog
+
+Defined in `specs/action-catalog.md`:
+
+```markdown
+# Action Catalog
+
+## Available Actions
+
+| Action | Purpose | Preconditions | Effects |
+|--------|---------|---------------|---------|
+| action-init | Initialize state | status=pending | status=running |
+| action-process | Process pending items | pending_items.length>0 | pending_items-- |
+| action-review | User review | needs_review=true | needs_review=false |
+| action-complete | Complete task | pending_items.length=0 | status=completed |
+| action-abort | Abort task | error_count>MAX | status=failed |
+
+## Action Dependencies Graph
+
+```mermaid
+graph TD
+    INIT[action-init] --> PROCESS[action-process]
+    PROCESS --> PROCESS
+    PROCESS --> REVIEW[action-review]
+    REVIEW --> PROCESS
+    REVIEW --> COMPLETE[action-complete]
+    PROCESS --> ABORT[action-abort]
+```
+```
+
+### Applicable Scenarios
+
+- **Interactive Tasks**: Q&A, dialog, form filling
+- **State Machine Tasks**: Issue management, workflow approval
+- **Exploratory Tasks**: Debugging, diagnosis, search
+
+### Advantages
+
+- Highly flexible, adapts to dynamic requirements
+- Supports complex branching logic
+- Easy to extend with new actions
+
+### Disadvantages
+
+- High complexity
+- State management overhead
+- Large debugging difficulty
+
+---
+
+## Mode Selection Guide
+
+### Decision Flow
+
+```
+Analyze user requirements
+     │
+     ▼
+┌────────────────────────────┐
+│ Are there strong           │
+│ dependencies between       │
+│ phases?                    │
+└────────────────────────────┘
+     │
+     ├── Yes → Sequential
+     │
+     └── No → Continue decision
+              │
+              ▼
+     ┌────────────────────────────┐
+     │ Do you need dynamic         │
+     │ response to user intent?    │
+     └────────────────────────────┘
+              │
+              ├── Yes → Autonomous
+              │
+              └── No → Sequential
+```
+
+### Quick Decision Table
+
+| Question | Sequential | Autonomous |
+|----------|------------|------------|
+| Is output structure fixed? | Yes | No |
+| Do you need multi-turn user interaction? | No | Yes |
+| Can phases be skipped/repeated? | No | Yes |
+| Is there complex branching logic? | No | Yes |
+| Should debugging be simple? | Yes | No |
+
+---
+
+## Hybrid Mode
+
+Some complex Skills may need to use both modes in combination:
+
+```
+phases/
+├── 01-init.md                 # Sequential: initialization
+├── 02-orchestrator.md         # Autonomous: core interaction loop
+│   └── actions/
+│       ├── action-a.md
+│       └── action-b.md
+└── 03-finalize.md             # Sequential: finalization
+```
+
+**Applicable Scenarios**:
+- Initialization and finalization are fixed, middle interaction is flexible
+- Multi-phase tasks where certain phases need dynamic decisions

package/.claude/skills/skill-generator/specs/reference-docs-spec.md

@@ -0,0 +1,271 @@
+# Reference Documents Generation Specification
+
+> **IMPORTANT**: This specification defines how to organize and present reference documents in generated skills to avoid duplication issues.
+
+## Core Principles
+
+### 1. Phase-Based Organization
+
+Reference documents must be organized by skill execution phases, not as a flat list.
+
+**Wrong Approach** (Flat List):
+```markdown
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| doc1.md | ... |
+| doc2.md | ... |
+| doc3.md | ... |
+```
+
+**Correct Approach** (Phase-Based Navigation):
+```markdown
+## Reference Documents by Phase
+
+### Phase 1: Analysis
+Documents to refer to when executing Phase 1
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| doc1.md | ... | Understand concept x |
+
+### Phase 2: Implementation
+Documents to refer to when executing Phase 2
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| doc2.md | ... | Implement feature y |
+```
+
+### 2. Four Standard Groupings
+
+Reference documents must be divided into the following four groupings:
+
+| Grouping | When to Use | Content |
+|----------|------------|---------|
+| **Phase N: [Name]** | When executing this phase | All documents related to this phase |
+| **Debugging** | When encountering problems | Issue to documentation mapping table |
+| **Reference** | When learning in depth | Templates, original implementations, best practices |
+| (Optional) **Quick Links** | Quick navigation | Most frequently consulted 5-7 documents |
+
+### 3. Each Document Entry Must Include
+
+```
+| [path](path) | Purpose | When to Use |
+```
+
+**When to Use Column Requirements**:
+- Clear explanation of usage scenarios
+- Describe what problem is solved
+- Do not simply say "refer to" or "learn about"
+
+**Good Examples**:
+- "Understand issue data structure"
+- "Learn about the Planning Agent role"
+- "Check if implementation meets quality standards"
+- "Quickly locate the reason for status anomalies"
+
+**Poor Examples**:
+- "Reference document"
+- "More information"
+- "Background knowledge"
+
+### 4. Embedding Document Guidance in Execution Flow
+
+In the "Execution Flow" section, each Phase description should include "Refer to" hints:
+
+```markdown
+### Phase 2: Planning Pipeline
+→ **Refer to**: action-plan.md, subagent-roles.md
+→ Detailed flow description...
+```
+
+### 5. Quick Troubleshooting Reference Table
+
+Should contain common issue to documentation mapping:
+
+```markdown
+### Debugging & Troubleshooting
+
+| Issue | Solution Document |
+|-------|------------------|
+| Phase execution failed | Refer to corresponding phase documentation |
+| Output format incorrect | specs/quality-standards.md |
+| Data validation failed | specs/schema-validation.md |
+```
+
+---
+
+## Generation Rules
+
+### Rule 1: Document Classification Recognition
+
+Automatically generate groupings based on skill phases:
+
+```javascript
+const phaseEmojis = {
+  'discovery': '📋',      // Collection, exploration
+  'generation': '🔧',     // Generation, creation
+  'analysis': '🔍',       // Analysis, review
+  'implementation': '⚙️', // Implementation, execution
+  'validation': '✅',     // Validation, testing
+  'completion': '🏁',     // Completion, wrap-up
+};
+
+// Generate a section for each phase
+phases.forEach((phase, index) => {
+  const emoji = phaseEmojis[phase.type] || '📌';
+  const title = `### ${emoji} Phase ${index + 1}: ${phase.name}`;
+  // List all documents related to this phase
+});
+```
+
+### Rule 2: Document to Phase Mapping
+
+In config, specs and templates should be annotated with their belonging phases:
+
+```json
+{
+  "specs": [
+    {
+      "path": "specs/issue-handling.md",
+      "purpose": "Issue data specification",
+      "phases": ["phase-2", "phase-3"],  // Which phases this spec is related to
+      "context": "Understand issue structure and validation rules"
+    }
+  ]
+}
+```
+
+### Rule 3: Priority and Mandatory Reading
+
+Use visual symbols to distinguish document importance:
+
+```markdown
+| Document | When | Notes |
+|----------|------|-------|
+| spec.md | **Must Read Before Execution** | Mandatory prerequisite |
+| action.md | Refer to during execution | Operation guide |
+| template.md | Reference for learning | Optional in-depth |
+```
+
+### Rule 4: Avoid Duplication
+
+- **Mandatory Prerequisites** section: List mandatory P0 specifications
+- **Reference Documents by Phase** section: List all documents (including mandatory prerequisites)
+- Documents in both sections can overlap, but their purposes differ:
+  - Prerequisites: Emphasize "must read first"
+  - Reference: Provide "complete navigation"
+
+---
+
+## Implementation Example
+
+### Sequential Skill Example
+
+```markdown
+## Mandatory Prerequisites
+
+| Document | Purpose | When |
+|----------|---------|------|
+| [specs/issue-handling.md](specs/issue-handling.md) | Issue data specification | **Must Read Before Execution** |
+| [specs/solution-schema.md](specs/solution-schema.md) | Solution structure | **Must Read Before Execution** |
+
+---
+
+## Reference Documents by Phase
+
+### Phase 1: Issue Collection
+Documents to refer to when executing Phase 1
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/actions/action-list.md](phases/actions/action-list.md) | Issue loading logic | Understand how to collect issues |
+| [specs/issue-handling.md](specs/issue-handling.md) | Issue data specification | Verify issue format **Required Reading** |
+
+### Phase 2: Planning
+Documents to refer to when executing Phase 2
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/actions/action-plan.md](phases/actions/action-plan.md) | Planning process | Understand issue to solution transformation |
+| [specs/solution-schema.md](specs/solution-schema.md) | Solution structure | Verify solution JSON format **Required Reading** |
+
+### Debugging & Troubleshooting
+
+| Issue | Solution Document |
+|-------|------------------|
+| Phase 1 failed | [phases/actions/action-list.md](phases/actions/action-list.md) |
+| Planning output incorrect | [phases/actions/action-plan.md](phases/actions/action-plan.md) + [specs/solution-schema.md](specs/solution-schema.md) |
+| Data validation failed | [specs/issue-handling.md](specs/issue-handling.md) |
+
+### Reference & Background
+
+| Document | Purpose | Notes |
+|----------|---------|-------|
+| [../issue-plan.md](../../.codex/prompts/issue-plan.md) | Original implementation | Planning Agent system prompt |
+```
+
+---
+
+## Generation Algorithm
+
+```javascript
+function generateReferenceDocuments(config) {
+  let result = '## Reference Documents by Phase\n\n';
+
+  // Generate a section for each phase
+  const phases = config.phases || config.actions || [];
+
+  phases.forEach((phase, index) => {
+    const phaseNum = index + 1;
+    const emoji = getPhaseEmoji(phase.type);
+    const title = phase.display_name || phase.name;
+
+    result += `### ${emoji} Phase ${phaseNum}: ${title}\n`;
+    result += `Documents to refer to when executing Phase ${phaseNum}\n\n`;
+
+    // Find all documents related to this phase
+    const docs = config.specs.filter(spec =>
+      (spec.phases || []).includes(`phase-${phaseNum}`) ||
+      matchesByName(spec.path, phase.name)
+    );
+
+    if (docs.length > 0) {
+      result += '| Document | Purpose | When to Use |\n';
+      result += '|----------|---------|-------------|\n';
+      docs.forEach(doc => {
+        const required = doc.phases && doc.phases[0] === `phase-${phaseNum}` ? ' **Required Reading**' : '';
+        result += `| [${doc.path}](${doc.path}) | ${doc.purpose} | ${doc.context}${required} |\n`;
+      });
+      result += '\n';
+    }
+  });
+
+  // Troubleshooting section
+  result += '### Debugging & Troubleshooting\n\n';
+  result += generateDebuggingTable(config);
+
+  // In-depth reference learning
+  result += '### Reference & Background\n\n';
+  result += generateReferenceTable(config);
+
+  return result;
+}
+```
+
+---
+
+## Checklist
+
+When generating skill's SKILL.md, the reference documents section should satisfy:
+
+- [ ] Has clear "## Reference Documents by Phase" heading
+- [ ] Each phase has a corresponding section (identified with symbols)
+- [ ] Each document entry includes "When to Use" column
+- [ ] Includes "Debugging & Troubleshooting" section
+- [ ] Includes "Reference & Background" section
+- [ ] Mandatory reading documents are marked with **bold** text
+- [ ] Execution Flow section includes "→ **Refer to**: ..." guidance
+- [ ] Avoid overly long document lists (maximum 5-8 documents per phase)