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` | Five pressure scenarios with pass criteria, and how to run them with and without the skill |
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.1.0 install
35
+ npx orchestrator-skills@0.2.0 install
36
36
  # or
37
- bunx orchestrator-skills@0.1.0 install
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.1.0 install --global
43
+ npx orchestrator-skills@0.2.0 install --global
44
44
  # or
45
- bunx orchestrator-skills@0.1.0 install --global
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 give each a short name, so that the orchestrator can tell them apart in `ListAgents`.
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 | Read the ticket fully → In Progress → fresh `origin/main` → worktree + install + hooks → stage inputs → brief (`lane-briefs.md`) → plan first for non-trivial work |
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. Read the ticket fully. Set it to In Progress.
39
- 2. 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.
40
- 3. In the new worktree: install, git hooks. Without them the first commit fails.
41
- 4. Stage the inputs in `.scratch/`.
42
- 5. Send the brief. Non-trivial ticket: plan first, then your OK.
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
- - Free lane = next ticket, through the orchestrator.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "orchestrator-skills",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Claude Code skills for one orchestrator session that leads several lane sessions, one git worktree per ticket.",
5
5
  "keywords": [
6
6
  "claude-code",