// Orchestrate sub-agents and coordinate multi-agent workflows with granary. Use when delegating tasks, spawning workers, or managing parallel execution.
Set up granary in a new project. Use when asked to initialize granary, install it, or get started with task management.
Plan and organize multi-project initiatives or significant, substantial projects. Use when work spans multiple services, repositories, or has natural project boundaries.
Execute an assigned granary task as a sub-agent. Use when you receive a task ID to complete.
Plan and organize work into granary projects and tasks. Use when breaking down a feature, creating tasks, or setting up dependencies.
| name | granary-orchestrate |
| description | Orchestrate sub-agents and coordinate multi-agent workflows with granary. Use when delegating tasks, spawning workers, or managing parallel execution. |
This skill is for implementation-time orchestration. Your job is to coordinate sub-agents to implement planned work. You do NOT plan or design—you delegate and track.
NEVER determine task parallelism by:
blocked_by is null/empty on individual tasksgranary next --all returnsgranary next --all is the ONLY source of truth for what can run in parallel. It considers:
If granary next --all returns 2 tasks, spawn exactly 2 agents. Not 6. Not 4. Exactly 2.
Always use --format=prompt instead of --json for granary commands. The --format=prompt output is specifically designed for LLM consumption—it's token-efficient and easy to parse without wasting context on JSON syntax.
Only use --json when you need to extract specific fields via jq, and always filter the output:
# Only if you need specific fields
granary task <id> --json | jq '.id, .status'
You are prompted to implement a project. Follow these steps:
granary summary
This shows all projects, their status, and task counts. Understand what exists before proceeding.
If given a project name, find it:
granary projects
granary project <project-id>
Search for projects and tasks by title:
granary search "query" # Find matching projects and tasks
granary search "api" --format=prompt # LLM-friendly output
This is useful when you know part of the project or task name but not the exact ID.
Examine the project structure:
granary project <project-id> tasks
Decision tree:
| Situation | Action |
|---|---|
| Project has no tasks | Use /granary:plan-work skill to plan first |
| Project has tasks but they lack detail | Use /granary:plan-work skill to refine |
| Single simple project with clear description | Implement directly as one task |
| Project has tasks with dependencies | Happy path - proceed to Step 4 |
granary session start "implementing-<project-name>" --mode execute
granary session add <project-id>
Your sole focus: hand off tasks to sub-agents. You do NOT implement tasks yourself.
Key principle: Maximize parallelism. Always look for opportunities to run multiple tasks concurrently. Tasks without dependencies on each other can and should run in parallel.
# Get ONLY tasks the scheduler has determined are ready
granary next --all --format=prompt
This returns only the tasks that are ready to execute. The scheduler has already evaluated dependencies, project ordering, claims, and status. Spawn agents for exactly the tasks returned—no more, no fewer.
If no tasks are returned, either all tasks are complete or remaining tasks are blocked.
DO NOT bypass this by:
blocked_by == nullThe scheduler knows things you don't. Trust it.
When multiple tasks are unblocked, spawn them all at once using parallel Task tool calls:
# If granary next --all returns task-1, task-2, task-3:
Use Task tool (call all three in a SINGLE message):
1. prompt: "Execute granary task task-1. Use /granary:execute-task skill."
subagent_type: "general-purpose"
run_in_background: true
2. prompt: "Execute granary task task-2. Use /granary:execute-task skill."
subagent_type: "general-purpose"
run_in_background: true
3. prompt: "Execute granary task task-3. Use /granary:execute-task skill."
subagent_type: "general-purpose"
run_in_background: true
Important: Use run_in_background: true for parallel execution. This allows multiple agents to work simultaneously.
granary next --all --format=promptCritical: Never spawn more agents than tasks returned by granary next --all. If it returns 2 tasks, spawn 2 agents. Period.
If only one task is available or tasks must be sequential:
granary next --format=prompt
Then spawn a single agent and wait for completion before checking for the next task.
Each sub-agent is responsible for:
granary handoff --tasks <id>)granary task <id> start)granary task <id> done) or blockedNote: You do NOT need to run granary handoff yourself. Sub-agents handle their own context building. Your job is to identify unblocked tasks and spawn agents.
When all tasks are done:
granary session close --summary "Completed implementation of <project-name>"
If a sub-agent cannot complete:
# Sub-agent should have blocked the task:
granary task <task-id> block --reason "..."
# You see it when checking next task
granary next --format=prompt # Will skip blocked tasks
Sub-agents should claim tasks with leases:
granary task <task-id> claim --owner "Worker-1" --lease 30
# Exit code 4 = conflict (task claimed by another)
Before risky operations:
granary checkpoint create "before-major-change"
# If things go wrong
granary checkpoint restore before-major-change
# WRONG - Don't do this
granary project <id> tasks --json | jq '.[] | select(.blocked_by == null)'
This bypasses the scheduler and leads to race conditions. Just because a task has no explicit blocked_by value doesn't mean it's ready to run. The scheduler considers implicit dependencies, project ordering, and other factors you can't see in task metadata.
# WRONG - Don't assume tasks can run together
granary show task-1 # blocked_by: null
granary show task-2 # blocked_by: null
granary show task-3 # blocked_by: null
# "All three have no blockers, I'll run them all!"
Tasks may have implicit logical dependencies. Task-3 might implement a service that uses schemas from task-1. Running them in parallel causes compiler errors.
# WRONG - Don't second-guess the scheduler
granary next --all # Returns 2 tasks
# "But I checked and 6 tasks have no blockers, I'll launch 6 agents"
If granary next --all returns 2 tasks, there's a reason. Trust it.
# RIGHT - Trust the scheduler completely
granary next --all --format=prompt
# Returns task-1, task-2
# Spawn exactly 2 agents, one for each task
Only spawn agents for tasks returned by granary next --all. When they complete, run the command again to discover what's newly unblocked.
granary summarygranary projectsgranary session startgranary next --all, spawn agents for exactly the tasks returnedgranary session closeYour job is coordination, not implementation. Sub-agents use granary handoff to build their own context and do the actual work—you just spawn agents for the tasks that granary next --all returns.
Remember: granary next --all is the scheduler. Trust it completely. If it returns 2 tasks, spawn 2 agents. Don't inspect task metadata to make your own parallelism decisions—that path leads to race conditions and compiler errors.