maestro-flow 0.5.36 → 0.5.37

package/.agy/skills/skill-generator/phases/04-specs-templates.md

@@ -1,398 +1,398 @@
-# Phase 4: Specifications & Templates Generation
-
-Generate domain requirements, quality standards, agent templates, and action catalogs.
-
-## Objective
-
-Generate comprehensive specifications and templates:
-- Domain requirements document with validation function
-- Quality standards with automated check system
-- Agent base template with prompt structure
-- Action catalog for autonomous mode (conditional)
-
-## Input
-
-**File Dependencies**:
-- `skill-config.json` (from Phase 1)
-- `.claude/skills/{skill-name}/` directory (from Phase 2)
-- Generated phase/action files (from Phase 3)
-
-**Required Information**:
-- Skill name, display name, description
-- Execution mode (determines if action-catalog.md is generated)
-- Output format and location
-- Phase/action definitions
-
-## Output
-
-**Generated Files**:
-
-| File | Purpose | Generation Condition |
-|------|---------|---------------------|
-| `specs/{skill-name}-requirements.md` | Domain requirements with validation | Always |
-| `specs/quality-standards.md` | Quality evaluation criteria | Always |
-| `templates/agent-base.md` | Agent prompt template | Always |
-| `specs/action-catalog.md` | Action dependency graph and selection priority | Autonomous/Hybrid mode only |
-
-**File Structure**:
-
-**Domain Requirements** (`specs/{skill-name}-requirements.md`):
-```markdown
-# {display_name} Requirements
-- When to Use (phase/action reference table)
-- Domain Requirements (Functional requirements, Output requirements, Quality requirements)
-- Validation Function (JavaScript code)
-- Error Handling (recovery strategies)
-```
-
-**Quality Standards** (`specs/quality-standards.md`):
-```markdown
-# Quality Standards
-- Quality Dimensions (Completeness 25%, Consistency 25%, Accuracy 25%, Usability 25%)
-- Quality Gates (Pass ≥80%, Review 60-79%, Fail <60%)
-- Issue Classification (Errors, Warnings, Info)
-- Automated Checks (runQualityChecks function)
-```
-
-**Agent Base** (`templates/agent-base.md`):
-```markdown
-# Agent Base Template
-- Universal Prompt Structure (ROLE, PROJECT CONTEXT, TASK, CONSTRAINTS, OUTPUT_FORMAT, QUALITY_CHECKLIST)
-- Variable Description (workDir, output_path)
-- Return Format (AgentReturn interface)
-- Role Definition Reference (phase/action specific agents)
-```
-
-**Action Catalog** (`specs/action-catalog.md`, Autonomous/Hybrid only):
-```markdown
-# Action Catalog
-- Available Actions (table with Purpose, Preconditions, Effects)
-- Action Dependencies (Mermaid diagram)
-- State Transitions (state machine table)
-- Selection Priority (ordered action list)
-```
-
-## Decision Logic
-
-```
-Decision (execution_mode check):
-   ├─ mode === 'sequential' → Generate 3 files only
-   │  └─ Files: requirements.md, quality-standards.md, agent-base.md
-   │
-   ├─ mode === 'autonomous' → Generate 4 files
-   │  ├─ Files: requirements.md, quality-standards.md, agent-base.md
-   │  └─ Additional: action-catalog.md (with action dependencies)
-   │
-   └─ mode === 'hybrid' → Generate 4 files
-      ├─ Files: requirements.md, quality-standards.md, agent-base.md
-      └─ Additional: action-catalog.md (with hybrid logic)
-```
-
-## Execution Protocol
-
-```javascript
-// Phase 4: Generate Specifications & Templates
-// Reference: phases/04-specs-templates.md
-
-// Load config and setup
-const config = JSON.parse(view_file(`${workDir}/skill-config.json`));
-const skillDir = `.claude/skills/${config.skill_name}`;
-
-// Ensure specs and templates directories exist (created in Phase 2)
-// skillDir structure: phases/, specs/, templates/
-
-// Step 1: Generate domain requirements
-const domainRequirements = `# ${config.display_name} Requirements
-
-${config.description}
-
-## When to Use
-
-| Phase | Usage | Reference |
-|-------|-------|-----------|
-${config.execution_mode === 'sequential' ?
-  config.sequential_config.phases.map((p, i) =>
-    `| Phase ${i+1} | ${p.name} | ${p.id}.md |`
-  ).join('\n') :
-  `| Orchestrator | Action selection | orchestrator.md |
-| Actions | Action execution | actions/*.md |`}
-
----
-
-## Domain Requirements
-
-### Functional Requirements
-
-- [ ] Requirement 1: TODO
-- [ ] Requirement 2: TODO
-- [ ] Requirement 3: TODO
-
-### Output Requirements
-
-- [ ] Format: ${config.output.format}
-- [ ] Location: ${config.output.location}
-- [ ] Naming: ${config.output.filename_pattern}
-
-### Quality Requirements
-
-- [ ] Completeness: All necessary content exists
-- [ ] Consistency: Terminology and format unified
-- [ ] Accuracy: Content based on actual analysis
-
-## Validation Function
-
-\`\`\`javascript
-function validate${toPascalCase(config.skill_name)}(output) {
-  const checks = [
-    // TODO: Add validation rules
-    { name: "Format correct", pass: output.format === "${config.output.format}" },
-    { name: "Content complete", pass: output.content?.length > 0 }
-  ];
-
-  return {
-    passed: checks.filter(c => c.pass).length,
-    total: checks.length,
-    details: checks
-  };
-}
-\`\`\`
-
-## Error Handling
-
-| Error | Recovery |
-|-------|----------|
-| Missing input data | Return clear error message |
-| Processing timeout | Reduce scope, retry |
-| Output validation failure | Log issue, manual review |
-`;
-
-write_to_file(`${skillDir}/specs/${config.skill_name}-requirements.md`, domainRequirements);
-
-// Step 2: Generate quality standards
-const qualityStandards = `# Quality Standards
-
-Quality assessment standards for ${config.display_name}.
-
-## Quality Dimensions
-
-### 1. Completeness (Completeness) - 25%
-
-| Requirement | Weight | Validation Method |
-|------------|--------|-----------------|
-| All necessary outputs exist | 10 | File check |
-| Content coverage complete | 10 | Content analysis |
-| No placeholder remnants | 5 | Text search |
-
-### 2. Consistency (Consistency) - 25%
-
-| Aspect | Check |
-|--------|-------|
-| Terminology | Use same term for same concept |
-| Format | Title levels, code block format consistent |
-| Style | Tone and expression unified |
-
-### 3. Accuracy (Accuracy) - 25%
-
-| Requirement | Description |
-|-------------|------------|
-| Data correct | References and data error-free |
-| Logic correct | Process and relationship descriptions accurate |
-| Code correct | Code examples runnable |
-
-### 4. Usability (Usability) - 25%
-
-| Metric | Goal |
-|--------|------|
-| Readability | Clear structure, easy to understand |
-| Navigability | Table of contents and links correct |
-| Operability | Steps clear, executable |
-
-## Quality Gates
-
-| Gate | Threshold | Action |
-|------|-----------|--------|
-| Pass | >= 80% | Output final deliverables |
-| Review | 60-79% | Process warnings then continue |
-| Fail | < 60% | Must fix |
-
-## Issue Classification
-
-### Errors (Must Fix)
-
-- Necessary output missing
-- Data error
-- Code not runnable
-
-### Warnings (Should Fix)
-
-- Format inconsistency
-- Content depth insufficient
-- Missing examples
-
-### Info (Nice to Have)
-
-- Optimization suggestions
-- Enhancement opportunities
-
-## Automated Checks
-
-\`\`\`javascript
-function runQualityChecks(workDir) {
-  const results = {
-    completeness: checkCompleteness(workDir),
-    consistency: checkConsistency(workDir),
-    accuracy: checkAccuracy(workDir),
-    usability: checkUsability(workDir)
-  };
-
-  results.overall = (
-    results.completeness * 0.25 +
-    results.consistency * 0.25 +
-    results.accuracy * 0.25 +
-    results.usability * 0.25
-  );
-
-  return {
-    score: results.overall,
-    gate: results.overall >= 80 ? 'pass' :
-          results.overall >= 60 ? 'review' : 'fail',
-    details: results
-  };
-}
-\`\`\`
-`;
-
-write_to_file(`${skillDir}/specs/quality-standards.md`, qualityStandards);
-
-// Step 3: Generate agent base template
-const agentBase = `# Agent Base Template
-
-Agent base template for ${config.display_name}.
-
-## Universal Prompt Structure
-
-\`\`\`
-[ROLE] You are {role}, focused on {responsibility}.
-
-[PROJECT CONTEXT]
-Skill: ${config.skill_name}
-Objective: ${config.description}
-
-[TASK]
-{task description}
-- Output: {output_path}
-- Format: ${config.output.format}
-
-[CONSTRAINTS]
-- Constraint 1
-- Constraint 2
-
-[OUTPUT_FORMAT]
-1. Execute task
-2. Return JSON summary information
-
-[QUALITY_CHECKLIST]
-- [ ] Output format correct
-- [ ] Content complete without omission
-- [ ] No placeholder remnants
-\`\`\`
-
-## Variable Description
-
-| Variable | Source | Example |
-|----------|--------|---------|
-| {workDir} | Runtime | .workflow/.scratchpad/${config.skill_name}-xxx |
-| {output_path} | Configuration | ${config.output.location}/${config.output.filename_pattern} |
-
-## Return Format
-
-\`\`\`typescript
-interface AgentReturn {
-  status: "completed" | "partial" | "failed";
-  output_file: string;
-  summary: string;  // Max 50 chars
-  stats?: {
-    items_processed?: number;
-    errors?: number;
-  };
-}
-\`\`\`
-
-## Role Definition Reference
-
-${config.execution_mode === 'sequential' ?
-  config.sequential_config.phases.map((p, i) =>
-    `- **Phase ${i+1} Agent**: ${p.name} Expert`
-  ).join('\n') :
-  config.autonomous_config.actions.map(a =>
-    `- **${a.name} Agent**: ${a.description || a.name + ' Executor'}`
-  ).join('\n')}
-`;
-
-write_to_file(`${skillDir}/templates/agent-base.md`, agentBase);
-
-// Step 4: Conditional - Generate action catalog for autonomous/hybrid mode
-if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
-  const actionCatalog = `# Action Catalog
-
-Available action catalog for ${config.display_name}.
-
-## Available Actions
-
-| Action | Purpose | Preconditions | Effects |
-|--------|---------|---------------|---------|
-${config.autonomous_config.actions.map(a =>
-  `| [${a.id}](../phases/actions/${a.id}.md) | ${a.description || a.name} | ${a.preconditions?.join(', ') || '-'} | ${a.effects?.join(', ') || '-'} |`
-).join('\n')}
-
-## Action Dependencies
-
-\`\`\`mermaid
-graph TD
-${config.autonomous_config.actions.map((a, i, arr) => {
-  if (i === 0) return \`    ${a.id.replace(/-/g, '_')}[${a.name}]\`;
-  const prev = arr[i-1];
-  return \`    ${prev.id.replace(/-/g, '_')} --> ${a.id.replace(/-/g, '_')}[${a.name}]\`;
-}).join('\n')}
-\`\`\`
-
-## State Transitions
-
-| From State | Action | To State |
-|------------|--------|----------|
-| pending | action-init | running |
-${config.autonomous_config.actions.slice(1).map(a =>
-  `| running | ${a.id} | running |`
-).join('\n')}
-| running | action-complete | completed |
-| running | action-abort | failed |
-
-## Selection Priority
-
-When multiple actions' preconditions are met, select based on the following priority:
-
-${config.autonomous_config.actions.map((a, i) =>
-  \`${i + 1}. \\\`${a.id}\\\` - ${a.name}\`
-).join('\n')}
-`;
-
-  write_to_file(`${skillDir}/specs/action-catalog.md`, actionCatalog);
-}
-
-// Helper function
-function toPascalCase(str) {
-  return str.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
-}
-
-// Phase output summary
-console.log('Phase 4 complete: Generated specs and templates');
-```
-
-## Next Phase
-
-→ [Phase 5: Validation](05-validation.md)
-
-**Data Flow to Phase 5**:
-- All generated files in `specs/` and `templates/`
-- skill-config.json for validation reference
-- Complete skill directory structure ready for final validation
+# Phase 4: Specifications & Templates Generation
+
+Generate domain requirements, quality standards, agent templates, and action catalogs.
+
+## Objective
+
+Generate comprehensive specifications and templates:
+- Domain requirements document with validation function
+- Quality standards with automated check system
+- Agent base template with prompt structure
+- Action catalog for autonomous mode (conditional)
+
+## Input
+
+**File Dependencies**:
+- `skill-config.json` (from Phase 1)
+- `.claude/skills/{skill-name}/` directory (from Phase 2)
+- Generated phase/action files (from Phase 3)
+
+**Required Information**:
+- Skill name, display name, description
+- Execution mode (determines if action-catalog.md is generated)
+- Output format and location
+- Phase/action definitions
+
+## Output
+
+**Generated Files**:
+
+| File | Purpose | Generation Condition |
+|------|---------|---------------------|
+| `specs/{skill-name}-requirements.md` | Domain requirements with validation | Always |
+| `specs/quality-standards.md` | Quality evaluation criteria | Always |
+| `templates/agent-base.md` | Agent prompt template | Always |
+| `specs/action-catalog.md` | Action dependency graph and selection priority | Autonomous/Hybrid mode only |
+
+**File Structure**:
+
+**Domain Requirements** (`specs/{skill-name}-requirements.md`):
+```markdown
+# {display_name} Requirements
+- When to Use (phase/action reference table)
+- Domain Requirements (Functional requirements, Output requirements, Quality requirements)
+- Validation Function (JavaScript code)
+- Error Handling (recovery strategies)
+```
+
+**Quality Standards** (`specs/quality-standards.md`):
+```markdown
+# Quality Standards
+- Quality Dimensions (Completeness 25%, Consistency 25%, Accuracy 25%, Usability 25%)
+- Quality Gates (Pass ≥80%, Review 60-79%, Fail <60%)
+- Issue Classification (Errors, Warnings, Info)
+- Automated Checks (runQualityChecks function)
+```
+
+**Agent Base** (`templates/agent-base.md`):
+```markdown
+# Agent Base Template
+- Universal Prompt Structure (ROLE, PROJECT CONTEXT, TASK, CONSTRAINTS, OUTPUT_FORMAT, QUALITY_CHECKLIST)
+- Variable Description (workDir, output_path)
+- Return Format (AgentReturn interface)
+- Role Definition Reference (phase/action specific agents)
+```
+
+**Action Catalog** (`specs/action-catalog.md`, Autonomous/Hybrid only):
+```markdown
+# Action Catalog
+- Available Actions (table with Purpose, Preconditions, Effects)
+- Action Dependencies (Mermaid diagram)
+- State Transitions (state machine table)
+- Selection Priority (ordered action list)
+```
+
+## Decision Logic
+
+```
+Decision (execution_mode check):
+   ├─ mode === 'sequential' → Generate 3 files only
+   │  └─ Files: requirements.md, quality-standards.md, agent-base.md
+   │
+   ├─ mode === 'autonomous' → Generate 4 files
+   │  ├─ Files: requirements.md, quality-standards.md, agent-base.md
+   │  └─ Additional: action-catalog.md (with action dependencies)
+   │
+   └─ mode === 'hybrid' → Generate 4 files
+      ├─ Files: requirements.md, quality-standards.md, agent-base.md
+      └─ Additional: action-catalog.md (with hybrid logic)
+```
+
+## Execution Protocol
+
+```javascript
+// Phase 4: Generate Specifications & Templates
+// Reference: phases/04-specs-templates.md
+
+// Load config and setup
+const config = JSON.parse(view_file(`${workDir}/skill-config.json`));
+const skillDir = `.claude/skills/${config.skill_name}`;
+
+// Ensure specs and templates directories exist (created in Phase 2)
+// skillDir structure: phases/, specs/, templates/
+
+// Step 1: Generate domain requirements
+const domainRequirements = `# ${config.display_name} Requirements
+
+${config.description}
+
+## When to Use
+
+| Phase | Usage | Reference |
+|-------|-------|-----------|
+${config.execution_mode === 'sequential' ?
+  config.sequential_config.phases.map((p, i) =>
+    `| Phase ${i+1} | ${p.name} | ${p.id}.md |`
+  ).join('\n') :
+  `| Orchestrator | Action selection | orchestrator.md |
+| Actions | Action execution | actions/*.md |`}
+
+---
+
+## Domain Requirements
+
+### Functional Requirements
+
+- [ ] Requirement 1: TODO
+- [ ] Requirement 2: TODO
+- [ ] Requirement 3: TODO
+
+### Output Requirements
+
+- [ ] Format: ${config.output.format}
+- [ ] Location: ${config.output.location}
+- [ ] Naming: ${config.output.filename_pattern}
+
+### Quality Requirements
+
+- [ ] Completeness: All necessary content exists
+- [ ] Consistency: Terminology and format unified
+- [ ] Accuracy: Content based on actual analysis
+
+## Validation Function
+
+\`\`\`javascript
+function validate${toPascalCase(config.skill_name)}(output) {
+  const checks = [
+    // TODO: Add validation rules
+    { name: "Format correct", pass: output.format === "${config.output.format}" },
+    { name: "Content complete", pass: output.content?.length > 0 }
+  ];
+
+  return {
+    passed: checks.filter(c => c.pass).length,
+    total: checks.length,
+    details: checks
+  };
+}
+\`\`\`
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Missing input data | Return clear error message |
+| Processing timeout | Reduce scope, retry |
+| Output validation failure | Log issue, manual review |
+`;
+
+write_to_file(`${skillDir}/specs/${config.skill_name}-requirements.md`, domainRequirements);
+
+// Step 2: Generate quality standards
+const qualityStandards = `# Quality Standards
+
+Quality assessment standards for ${config.display_name}.
+
+## Quality Dimensions
+
+### 1. Completeness (Completeness) - 25%
+
+| Requirement | Weight | Validation Method |
+|------------|--------|-----------------|
+| All necessary outputs exist | 10 | File check |
+| Content coverage complete | 10 | Content analysis |
+| No placeholder remnants | 5 | Text search |
+
+### 2. Consistency (Consistency) - 25%
+
+| Aspect | Check |
+|--------|-------|
+| Terminology | Use same term for same concept |
+| Format | Title levels, code block format consistent |
+| Style | Tone and expression unified |
+
+### 3. Accuracy (Accuracy) - 25%
+
+| Requirement | Description |
+|-------------|------------|
+| Data correct | References and data error-free |
+| Logic correct | Process and relationship descriptions accurate |
+| Code correct | Code examples runnable |
+
+### 4. Usability (Usability) - 25%
+
+| Metric | Goal |
+|--------|------|
+| Readability | Clear structure, easy to understand |
+| Navigability | Table of contents and links correct |
+| Operability | Steps clear, executable |
+
+## Quality Gates
+
+| Gate | Threshold | Action |
+|------|-----------|--------|
+| Pass | >= 80% | Output final deliverables |
+| Review | 60-79% | Process warnings then continue |
+| Fail | < 60% | Must fix |
+
+## Issue Classification
+
+### Errors (Must Fix)
+
+- Necessary output missing
+- Data error
+- Code not runnable
+
+### Warnings (Should Fix)
+
+- Format inconsistency
+- Content depth insufficient
+- Missing examples
+
+### Info (Nice to Have)
+
+- Optimization suggestions
+- Enhancement opportunities
+
+## Automated Checks
+
+\`\`\`javascript
+function runQualityChecks(workDir) {
+  const results = {
+    completeness: checkCompleteness(workDir),
+    consistency: checkConsistency(workDir),
+    accuracy: checkAccuracy(workDir),
+    usability: checkUsability(workDir)
+  };
+
+  results.overall = (
+    results.completeness * 0.25 +
+    results.consistency * 0.25 +
+    results.accuracy * 0.25 +
+    results.usability * 0.25
+  );
+
+  return {
+    score: results.overall,
+    gate: results.overall >= 80 ? 'pass' :
+          results.overall >= 60 ? 'review' : 'fail',
+    details: results
+  };
+}
+\`\`\`
+`;
+
+write_to_file(`${skillDir}/specs/quality-standards.md`, qualityStandards);
+
+// Step 3: Generate agent base template
+const agentBase = `# Agent Base Template
+
+Agent base template for ${config.display_name}.
+
+## Universal Prompt Structure
+
+\`\`\`
+[ROLE] You are {role}, focused on {responsibility}.
+
+[PROJECT CONTEXT]
+Skill: ${config.skill_name}
+Objective: ${config.description}
+
+[TASK]
+{task description}
+- Output: {output_path}
+- Format: ${config.output.format}
+
+[CONSTRAINTS]
+- Constraint 1
+- Constraint 2
+
+[OUTPUT_FORMAT]
+1. Execute task
+2. Return JSON summary information
+
+[QUALITY_CHECKLIST]
+- [ ] Output format correct
+- [ ] Content complete without omission
+- [ ] No placeholder remnants
+\`\`\`
+
+## Variable Description
+
+| Variable | Source | Example |
+|----------|--------|---------|
+| {workDir} | Runtime | .workflow/.scratchpad/${config.skill_name}-xxx |
+| {output_path} | Configuration | ${config.output.location}/${config.output.filename_pattern} |
+
+## Return Format
+
+\`\`\`typescript
+interface AgentReturn {
+  status: "completed" | "partial" | "failed";
+  output_file: string;
+  summary: string;  // Max 50 chars
+  stats?: {
+    items_processed?: number;
+    errors?: number;
+  };
+}
+\`\`\`
+
+## Role Definition Reference
+
+${config.execution_mode === 'sequential' ?
+  config.sequential_config.phases.map((p, i) =>
+    `- **Phase ${i+1} Agent**: ${p.name} Expert`
+  ).join('\n') :
+  config.autonomous_config.actions.map(a =>
+    `- **${a.name} Agent**: ${a.description || a.name + ' Executor'}`
+  ).join('\n')}
+`;
+
+write_to_file(`${skillDir}/templates/agent-base.md`, agentBase);
+
+// Step 4: Conditional - Generate action catalog for autonomous/hybrid mode
+if (config.execution_mode === 'autonomous' || config.execution_mode === 'hybrid') {
+  const actionCatalog = `# Action Catalog
+
+Available action catalog for ${config.display_name}.
+
+## Available Actions
+
+| Action | Purpose | Preconditions | Effects |
+|--------|---------|---------------|---------|
+${config.autonomous_config.actions.map(a =>
+  `| [${a.id}](../phases/actions/${a.id}.md) | ${a.description || a.name} | ${a.preconditions?.join(', ') || '-'} | ${a.effects?.join(', ') || '-'} |`
+).join('\n')}
+
+## Action Dependencies
+
+\`\`\`mermaid
+graph TD
+${config.autonomous_config.actions.map((a, i, arr) => {
+  if (i === 0) return \`    ${a.id.replace(/-/g, '_')}[${a.name}]\`;
+  const prev = arr[i-1];
+  return \`    ${prev.id.replace(/-/g, '_')} --> ${a.id.replace(/-/g, '_')}[${a.name}]\`;
+}).join('\n')}
+\`\`\`
+
+## State Transitions
+
+| From State | Action | To State |
+|------------|--------|----------|
+| pending | action-init | running |
+${config.autonomous_config.actions.slice(1).map(a =>
+  `| running | ${a.id} | running |`
+).join('\n')}
+| running | action-complete | completed |
+| running | action-abort | failed |
+
+## Selection Priority
+
+When multiple actions' preconditions are met, select based on the following priority:
+
+${config.autonomous_config.actions.map((a, i) =>
+  \`${i + 1}. \\\`${a.id}\\\` - ${a.name}\`
+).join('\n')}
+`;
+
+  write_to_file(`${skillDir}/specs/action-catalog.md`, actionCatalog);
+}
+
+// Helper function
+function toPascalCase(str) {
+  return str.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
+}
+
+// Phase output summary
+console.log('Phase 4 complete: Generated specs and templates');
+```
+
+## Next Phase
+
+→ [Phase 5: Validation](05-validation.md)
+
+**Data Flow to Phase 5**:
+- All generated files in `specs/` and `templates/`
+- skill-config.json for validation reference
+- Complete skill directory structure ready for final validation