orchestrator
Orchestration workflow for orchestrator role ONLY. Use when: - Agent's role name (tmux pane title) is "orchestrator"
How do I install this agent skill?
npx skills add https://github.com/i9wa4/dotfiles --skill orchestratorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The orchestrator skill coordinates tasks between agents using tools like GitHub CLI and Codex. It implements safety best practices such as sandboxed subagent execution and mandatory draft pull requests. A potential vulnerability surface for indirect prompt injection exists because the skill processes data from external sources like GitHub issues and Jira to drive its workflows.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1/1 file flagged
What does this agent skill do?
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
--modeloption -opath 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.mdif 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/i9wa4/dotfiles/orchestrator">View orchestrator on skillZs</a>