Use when the user types the exact trigger '/fruit-agent-orchestrate' to triage open issues and produce copy-pasteable plain-paragraph work assignments for each fruit agent (APPLE, BANANA, CHERRY, DRAGONFRUIT, ELDERBERRY, FIG, GRAPE, HONEYDEW, INCABERRY, JACKFRUIT, KIWI). Never self-trigger. Read-only: no claims, no labels, no mutations.
Instrucciones de origen · Vista previa de solo lectura
name
fruit-agent-orchestrate
description
Use when the user types the exact trigger '/fruit-agent-orchestrate' to triage open issues and produce copy-pasteable plain-paragraph work assignments for each fruit agent (APPLE, BANANA, CHERRY, DRAGONFRUIT, ELDERBERRY, FIG, GRAPE, HONEYDEW, INCABERRY, JACKFRUIT, KIWI). Never self-trigger. Read-only: no claims, no labels, no mutations.
Fruit Agent Orchestrate — Issue Triage & Agent Assignment
Triage the open issue queue and assign the top work to each fruit agent as copy-pasteable plain-paragraph instructions. Read-only — no claims, no labels, no mutations.
Overview
This skill provides a complete workflow for triaging open GitHub issues and generating per-agent assignment paragraphs. It combines puzzle-triage ranking logic with area-based clustering and agent roster management to produce ready-to-paste work assignments.
The skill is single-round / short-lived by design: it captures a snapshot of open issue state at triage time, freezes it into prose, and that prose decays as agents close tickets. The output includes a freshness banner with the triage timestamp. Re-run the skill each round (or after several closes) rather than reusing one assignment list across a long session.
When to Use
User types the exact trigger: /fruit-agent-orchestrate
Before a new orchestration round to assign fresh work to available agents
When the user explicitly requests triage + assignment (not just ranking — see puzzle-triage)
Don't use for:
Just ranking/filtering issues — use puzzle-triage (read-only ranking, no agent assignment)
Mutating issues (labels, claims, edits) — this skill is read-only
Autonomous triggering — runs ONLY on the exact verbatim trigger
Configuration
Set these environment variables or pass as parameters to make the skill portable across projects:
Variable
Default
Description
ORCH_GH_CMD
gh
GitHub CLI command (or wrapper)
ORCH_REPO
(auto-detected via gh repo view)
Repo in owner/repo format — auto-detected if unset
In the skill body, reference as $ORCH_GH_CMD, $ORCH_PUZZLE_STATUS_CMD, etc.
Algorithm
Step 1 — Collect Data (all in parallel)
Fetch all required data in a single parallel tool-use call. Read all outputs before proceeding.
# 1. All open issues with labels (tab-separated for large lists)$ORCH_GH_CMD issue list --state open --limit 100 \
--json number,title,labels,createdAt \
-q '.[] | "\(.number)\t\([.labels[].name]|join(\",\"))\t\(.title)"'# 2. Puzzle status (stale markers, sequencing constraints)$ORCH_PUZZLE_STATUS_CMD# 3. Active worktrees
git worktree list
# 4. Triage timestamp (freshness contract)date'+%Y-%m-%dT%H:%M:%S%z'
Freshness contract. This skill takes a snapshot of open issue state at triage time and freezes it into prose consumed asynchronously — often one agent at a time, over a long session — while those same agents are rapidly closing tickets. The snapshot decays: a later assignment can name a #N that closed hours earlier. To bound staleness, capture the date above and stamp it on the output (see Output Shape), and treat the output as single-round / short-lived — re-run the skill each round rather than reusing one assignment list across a multi-hour session.
Step 2 — Pre-flight Cleanup
Before ranking, scan for and surface:
Stale markers: puzzle:status rows flagged [STALE] — issue is CLOSED but marker still exists. Note the file + line.
Stale worktrees: git worktree list entries whose branch issue number resolves to a CLOSED issue (gh issue view N --json state -q .state). Note the path and branch.
Sequencing constraints: Tickets whose body carries Sequenced after: #N must not be assigned ahead of their dependency. Cheap pre-filter: only inspect bodies of tickets carrying the sequenced label; without the label, checking every body is too expensive at 50+ issues. For each constrained ticket:
#N OPEN and claimed/in-flight → hold dependent ticket; annotate ⏳ waiting on #N (in-flight)
#N OPEN and unclaimed → assign #N first (to most available agent); hold dependent for later round
Report held tickets under ## ⏳ Sequenced — waiting on dependency. Never assign a dependent ticket and its open predecessor to two agents in the same round.
Dependency-coupled grooming: A PM/grooming/hygiene ticket whose body is dependency metadata about another ticket X must not be co-scheduled in the same wave that assigns X's blockers. Detect by scanning the grooming ticket's body for referenced #Ns; if any referenced #N is actionable and assigned this wave, defer the grooming ticket to a later, quieter wave (list under held section). When deferral is unavoidable, the assignment paragraph MUST carry the execution-time referent stamp (see Step 5b exception).
Report stale markers and stale worktrees at the top of the output under ## ⚠ Pre-flight cleanup — attributed to the owning agent (fruit name in branch/file). That agent must resolve cleanup before claiming new work.
Step 3 — Triage (embedded puzzle-triage logic)
Rank actionable issues using the full puzzle-triage algorithm:
Partition first:
🧑 Requires human routing — has humans-only, decision, or human-decision-required label → separate section, not assigned to any agent. The guide-human-decision skill handles these when a human explicitly directs an agent.
💤 Icebox — has proposal or wontfix label → separate section, not ranked for action
⛔ Blocked — has blocked label → separate section, note blocker, not grabbable
🔵 In-flight — has a live worktree (from git worktree list) → separate section, skip for assignment
Shortest estimate first (from @todo #N:Est marker if present; ~ if absent)
Lowest issue number as tiebreak
Render the actionable queue as a compact table. Keep it scannable — one line per issue.
Step 4 — Agent Roster
Fixed roster (future: dynamic detection from worktrees):
Agent
Assumed state
APPLE
available
BANANA
available
CHERRY
available
DRAGONFRUIT
available
ELDERBERRY
available
FIG
available
GRAPE
available
HONEYDEW
available
INCABERRY
available
JACKFRUIT
available
KIWI
available
Future enhancement: After running git worktree list, parse branch names for fruit identities, cross-reference with npm run puzzle:status to determine which agents are IN-PROGRESS. Mark those agents as unavailable and omit them from assignment (or flag them as "finish current work first"). For now, all eleven agents are assumed available and the user is expected to supply context about in-flight work before invoking the skill.
Step 5 — Produce Assignments
5a — Group Issues by Area
Before writing paragraphs, partition the actionable issue queue by area:* label:
Extract the area:* label(s) from each actionable issue (captured in Step 1). An issue with multiple area:* labels belongs to its first-listed area:* label.
Build a cluster map: area → [issue list], sorted within each cluster by Yegor priority (severity → estimate → number).
Issues with no area:* label go into a wildcard pool — assignable to any agent.
Sort clusters by size (largest first). Assign each cluster to the agent with the fewest issues so far (greedy bin-packing). Never assign overlapping area clusters to the same agent.
Distribute wildcard issues to the lightest-loaded agents after cluster assignment.
Goal: each agent touches at most one area:* cluster per session. If there are more agents than clusters, some agents receive only wildcard issues — that is acceptable.
5b — Write One Paragraph Per Agent
For each agent, write one plain paragraph. Rules:
No blockquote > prefix, no code fences
Name the ticket number and title
State the agent's assigned area lane: "Your area lane: area:X" (or "area unlabelled" for wildcard-only agents)
One sentence of rationale (why this agent, why this ticket now)
If the agent has pre-flight cleanup (from Step 2), lead with that before the ticket assignment
Format must be directly copy-pasteable as a human instruction to that agent
Do NOT append a per-paragraph "verify the issue is OPEN / run npm run preflight <N>" instruction. The freshness re-check is surfaced once, globally, in the ## ⏱ Triaged as of … banner — repeating it per agent is boilerplate that bloats assignment and undercuts its self-contained legibility.
Exception — execution-time referent stamp for dependency-coupled grooming: The global OPEN banner covers the assigned ticket's state; it does not cover the #Ns a grooming/PM ticket references. So when a PM/grooming/hygiene ticket whose content is another ticket's dependency metadata could not be deferred (Step 2), append exactly one targeted line: "Before you edit or close this, re-verify the live state of every #N it references (gh issue view N --json state) — those deps may be closing in this same wave." This is the only sanctioned per-paragraph freshness stamp; it targets referents (uncovered by the banner), not the assigned ticket, and appears only on dependency-coupled grooming assignments — never on ordinary tickets.
Good fit heuristics:
Match ticket role (WRITER / RESEARCHER / ARCHITECT / DEV) to the agent's recent work domain if known from user context
Prefer unblocking tickets (e.g. a RESEARCH that unblocks a WRITER) when an agent is free and the pair exists
Medium-severity tickets before low when an agent is fresh
Never assign two agents to the same area:* cluster (enforced by 5a; flag explicitly if unavoidable)
Output Shape
The output must open with the freshness banner (the date from Step 1), then the rest:
## ⏱ Triaged as of <ISO triage timestamp> — re-validate before claiming
This snapshot decays as agents close tickets. `npm run claim` gates on CLOSED state (it refuses a
closed issue), but that guard skips when `gh` is offline — so verify OPEN if in doubt. Re-run this
skill each round (or after several closes); do not reuse this list across a long multi-hour session.
## ⚠ Pre-flight cleanup
[stale markers and worktrees, attributed to owning agent]
## 🎯 Actionable — Yegor priority order
[compact ranked table]
## 🧑 Requires human routing
[tickets with humans-only / decision / human-decision-required labels — not assigned to any agent]
## ⛔ Blocked / 💤 Icebox / 🔵 In-flight
[brief lists]
## ⏳ Sequenced — waiting on dependency
[held tickets with dependency annotations]
## 👥 Assignments
APPLE: [plain paragraph]
BANANA: [plain paragraph]
CHERRY: [plain paragraph]
DRAGONFRUIT: [plain paragraph]
ELDERBERRY: [plain paragraph]
FIG: [plain paragraph]
GRAPE: [plain paragraph]
HONEYDEW: [plain paragraph]
INCABERRY: [plain paragraph]
JACKFRUIT: [plain paragraph]
KIWI: [plain paragraph]
Firing on anything but /fruit-agent-orchestrate — never trigger on "you are agent X, are you ready?" or similar. Respond with confirmation and wait for the exact verbatim trigger.
Assigning humans-only / decision tickets to agents — these must be partitioned out in Step 3. Agents cannot grab them; guide-human-decision handles them when a human directs.
Ignoring in-flight worktrees — always check git worktree list to avoid double-assignment. An agent with an active worktree should finish current work before receiving new assignments.
Treating @todo estimates as exact — estimates are ≤60m caps, not promises. Use ~ when absent.
Large issue lists truncate output — gh issue list --json on 100+ issues produces 50K+ chars with embedded control characters that exceed context. Use the tab-separated -q format and process in a script (execute_code) to partition/rank, rather than processing raw JSON in the LLM context.
Hardcoding lccjs-specific paths/commands — use the Configuration env vars ($ORCH_PUZZLE_STATUS_CMD, $ORCH_CLAIM_CMD, $ORCH_VELOCITY_DB, $ORCH_WORKTREE_BASE) so the skill works in other projects.
Skipping the freshness banner — the date timestamp is mandatory. Without it, assignments become stale silently.
Per-paragraph boilerplate — do not append "verify OPEN" to each assignment. The global banner covers the assigned ticket; only dependency-coupled grooming gets a targeted referent stamp.
Verification Checklist
All open issues fetched with labels (tab-separated format for large lists)
