orchestrator

Orchestrator Skill

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

1. Immediate Actions

When /orchestrator is invoked:

1. Find available Workers (Section 3)
2. Detect task type from user message
3. Start appropriate workflow

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

2. Roles and Capabilities

2.1. Roles

Role	Description	Launch Subagent
Orchestrator	Coordinator. Does NOT execute	Yes (review)
Worker	Executor in another tmux pane	claude only
Subagent	Executor as child process	No

2.2. Capability

Capability	Description	Tools
READONLY	Investigation, review	Read, Glob, Grep, Bash (ro)
WRITABLE	Implementation, modification	All tools allowed

Role	READONLY	WRITABLE
Worker	Yes	Yes
Subagent	Yes	No

Both modes allow writes to .i9wa4/.

2.3. Worker Assignment

Agent	Role	Capability
codex	Consultation	READONLY
claude	Consultation, Implementation	WRITABLE

2.4. Orchestrator Constraints

• NEVER: Edit, Write, NotebookEdit (project files)
• ALLOWED: Read, Glob, Grep, Bash (read-only)
• ALLOWED: Write to .i9wa4/
• DELEGATE: Execution to Worker/Subagent

2.5. Worker/Subagent Constraints (Claude Code)

When Worker/Subagent is Claude Code:

• NEVER: Use AskUserQuestion tool (user interaction is Orchestrator's role)
• NEVER: Ask questions directly to user
• MUST: Report unclear points in response to Orchestrator
• MUST: Orchestrator handles all user communication

3. Communication

Communication is handled by postman daemon (file-based messaging).

3.1. Message Format

Filename: {timestamp}-from-{sender}-to-{recipient}.md Location: .i9wa4/post/

Example: 20260124-175300-from-orchestrator-to-worker-claude.md

3.2. Sending Messages

1. Create message file in .i9wa4/post/
2. postman daemon detects and delivers to recipient

3.3. Receiving Responses

postman delivers a message to Worker with response_file set.

Worker writes to .i9wa4/draft/{response_file} then moves to .i9wa4/post/.

3.4. Worker Discovery

A2A_PEER Mode (postman)

When $A2A_PEER is set, discover Workers from postman inbox:

discover_workers() {
  if [[ -d .postman/inbox ]]; then
    ls -1 .postman/inbox 2>/dev/null | grep "^worker"
  fi
}

# Usage
WORKERS=$(discover_workers)
# Output:
# worker-claude
# worker-codex

Legacy Mode (tmux only)

When $A2A_PEER is not set, use tmux pane detection:

Your own pane: $TMUX_PANE

find_agent_pane() {
  local agent="$1"
  tmux list-panes -s -F "#{pane_pid} #{pane_id}" | while read pid id; do
    ps -ax -o ppid,command | grep -v grep | grep -F "$agent" \
      | grep -q "^\s*$pid" && echo "$id"
  done
}

# Usage
CLAUDE=$(find_agent_pane claude)
CODEX=$(find_agent_pane codex)

If no Workers found, inform user and wait.

4. Delegation Priority

Task Type	First Choice	Fallback
Implementation	Worker (WRITABLE)	N/A
Complex investigation	Worker (READONLY)	Task tool
Simple review	Task tool	-
Parallel reviews	codex exec	Task tool

5. Subagent Execution

Subagents are READONLY only. Skip mood status updates.

5.1. Task Tool (Claude Code)

[SUBAGENT capability=READONLY]
{task content}

Return results directly. Write to .i9wa4/ if file output needed.

5.2. Codex CLI

FILE=$(${CLAUDE_CONFIG_DIR}/scripts/touchfile.sh .i9wa4/reviews --type "${ROLE}-cx") && \
codex exec --sandbox workspace-write -C .i9wa4 \
  -o "$FILE" \
  "[SUBAGENT 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)

6. Phase Management

6.1. Phase Flow

START -> PLAN -> CODE -> PR -> COMPLETE

Each phase (except PR): Consult both Workers (codex + claude) -> Fix -> Parallel review -> Approval

PR phase: Consult both Workers (codex + claude) -> Fix -> Create PR (no parallel review)

6.2. Phase Log

File: .i9wa4/phase.log

2025-01-01 10:00:00 | START -> PLAN
2025-01-01 11:00:00 | PLAN -> CODE

7. Task Management

7.1. Files

Path	Purpose	Updated by
.i9wa4/roadmap.md	Overall progress	Orchestrator
.i9wa4/status-pane{id}	Pane current state	Orchestrator
.i9wa4/phase.log	Phase transitions	Orchestrator
.i9wa4/plans/	Plan documents	Orchestrator
.i9wa4/reviews/	Review results	Subagent
.i9wa4/post/	Message exchange	All

7.2. Status File Format

CURRENT: <what was done> | <mood> <emoji>
NEXT: <what is needed to continue>

7.3. Roadmap Format

# Roadmap: <Feature Name>

## Phase: PLAN

- [x] Read requirements
- [x] Investigate existing code
- [x] Consult Workers
- [x] Create plan document
- [x] Parallel review
- [x] User approval

## Phase: CODE

- [x] Implement changes
- [x] Add tests
- [x] Consult Workers
- [ ] Parallel review
- [ ] User approval

## Phase: PR

- [ ] Consult Workers
- [ ] Create draft PR

## Blocked

- [ ] <blocked item> (reason)

8. Plan Workflow

8.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

8.2. Plan Template

Create file:

${CLAUDE_CONFIG_DIR}/scripts/touchfile.sh .i9wa4/plans --type plan

# Plan: {title}

## Source

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

## Context

<additional context from user>

## Investigation Summary

<findings from investigation phase>

## Implementation Plan

### Step 1: <step title>

- Files: <affected files>
- Changes: <what to change>

## Risks and Considerations

- <risk 1>

## Test Strategy

- <how to verify>

9. Code Workflow

9.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

9.2. Execution

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

9.3. Completion Report

Create file:

${CLAUDE_CONFIG_DIR}/scripts/touchfile.sh .i9wa4/reviews --type completion

# Implementation Complete

## Plan Reference

- File: .i9wa4/plans/plan-file.md

## Changes Made

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

## Test Results

- <test outcome>

## PR / Commit

- <PR number or commit hash>

10. Review Workflow

10.1. Setup

Parameter	Options
review_type	code, design
target_type	pr, commit, branch, issue, document
target	PR number, commit hash, file path

Default: 10 parallel (cx x 5 + cc x 5)

10.2. Priority (Code Review)

Priority	Role	Focus
1	security	OWASP, vulnerabilities
2	architecture	Patterns, structure
3	historian	History, context
4	code	Quality, readability
5	qa	Edge cases, acceptance

For design review: replace code with data (Data model, schema). Assign: cx first (1-5), then cc (1-5). cx manages token usage of cc.

10.3. References

Target Type	Command
pr	gh pr view {target} --json body,comments + diff
commit	git show {target}
branch	git diff main...HEAD
issue	gh issue view {target} --json body,comments
document	Read the file at {target}

Agent file: @~/ghq/github.com/i9wa4/dotfiles/config/claude/agents/reviewer-{ROLE}.md

10.4. Review Execution

IMPORTANT: Always execute 10-parallel reviews as standard practice

Always execute the following for design/code reviews:

• cc x 5: Launch reviewer-* agents in parallel via Task tool
• cx x 5: Execute codex exec sequentially via worker-codex

2-parallel execution (worker-claude + worker-codex only) is prohibited.

Task content template:

[SUBAGENT capability=READONLY]
<!-- REVIEW_SESSION
timestamp: {TS}, source: {SOURCE}, role: {ROLE}
review_type: {REVIEW_TYPE}, target_type: {TARGET_TYPE}, target: {TARGET}
-->
Return your review directly. Do NOT create files.

Method A: Task Tool (Recommended for Claude Code)

Use Task tool with reviewer agents. Launch multiple Task tools in a single message for parallel execution with clean output isolation.

Task tool calls (parallel):
- subagent_type: reviewer-security
- subagent_type: reviewer-architecture
- subagent_type: reviewer-historian
- subagent_type: reviewer-code
- subagent_type: reviewer-qa

Each reviewer agent reads the agent file automatically.

Method B: Codex CLI Sequential (Recommended for Codex)

NEVER use background processes (&) with codex exec - causes output interleaving.

for ROLE in security architecture historian code qa; do
  FILE=$(${CLAUDE_CONFIG_DIR}/scripts/touchfile.sh .i9wa4/reviews --type "${ROLE}-cx")
  codex exec --sandbox workspace-write -C .i9wa4 -o "$FILE" "{task}"
done

Method C: Codex CLI Parallel (Advanced)

For true parallelism without output mixing, use separate terminal sessions or accept that outputs will be written to files (not displayed cleanly).

WARNING: Background execution (&) with wait causes stderr/stdout mixing.

10.4.1 Parallel Execution for 10-Review (cc x 5 + cx x 5)

IMPORTANT: Start cc and cx reviews simultaneously for true parallelism.

Step 1: Prepare PR Diff

codex exec cannot access PR diff directly. Save it beforehand:

gh pr diff $PR_NUMBER > .i9wa4/tmp/pr-diff.txt

Step 2: Launch cc x 5 (Single Message)

In one message, call Task tool 5 times in parallel:

Task tool calls (parallel, single message):
- subagent_type: reviewer-security
- subagent_type: reviewer-architecture
- subagent_type: reviewer-historian
- subagent_type: reviewer-code (or reviewer-data for design review)
- subagent_type: reviewer-qa

Each prompt should include:

[SUBAGENT capability=READONLY]
Review PR #N from {ROLE} perspective.
See .i9wa4/tmp/pr-diff.txt for the diff.

Step 3: Launch cx x 5 (Background Processes)

Use file output to avoid interleaving:

for ROLE in security architecture historian data qa; do
  FILE=$("${CLAUDE_CONFIG_DIR}/scripts/touchfile.sh" .i9wa4/reviews --type "review-${ROLE}-cx")
  codex exec --sandbox workspace-write -o "$FILE" \
    "[SUBAGENT capability=READONLY] Review PR #N from ${ROLE} perspective. See .i9wa4/tmp/pr-diff.txt for the diff." &
done
wait

Step 4: Collect Results

# Check all review files
ls -la .i9wa4/reviews/*-review-*.md

# Read and summarize
cat .i9wa4/reviews/*-review-*.md

Timing Optimization

Action	Timing
Save PR diff	Before starting reviews
Launch cc x 5	Immediately (Task tool)
Launch cx x 5	Immediately (background)
Collect results	After wait completes

10.5. Observer Deliberation

After Phase 1 review completion, discuss with all observers to collect additional findings.

10.5.1. Purpose

1. Collect additional findings from other perspectives
2. Prevent cross-functional oversights
3. Ensure comprehensive multi-angle coverage

10.5.2. Deliberation Prompt

Share all Phase 1 review results with each observer and request additional findings.

[SUBAGENT capability=READONLY]
<!-- DELIBERATION_SESSION
timestamp: {TS}, role: {ROLE}
review_type: {REVIEW_TYPE}, target_type: {TARGET_TYPE}, target: {TARGET}
-->

## Phase 1 Review Results Summary

{List all Phase 1 findings sorted by severity}

## Questions

Based on other reviewers' findings, from your expert perspective ({ROLE}):

1. Are there any additional points to raise?
2. Are there any supplementary points related to other findings?
3. Are there any overlooked perspectives?

Output in the same format as Phase 1 only if there are additional findings.
If no additional findings, explicitly state "No additional findings."

10.5.3. Deliberation Execution

Execute 10-parallel (cc x 5 + cx x 5) same as Phase 1.

Task tool calls (parallel, single message):
- subagent_type: reviewer-security (with Phase 1 results)
- subagent_type: reviewer-architecture (with Phase 1 results)
- subagent_type: reviewer-historian (with Phase 1 results)
- subagent_type: reviewer-code or reviewer-data (with Phase 1 results)
- subagent_type: reviewer-qa (with Phase 1 results)

10.5.4. Result Files

Save deliberation results to .i9wa4/reviews/:

• cc: Use Task tool results directly
• cx: {timestamp}-deliberation-{ROLE}-cx.md

10.6. Summary Output

Create file:

${CLAUDE_CONFIG_DIR}/scripts/touchfile.sh .i9wa4/reviews/summary.md

# Review Summary

## Target

- Type: {review_type} / {target_type}, Target: {target}

## Findings by Phase

### Phase 1: Initial Review

| # | Issue               | Reporter     | Severity | File               |
| - | ------------------- | ------------ | -------- | ------------------ |
| 1 | {issue description} | {role}-{src} | High     | `path/to/file:123` |

### Phase 2: Deliberation

| # | Issue                | Reporter     | Triggered By | Severity | File               |
| - | -------------------- | ------------ | ------------ | -------- | ------------------ |
| 1 | {additional finding} | {role}-{src} | {role}       | Medium   | `path/to/file:456` |

## Coverage Analysis

| Perspective  | Phase 1 | Phase 2 | Total |
| ------------ | ------- | ------- | ----- |
| Security     | N       | M       | N+M   |
| Architecture | N       | M       | N+M   |
| Historian    | N       | M       | N+M   |
| Code/Data    | N       | M       | N+M   |
| QA           | N       | M       | N+M   |
| **Total**    | **X**   | **Y**   | **Z** |

11. PR Workflow

11.1. Prerequisites

• Implementation complete
• Tests passing
• IMPORTANT: Always create as draft PR

11.2. Gather PR Context

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

11.3. Create PR

[WORKER capability=WRITABLE to=%N]

Create draft PR with:
- Title: <title>
- Body: <body>
- Base: main

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

11.4. Post-PR

1. Record in phase.log: CODE -> PR -> COMPLETE
2. Display PR URL to user