orchestrator-skills 0.1.0 → 0.2.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
|
@@ -18,7 +18,7 @@ This is an opinionated approach, not a general framework. It assumes one human l
|
|
|
18
18
|
| `orchestrating-agent-lanes/lane-briefs.md` | Brief template, message format, handoff file, lane lifecycle |
|
|
19
19
|
| `orchestrating-agent-lanes/merge-gates.md` | Merge gates in order, after-merge steps, ticket status |
|
|
20
20
|
| `orchestrating-agent-lanes/setup-checklist.md` | Decisions for a new project, repository baseline, safety baseline |
|
|
21
|
-
| `tests/pressure-scenarios.md` |
|
|
21
|
+
| `tests/pressure-scenarios.md` | Six pressure scenarios with pass criteria, and how to run them with and without the skill |
|
|
22
22
|
| `bin/cli.mjs` | The installer behind `npx` / `bunx`. Tests: `npm test` |
|
|
23
23
|
|
|
24
24
|
## Requirements
|
|
@@ -32,17 +32,17 @@ This is an opinionated approach, not a general framework. It assumes one human l
|
|
|
32
32
|
1. **Install the skill.** Use `npx` (Node 18.17 or later) or `bunx`. Both run the same installer.
|
|
33
33
|
- For one project, committed with the repo. Run this in the repository root:
|
|
34
34
|
```bash
|
|
35
|
-
npx orchestrator-skills@0.
|
|
35
|
+
npx orchestrator-skills@0.2.0 install
|
|
36
36
|
# or
|
|
37
|
-
bunx orchestrator-skills@0.
|
|
37
|
+
bunx orchestrator-skills@0.2.0 install
|
|
38
38
|
|
|
39
39
|
git add .claude/skills/orchestrating-agent-lanes
|
|
40
40
|
```
|
|
41
41
|
- For all your projects (installs into `~/.claude/skills`):
|
|
42
42
|
```bash
|
|
43
|
-
npx orchestrator-skills@0.
|
|
43
|
+
npx orchestrator-skills@0.2.0 install --global
|
|
44
44
|
# or
|
|
45
|
-
bunx orchestrator-skills@0.
|
|
45
|
+
bunx orchestrator-skills@0.2.0 install --global
|
|
46
46
|
```
|
|
47
47
|
The skill is available in the next Claude Code session.
|
|
48
48
|
|
|
@@ -65,7 +65,7 @@ This is an opinionated approach, not a general framework. It assumes one human l
|
|
|
65
65
|
## Use
|
|
66
66
|
|
|
67
67
|
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
|
|
68
|
+
2. Open one tab per lane 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.
|
|
69
69
|
3. Give the orchestrator tickets. It reads them, sets up a worktree per lane, stages the inputs, and sends each lane its brief. 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
70
|
|
|
71
71
|
## Customizing
|
|
@@ -1,6 +1,6 @@
|
|
|
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 and one git worktree per ticket) - assigning tickets to lanes, writing lane briefs, reporting to the lead, 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.
|
|
3
|
+
description: Use when this session is the orchestrator for a human lead and several Claude lane sessions (one terminal tab and 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
|
|
@@ -11,6 +11,15 @@ One orchestrator session talks to the human **lead**. Several **lane** sessions
|
|
|
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
|
+
## Lane names
|
|
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
|
+
- **Worktrees and branches are named after the ticket** (`app-212-settings`), never after the lane. A lane gets a new worktree for every ticket.
|
|
21
|
+
- **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.
|
|
22
|
+
|
|
14
23
|
## The hard rules
|
|
15
24
|
|
|
16
25
|
1. **Stage inputs before the lane starts.** A lane reads only inside its own worktree. Copy every outside file it needs (UI kits, design exports, specs from Downloads, notes from the main checkout) into `<worktree>/.scratch/` first. 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/`).
|
|
@@ -22,13 +31,13 @@ One orchestrator session talks to the human **lead**. Several **lane** sessions
|
|
|
22
31
|
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
32
|
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
33
|
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.
|
|
34
|
+
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
35
|
|
|
27
36
|
## Quick reference
|
|
28
37
|
|
|
29
38
|
| Situation | Do |
|
|
30
39
|
|---|---|
|
|
31
|
-
| New ticket for a lane |
|
|
40
|
+
| New ticket for a lane | Lowest-numbered free lane → read the ticket fully → In Progress → fresh `origin/main` → worktree + install + hooks → stage inputs → brief (`lane-briefs.md`) → plan first for non-trivial work |
|
|
32
41
|
| Lane asks for an outside file | Copy it into its `.scratch/`, send the new path |
|
|
33
42
|
| Lane reports a hook refusal or denial | Tell the lead in one line. Decide: continue inside the rules, or stop |
|
|
34
43
|
| Lane shows `waiting` | Tell the lead at once: lane, prompt, what it was doing |
|
|
@@ -50,6 +59,7 @@ One orchestrator session talks to the human **lead**. Several **lane** sessions
|
|
|
50
59
|
| "Small fix, the pipeline is green, merge it" | Re-read the ticket first. Rulings arrive after pushes. |
|
|
51
60
|
| "Merged, so the ticket is Done" | In Review until the test environment check. |
|
|
52
61
|
| "I will fill in a sensible default in the lead's draft" | Facts and the lead's rulings only. Ask with a list. |
|
|
62
|
+
| "This ticket is DB work, so call the lane `db`" | Lanes are slots, not topics. Use the next free `laneN`. |
|
|
53
63
|
| "Quick `git stash` to switch" | The stash is shared by all worktrees. Make a WIP commit. |
|
|
54
64
|
| "Five agents in parallel will be faster" | The lead pays for each one. Start what the task needs. |
|
|
55
65
|
|
|
@@ -35,11 +35,12 @@ 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`, Lane names). Record lane and ticket in the status file.
|
|
39
|
+
2. Read the ticket fully. Set it to In Progress.
|
|
40
|
+
3. Fetch `origin/main`. Create the worktree and branch from it. Never stack on an unmerged branch. If the work depends on one, the lead merges it first.
|
|
41
|
+
4. In the new worktree: install, git hooks. Without them the first commit fails.
|
|
42
|
+
5. Stage the inputs in `.scratch/`.
|
|
43
|
+
6. Send the brief. Non-trivial ticket: plan first, then your OK.
|
|
43
44
|
|
|
44
45
|
### During the work
|
|
45
46
|
- Commit at once, in small steps. No `git stash`; make a WIP commit to set work aside.
|
|
@@ -54,4 +55,4 @@ When a lane stops for the day or hands over, it writes `.scratch/handoff.md` in
|
|
|
54
55
|
### End
|
|
55
56
|
- Merge gates (`merge-gates.md`), then the merge.
|
|
56
57
|
- Remove the worktree. Archive its `.scratch/` in the main checkout's `.scratch/archive/<ticket>/`.
|
|
57
|
-
-
|
|
58
|
+
- Mark the lane as free in the status file. It keeps its name and takes the next ticket of any area, through the orchestrator.
|
|
@@ -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.
|
package/package.json
CHANGED