orchestrator-skills 0.0.0-stage → 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hagen Hübel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,83 @@
1
- # Temporary Holding Version
1
+ # orchestrating-agent-lanes
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An opinionated Claude Code skill for running one **orchestrator** session that leads several **lane** sessions for one human **lead**.
4
+
5
+ - Each lane works on one ticket, in its own terminal tab and its own git worktree.
6
+ - The orchestrator talks to the lead, assigns tickets, writes the lane briefs and stages the input files.
7
+ - It also owns the shared resources, runs the merge gates and keeps the ticket status true.
8
+
9
+ 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
+ This is an opinionated approach, not a general framework. It assumes one human lead, one ticket per lane, a git worktree per lane, 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
+ ## What is in it
14
+
15
+ | File | Content |
16
+ |---|---|
17
+ | `orchestrating-agent-lanes/SKILL.md` | When the skill applies, the ten hard rules, a quick reference, red flags |
18
+ | `orchestrating-agent-lanes/lane-briefs.md` | Brief template, message format, handoff file, lane lifecycle |
19
+ | `orchestrating-agent-lanes/merge-gates.md` | Merge gates in order, after-merge steps, ticket status |
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 |
22
+ | `bin/cli.mjs` | The installer behind `npx` / `bunx`. Tests: `npm test` |
23
+
24
+ ## Requirements
25
+
26
+ - [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. Lanes use one `git worktree` each.
28
+ - 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
+
30
+ ## Setup
31
+
32
+ 1. **Install the skill.** Use `npx` (Node 18.17 or later) or `bunx`. Both run the same installer.
33
+ - For one project, committed with the repo. Run this in the repository root:
34
+ ```bash
35
+ npx orchestrator-skills@0.1.0 install
36
+ # or
37
+ bunx orchestrator-skills@0.1.0 install
38
+
39
+ git add .claude/skills/orchestrating-agent-lanes
40
+ ```
41
+ - For all your projects (installs into `~/.claude/skills`):
42
+ ```bash
43
+ npx orchestrator-skills@0.1.0 install --global
44
+ # or
45
+ bunx orchestrator-skills@0.1.0 install --global
46
+ ```
47
+ The skill is available in the next Claude Code session.
48
+
49
+ Pin the version as shown. A bare `npx orchestrator-skills` runs whatever version is newest on the day you run it. The package has no dependencies and no install scripts. The installer only copies the skill folders that ship with it and does not use the network.
50
+
51
+ | Option | Effect |
52
+ |---|---|
53
+ | `install <skill>…` | Install only the named skills. Without names, all skills are installed. |
54
+ | `-g`, `--global` | Install into `~/.claude/skills` instead of `./.claude/skills` |
55
+ | `--dir <path>` | Install into `<path>` |
56
+ | `-f`, `--force` | Replace a skill folder that already exists (for updates). Without it, the installer stops and changes nothing. |
57
+ | `-n`, `--dry-run` | Print what would be copied, change nothing |
58
+ | `list` | List the skills in the package |
59
+
60
+ To update, run the install again with the new version and `--force`. To remove a skill, delete its folder from `.claude/skills`.
61
+ 2. **Ignore the scratch folder.** Add `.scratch/` to `.gitignore`. Lanes keep their inputs, PR descriptions and review diffs there.
62
+ 3. **Go through `setup-checklist.md` with the lead.** It lists the team decisions to make before the first lane starts: language, WIP limit, PR size, who creates tickets, which commands only the lead runs, and where design inputs live. Do not copy these decisions from another project.
63
+ 4. **Grant the everyday commands** in `.claude/settings.json`: tests, lint, format, `git add/commit/push/fetch`, `gh pr` and `gh run`, your make targets. Lanes then get fewer permission prompts in tabs that nobody watches. Personal grants go in `.claude/settings.local.json`, which is not committed.
64
+
65
+ ## Use
66
+
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`.
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
+
71
+ ## Customizing
72
+
73
+ The files are product-neutral. Adapt these points to your project:
74
+
75
+ - The tool names: ticket tool, external reviewer, CI.
76
+ - The allowlist of shell programs in the brief template.
77
+ - The list of heavy topics that need an external review.
78
+
79
+ Keep the hard rules in `SKILL.md` short. A rule that applies to every session belongs in the project's `CLAUDE.md`, not here.
80
+
81
+ ## License
82
+
83
+ MIT, see [LICENSE](LICENSE).
package/bin/cli.mjs ADDED
@@ -0,0 +1,131 @@
1
+ #!/usr/bin/env node
2
+ // Installs the skills of this package into a Claude Code skills folder.
3
+ // No dependencies, no network access: it only copies files that ship in the package.
4
+
5
+ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
6
+ import { homedir } from 'node:os';
7
+ import { dirname, join, resolve } from 'node:path';
8
+ import { fileURLToPath } from 'node:url';
9
+
10
+ const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
11
+ const PKG = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
12
+
13
+ const HELP = `${PKG.name} ${PKG.version}
14
+
15
+ Usage:
16
+ ${PKG.name} install [skill...] [options] Copy skills into .claude/skills
17
+ ${PKG.name} list List the skills in this package
18
+ ${PKG.name} --help | --version
19
+
20
+ Without skill names, install copies all skills.
21
+
22
+ Options:
23
+ -g, --global Install into ~/.claude/skills (all projects)
24
+ Default: ./.claude/skills (this project)
25
+ --dir <path> Install into <path> instead
26
+ -f, --force Replace a skill folder that already exists
27
+ -n, --dry-run Print what would be copied, change nothing
28
+ `;
29
+
30
+ export function listSkills(root = PKG_ROOT) {
31
+ return readdirSync(root, { withFileTypes: true })
32
+ .filter((e) => e.isDirectory() && existsSync(join(root, e.name, 'SKILL.md')))
33
+ .map((e) => e.name)
34
+ .sort();
35
+ }
36
+
37
+ export function parseArgs(argv) {
38
+ const opts = { command: null, skills: [], global: false, dir: null, force: false, dryRun: false };
39
+ for (let i = 0; i < argv.length; i++) {
40
+ const a = argv[i];
41
+ if (a === '-h' || a === '--help') opts.command = 'help';
42
+ else if (a === '-v' || a === '--version') opts.command = 'version';
43
+ else if (a === '-g' || a === '--global') opts.global = true;
44
+ else if (a === '-f' || a === '--force') opts.force = true;
45
+ else if (a === '-n' || a === '--dry-run') opts.dryRun = true;
46
+ else if (a === '--dir') {
47
+ opts.dir = argv[++i];
48
+ if (!opts.dir) throw new Error('--dir needs a path');
49
+ } else if (a.startsWith('--dir=')) opts.dir = a.slice('--dir='.length);
50
+ else if (a.startsWith('-')) throw new Error(`Unknown option: ${a}`);
51
+ else if (!opts.command) opts.command = a;
52
+ else opts.skills.push(a);
53
+ }
54
+ if (opts.global && opts.dir) throw new Error('Use either --global or --dir, not both');
55
+ return opts;
56
+ }
57
+
58
+ export function targetDir(opts, { cwd = process.cwd(), home = homedir() } = {}) {
59
+ if (opts.dir) return resolve(cwd, opts.dir);
60
+ if (opts.global) return join(home, '.claude', 'skills');
61
+ return join(cwd, '.claude', 'skills');
62
+ }
63
+
64
+ export function install(opts, { root = PKG_ROOT, cwd, home, log = console.log } = {}) {
65
+ const available = listSkills(root);
66
+ const unknown = opts.skills.filter((s) => !available.includes(s));
67
+ if (unknown.length) {
68
+ throw new Error(`Unknown skill: ${unknown.join(', ')}. Available: ${available.join(', ')}`);
69
+ }
70
+ const chosen = opts.skills.length ? opts.skills : available;
71
+ const dest = targetDir(opts, { cwd, home });
72
+
73
+ const clashes = chosen.filter((s) => existsSync(join(dest, s)));
74
+ if (clashes.length && !opts.force) {
75
+ throw new Error(
76
+ `Already installed in ${dest}: ${clashes.join(', ')}. Use --force to replace.`,
77
+ );
78
+ }
79
+
80
+ const prefix = opts.dryRun ? '[dry run] ' : '';
81
+ if (!opts.dryRun) mkdirSync(dest, { recursive: true });
82
+ for (const skill of chosen) {
83
+ const to = join(dest, skill);
84
+ if (!opts.dryRun) {
85
+ if (existsSync(to)) rmSync(to, { recursive: true, force: true });
86
+ cpSync(join(root, skill), to, { recursive: true, verbatimSymlinks: true });
87
+ }
88
+ log(`${prefix}${clashes.includes(skill) ? 'replaced' : 'installed'} ${skill} -> ${to}`);
89
+ }
90
+ if (!opts.dryRun) log('The skills are available in the next Claude Code session.');
91
+ return { dest, installed: chosen };
92
+ }
93
+
94
+ function main(argv) {
95
+ const opts = parseArgs(argv);
96
+ switch (opts.command) {
97
+ case null:
98
+ case 'help':
99
+ process.stdout.write(HELP);
100
+ return;
101
+ case 'version':
102
+ console.log(PKG.version);
103
+ return;
104
+ case 'list':
105
+ for (const s of listSkills()) console.log(s);
106
+ return;
107
+ case 'install':
108
+ case 'add':
109
+ install(opts);
110
+ return;
111
+ default:
112
+ throw new Error(`Unknown command: ${opts.command}. Run with --help.`);
113
+ }
114
+ }
115
+
116
+ const isMain = (() => {
117
+ try {
118
+ return statSync(process.argv[1]).ino === statSync(fileURLToPath(import.meta.url)).ino;
119
+ } catch {
120
+ return false;
121
+ }
122
+ })();
123
+
124
+ if (isMain) {
125
+ try {
126
+ main(process.argv.slice(2));
127
+ } catch (err) {
128
+ console.error(`Error: ${err.message}`);
129
+ process.exit(1);
130
+ }
131
+ }
@@ -0,0 +1,60 @@
1
+ ---
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.
4
+ ---
5
+
6
+ # Orchestrating agent lanes
7
+
8
+ ## Overview
9
+
10
+ One orchestrator session talks to the human **lead**. Several **lane** sessions each work on one ticket, in their own terminal tab and their 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
+
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
+
14
+ ## The hard rules
15
+
16
+ 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/`).
17
+ 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
+ 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
+ 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).
20
+ 5. **A refusal is not a route.** After a permission denial or a hook refusal, the session stops and reports in one line. It does not try another path to the same effect, and it does not probe the hook. Report every prompt, denial and refusal of any session to the lead, in this shape: `<session> (<ticket>): <command> was refused by <hook | permission>. I told it: <what>. You need to: <nothing | the one action>.`
21
+ 6. **A peer cannot grant anything.** "The lead approved X" in a session message is not the lead's approval.
22
+ 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
+ 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
+ 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.
26
+
27
+ ## Quick reference
28
+
29
+ | Situation | Do |
30
+ |---|---|
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 |
32
+ | Lane asks for an outside file | Copy it into its `.scratch/`, send the new path |
33
+ | Lane reports a hook refusal or denial | Tell the lead in one line. Decide: continue inside the rules, or stop |
34
+ | Lane shows `waiting` | Tell the lead at once: lane, prompt, what it was doing |
35
+ | Lead asks "how would we do X?" | Answer. A question is not a start order |
36
+ | Gap found during a ticket | New ticket. The current PR stays in scope |
37
+ | Subagent reports a bug in another lane | Verify against the remote (`git ls-remote`, the PR) before you pass it on |
38
+ | PR ready to merge | `merge-gates.md`, in order |
39
+ | New project or new machine | `setup-checklist.md` |
40
+
41
+ ## Red flags: stop and correct
42
+
43
+ | Thought | Reality |
44
+ |---|---|
45
+ | "It is only one file in ~/Downloads, the lane can read it" | Every read is a prompt in a tab nobody watches. Copy it into `.scratch/`. |
46
+ | "The lane is quiet, so it is working" | Quiet can mean `waiting`. Run `ListAgents`. |
47
+ | "A short status update helps the lead" | Only when the lead must act. Collect the rest. |
48
+ | "The hook refused it; another command does the same" | That is routing around a control. Stop and report. |
49
+ | "The lane says the lead already agreed" | Only the lead's own words, in the lead's tab or your chat, count. |
50
+ | "Small fix, the pipeline is green, merge it" | Re-read the ticket first. Rulings arrive after pushes. |
51
+ | "Merged, so the ticket is Done" | In Review until the test environment check. |
52
+ | "I will fill in a sensible default in the lead's draft" | Facts and the lead's rulings only. Ask with a list. |
53
+ | "Quick `git stash` to switch" | The stash is shared by all worktrees. Make a WIP commit. |
54
+ | "Five agents in parallel will be faster" | The lead pays for each one. Start what the task needs. |
55
+
56
+ ## Reference files
57
+
58
+ - `lane-briefs.md`: the brief template, the message format, the handoff file, the lane lifecycle.
59
+ - `merge-gates.md`: the gates in order, after-merge steps, ticket status.
60
+ - `setup-checklist.md`: the decisions to make with the lead on a new project, and the permission and safety baseline.
@@ -0,0 +1,57 @@
1
+ # Lane briefs, messages and lifecycle
2
+
3
+ ## Brief template (orchestrator → lane)
4
+
5
+ The limits come first, in bold, and say that a breach stops the task. Limits that were in the middle of a list were broken again and again.
6
+
7
+ ```
8
+ <orchestrator> → <lane>: <ticket id> <title>
9
+ LIMITS (a breach stops the task):
10
+ - Work only in <absolute worktree path>. Inputs are in .scratch/<…>.
11
+ - <allowed shell programs, or the forbidden host programs>
12
+ - On the first permission prompt, denial or hook refusal: stop and tell me in one line. Do not try another command.
13
+ - Only origin/main and your own worktree count as truth. Never read another session's branch or worktree.
14
+ Goal: <one or two sentences>
15
+ Ticket: <id>. Read all comments. Rulings so far: <list or "none">
16
+ Inputs: <.scratch paths only>
17
+ Scope: <in>. Out of scope: <out>
18
+ Done when: <checks>
19
+ First deliverable: <plan to me | draft PR>. No code before my OK on the plan.
20
+ ```
21
+
22
+ Give subagents the same limits, and an allowlist of shell programs instead of a blocklist.
23
+
24
+ ## Message format (any direction)
25
+
26
+ - Status: `<from> → <to>: <ticket>: <state>. <next step>. <blocker or "no blocker">.`
27
+ - A question carries the options and a recommendation.
28
+ - A command result is reported after the result, never before.
29
+ - Lanes send questions for stakeholders (designer, PM, client) to the orchestrator. The orchestrator takes them to the lead.
30
+
31
+ ## Handoff file
32
+
33
+ When a lane stops for the day or hands over, it writes `.scratch/handoff.md` in its worktree: branch, head commit, PR, done, next, open questions, held shared resources.
34
+
35
+ ## Lane lifecycle
36
+
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.
43
+
44
+ ### During the work
45
+ - Commit at once, in small steps. No `git stash`; make a WIP commit to set work aside.
46
+ - Push alone: never in a parallel tool call, and never commit while a push runs.
47
+ - Open a draft PR right after the first push.
48
+ - Merge main in. Never rebase a pushed branch.
49
+ - Test locally only what the change touches. The full suite belongs to CI.
50
+ - A local test that uses a stub is reported as such, loudly.
51
+ - A gap found during the work becomes a new ticket. The PR stays in scope.
52
+ - Never `--no-verify`.
53
+
54
+ ### End
55
+ - Merge gates (`merge-gates.md`), then the merge.
56
+ - Remove the worktree. Archive its `.scratch/` in the main checkout's `.scratch/archive/<ticket>/`.
57
+ - Free lane = next ticket, through the orchestrator.
@@ -0,0 +1,34 @@
1
+ # Merge gates and ticket status
2
+
3
+ ## Gates, in this order
4
+
5
+ 1. **Re-read the ticket**, all comments and threaded replies. A ruling that came after the last push means: hold, and send it to the lane.
6
+ 2. **Pipeline green** on the PR head commit. Use the full 40-character SHA in API queries. A short SHA can return an empty list without an error.
7
+ 3. **Review record exists for the head commit.** A push after the review needs a review of the new diff (at least the in-house review of what changed).
8
+ - In-house: three read-only `code-reviewer` subagents in parallel (correctness, security, tests and spec) on `git diff origin/main...HEAD > .scratch/review.diff`.
9
+ - External reviewer (for example CodeRabbit) only for heavy topics: migrations, auth and permissions, money, infrastructure and secrets, public endpoints. Collect fixes into one push, then ask once.
10
+ - Every finding is fixed or answered in its thread.
11
+ 4. **Merge fallout.** Compute the merge against the current `origin/main` (`git merge-tree --write-tree origin/main HEAD`). Check conflicts, migration numbers and order, and code that changed under the branch.
12
+ 5. **Browser check** for UI or money changes, against the design reference. Images must render, not only their alt text.
13
+ 6. Merge (or ask the lead, if the lead keeps the merge).
14
+
15
+ "Ready to merge" without a review record is not allowed.
16
+
17
+ ## After the merge
18
+
19
+ - Ticket to **In Review**. Re-check after about 30 s: the GitHub integration may have set Done.
20
+ - Remove the lane's worktree, archive its `.scratch/`.
21
+ - Update the status file.
22
+
23
+ ## Ticket status
24
+
25
+ | Status | When |
26
+ |---|---|
27
+ | In Progress | A lane starts the ticket |
28
+ | In Review | Everything is built and merged |
29
+ | Done | Checked on the test environment |
30
+
31
+ - Open questions keep a ticket open.
32
+ - Brainstorm questions and rulings go on the ticket as they happen, one comment each, numbered, with the reason.
33
+ - Mention a stakeholder only on a comment that needs their ruling.
34
+ - Before the first write, check that the ticket tool points at the right workspace.
@@ -0,0 +1,38 @@
1
+ # Setup checklist for a new project
2
+
3
+ ## Decide with the lead (do not copy them from another project)
4
+
5
+ - [ ] Language and tone for the lead. Language for lanes, tickets, commits and PRs.
6
+ - [ ] WIP limit per lane. PR size policy (bundle by area or small PRs; the external reviewer may skip PRs above a file limit).
7
+ - [ ] Who creates tickets.
8
+ - [ ] External reviewer yes or no, and its allowance.
9
+ - [ ] One shared local runtime stack for all worktrees? If yes: one owner at a time and a guard on every command that changes it.
10
+ - [ ] Heavy local runs one at a time on the machine?
11
+ - [ ] Where the orchestrator's status file lives. Claude memory is personal and not in git. A gitignored `.scratch/orchestrator/` file in the main checkout is visible on the machine.
12
+ - [ ] Commands only the lead runs: infrastructure apply, deploys, secrets, messages to other people.
13
+ - [ ] Host interpreters allowed, or containers only (then a PreToolUse hook that refuses them).
14
+ - [ ] Where design inputs live: committed in the repo (recommended) or staged per lane.
15
+
16
+ ## Repository baseline
17
+
18
+ - `.scratch/` in `.gitignore`. MR/PR descriptions, review diffs and staged inputs go there.
19
+ - `.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
+ - `.claude/settings.local.json` (gitignored): personal and one-off grants. Never commit it.
21
+ - `.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.
22
+ - Git hooks: pre-commit (format, lint), pre-push (tests of the changed area; a path nobody mapped means more checks, never none).
23
+ - 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
+ - Linear's GitHub integration on, and its "Done on merge" behavior known.
25
+ - Every hook that rewrites commands tested together with the permission mode in use.
26
+
27
+ ## Safety baseline for every session
28
+
29
+ - Pin exact versions and image digests. Never fetch-and-execute (`curl … | sh`). Fail closed when something cannot be pinned or verified.
30
+ - Secrets never in a URL, log, commit or chat. The lead creates them.
31
+ - Never log request or response bodies that carry personal data.
32
+ - Confirm destructive or outward-facing steps with the lead: force-push, deleting tracked files, deploys, messages to other people.
33
+
34
+ ## Install
35
+
36
+ - Per project: run `npx orchestrator-skills@<version> install` (or `bunx`) in the repository root, then commit `.claude/skills/orchestrating-agent-lanes/`.
37
+ - Personal, all projects: add `--global`. It installs into `~/.claude/skills/`.
38
+ - The skill loads in a new session, or when the skill list refreshes.
package/package.json CHANGED
@@ -1,6 +1,37 @@
1
1
  {
2
2
  "name": "orchestrator-skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Claude Code skills for one orchestrator session that leads several lane sessions, one git worktree per ticket.",
5
+ "keywords": [
6
+ "claude-code",
7
+ "claude",
8
+ "skills",
9
+ "agent-skills",
10
+ "orchestrator",
11
+ "git-worktree"
12
+ ],
13
+ "license": "MIT",
14
+ "author": "Hagen Hübel",
15
+ "homepage": "https://github.com/itinance/orchestrator-skills#readme",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/itinance/orchestrator-skills.git"
19
+ },
20
+ "bugs": {
21
+ "url": "https://github.com/itinance/orchestrator-skills/issues"
22
+ },
23
+ "type": "module",
24
+ "bin": {
25
+ "orchestrator-skills": "bin/cli.mjs"
26
+ },
27
+ "files": [
28
+ "bin/",
29
+ "orchestrating-agent-lanes/"
30
+ ],
31
+ "engines": {
32
+ "node": ">=18.17"
33
+ },
34
+ "scripts": {
35
+ "test": "node --test tests/*.test.mjs"
36
+ }
37
+ }