Workflow Orchestrator
A skill that coordinates workflows across multiple skills by evaluating hook metadata, recording pending follow-ups, and running only the actions that are safe and supported in the current host runtime.
When This Skill Activates
This skill should be used when:
- A skill completes its main workflow
- A milestone is reached (PRD complete, implementation done, etc.)
- User says "complete workflow" or "finish the process"
How It Works
┌─────────────────────────────────────────────────────────────┐ │ Workflow Orchestration │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 1. Detect Milestone → 2. Read Hooks → 3. Record/Run Safe Follow-ups │ │ │ │ prd-planner complete │ │ ↓ │ │ workflow-orchestrator │ │ ↓ │ │ ┌─────────────────────────────────────┐ │ │ │ declared self-improving follow-up │ (record/run) │ │ │ declared session logging follow-up │ (record/run) │ │ └─────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘
Trigger Configuration
Read trigger definitions from skills/auto-trigger/SKILL.md:
yamlhooks: after_complete: - trigger: self-improving-agent mode: background - trigger: session-logger mode: auto on_error: - trigger: self-improving-agent mode: background
Execution Modes
| Mode | Behavior | Use When |
|---|---|---|
auto | Run or record a low-risk follow-up when the host supports it | Logging, status updates |
background | Record a non-blocking follow-up | Reflection, analysis |
ask_first | Ask user before executing | PRs, deployments, major changes |
Milestone Detection
PRD Complete
markdownDetected when: - docs/{scope}-prd.md exists - All phases in {scope}-prd-task-plan.md are checked - Status shows "COMPLETE" Actions: 1. Record self-improving-agent as a background follow-up 2. Run or record session-logger if the host supports it
Implementation Complete
markdownDetected when: - All PRD requirements implemented - Tests pass - Code committed Actions: 1. Ask before running code-reviewer 2. Run create-pr only when the user requested submission 3. Run or record session-logger if the host supports it
Self-Improvement Applied
markdownDetected when: - Candidate validated with auditable evidence - One named durable owner changed - Representative behavior rerun - Candidate recorded as applied Actions: 1. Ask before running create-pr 2. Run or record session-logger if the host supports it
Learning Candidate (Skill Complete)
markdownDetected when: - A skill completes its workflow and produces reusable evidence - User provides feedback - Error or issue encountered Actions: 1. Record self-improving-agent as a background follow-up 2. Run or record session-logger if the host supports it The self-improving-agent: - Captures a candidate only when reusable evidence exists - Excludes raw transcripts and private tool payloads - Keeps uncertain findings under observation - Validates candidates only with explicit, auditable evidence - Applies validated changes only to a named durable owner with a change reference - Proves the representative behavior after application
Error Handling (on_error)
Detected when:
- A command returns non-zero exit code
- Tests fail after following skill guidance
- User reports the guidance produced incorrect results
Actions:
- Record self-improving-agent (background) for self-correction
- Run or record session-logger to capture error context
Hook Implementation in Skills
To declare follow-up metadata, add this section to any skill's SKILL.md:
markdown## Auto-Trigger (After Completion) When this skill completes, record or run supported follow-ups: ```yaml hooks: after_complete: - trigger: skill-name mode: auto|background|ask_first context: "relevant context" on_error: - trigger: self-improving-agent mode: background
Current Hook Contract
Hook metadata is declarative intent, not proof of CLI automation. Read the current skill front matter before acting. An absent hook means no declared follow-up; an existing hook still requires host support and the permission boundary for the target action.
Universal Learning Pattern
┌─────────────────────────────────────────────────────────────┐ │ Skill Completes With Evidence │ └──────────────┬──────────────────────────────────────────────┘ │ ↓ ┌──────────────────────┐ │ workflow-orchestrator │ └──────────┬───────────┘ │ ┌──────────┴─────────┐ ↓ ↓ self-improving-agent session-logger ↓ ↓ Capture candidate Save bounded context ↓ ↓ Validate evidence Log session ↓ Apply to named owner ↓ create-pr (only if submission was requested)
## Workflow Examples ### Example 1: PRD Creation Workflow
User: "Create a PRD for user authentication" ↓ prd-planner executes ↓ Phase 6 complete: PRD delivered ↓ workflow-orchestrator detects milestone ↓ ┌─────────────────────────────────┐ │ Background: self-improving-agent │ → Records learning proposal │ Auto: session-logger │ → Saves session when supported └─────────────────────────────────┘
### Example 2: Full Feature Workflow
User: "Create a PRD and implement it" ↓ prd-planner → workflow-orchestrator ↓ self-improving-agent (candidate capture only) ↓ prd-implementation-precheck ↓ implementation complete → workflow-orchestrator ↓ code-reviewer → optional candidate capture ↓ create-pr (only when requested) → workflow-orchestrator ↓ session-logger
Each milestone can produce a `self-improving-agent` follow-up, but durable skill edits still require validation or explicit approval. ## Implementation Steps ### Step 1: Detect Milestone Check for completion indicators: ```bash # PRD complete? grep -q "COMPLETE" docs/{scope}-prd-task-plan.md # All phases checked? grep -q "^\- \[x\].*Phase 6" docs/{scope}-prd-task-plan.md # PRD file exists? ls docs/{scope}-prd.md
Step 2: Read Trigger Config
bash# Read hooks from auto-trigger skill cat skills/auto-trigger/SKILL.md
Step 3: Record or Execute Hooks
For each hook in order (before_start, after_complete, on_error):
- Check if condition is met
- Record or execute based on mode and host support
- Pass context to triggered skill
- Wait/continue based on mode
Step 4: Update Status
Log what was triggered and the result:
markdown## Workflow Execution - [x] self-improving-agent (background) - Started - [x] session-logger (auto) - Session saved - [ ] create-pr (ask_first) - Pending user approval
Skills with Auto-Trigger
| Skill | Triggers After |
|---|---|
prd-planner | self-improving-agent, session-logger |
self-improving-agent | No automatic PR; applied changes may declare a logging follow-up |
prd-implementation-precheck | self-improving-agent, session-logger |
code-reviewer | self-improving-agent, session-logger |
create-pr | session-logger |
refactoring-specialist | self-improving-agent, session-logger |
debugger | self-improving-agent, session-logger |
Adding Follow-up Metadata to Existing Skills
To add follow-up metadata to an existing skill, add to the end of its SKILL.md:
markdown--- ## Auto-Trigger When this skill completes, record or run supported follow-ups: ```yaml hooks: after_complete: - trigger: session-logger mode: auto context: "Save session context"
For more complex triggers, specify mode and context: ```markdown ## Auto-Trigger When this skill completes: ```yaml hooks: after_complete: - trigger: next-skill mode: background context: "Description" - trigger: session-logger mode: auto context: "Save session" - trigger: create-pr mode: ask_first context: "Create PR if files modified" on_error: - trigger: self-improving-agent mode: background
## Best Practices 1. **Log only when supported and appropriate** - Session logging is a bounded optional follow-up 2. **Ask before major actions** - PRs, deployments, destructive changes 3. **Background for analysis** - Reflection, evaluation, optimization 4. **Auto for status** - Logging, status updates, bookmarks 5. **Don't create loops** - Ensure chains terminate
