Orchestrator Skill Skill

Orchestrator Skill

You are the Orchestrator (coordinator). You do NOT execute tasks yourself. Delegate execution to Worker/Subagent.

NOTE: postman daemon handles all message delivery automatically. Role constraints and communication paths are defined in postman config.

1. Immediate Actions

When orchestrator skill is invoked:

Detect task type from user message
Start appropriate workflow

| Keyword | Workflow | | ---------------- | -------- | | plan, design | Plan | | review | Review | | code, implement | Code | | pr, pull request | PR |

2. Subagent Execution

Subagents are READONLY only. Skip mood status updates.

2.1. Task Tool (Claude Code)

[Your capability=READONLY]
{task content}

Return results directly. Use mkmd if file output needed.

2.2. Codex CLI

FILE=$(mkmd --dir reviews --label "${ROLE}-cx") && \
codex exec --sandbox workspace-write \
  -o "$FILE" \
  "[Your capability=READONLY] {task content}" &
wait

NOTE:

Do NOT use --model option
-o path is relative to caller's directory (not affected by -C)
When using -o, return results directly (do NOT create files)

3. Plan Workflow

3.1. Source Types

| Type | Format | How to Fetch | | ----- | ----------------- | ------------------------------------ | | issue | issue <number> | gh issue view --json body,comments | | jira | jira <key> | Jira API or manual paste | | pr | pr <number> | gh pr view --json body,comments | | memo | memo <path> | Read file | | text | "<description>" | Direct input |

3.2. Planning Process

Before creating the plan file:

Research phase: Create a research artifact first.
```
mkmd --dir research --label "${feature}-investigation"
```
Document: files examined, patterns found, design decisions, recommendations.
Annotation cycle (1-6 rounds): Iterate on the plan draft. Guard: do NOT dispatch workers until all annotation cycles complete.
- Round 1: draft scope and steps
- Rounds 2+: review, trim, question assumptions
- Stop when the plan is minimal and unambiguous
Decision logging: For each non-obvious choice, record:
- What: the chosen approach
- Why: rationale, constraints, trade-offs considered
Scope checkpoint: Trim to minimum before dispatching. "When in doubt, do less."
Self-containment check: Verify the plan is self-contained.
- Every domain term defined (no assumed knowledge)
- All file paths are concrete and absolute
- Function signatures specified where relevant
- Commands are copy-pasteable with expected output
- A developer with no repo context can execute the plan
Reference identification: For each milestone, cite concrete reference implementations when available.
- Existing code in the repo that demonstrates the pattern
- File path and line range for each reference
- What to reuse vs. what to adapt

3.3. Plan Template

Create file:

mkmd --dir plans --label plan

# Plan: {title}

## Purpose

<1-2 sentence big-picture goal. Why does this matter?>

## Source

- Type: <source_type>
- Reference: <source_reference>

## Context

<additional context from user>

## Investigation Summary

<findings from investigation phase>

## Acceptance Criteria

Observable, human-verifiable behaviors that define "done":

1. <criterion: e.g., "Running `nix flake check` exits 0">
2. <criterion>

## Implementation Plan

### Milestone 1: <title> [status: pending]

- **Scope**: <what this milestone covers>
- **Deliverables**: <concrete outputs>
- **Files**: <affected files with paths>
- **Changes**: <what to change>
- **Reference**: <existing code to follow, file:line>
- **Verification**:
  - Command: `<idempotent command>`
  - Expected: `<expected output>`

### Milestone P: <title> [prototype] [status: pending]

Use `[prototype]` label for proof-of-concept milestones that de-risk
later work. Place before the milestones they de-risk.

## Decision Log

| #   | Decision           | Why                         | Alternatives Considered |
| --- | ------------------ | --------------------------- | ----------------------- |
| 1   | <what was decided> | <rationale and constraints> | <what was rejected>     |

## Risks and Considerations

- <risk 1>

## Test Strategy

- <how to verify overall>

## Progress

Timestamped checkpoints updated during implementation:

- [ ] {YYYY-MM-DD HH:MM} Milestone 1 started
- [x] {YYYY-MM-DD HH:MM} Milestone 1 completed -- <evidence>

## Surprises and Discoveries

Unexpected findings during implementation:

- {YYYY-MM-DD} <description and impact on plan>

3.4. Living Document Management

Update plan during implementation:

When to update

A surprise or blocker invalidates a milestone
A design pivot changes the approach
New information changes scope
A milestone starts or completes

How to update

Progress section: Add timestamped checkpoint when milestone starts or completes
Milestone status: Update [status: pending] to [status: in-progress] or [status: done]
Surprises section: Append unexpected findings with date and impact
Decision Log: Append new decisions made during implementation
Evidence: Append terminal transcripts and test results under completed milestones
Escalate to user before proceeding if a design change is required

Worker responsibility

Workers MUST update the plan file when completing milestones:

Mark milestone status as [status: done]
Add timestamped entry to Progress section
Log any surprises in Surprises and Discoveries section

4. Code Workflow

4.1. Task Breakdown

Break plan steps into atomic tasks:

| Task Type | Description | | -------------- | ------------------------------------ | | File creation | Create new files | | File edit | Modify existing files | | Multi-file | 2+ files requiring coordinated edits | | Test execution | Run tests and verify | | Build | Build and verify |

4.2. Execution

Sequential: Delegate -> Wait -> Verify -> Next task Parallel: Send to multiple Workers simultaneously

4.3. Completion Report

Create file:

mkmd --dir reviews --label completion

# Implementation Complete

## Plan Reference

- File: {mkmd-generated plan file path}

## Changes Made

| File   | Change Type | Description |
| ------ | ----------- | ----------- |
| <file> | <type>      | <desc>      |

## Test Results

- <test outcome>

## PR / Commit

- <PR number or commit hash>

NOTE: For review workflow, see subagent-review skill.

5. PR Workflow

5.1. Prerequisites

Implementation complete
Tests passing
IMPORTANT: Always create as draft PR

5.2. Gather PR Context

Read .github/PULL_REQUEST_TEMPLATE.md if exists
Reference recent PRs: gh pr list --author i9wa4 --limit 10
Match the style of existing PRs
Check: README, CHANGELOG need update?

5.3. Create PR

Use: gh pr create --draft --title "..." --body "..."

5.4. Post-PR

Display PR URL to user

Agent Skills: Orchestrator Skill

Install this agent skill to your local

Skill Files