orchestrator-skills 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -2,13 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
An opinionated Claude Code skill for running one **orchestrator** session that leads several **lane** sessions for one human **lead**.
|
|
4
4
|
|
|
5
|
-
- Each lane works on one ticket
|
|
5
|
+
- Each lane is a long-lived terminal tab that works on one ticket at a time. A lane has no folder of its own.
|
|
6
|
+
- Each ticket gets its own git worktree. The lane creates it when it starts the ticket.
|
|
6
7
|
- The orchestrator talks to the lead, assigns tickets, writes the lane briefs and stages the input files.
|
|
7
8
|
- It also owns the shared resources, runs the merge gates and keeps the ticket status true.
|
|
8
9
|
|
|
9
10
|
The rules come from several months of daily multi-lane work on a real product. Most of them exist because something went wrong without them: a lane waited on a permission prompt that nobody saw, a merge ignored a late ruling, or a ticket was called Done before anyone checked it.
|
|
10
11
|
|
|
11
|
-
This is an opinionated approach, not a general framework. It assumes one human lead, one ticket per lane, a git worktree per
|
|
12
|
+
This is an opinionated approach, not a general framework. It assumes one human lead, one ticket at a time per lane, a git worktree per ticket, and merge gates that nobody skips. It works best when you adopt these choices as a whole. If they do not fit your team, take the parts that do, and change the rest in your own copy.
|
|
12
13
|
|
|
13
14
|
## What is in it
|
|
14
15
|
|
|
@@ -18,13 +19,14 @@ This is an opinionated approach, not a general framework. It assumes one human l
|
|
|
18
19
|
| `orchestrating-agent-lanes/lane-briefs.md` | Brief template, message format, handoff file, lane lifecycle |
|
|
19
20
|
| `orchestrating-agent-lanes/merge-gates.md` | Merge gates in order, after-merge steps, ticket status |
|
|
20
21
|
| `orchestrating-agent-lanes/setup-checklist.md` | Decisions for a new project, repository baseline, safety baseline |
|
|
21
|
-
| `tests/pressure-scenarios.md` |
|
|
22
|
+
| `tests/pressure-scenarios.md` | Six pressure scenarios with pass criteria, and how to run them with and without the skill |
|
|
22
23
|
| `bin/cli.mjs` | The installer behind `npx` / `bunx`. Tests: `npm test` |
|
|
24
|
+
| `Makefile` | Release workflow: `make release BUMP=minor`, then `make publish OTP=<code>` |
|
|
23
25
|
|
|
24
26
|
## Requirements
|
|
25
27
|
|
|
26
28
|
- [Claude Code](https://docs.claude.com/en/docs/claude-code), with several sessions on one machine that can list and message each other (the `ListAgents` and `SendMessage` tools).
|
|
27
|
-
- A git repository.
|
|
29
|
+
- A git repository. Each ticket gets one `git worktree`, created with Claude Code's `EnterWorktree` tool.
|
|
28
30
|
- Optional, as the files assume them: GitHub (`gh`) for PRs and CI, Linear for tickets, a read-only `code-reviewer` subagent for in-house reviews, and the [superpowers](https://github.com/obra/superpowers) plugin for brainstorming, plans and reviews. Other tools work too. Replace the names in the files.
|
|
29
31
|
|
|
30
32
|
## Setup
|
|
@@ -32,17 +34,17 @@ This is an opinionated approach, not a general framework. It assumes one human l
|
|
|
32
34
|
1. **Install the skill.** Use `npx` (Node 18.17 or later) or `bunx`. Both run the same installer.
|
|
33
35
|
- For one project, committed with the repo. Run this in the repository root:
|
|
34
36
|
```bash
|
|
35
|
-
npx orchestrator-skills@0.
|
|
37
|
+
npx orchestrator-skills@0.3.0 install
|
|
36
38
|
# or
|
|
37
|
-
bunx orchestrator-skills@0.
|
|
39
|
+
bunx orchestrator-skills@0.3.0 install
|
|
38
40
|
|
|
39
41
|
git add .claude/skills/orchestrating-agent-lanes
|
|
40
42
|
```
|
|
41
43
|
- For all your projects (installs into `~/.claude/skills`):
|
|
42
44
|
```bash
|
|
43
|
-
npx orchestrator-skills@0.
|
|
45
|
+
npx orchestrator-skills@0.3.0 install --global
|
|
44
46
|
# or
|
|
45
|
-
bunx orchestrator-skills@0.
|
|
47
|
+
bunx orchestrator-skills@0.3.0 install --global
|
|
46
48
|
```
|
|
47
49
|
The skill is available in the next Claude Code session.
|
|
48
50
|
|
|
@@ -65,8 +67,8 @@ This is an opinionated approach, not a general framework. It assumes one human l
|
|
|
65
67
|
## Use
|
|
66
68
|
|
|
67
69
|
1. Open one terminal tab for the orchestrator. Tell it that it is the orchestrator for this repository and that you are the lead.
|
|
68
|
-
2. Open one tab per lane and
|
|
69
|
-
3. Give the orchestrator tickets. It reads them
|
|
70
|
+
2. Open one tab per lane in the repository root and name the lanes by number: `lane1`, `lane2`, … A lane is a reusable slot, not a topic, so the orchestrator can give the next ticket to the next free lane, whatever its area. Give a role name (`review`, `tester`) only to a lane whose purpose never changes.
|
|
71
|
+
3. Give the orchestrator tickets. It reads them and sends each lane its brief. The lane creates a worktree for its ticket, and the orchestrator copies the inputs into it. Then it reports to you only when you must act: a decision, an approval, a command only you may run, or a lane that is waiting on a prompt.
|
|
70
72
|
|
|
71
73
|
## Customizing
|
|
72
74
|
|
|
@@ -1,19 +1,32 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: orchestrating-agent-lanes
|
|
3
|
-
description: Use when this session is the orchestrator for a human lead and several Claude lane sessions (one terminal tab
|
|
3
|
+
description: Use when this session is the orchestrator for a human lead and several Claude lane sessions (one terminal tab per lane, one git worktree per ticket) - assigning tickets to lanes, writing lane briefs, reporting to the lead, naming or picking a lane, handling a lane's question, permission prompt or hook refusal, staging input files for a lane, merging a lane's PR, or updating ticket status.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Orchestrating agent lanes
|
|
7
7
|
|
|
8
8
|
## Overview
|
|
9
9
|
|
|
10
|
-
One orchestrator session talks to the human **lead**. Several **lane** sessions
|
|
10
|
+
One orchestrator session talks to the human **lead**. Several **lane** sessions are long-lived terminal tabs that work through the orchestrator's instructions, one ticket at a time. Each ticket gets its own git worktree. The orchestrator plans, assigns, stages inputs, owns the shared resources, runs the merge gates and keeps the ticket status true. The lead decides, approves and runs the commands only the lead may run.
|
|
11
11
|
|
|
12
12
|
**Core principle:** every minute a lane waits for something nobody sees (a permission prompt, a missing file, an unanswered question) is lost. The lead does not watch every tab. The orchestrator makes the waiting visible, or prevents it.
|
|
13
13
|
|
|
14
|
+
## Lanes, names and worktrees
|
|
15
|
+
|
|
16
|
+
A lane is a reusable slot, not a topic. The ticket decides what a lane works on, and the next free lane takes the next ticket, whatever its area.
|
|
17
|
+
|
|
18
|
+
- **Numbered names for all general lanes:** `lane1`, `lane2`, … `lane6`. Never name a lane after the area of its first ticket (`db`, `app`, `frontend`). A lane called `db` cannot take the next app ticket without confusion.
|
|
19
|
+
- **A role name only for a fixed purpose** that stays the same for every task, for example `review` or `tester`.
|
|
20
|
+
- **A lane is a tab, not a folder.** It starts in the main checkout (the repository root, on a clean `main`). It has no worktree and no folder of its own until it gets a ticket. Never create folders or worktrees per lane.
|
|
21
|
+
- **A worktree belongs to a ticket.** At ticket start the lane creates it itself, with Claude Code's `EnterWorktree` tool, from a freshly fetched `origin/main` (it goes under `.claude/worktrees/`). It names the branch after the ticket, in the project's scheme (for example `<user>/<ticket>-<slug>`), and reports the worktree path. The orchestrator creates a worktree only for its own work (deploy, hotfix), the same way.
|
|
22
|
+
- **A lane keeps its tab and name through many tickets.** After the merge it leaves the merged worktree with `ExitWorktree`, and creates the worktree for its next ticket with `EnterWorktree`.
|
|
23
|
+
- **Resume:** the brief names the existing worktree path. The lane leaves its current worktree with `ExitWorktree`. That returns it to its previous directory, which can be another worktree. The lane checks its current directory and calls `EnterWorktree` with the path only if it is not in that worktree yet. A session never reaches into another worktree with `cd`, `git -C` or absolute paths. The isolation hook refuses that.
|
|
24
|
+
- **Reading only inside the own worktree** needs a PreToolUse hook that refuses commands aimed at another worktree (for example `git -C <other worktree>`). Without such a hook, the rule is discipline only (`setup-checklist.md`).
|
|
25
|
+
- **Picking a lane:** the lowest-numbered free lane. Free means: no ticket in the status file, and `ListAgents` shows it idle. No free lane: ask the lead to open the next number, or queue the ticket.
|
|
26
|
+
|
|
14
27
|
## The hard rules
|
|
15
28
|
|
|
16
|
-
1. **Stage inputs before the lane starts.** A lane reads only inside its own worktree.
|
|
29
|
+
1. **Stage inputs before the lane starts the work.** A lane reads only inside its own worktree. Collect every outside file it needs (UI kits, design exports, specs from Downloads, notes from the main checkout) in your own `.scratch/` first (for example `.scratch/kits/<name>/`). When the lane reports its new worktree path, copy them into `<worktree>/.scratch/` and send the paths. Briefs name only `.scratch` paths. Before you send a brief, search it for `~/`, `/Users/` and "main checkout", copy each hit, and replace the path. Things that are needed again and again belong in the repo (for example `design/`).
|
|
17
30
|
2. **`ListAgents` first.** It is the first tool call of every turn in which you write to the lead. Any lane shown as `waiting` holds a prompt only the lead can answer. Name it in one line, with what you told it to do.
|
|
18
31
|
3. **Talk to the lead only when the lead must act.** One step or one question per message. Real status first: done and verified, failed (with the error), skipped. Say when a deliverable does not exist yet.
|
|
19
32
|
4. **No invented assumptions in the lead's name.** Drafts contain code facts, ticket facts and the lead's rulings. Your own proposals go to the lead as a list first. Record every ruling on the ticket at once (Q1, Q2, … with the reason).
|
|
@@ -22,13 +35,14 @@ One orchestrator session talks to the human **lead**. Several **lane** sessions
|
|
|
22
35
|
7. **Merge gates, every time.** Re-read the ticket including replies (a ruling after the last push means hold), green pipeline, a review record for the head commit, merge fallout against the current `origin/main`, browser check for UI or money. Details: `merge-gates.md`.
|
|
23
36
|
8. **Ticket status follows the work.** In Progress at lane start. In Review after the merge (re-check after about 30 s, because integrations may set Done). Done only after the check on the test environment.
|
|
24
37
|
9. **You own the shared resources.** The shared local stack, migration numbers, heavy local runs, the external review allowance, browser sessions. Lanes ask before they use them.
|
|
25
|
-
10. **Keep one status file** of all lanes (ticket, branch, PR, resource holds, migration register, open questions for the lead). Update it at every change of state. It must survive a context reset.
|
|
38
|
+
10. **Keep one status file** of all lanes (lane name, ticket or free, branch, PR, resource holds, migration register, open questions for the lead). Update it at every change of state. It must survive a context reset.
|
|
26
39
|
|
|
27
40
|
## Quick reference
|
|
28
41
|
|
|
29
42
|
| Situation | Do |
|
|
30
43
|
|---|---|
|
|
31
|
-
| New ticket for a lane |
|
|
44
|
+
| New ticket for a lane | Lowest-numbered free lane → read the ticket fully → In Progress → brief (`lane-briefs.md`) → lane creates the worktree from fresh `origin/main` + install + hooks, reports the path → copy the inputs into its `.scratch/` → plan first for non-trivial work |
|
|
45
|
+
| Resume a ticket in an existing worktree | The brief names the worktree path. The lane runs `ExitWorktree`, checks its current directory, and runs `EnterWorktree` with the path only if it is not there yet |
|
|
32
46
|
| Lane asks for an outside file | Copy it into its `.scratch/`, send the new path |
|
|
33
47
|
| Lane reports a hook refusal or denial | Tell the lead in one line. Decide: continue inside the rules, or stop |
|
|
34
48
|
| Lane shows `waiting` | Tell the lead at once: lane, prompt, what it was doing |
|
|
@@ -50,6 +64,8 @@ One orchestrator session talks to the human **lead**. Several **lane** sessions
|
|
|
50
64
|
| "Small fix, the pipeline is green, merge it" | Re-read the ticket first. Rulings arrive after pushes. |
|
|
51
65
|
| "Merged, so the ticket is Done" | In Review until the test environment check. |
|
|
52
66
|
| "I will fill in a sensible default in the lead's draft" | Facts and the lead's rulings only. Ask with a list. |
|
|
67
|
+
| "This ticket is DB work, so call the lane `db`" | Lanes are slots, not topics. Use the next free `laneN`. |
|
|
68
|
+
| "Each lane needs its own folder" | A lane is a tab. Worktrees belong to tickets, and the lane creates one at ticket start. |
|
|
53
69
|
| "Quick `git stash` to switch" | The stash is shared by all worktrees. Make a WIP commit. |
|
|
54
70
|
| "Five agents in parallel will be faster" | The lead pays for each one. Start what the task needs. |
|
|
55
71
|
|
|
@@ -7,13 +7,13 @@ The limits come first, in bold, and say that a breach stops the task. Limits tha
|
|
|
7
7
|
```
|
|
8
8
|
<orchestrator> → <lane>: <ticket id> <title>
|
|
9
9
|
LIMITS (a breach stops the task):
|
|
10
|
-
-
|
|
10
|
+
- Worktree: <new: create one for this ticket with EnterWorktree from a freshly fetched origin/main, report its path, then wait for my inputs | resume: <existing worktree path>>. Work only in that worktree.
|
|
11
11
|
- <allowed shell programs, or the forbidden host programs>
|
|
12
12
|
- On the first permission prompt, denial or hook refusal: stop and tell me in one line. Do not try another command.
|
|
13
13
|
- Only origin/main and your own worktree count as truth. Never read another session's branch or worktree.
|
|
14
14
|
Goal: <one or two sentences>
|
|
15
15
|
Ticket: <id>. Read all comments. Rulings so far: <list or "none">
|
|
16
|
-
Inputs: <.scratch paths only>
|
|
16
|
+
Inputs: <.scratch paths only; for a new worktree I send them after you report its path>
|
|
17
17
|
Scope: <in>. Out of scope: <out>
|
|
18
18
|
Done when: <checks>
|
|
19
19
|
First deliverable: <plan to me | draft PR>. No code before my OK on the plan.
|
|
@@ -35,11 +35,15 @@ When a lane stops for the day or hands over, it writes `.scratch/handoff.md` in
|
|
|
35
35
|
## Lane lifecycle
|
|
36
36
|
|
|
37
37
|
### Start
|
|
38
|
-
1.
|
|
39
|
-
2.
|
|
40
|
-
3.
|
|
41
|
-
4.
|
|
42
|
-
5.
|
|
38
|
+
1. Pick the lowest-numbered free lane (`SKILL.md`, Lanes, names and worktrees). Record lane and ticket in the status file.
|
|
39
|
+
2. Read the ticket fully. Set it to In Progress. Collect the inputs in your own `.scratch/`.
|
|
40
|
+
3. Send the brief. It names the ticket, not a path that does not exist yet.
|
|
41
|
+
4. The lane fetches `origin/main` and creates the worktree from it with `EnterWorktree`. It names the branch after the ticket. Never stack on an unmerged branch. If the work depends on one, the lead merges it first.
|
|
42
|
+
5. In the new worktree, the lane runs install and sets up the git hooks. Without them the first commit fails.
|
|
43
|
+
6. The lane reports the worktree path. Copy the inputs into its `.scratch/` and send the paths.
|
|
44
|
+
7. Non-trivial ticket: plan first, then your OK.
|
|
45
|
+
|
|
46
|
+
**Resume** a ticket that already has a worktree: the brief names its path. The lane leaves its current worktree with `ExitWorktree`. That returns it to its previous directory, which can be another worktree. It checks its current directory and calls `EnterWorktree` with the path only if it is not in that worktree yet. It never reaches into another worktree with `cd`, `git -C` or absolute paths.
|
|
43
47
|
|
|
44
48
|
### During the work
|
|
45
49
|
- Commit at once, in small steps. No `git stash`; make a WIP commit to set work aside.
|
|
@@ -53,5 +57,7 @@ When a lane stops for the day or hands over, it writes `.scratch/handoff.md` in
|
|
|
53
57
|
|
|
54
58
|
### End
|
|
55
59
|
- Merge gates (`merge-gates.md`), then the merge.
|
|
56
|
-
-
|
|
57
|
-
-
|
|
60
|
+
- The lane reports "merged + tree clean".
|
|
61
|
+
- Archive the worktree's `.scratch/` in the main checkout's `.scratch/archive/<ticket>/`.
|
|
62
|
+
- The lane leaves the merged worktree with `ExitWorktree` and checks where it landed: its previous directory, which can be another worktree. Then the orchestrator removes the merged worktree (`git worktree remove`).
|
|
63
|
+
- Mark the lane as free in the status file. The lane keeps its tab and name, and takes the next ticket of any area, through the orchestrator. It creates the worktree for that ticket with `EnterWorktree`.
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
## After the merge
|
|
18
18
|
|
|
19
19
|
- Ticket to **In Review**. Re-check after about 30 s: the GitHub integration may have set Done.
|
|
20
|
-
-
|
|
20
|
+
- Archive the ticket worktree's `.scratch/`, then remove the worktree.
|
|
21
21
|
- Update the status file.
|
|
22
22
|
|
|
23
23
|
## Ticket status
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
## Decide with the lead (do not copy them from another project)
|
|
4
4
|
|
|
5
5
|
- [ ] Language and tone for the lead. Language for lanes, tickets, commits and PRs.
|
|
6
|
+
- [ ] How many numbered lanes (`lane1` … `laneN`), and which fixed-role lanes, if any (for example `review`, `tester`). No lanes named after an area.
|
|
6
7
|
- [ ] WIP limit per lane. PR size policy (bundle by area or small PRs; the external reviewer may skip PRs above a file limit).
|
|
7
8
|
- [ ] Who creates tickets.
|
|
8
9
|
- [ ] External reviewer yes or no, and its allowance.
|
|
@@ -19,6 +20,7 @@
|
|
|
19
20
|
- `.claude/settings.json` (committed): the commands lanes need every day, so they get no prompts: tests, lint, format, `git add/commit/push/fetch`, `gh pr`, `gh run`, `gh api`, the project's make targets. No destructive grants.
|
|
20
21
|
- `.claude/settings.local.json` (gitignored): personal and one-off grants. Never commit it.
|
|
21
22
|
- `.claude/agents/code-reviewer.md`: read-only reviewer (Read, Grep, Glob), input a diff path and a focus, output findings with `file:line`, a failure scenario and a severity.
|
|
23
|
+
- A PreToolUse isolation hook that refuses commands aimed at another worktree (for example `git -C <other worktree>`). Without it, "read only inside your own worktree" is discipline only.
|
|
22
24
|
- Git hooks: pre-commit (format, lint), pre-push (tests of the changed area; a path nobody mapped means more checks, never none).
|
|
23
25
|
- CI: fast jobs on every PR, heavy jobs only on PRs that are ready for review, and branch protection with required checks. Test that a draft PR cannot merge: a skipped job passes a required check by default.
|
|
24
26
|
- Linear's GitHub integration on, and its "Done on merge" behavior known.
|
package/package.json
CHANGED