mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-14 02:42:04 +08:00
Add orchestrator design, phase file generation, and validation processes
- Implement Phase 2: Orchestrator Design with detailed steps for generating SKILL.md - Introduce Phase 3: Phase Files Design to create phase files with content fidelity - Establish Phase 4: Validation & Integration to ensure structural completeness and reference integrity - Include comprehensive validation checks for content quality and data flow consistency - Enhance documentation with clear objectives and critical rules for each phase
This commit is contained in:
catlog22
319
.claude/skills/workflow-skill-designer/SKILL.md
Normal file
319
.claude/skills/workflow-skill-designer/SKILL.md
Normal file
@@ -0,0 +1,319 @@
|
||||
---
|
||||
name: workflow-skill-designer
|
||||
description: Meta-skill for designing orchestrator+phases structured workflow skills. Creates SKILL.md coordinator with progressive phase loading, TodoWrite patterns, and data flow. Triggers on "design workflow skill", "create workflow skill", "workflow skill designer".
|
||||
allowed-tools: Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep
|
||||
---
|
||||
|
||||
# Workflow Skill Designer
|
||||
|
||||
Meta-skill for creating structured workflow skills following the orchestrator + phases pattern. Generates complete skill packages with SKILL.md as coordinator and phases/ folder for execution details.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Workflow Skill Designer │
|
||||
│ → Analyze requirements → Design orchestrator → Generate phases │
|
||||
└───────────────┬─────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────┼───────────┬───────────┐
|
||||
↓ ↓ ↓ ↓
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │ │ Phase 4 │
|
||||
│ Require │ │ Orch │ │ Phases │ │ Valid │
|
||||
│ Analysis│ │ Design │ │ Design │ │ & Integ │
|
||||
└─────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||
↓ ↓ ↓ ↓
|
||||
workflow SKILL.md phases/ Complete
|
||||
config generated 0N-*.md skill pkg
|
||||
```
|
||||
|
||||
## Target Output Structure
|
||||
|
||||
The skill this meta-skill produces follows this structure:
|
||||
|
||||
```
|
||||
.claude/skills/{skill-name}/
|
||||
├── SKILL.md # Orchestrator: coordination, data flow, TodoWrite
|
||||
├── phases/
|
||||
│ ├── 01-{phase-name}.md # Phase execution detail (full content)
|
||||
│ ├── 02-{phase-name}.md
|
||||
│ ├── ...
|
||||
│ └── 0N-{phase-name}.md
|
||||
├── specs/ # [Optional] Domain specifications
|
||||
└── templates/ # [Optional] Reusable templates
|
||||
```
|
||||
|
||||
## Core Design Patterns
|
||||
|
||||
Patterns extracted from successful workflow skill implementations (workflow-plan, project-analyze, etc.):
|
||||
|
||||
### Pattern 1: Orchestrator + Progressive Loading
|
||||
|
||||
**SKILL.md** = Pure coordinator. Contains:
|
||||
- Architecture diagram (ASCII)
|
||||
- Execution flow with `Ref: phases/0N-xxx.md` markers
|
||||
- Phase Reference Documents table (read on-demand)
|
||||
- Data flow between phases
|
||||
- Core rules and error handling
|
||||
|
||||
**Phase files** = Full execution detail. Contains:
|
||||
- Complete agent prompts, bash commands, code implementations
|
||||
- Validation checklists, error handling
|
||||
- Input/Output specification
|
||||
- Next Phase link
|
||||
|
||||
**Key Rule**: SKILL.md references phase docs via `Ref:` markers. Phase docs are read **only when that phase executes**, not all at once.
|
||||
|
||||
### Pattern 2: TodoWrite Attachment/Collapse
|
||||
|
||||
```
|
||||
Phase starts:
|
||||
→ Sub-tasks ATTACHED to TodoWrite (in_progress + pending)
|
||||
→ Orchestrator executes sub-tasks sequentially
|
||||
|
||||
Phase ends:
|
||||
→ Sub-tasks COLLAPSED back to high-level summary (completed)
|
||||
→ Next phase begins
|
||||
```
|
||||
|
||||
### Pattern 3: Inter-Phase Data Flow
|
||||
|
||||
```
|
||||
Phase N output → stored in memory/variable → Phase N+1 input
|
||||
└─ or written to session file for persistence
|
||||
```
|
||||
|
||||
Each phase receives outputs from prior phases via:
|
||||
- In-memory variables (sessionId, contextPath, etc.)
|
||||
- Session directory files (.workflow/active/{sessionId}/...)
|
||||
- Planning notes (accumulated constraints document)
|
||||
|
||||
### Pattern 4: Conditional Phase Execution
|
||||
|
||||
```
|
||||
Phase N output contains condition flag
|
||||
├─ condition met → Execute Phase N+1
|
||||
└─ condition not met → Skip to Phase N+2
|
||||
```
|
||||
|
||||
### Pattern 5: Input Structuring
|
||||
|
||||
User input (free text) → Structured format before Phase 1:
|
||||
```
|
||||
GOAL: [objective]
|
||||
SCOPE: [boundaries]
|
||||
CONTEXT: [background/constraints]
|
||||
```
|
||||
|
||||
## Execution Flow
|
||||
|
||||
```
|
||||
Phase 1: Requirements Analysis
|
||||
└─ Ref: phases/01-requirements-analysis.md
|
||||
├─ Input source: commands, descriptions, user interaction
|
||||
└─ Output: workflowConfig (phases, data flow, agents, conditions)
|
||||
|
||||
Phase 2: Orchestrator Design (SKILL.md)
|
||||
└─ Ref: phases/02-orchestrator-design.md
|
||||
├─ Input: workflowConfig
|
||||
└─ Output: .claude/skills/{name}/SKILL.md
|
||||
|
||||
Phase 3: Phase Files Design
|
||||
└─ Ref: phases/03-phase-design.md
|
||||
├─ Input: workflowConfig + source content
|
||||
└─ Output: .claude/skills/{name}/phases/0N-*.md
|
||||
|
||||
Phase 4: Validation & Integration
|
||||
└─ Ref: phases/04-validation.md
|
||||
└─ Output: Validated skill package
|
||||
```
|
||||
|
||||
**Phase Reference Documents** (read on-demand):
|
||||
|
||||
| Phase | Document | Purpose |
|
||||
|-------|----------|---------|
|
||||
| 1 | [phases/01-requirements-analysis.md](phases/01-requirements-analysis.md) | Analyze workflow requirements from various sources |
|
||||
| 2 | [phases/02-orchestrator-design.md](phases/02-orchestrator-design.md) | Generate SKILL.md with orchestration patterns |
|
||||
| 3 | [phases/03-phase-design.md](phases/03-phase-design.md) | Generate phase files preserving full execution detail |
|
||||
| 4 | [phases/04-validation.md](phases/04-validation.md) | Validate structure, references, and integration |
|
||||
|
||||
## Input Sources
|
||||
|
||||
This meta-skill accepts workflow definitions from multiple sources:
|
||||
|
||||
| Source | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| **Existing commands** | Convert `.claude/commands/` orchestrator + sub-commands | `plan.md` + `session/start.md` + `tools/*.md` |
|
||||
| **Text description** | User describes workflow in natural language | "Create a 3-phase code review workflow" |
|
||||
| **Requirements doc** | Structured requirements file | `requirements.md` with phases/agents/outputs |
|
||||
| **Existing skill** | Refactor/redesign an existing skill | Restructure a flat skill into phases |
|
||||
|
||||
## Frontmatter Conversion Rules
|
||||
|
||||
When converting from command format to skill format:
|
||||
|
||||
| Command Field | Skill Field | Transformation |
|
||||
|---------------|-------------|----------------|
|
||||
| `name` | `name` | Prefix with group: `plan` → `workflow-plan` |
|
||||
| `description` | `description` | Append trigger phrase: `Triggers on "xxx"` |
|
||||
| `argument-hint` | _(removed)_ | Arguments handled in Input Processing section |
|
||||
| `examples` | _(removed)_ | Examples moved to inline documentation |
|
||||
| `allowed-tools` | `allowed-tools` | Expand wildcards: `Skill(*)` → `Skill`, add commonly needed tools |
|
||||
| `group` | _(removed)_ | Embedded in `name` prefix |
|
||||
|
||||
## Orchestrator Content Mapping
|
||||
|
||||
What goes into SKILL.md vs what goes into phase files:
|
||||
|
||||
### SKILL.md (Coordinator)
|
||||
|
||||
| Section | Content | Source |
|
||||
|---------|---------|--------|
|
||||
| Frontmatter | name, description, allowed-tools | Command frontmatter (converted) |
|
||||
| Architecture Overview | ASCII diagram of phase flow | Derived from execution structure |
|
||||
| Key Design Principles | Coordination rules | Extracted from command coordinator role |
|
||||
| Execution Flow | Phase sequence with `Ref:` markers + Phase Reference table | Command execution process |
|
||||
| Core Rules | Orchestration constraints | Command core rules |
|
||||
| Input Processing | Structured format conversion | Command input processing |
|
||||
| Data Flow | Inter-phase data passing | Command data flow |
|
||||
| TodoWrite Pattern | Attachment/collapse lifecycle | Command TodoWrite sections |
|
||||
| Post-Phase Updates | Planning notes / state updates between phases | Command inter-phase update code |
|
||||
| Error Handling | Failure recovery | Command error handling |
|
||||
| Coordinator Checklist | Pre/post phase actions | Command coordinator checklist |
|
||||
| Related Commands | Prerequisites and follow-ups | Command related commands |
|
||||
|
||||
### Phase Files (Execution Detail)
|
||||
|
||||
| Content | Rule |
|
||||
|---------|------|
|
||||
| Full agent prompts | Preserve verbatim from source command |
|
||||
| Bash command blocks | Preserve verbatim |
|
||||
| Code implementations | Preserve verbatim |
|
||||
| Validation checklists | Preserve verbatim |
|
||||
| Error handling details | Preserve verbatim |
|
||||
| Input/Output spec | Add if not present in source |
|
||||
| Phase header | Add `# Phase N: {Name}` |
|
||||
| Objective section | Add `## Objective` with bullet points |
|
||||
| Next Phase link | Add `## Next Phase` with link to next |
|
||||
|
||||
**Critical Rule**: Phase files must be **content-faithful** to their source. Do NOT summarize, abbreviate, or simplify. The phase file IS the execution instruction - every bash command, every agent prompt, every validation step must be preserved.
|
||||
|
||||
## SKILL.md Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: {skill-name}
|
||||
description: {description}. Triggers on "{trigger1}", "{trigger2}".
|
||||
allowed-tools: {tools}
|
||||
---
|
||||
|
||||
# {Title}
|
||||
|
||||
{One-paragraph description of what this skill does and what it produces.}
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
{ASCII diagram showing phases and data flow}
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
1. **{Principle}**: {Description}
|
||||
...
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: {auto-mode behavior}.
|
||||
|
||||
## Execution Flow
|
||||
|
||||
{Phase sequence with Ref: markers}
|
||||
|
||||
**Phase Reference Documents** (read on-demand when phase executes):
|
||||
|
||||
| Phase | Document | Purpose |
|
||||
|-------|----------|---------|
|
||||
| 1 | [phases/01-xxx.md](phases/01-xxx.md) | ... |
|
||||
...
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. {Rule}
|
||||
...
|
||||
|
||||
## Input Processing
|
||||
|
||||
{How user input is converted to structured format}
|
||||
|
||||
## Data Flow
|
||||
|
||||
{Inter-phase data passing diagram}
|
||||
|
||||
## TodoWrite Pattern
|
||||
|
||||
{Attachment/collapse lifecycle description with examples}
|
||||
|
||||
## Post-Phase Updates
|
||||
|
||||
{State updates between phases}
|
||||
|
||||
## Error Handling
|
||||
|
||||
{Failure recovery rules}
|
||||
|
||||
## Coordinator Checklist
|
||||
|
||||
{Pre/post phase action list}
|
||||
|
||||
## Related Commands
|
||||
|
||||
{Prerequisites and follow-ups}
|
||||
```
|
||||
|
||||
## Phase File Template
|
||||
|
||||
```markdown
|
||||
# Phase N: {Phase Name}
|
||||
|
||||
{One-sentence description of this phase's goal.}
|
||||
|
||||
## Objective
|
||||
|
||||
- {Goal 1}
|
||||
- {Goal 2}
|
||||
|
||||
## Execution
|
||||
|
||||
### Step N.1: {Step Name}
|
||||
|
||||
{Full execution detail: commands, agent prompts, code}
|
||||
|
||||
### Step N.2: {Step Name}
|
||||
|
||||
{Full execution detail}
|
||||
|
||||
## Output
|
||||
|
||||
- **Variable**: `{variableName}` (e.g., `sessionId`)
|
||||
- **File**: `{output file path}`
|
||||
- **TodoWrite**: Mark Phase N completed, Phase N+1 in_progress
|
||||
|
||||
## Next Phase
|
||||
|
||||
Return to orchestrator, then auto-continue to [Phase N+1: xxx](0N+1-xxx.md).
|
||||
```
|
||||
|
||||
## Design Decision Framework
|
||||
|
||||
When designing a new workflow skill, answer these questions:
|
||||
|
||||
| Question | Impact | Example |
|
||||
|----------|--------|---------|
|
||||
| How many phases? | Directory structure | 3-7 phases typical |
|
||||
| Which phases are conditional? | Orchestrator logic | "Phase 3 only if conflict_risk >= medium" |
|
||||
| What data flows between phases? | Data Flow section | sessionId, contextPath, configFlags |
|
||||
| Which phases use agents? | Phase file complexity | Agent prompts need verbatim preservation |
|
||||
| What's the TodoWrite granularity? | TodoWrite Pattern | Some phases have sub-tasks, others are atomic |
|
||||
| Is there a planning notes pattern? | Post-Phase Updates | Accumulated state document across phases |
|
||||
| What's the error recovery? | Error Handling | Retry once then report, vs rollback |
|
||||
| Does it need auto mode? | Auto Mode section | Skip confirmations with --yes flag |
|
||||
Reference in New Issue
Block a user