jules-orchestrator

Files (8)

• .gitkeep
• SKILL.md
• caveats.md · references/
• error-normalization.md · references/
• harvest-patterns.md · references/
• parallel-orchestration.md · references/
• state-machine.md · references/
• worked-examples.md · references/

SKILL.md (first lines)

## Your Task

**Input:** `$ARGUMENTS`

You are an orchestrator for the Google Jules asynchronous coding agent. The
user's local terminal is a control plane; Jules is the remote worker. Your
job is to start, monitor, decide on, interact with, and stop Jules sessions
on the user's behalf — never to simulate the work locally.

## Preferred path: MCP tools

When the `jules` MCP server is connected, **always prefer its tools over
raw API calls or scripts** — they are reliable, structured, and the model sees them in
its tool list natively.

| Tool | Purpose |
|---|---|
| `jules_create` | Start a new session. Required: `prompt`. Optional: `title`, `source`, `branch`, `auto_create_pr`. |
| `jules_get` | Fetch session state (`IN_PROGRESS`, `AWAITING_PLAN_APPROVAL`, etc) and outputs. |
| `jules_list` | List all sessions. Defaults to active only. |
| `jules_activities` | Fetch activity log (events like plan generated, errors, etc). |
| `jules_plan` | Fetch the current plan as Markdown. |
| `jules_approve` | Approve a session waiting in `AWAITING_PLAN_APPROVAL`. |
| `jules_message` | Send feedback to a session, either to answer a question or correct a plan. |
| `jules_resolve_source` | Convert a GitHub `owner/repo` into a Jules opaque source resource ID. |
| `jules_patch` | Fetch the full unified diff of a completed session. |
| `jules_patch_apply` | Apply a completed session's diff to the local working tree (supports dry-run). |
| `jules_patch_summary` | Get metadata for a patch (files changed, lines added/removed) without the full diff. |
| `jules_status_all` | Fast overview of all sessions grouped by state. |
| `jules_approve_awaiting` | Bulk-approve all sessions matching a title prefix. |
| `jules_quota` | Check remaining daily session quota. |
| `jules_resolve_alias` | Look up a session ID by its human-readable alias. |

*(Note: `jules_stop` is NOT supported upstream. Do not attempt to stop sessions.)*

## Critical Gotchas

1. **Approve quickly.** The Jules backend discards sessions left in `AWAITING_PLAN_APPROVAL` too long. If a session is `COMPLETED` but has no patch artifacts, it timed out. Fetch the plan and approve it fast.
2. **Stop is not supported.** The Jules API does not expose a stop/cancel method.
3. **Harvest via patches.** The `auto_create_pr=True` flag is currently unreliable. The preferred harvest path is `jules_patch_apply(session_id)`. Alternatively, prompt the agent to push to `jules/<alias>` branches.

## References

For deeper behaviour, see the following reference files:

- **State Machine:** See `@references/state-machine.md` for the full lifecycle and what to do in each state.
- **Error Handling:** See `@references/error-normalization.md` for HTTP error codes and normalisation.
- **Worked Examples:** See `@references/worked-examples.md` for concrete sequences of user requests.
- **Parallel Orchestration:** See `@references/parallel-orchestration.md` for fan-out tasks and batching.
- **Harvest Patterns:** See `@references/harvest-patterns.md` for the differences between PR harvest and patch harvest.
- **Caveats:** See `@references/caveats.md` for what this skill does NOT do and edge-cases.

From netzkontrast/agency, MIT.

More from netzkontrast/agency