maestro-flow 0.5.36 → 0.5.37

package/.agents/skills/skill-generator/SKILL.md

@@ -5,469 +5,469 @@ allowed-tools: delegate_subagent, ask_user, read_file, shell, find_files, search
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-
-# Skill Generator
-
-Meta-skill for creating new Claude Code skills with configurable execution modes.
-
-## Pre-load (before execution)
-
-1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
-2. **Specs**: `maestro spec load --category coding` — load coding conventions
-3. **Wiki knowledge**: `maestro search "skill design optimization" --json` — top 5 entries as prior context
-4. All optional — proceed without if unavailable
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    Skill Generator                               │
-│                                                                  │
-│  Input: User Request (skill name, purpose, mode)                │
-│                         ↓                                        │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │  Phase 0-5: Sequential Pipeline                          │    │
-│  │  ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐             │    │
-│  │  │ P0 │→│ P1 │→│ P2 │→│ P3 │→│ P4 │→│ P5 │             │    │
-│  │  │Spec│ │Req │ │Dir │ │Gen │ │Spec│ │Val │             │    │
-│  │  └────┘ └────┘ └────┘ └─┬──┘ └────┘ └────┘             │    │
-│  │                         │                                │    │
-│  │                    ┌────┴────┐                           │    │
-│  │                    ↓         ↓                           │    │
-│  │              Sequential  Autonomous                      │    │
-│  │              (phases/)   (actions/)                      │    │
-│  └─────────────────────────────────────────────────────────┘    │
-│                         ↓                                        │
-│  Output: .claude/skills/{skill-name}/ (complete package)        │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Execution Modes
-
-### Mode 1: Sequential (Fixed Order)
-
-Traditional linear execution model, phases execute in numeric prefix order.
-
-```
-Phase 01 -> Phase 02 -> Phase 03 -> ... -> Phase N
-```
-
-**Use Cases**:
-- Pipeline tasks (collect -> analyze -> generate)
-- Strong dependencies between phases
-- Fixed output structure
-
-**Examples**: `software-manual`, `copyright-docs`
-
-### Mode 2: Autonomous (Stateless Auto-Select)
-
-Intelligent routing model, dynamically selects execution path based on context.
-
-```
----------------------------------------------------
-                Orchestrator delegate_subagent(Read state -> Select Phase -> Execute -> Update)
----------------------------------------------------
-                |
-    ---------+----------+----------
-    |        |          |
-  Phase A   Phase B    Phase C
-  (standalone)  (standalone)  (standalone)
-```
-
-**Use Cases**:
-- Interactive tasks (chat, Q&A)
-- No strong dependencies between phases
-- Dynamic user intent response required
-
-**Examples**: `issue-manage`, `workflow-debug`
-
-## Key Design Principles
-
-1. **Mode Awareness**: Automatically recommend execution mode based on task characteristics
-2. **Skeleton Generation**: Generate complete directory structure and file skeletons
-3. **Standards Compliance**: Strictly follow `_shared/SKILL-DESIGN-SPEC.md`
-4. **Extensibility**: Generated Skills are easy to extend and modify
-
----
-
-## Required Prerequisites
-
-IMPORTANT: Before any generation operation, read the following specification documents. Generating without understanding these standards will result in non-conforming output.
-
-### Core Specifications (Mandatory Read)
-
-| Document | Purpose | Priority |
-|----------|---------|----------|
-| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Universal design spec - defines structure, naming, quality standards for all Skills | **P0 - Critical** |
-| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document generation spec - ensures generated Skills have proper phase-based Reference Documents with usage timing guidance | **P0 - Critical** |
-
-### Template Files (Read Before Generation)
-
-| Document | Purpose |
-|----------|---------|
-| [templates/skill-md.md](templates/skill-md.md) | SKILL.md entry file template |
-| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase template |
-| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Autonomous Orchestrator template |
-| [templates/autonomous-action.md](templates/autonomous-action.md) | Autonomous Action template |
-| [templates/code-analysis-action.md](templates/code-analysis-action.md) | Code Analysis Action template |
-| [templates/llm-action.md](templates/llm-action.md) | LLM Action template |
-| [templates/script-template.md](templates/script-template.md) | Unified Script Template (Bash + Python) |
-
-### Specification Documents (Read as Needed)
-
-| Document | Purpose |
-|----------|---------|
-| [specs/execution-modes.md](specs/execution-modes.md) | Execution Modes Specification |
-| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill Requirements Specification |
-| [specs/cli-integration.md](specs/cli-integration.md) | CLI Integration Specification |
-| [specs/scripting-integration.md](specs/scripting-integration.md) | Script Integration Specification |
-
-### Phase Execution Guides (Reference During Execution)
-
-| Document | Purpose |
-|----------|---------|
-| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Collect Skill Requirements |
-| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Generate Directory Structure |
-| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Generate Phase Files |
-| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Generate Specs and Templates |
-| [phases/05-validation.md](phases/05-validation.md) | Validation and Documentation |
-
----
-
-## Execution Flow
-
-```
-Input Parsing:
-   └─ Convert user request to structured format (skill-name/purpose/mode)
-
-Phase 0: Specification Study (MANDATORY - Must complete before proceeding)
-   - Read specification documents
-   - Load: ../_shared/SKILL-DESIGN-SPEC.md
-   - Load: All templates/*.md files
-   - Understand: Structure rules, naming conventions, quality standards
-   - Output: Internalized requirements (in-memory, no file output)
-   - Validation: MUST complete before Phase 1
-
-Phase 1: Requirements Discovery
-   - Gather skill requirements via user interaction
-   - Tool: ask_user
-   - Collect: Skill name, purpose, execution mode
-   - Collect: Phase/Action definition
-   - Collect: Tool dependencies, output format
-   - Process: Generate configuration object
-   - Output: skill-config.json
-   - Contains: skill_name, execution_mode, phases/actions, allowed_tools
-
-Phase 2: Structure Generation
-   - Create directory structure and entry file
-   - Input: skill-config.json (from Phase 1)
-   - Tool: Bash
-   - Execute: mkdir -p .claude/skills/{skill-name}/{phases,specs,templates,scripts}
-   - Tool: Write
-   - Generate: SKILL.md (entry point with architecture diagram)
-   - Output: Complete directory structure
-
-Phase 3: Phase/Action Generation
-   - Decision (execution_mode check):
-   - IF execution_mode === "sequential": Generate Sequential Phases
-   - Read template: templates/sequential-phase.md
-   - Loop: For each phase in config.sequential_config.phases
-   - Generate: phases/{phase-id}.md
-   - Link: Previous phase output -> Current phase input
-   - Write: phases/_orchestrator.md
-   - Write: workflow.json
-   - Output: phases/01-{name}.md, phases/02-{name}.md, ...
-
-   - ELSE IF execution_mode === "autonomous": Generate Orchestrator + Actions
-   - Read template: templates/autonomous-orchestrator.md
-   - Write: phases/state-schema.md
-   - Write: phases/orchestrator.md
-   - Write: specs/action-catalog.md
-   - Loop: For each action in config.autonomous_config.actions
-   - Read template: templates/autonomous-action.md
-   - Generate: phases/actions/{action-id}.md
-   - Output: phases/orchestrator.md, phases/actions/*.md
-
-Phase 4: Specs & Templates
-   - Generate domain specifications and templates
-   - Input: skill-config.json (domain context)
-   - Reference: [specs/reference-docs-spec.md](specs/reference-docs-spec.md) for document organization
-   - Tool: Write
-   - Generate: specs/{domain}-requirements.md
-   - Generate: specs/quality-standards.md
-   - Generate: templates/agent-base.md (if needed)
-   - Output: Domain-specific documentation
-
-Phase 5: Validation & Documentation
-   - Verify completeness and generate usage guide
-   - Input: All generated files from previous phases
-   - Tool: Glob + Read
-   - Check: Required files exist and contain proper structure
-   - Tool: Write
-   - Generate: README.md (usage instructions)
-   - Generate: validation-report.json (completeness check)
-   - Output: Final documentation
-```
-
-**Execution Protocol**:
-
-```javascript
-// Phase 0: Read specifications (in-memory)
-read_file('.claude/skills/_shared/SKILL-DESIGN-SPEC.md');
-read_file('.claude/skills/skill-generator/templates/*.md'); // All templates
-
-// Phase 1: Gather requirements
-const answers = ask_user({
-  questions: [
-    { question: "Skill name?", header: "Name", options: [...] },
-    { question: "Execution mode?", header: "Mode", options: ["Sequential", "Autonomous"] }
-  ]
-});
-
-const config = generateConfig(answers);
-const workDir = `.workflow/.scratchpad/skill-gen-${timestamp}`;
-write_file(`${workDir}/skill-config.json`, JSON.stringify(config));
-
-// Phase 2: Create structure
-const skillDir = `.claude/skills/${config.skill_name}`;
-shell(`mkdir -p "${skillDir}/phases" "${skillDir}/specs" "${skillDir}/templates"`);
-write_file(`${skillDir}/SKILL.md`, generateSkillEntry(config));
-
-// Phase 3: Generate phases (mode-dependent)
-if (config.execution_mode === 'sequential') {
-  write_file(`${skillDir}/phases/_orchestrator.md`, generateOrchestrator(config));
-  write_file(`${skillDir}/workflow.json`, generateWorkflowDef(config));
-  config.sequential_config.phases.forEach(phase => {
-    write_file(`${skillDir}/phases/${phase.id}.md`, generatePhase(phase, config));
-  });
-} else {
-  write_file(`${skillDir}/phases/orchestrator.md`, generateAutonomousOrchestrator(config));
-  write_file(`${skillDir}/phases/state-schema.md`, generateStateSchema(config));
-  config.autonomous_config.actions.forEach(action => {
-    write_file(`${skillDir}/phases/actions/${action.id}.md`, generateAction(action, config));
-  });
-}
-
-// Phase 4: Generate specs
-write_file(`${skillDir}/specs/${config.skill_name}-requirements.md`, generateRequirements(config));
-write_file(`${skillDir}/specs/quality-standards.md`, generateQualityStandards(config));
-
-
-// Phase 5: Validate & Document
-const validation = validateStructure(skillDir);
-write_file(`${skillDir}/validation-report.json`, JSON.stringify(validation));
-write_file(`${skillDir}/README.md`, generateReadme(config, validation));
-```
-
----
-
-
-## Reference Documents by Phase
-
-IMPORTANT: This section demonstrates how skill-generator organizes its own reference documentation. This is the pattern that all generated Skills should emulate. See [specs/reference-docs-spec.md](specs/reference-docs-spec.md) for details.
-
-### Phase 0: Specification Study (Mandatory Prerequisites)
-
-Specification documents that must be read before any generation operation
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Universal Skill design specification | Understand Skill structure and naming conventions - **REQUIRED** |
-| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document generation specification | Ensure Reference Documents have proper phase-based organization - **REQUIRED** |
-
-### Phase 1: Requirements Discovery
-
-Collect Skill requirements and configuration
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1 execution guide | Understand how to collect user requirements and generate configuration |
-| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill requirements specification | Understand what information a Skill should contain |
-
-### Phase 2: Structure Generation
-
-Generate directory structure and entry file
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2 execution guide | Understand how to generate directory structure |
-| [templates/skill-md.md](templates/skill-md.md) | SKILL.md template | Learn how to generate the entry file |
-
-### Phase 3: Phase/Action Generation
-
-Generate specific phase or action files based on execution mode
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3 execution guide | Understand Sequential vs Autonomous generation logic |
-| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase template | Generate phase files for Sequential mode |
-| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator template | Generate orchestrator for Autonomous mode |
-| [templates/autonomous-action.md](templates/autonomous-action.md) | Action template | Generate action files for Autonomous mode |
-
-### Phase 4: Specs & Templates
-
-Generate domain-specific specifications and templates
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4 execution guide | Understand how to generate domain-specific documentation |
-| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document specification | IMPORTANT: Follow this spec when generating Specs |
-
-### Phase 5: Validation & Documentation
-
-Verify results and generate final documentation
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/05-validation.md](phases/05-validation.md) | Phase 5 execution guide | Understand how to verify generated Skill completeness |
-
-### Debugging & Troubleshooting
-
-Reference documents when encountering issues
-
-| Issue | Solution Document |
-|-------|------------------|
-| Generated Skill missing Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - verify phase-based organization is followed |
-| Reference document organization unclear | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - Core Principles section |
-| Generated documentation does not meet quality standards | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) |
-
-### Reference & Background
-
-Documents for deep learning and design decisions
-
-| Document | Purpose | Notes |
-|----------|---------|-------|
-| [specs/execution-modes.md](specs/execution-modes.md) | Detailed execution modes specification | Comparison and use cases for Sequential vs Autonomous |
-| [specs/cli-integration.md](specs/cli-integration.md) | CLI integration specification | How generated Skills integrate with CLI |
-| [specs/scripting-integration.md](specs/scripting-integration.md) | Script integration specification | How to use scripts in Phases |
-| [templates/script-template.md](templates/script-template.md) | Script template | Unified Bash + Python template |
-
----
-
-## Output Structure
-
-### Sequential Mode
-
-```
-.claude/skills/{skill-name}/
-├── SKILL.md                        # Entry file
-├── phases/
-│   ├── _orchestrator.md            # Declarative orchestrator
-│   ├── workflow.json               # Workflow definition
-│   ├── 01-{step-one}.md           # Phase 1
-│   ├── 02-{step-two}.md           # Phase 2
-│   └── 03-{step-three}.md         # Phase 3
-├── specs/
-│   ├── {skill-name}-requirements.md
-│   └── quality-standards.md
-├── templates/
-│   └── agent-base.md
-├── scripts/
-└── README.md
-```
-
-### Autonomous Mode
-
-```
-.claude/skills/{skill-name}/
-├── SKILL.md                        # Entry file
-├── phases/
-│   ├── orchestrator.md             # Orchestrator (state-driven)
-│   ├── state-schema.md             # State schema definition
-│   └── actions/
-│       ├── action-init.md
-│       ├── action-create.md
-│       └── action-list.md
-├── specs/
-│   ├── {skill-name}-requirements.md
-│   ├── action-catalog.md
-│   └── quality-standards.md
-├── templates/
-│   ├── orchestrator-base.md
-│   └── action-base.md
-├── scripts/
-└── README.md
-```
-
----
-
-## Reference Documents by Phase
-
-IMPORTANT: This section demonstrates how skill-generator organizes its own reference documentation. This is the pattern that all generated Skills should emulate. See [specs/reference-docs-spec.md](specs/reference-docs-spec.md) for details.
-
-### Phase 0: Specification Study (Mandatory Prerequisites)
-
-Specification documents that must be read before any generation operation
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Universal Skill design specification | Understand Skill structure and naming conventions - **REQUIRED** |
-| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document generation specification | Ensure Reference Documents have proper phase-based organization - **REQUIRED** |
-
-### Phase 1: Requirements Discovery
-
-Collect Skill requirements and configuration
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1 execution guide | Understand how to collect user requirements and generate configuration |
-| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill requirements specification | Understand what information a Skill should contain |
-
-### Phase 2: Structure Generation
-
-Generate directory structure and entry file
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2 execution guide | Understand how to generate directory structure |
-| [templates/skill-md.md](templates/skill-md.md) | SKILL.md template | Learn how to generate the entry file |
-
-### Phase 3: Phase/Action Generation
-
-Generate specific phase or action files based on execution mode
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3 execution guide | Understand Sequential vs Autonomous generation logic |
-| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase template | Generate phase files for Sequential mode |
-| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator template | Generate orchestrator for Autonomous mode |
-| [templates/autonomous-action.md](templates/autonomous-action.md) | Action template | Generate action files for Autonomous mode |
-
-### Phase 4: Specs & Templates
-
-Generate domain-specific specifications and templates
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4 execution guide | Understand how to generate domain-specific documentation |
-| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document specification | IMPORTANT: Follow this spec when generating Specs |
-
-### Phase 5: Validation & Documentation
-
-Verify results and generate final documentation
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [phases/05-validation.md](phases/05-validation.md) | Phase 5 execution guide | Understand how to verify generated Skill completeness |
-
-### Debugging & Troubleshooting
-
-Reference documents when encountering issues
-
-| Issue | Solution Document |
-|-------|------------------|
-| Generated Skill missing Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - verify phase-based organization is followed |
-| Reference document organization unclear | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - Core Principles section |
-| Generated documentation does not meet quality standards | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) |
-
-### Reference & Background
-
-Documents for deep learning and design decisions
-
-| Document | Purpose | Notes |
-|----------|---------|-------|
-| [specs/execution-modes.md](specs/execution-modes.md) | Detailed execution modes specification | Comparison and use cases for Sequential vs Autonomous |
-| [specs/cli-integration.md](specs/cli-integration.md) | CLI integration specification | How generated Skills integrate with CLI |
-| [specs/scripting-integration.md](specs/scripting-integration.md) | Script integration specification | How to use scripts in Phases |
+
+# Skill Generator
+
+Meta-skill for creating new Claude Code skills with configurable execution modes.
+
+## Pre-load (before execution)
+
+1. **Codebase docs**: If `.workflow/codebase/ARCHITECTURE.md` exists, read for project context
+2. **Specs**: `maestro load --type spec --category coding` — load coding conventions
+3. **Wiki knowledge**: `maestro search "skill design optimization" --json` — top 5 entries as prior context
+4. All optional — proceed without if unavailable
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Skill Generator                               │
+│                                                                  │
+│  Input: User Request (skill name, purpose, mode)                │
+│                         ↓                                        │
+│  ┌─────────────────────────────────────────────────────────┐    │
+│  │  Phase 0-5: Sequential Pipeline                          │    │
+│  │  ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐             │    │
+│  │  │ P0 │→│ P1 │→│ P2 │→│ P3 │→│ P4 │→│ P5 │             │    │
+│  │  │Spec│ │Req │ │Dir │ │Gen │ │Spec│ │Val │             │    │
+│  │  └────┘ └────┘ └────┘ └─┬──┘ └────┘ └────┘             │    │
+│  │                         │                                │    │
+│  │                    ┌────┴────┐                           │    │
+│  │                    ↓         ↓                           │    │
+│  │              Sequential  Autonomous                      │    │
+│  │              (phases/)   (actions/)                      │    │
+│  └─────────────────────────────────────────────────────────┘    │
+│                         ↓                                        │
+│  Output: .claude/skills/{skill-name}/ (complete package)        │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Execution Modes
+
+### Mode 1: Sequential (Fixed Order)
+
+Traditional linear execution model, phases execute in numeric prefix order.
+
+```
+Phase 01 -> Phase 02 -> Phase 03 -> ... -> Phase N
+```
+
+**Use Cases**:
+- Pipeline tasks (collect -> analyze -> generate)
+- Strong dependencies between phases
+- Fixed output structure
+
+**Examples**: `software-manual`, `copyright-docs`
+
+### Mode 2: Autonomous (Stateless Auto-Select)
+
+Intelligent routing model, dynamically selects execution path based on context.
+
+```
+---------------------------------------------------
+                Orchestrator delegate_subagent(Read state -> Select Phase -> Execute -> Update)
+---------------------------------------------------
+                |
+    ---------+----------+----------
+    |        |          |
+  Phase A   Phase B    Phase C
+  (standalone)  (standalone)  (standalone)
+```
+
+**Use Cases**:
+- Interactive tasks (chat, Q&A)
+- No strong dependencies between phases
+- Dynamic user intent response required
+
+**Examples**: `issue-manage`, `workflow-debug`
+
+## Key Design Principles
+
+1. **Mode Awareness**: Automatically recommend execution mode based on task characteristics
+2. **Skeleton Generation**: Generate complete directory structure and file skeletons
+3. **Standards Compliance**: Strictly follow `_shared/SKILL-DESIGN-SPEC.md`
+4. **Extensibility**: Generated Skills are easy to extend and modify
+
+---
+
+## Required Prerequisites
+
+IMPORTANT: Before any generation operation, read the following specification documents. Generating without understanding these standards will result in non-conforming output.
+
+### Core Specifications (Mandatory Read)
+
+| Document | Purpose | Priority |
+|----------|---------|----------|
+| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Universal design spec - defines structure, naming, quality standards for all Skills | **P0 - Critical** |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document generation spec - ensures generated Skills have proper phase-based Reference Documents with usage timing guidance | **P0 - Critical** |
+
+### Template Files (Read Before Generation)
+
+| Document | Purpose |
+|----------|---------|
+| [templates/skill-md.md](templates/skill-md.md) | SKILL.md entry file template |
+| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase template |
+| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Autonomous Orchestrator template |
+| [templates/autonomous-action.md](templates/autonomous-action.md) | Autonomous Action template |
+| [templates/code-analysis-action.md](templates/code-analysis-action.md) | Code Analysis Action template |
+| [templates/llm-action.md](templates/llm-action.md) | LLM Action template |
+| [templates/script-template.md](templates/script-template.md) | Unified Script Template (Bash + Python) |
+
+### Specification Documents (Read as Needed)
+
+| Document | Purpose |
+|----------|---------|
+| [specs/execution-modes.md](specs/execution-modes.md) | Execution Modes Specification |
+| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill Requirements Specification |
+| [specs/cli-integration.md](specs/cli-integration.md) | CLI Integration Specification |
+| [specs/scripting-integration.md](specs/scripting-integration.md) | Script Integration Specification |
+
+### Phase Execution Guides (Reference During Execution)
+
+| Document | Purpose |
+|----------|---------|
+| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Collect Skill Requirements |
+| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Generate Directory Structure |
+| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Generate Phase Files |
+| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Generate Specs and Templates |
+| [phases/05-validation.md](phases/05-validation.md) | Validation and Documentation |
+
+---
+
+## Execution Flow
+
+```
+Input Parsing:
+   └─ Convert user request to structured format (skill-name/purpose/mode)
+
+Phase 0: Specification Study (MANDATORY - Must complete before proceeding)
+   - Read specification documents
+   - Load: ../_shared/SKILL-DESIGN-SPEC.md
+   - Load: All templates/*.md files
+   - Understand: Structure rules, naming conventions, quality standards
+   - Output: Internalized requirements (in-memory, no file output)
+   - Validation: MUST complete before Phase 1
+
+Phase 1: Requirements Discovery
+   - Gather skill requirements via user interaction
+   - Tool: ask_user
+   - Collect: Skill name, purpose, execution mode
+   - Collect: Phase/Action definition
+   - Collect: Tool dependencies, output format
+   - Process: Generate configuration object
+   - Output: skill-config.json
+   - Contains: skill_name, execution_mode, phases/actions, allowed_tools
+
+Phase 2: Structure Generation
+   - Create directory structure and entry file
+   - Input: skill-config.json (from Phase 1)
+   - Tool: Bash
+   - Execute: mkdir -p .claude/skills/{skill-name}/{phases,specs,templates,scripts}
+   - Tool: Write
+   - Generate: SKILL.md (entry point with architecture diagram)
+   - Output: Complete directory structure
+
+Phase 3: Phase/Action Generation
+   - Decision (execution_mode check):
+   - IF execution_mode === "sequential": Generate Sequential Phases
+   - Read template: templates/sequential-phase.md
+   - Loop: For each phase in config.sequential_config.phases
+   - Generate: phases/{phase-id}.md
+   - Link: Previous phase output -> Current phase input
+   - Write: phases/_orchestrator.md
+   - Write: workflow.json
+   - Output: phases/01-{name}.md, phases/02-{name}.md, ...
+
+   - ELSE IF execution_mode === "autonomous": Generate Orchestrator + Actions
+   - Read template: templates/autonomous-orchestrator.md
+   - Write: phases/state-schema.md
+   - Write: phases/orchestrator.md
+   - Write: specs/action-catalog.md
+   - Loop: For each action in config.autonomous_config.actions
+   - Read template: templates/autonomous-action.md
+   - Generate: phases/actions/{action-id}.md
+   - Output: phases/orchestrator.md, phases/actions/*.md
+
+Phase 4: Specs & Templates
+   - Generate domain specifications and templates
+   - Input: skill-config.json (domain context)
+   - Reference: [specs/reference-docs-spec.md](specs/reference-docs-spec.md) for document organization
+   - Tool: Write
+   - Generate: specs/{domain}-requirements.md
+   - Generate: specs/quality-standards.md
+   - Generate: templates/agent-base.md (if needed)
+   - Output: Domain-specific documentation
+
+Phase 5: Validation & Documentation
+   - Verify completeness and generate usage guide
+   - Input: All generated files from previous phases
+   - Tool: Glob + Read
+   - Check: Required files exist and contain proper structure
+   - Tool: Write
+   - Generate: README.md (usage instructions)
+   - Generate: validation-report.json (completeness check)
+   - Output: Final documentation
+```
+
+**Execution Protocol**:
+
+```javascript
+// Phase 0: Read specifications (in-memory)
+read_file('.claude/skills/_shared/SKILL-DESIGN-SPEC.md');
+read_file('.claude/skills/skill-generator/templates/*.md'); // All templates
+
+// Phase 1: Gather requirements
+const answers = ask_user({
+  questions: [
+    { question: "Skill name?", header: "Name", options: [...] },
+    { question: "Execution mode?", header: "Mode", options: ["Sequential", "Autonomous"] }
+  ]
+});
+
+const config = generateConfig(answers);
+const workDir = `.workflow/.scratchpad/skill-gen-${timestamp}`;
+write_file(`${workDir}/skill-config.json`, JSON.stringify(config));
+
+// Phase 2: Create structure
+const skillDir = `.claude/skills/${config.skill_name}`;
+shell(`mkdir -p "${skillDir}/phases" "${skillDir}/specs" "${skillDir}/templates"`);
+write_file(`${skillDir}/SKILL.md`, generateSkillEntry(config));
+
+// Phase 3: Generate phases (mode-dependent)
+if (config.execution_mode === 'sequential') {
+  write_file(`${skillDir}/phases/_orchestrator.md`, generateOrchestrator(config));
+  write_file(`${skillDir}/workflow.json`, generateWorkflowDef(config));
+  config.sequential_config.phases.forEach(phase => {
+    write_file(`${skillDir}/phases/${phase.id}.md`, generatePhase(phase, config));
+  });
+} else {
+  write_file(`${skillDir}/phases/orchestrator.md`, generateAutonomousOrchestrator(config));
+  write_file(`${skillDir}/phases/state-schema.md`, generateStateSchema(config));
+  config.autonomous_config.actions.forEach(action => {
+    write_file(`${skillDir}/phases/actions/${action.id}.md`, generateAction(action, config));
+  });
+}
+
+// Phase 4: Generate specs
+write_file(`${skillDir}/specs/${config.skill_name}-requirements.md`, generateRequirements(config));
+write_file(`${skillDir}/specs/quality-standards.md`, generateQualityStandards(config));
+
+
+// Phase 5: Validate & Document
+const validation = validateStructure(skillDir);
+write_file(`${skillDir}/validation-report.json`, JSON.stringify(validation));
+write_file(`${skillDir}/README.md`, generateReadme(config, validation));
+```
+
+---
+
+
+## Reference Documents by Phase
+
+IMPORTANT: This section demonstrates how skill-generator organizes its own reference documentation. This is the pattern that all generated Skills should emulate. See [specs/reference-docs-spec.md](specs/reference-docs-spec.md) for details.
+
+### Phase 0: Specification Study (Mandatory Prerequisites)
+
+Specification documents that must be read before any generation operation
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Universal Skill design specification | Understand Skill structure and naming conventions - **REQUIRED** |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document generation specification | Ensure Reference Documents have proper phase-based organization - **REQUIRED** |
+
+### Phase 1: Requirements Discovery
+
+Collect Skill requirements and configuration
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1 execution guide | Understand how to collect user requirements and generate configuration |
+| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill requirements specification | Understand what information a Skill should contain |
+
+### Phase 2: Structure Generation
+
+Generate directory structure and entry file
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2 execution guide | Understand how to generate directory structure |
+| [templates/skill-md.md](templates/skill-md.md) | SKILL.md template | Learn how to generate the entry file |
+
+### Phase 3: Phase/Action Generation
+
+Generate specific phase or action files based on execution mode
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3 execution guide | Understand Sequential vs Autonomous generation logic |
+| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase template | Generate phase files for Sequential mode |
+| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator template | Generate orchestrator for Autonomous mode |
+| [templates/autonomous-action.md](templates/autonomous-action.md) | Action template | Generate action files for Autonomous mode |
+
+### Phase 4: Specs & Templates
+
+Generate domain-specific specifications and templates
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4 execution guide | Understand how to generate domain-specific documentation |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document specification | IMPORTANT: Follow this spec when generating Specs |
+
+### Phase 5: Validation & Documentation
+
+Verify results and generate final documentation
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/05-validation.md](phases/05-validation.md) | Phase 5 execution guide | Understand how to verify generated Skill completeness |
+
+### Debugging & Troubleshooting
+
+Reference documents when encountering issues
+
+| Issue | Solution Document |
+|-------|------------------|
+| Generated Skill missing Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - verify phase-based organization is followed |
+| Reference document organization unclear | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - Core Principles section |
+| Generated documentation does not meet quality standards | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) |
+
+### Reference & Background
+
+Documents for deep learning and design decisions
+
+| Document | Purpose | Notes |
+|----------|---------|-------|
+| [specs/execution-modes.md](specs/execution-modes.md) | Detailed execution modes specification | Comparison and use cases for Sequential vs Autonomous |
+| [specs/cli-integration.md](specs/cli-integration.md) | CLI integration specification | How generated Skills integrate with CLI |
+| [specs/scripting-integration.md](specs/scripting-integration.md) | Script integration specification | How to use scripts in Phases |
+| [templates/script-template.md](templates/script-template.md) | Script template | Unified Bash + Python template |
+
+---
+
+## Output Structure
+
+### Sequential Mode
+
+```
+.claude/skills/{skill-name}/
+├── SKILL.md                        # Entry file
+├── phases/
+│   ├── _orchestrator.md            # Declarative orchestrator
+│   ├── workflow.json               # Workflow definition
+│   ├── 01-{step-one}.md           # Phase 1
+│   ├── 02-{step-two}.md           # Phase 2
+│   └── 03-{step-three}.md         # Phase 3
+├── specs/
+│   ├── {skill-name}-requirements.md
+│   └── quality-standards.md
+├── templates/
+│   └── agent-base.md
+├── scripts/
+└── README.md
+```
+
+### Autonomous Mode
+
+```
+.claude/skills/{skill-name}/
+├── SKILL.md                        # Entry file
+├── phases/
+│   ├── orchestrator.md             # Orchestrator (state-driven)
+│   ├── state-schema.md             # State schema definition
+│   └── actions/
+│       ├── action-init.md
+│       ├── action-create.md
+│       └── action-list.md
+├── specs/
+│   ├── {skill-name}-requirements.md
+│   ├── action-catalog.md
+│   └── quality-standards.md
+├── templates/
+│   ├── orchestrator-base.md
+│   └── action-base.md
+├── scripts/
+└── README.md
+```
+
+---
+
+## Reference Documents by Phase
+
+IMPORTANT: This section demonstrates how skill-generator organizes its own reference documentation. This is the pattern that all generated Skills should emulate. See [specs/reference-docs-spec.md](specs/reference-docs-spec.md) for details.
+
+### Phase 0: Specification Study (Mandatory Prerequisites)
+
+Specification documents that must be read before any generation operation
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) | Universal Skill design specification | Understand Skill structure and naming conventions - **REQUIRED** |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document generation specification | Ensure Reference Documents have proper phase-based organization - **REQUIRED** |
+
+### Phase 1: Requirements Discovery
+
+Collect Skill requirements and configuration
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/01-requirements-discovery.md](phases/01-requirements-discovery.md) | Phase 1 execution guide | Understand how to collect user requirements and generate configuration |
+| [specs/skill-requirements.md](specs/skill-requirements.md) | Skill requirements specification | Understand what information a Skill should contain |
+
+### Phase 2: Structure Generation
+
+Generate directory structure and entry file
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/02-structure-generation.md](phases/02-structure-generation.md) | Phase 2 execution guide | Understand how to generate directory structure |
+| [templates/skill-md.md](templates/skill-md.md) | SKILL.md template | Learn how to generate the entry file |
+
+### Phase 3: Phase/Action Generation
+
+Generate specific phase or action files based on execution mode
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/03-phase-generation.md](phases/03-phase-generation.md) | Phase 3 execution guide | Understand Sequential vs Autonomous generation logic |
+| [templates/sequential-phase.md](templates/sequential-phase.md) | Sequential Phase template | Generate phase files for Sequential mode |
+| [templates/autonomous-orchestrator.md](templates/autonomous-orchestrator.md) | Orchestrator template | Generate orchestrator for Autonomous mode |
+| [templates/autonomous-action.md](templates/autonomous-action.md) | Action template | Generate action files for Autonomous mode |
+
+### Phase 4: Specs & Templates
+
+Generate domain-specific specifications and templates
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/04-specs-templates.md](phases/04-specs-templates.md) | Phase 4 execution guide | Understand how to generate domain-specific documentation |
+| [specs/reference-docs-spec.md](specs/reference-docs-spec.md) | Reference document specification | IMPORTANT: Follow this spec when generating Specs |
+
+### Phase 5: Validation & Documentation
+
+Verify results and generate final documentation
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [phases/05-validation.md](phases/05-validation.md) | Phase 5 execution guide | Understand how to verify generated Skill completeness |
+
+### Debugging & Troubleshooting
+
+Reference documents when encountering issues
+
+| Issue | Solution Document |
+|-------|------------------|
+| Generated Skill missing Reference Documents | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - verify phase-based organization is followed |
+| Reference document organization unclear | [specs/reference-docs-spec.md](specs/reference-docs-spec.md) - Core Principles section |
+| Generated documentation does not meet quality standards | [../_shared/SKILL-DESIGN-SPEC.md](../_shared/SKILL-DESIGN-SPEC.md) |
+
+### Reference & Background
+
+Documents for deep learning and design decisions
+
+| Document | Purpose | Notes |
+|----------|---------|-------|
+| [specs/execution-modes.md](specs/execution-modes.md) | Detailed execution modes specification | Comparison and use cases for Sequential vs Autonomous |
+| [specs/cli-integration.md](specs/cli-integration.md) | CLI integration specification | How generated Skills integrate with CLI |
+| [specs/scripting-integration.md](specs/scripting-integration.md) | Script integration specification | How to use scripts in Phases |
 | [templates/script-template.md](templates/script-template.md) | Script template | Unified Bash + Python template |