maestro-flow 0.5.31 → 0.5.33

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

@@ -0,0 +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(read_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_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_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_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_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