playmakerlabs 0.0.0-stage → 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "sinteselabs-playmaker",
+  "description": "Playmaker: parallel multi-agent orchestration for Claude Code, by Síntese Labs.",
+  "owner": {
+    "name": "Síntese Labs"
+  },
+  "plugins": [
+    {
+      "name": "playmaker",
+      "source": "./",
+      "description": "Offers to run parallel work with the agent CLIs you already have installed, and coordinates the workers through git worktrees and Lore."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "playmaker",
+  "displayName": "Playmaker",
+  "version": "0.1.0",
+  "description": "Notices when there is enough parallelizable work, offers to run it with the agent CLIs you already have installed (Claude Code, Codex, Gemini/Antigravity, Copilot), and coordinates the workers through git worktrees and Lore.",
+  "author": {
+    "name": "Síntese Labs"
+  },
+  "homepage": "https://github.com/sinteselabs/Playmaker",
+  "repository": "https://github.com/sinteselabs/Playmaker",
+  "license": "MIT",
+  "keywords": ["multi-agent", "orchestration", "parallel", "worktree", "lore"],
+  "userConfig": {
+    "proactive": {
+      "type": "boolean",
+      "title": "Proactive offers",
+      "description": "Let Playmaker nudge Claude to offer parallel execution when many tasks are open. Turn off to use only the /playmaker:orchestrate skill on demand.",
+      "default": true
+    },
+    "min_tasks": {
+      "type": "number",
+      "title": "Open tasks before nudging",
+      "description": "How many open tasks in the session task list trigger the nudge.",
+      "default": 4,
+      "min": 2,
+      "max": 20
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Síntese Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,257 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+# 🎯 Playmaker
+
+> **Your agent notices when the work can run in parallel, and offers to manage it.**
+
+A plugin and a set of skills that turn the agent you are talking to into the
+manager of a parallel run: it proposes the split, you approve, and workers run
+on the agent CLIs you already have installed and signed in (Claude Code, Codex,
+Gemini, Antigravity, Copilot), each in its own git worktree and branch.
+
+[![npm](https://img.shields.io/npm/v/playmakerlabs?label=playmakerlabs)](https://www.npmjs.com/package/playmakerlabs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen)](package.json)
+[![Agent Skills](https://img.shields.io/badge/format-Agent%20Skills-blue)](https://agentskills.io)
+
+</div>
+
+---
+
+## Who talks to whom
+
+Only the manager talks to the workers, and only through two things: the brief
+it hands out and the report it gets back. Workers do not talk to each other and
+do not talk to you. The manager talks to you when it makes the offer, when it
+needs a decision, and when everything is finished.
+
+```
+you  <->  manager (Playmaker)  ->  worker A  (worktree + branch)
+                                ->  worker B  (worktree + branch)
+                                ->  worker C  (worktree + branch)
+```
+
+## What it does
+
+**Notices.** A hook counts the open tasks in the session (`TaskCreate`,
+`TaskUpdate`, `TodoWrite`). Past a threshold (4 by default) it adds one short,
+factual note to the context. That is only a nudge. The `orchestrate` skill
+decides whether a parallel run is worth it, and it also triggers on its own when
+you talk about parallel agents, multi-agent work or orchestration.
+
+**Offers, once.** The skill checks that the tasks are independent (different
+files, clear dependencies, big enough to be worth a worker). If they are, it
+sends one message with the split, a suggested provider per task, the cost, the
+merge policy (automatic when the gates pass, or ask before each merge) and
+whether the run is autonomous. Nothing starts without your "yes", unless you
+already said "parallel run". If you say no, it drops that plan.
+
+**Builds the board.** `.playmaker/board.json` holds the tasks, the files each
+one owns (`owns`), dependencies, shared files, exclusive resources and the
+project's gates.
+
+**Runs the loop (the `run` skill).**
+
+1. `board ready` computes the batch: tasks whose dependencies are merged and
+   that collide with nothing running (files, shared files, resources), up to the
+   worker cap (4 by default).
+2. `board start` creates one worktree and branch per task and starts each worker
+   in the background.
+3. `board wait` runs in the background. When a worker delivers or fails, the
+   agent is woken up.
+4. The manager reads the report, checks the real diff and runs
+   `board integrate`: rebase on the current base, gates run by the manager
+   itself, fast-forward merge, status `To test`, worktree and branch removed.
+5. If that fails, the task goes back for rework with the reason in its brief.
+   After two failed rounds it is parked as `ReFix`, and the manager does not try
+   to fix it.
+6. A delivery unblocks new tasks, which start right away. When nothing is
+   running or ready, the manager gives you the final report (and sends a push
+   notification if the tool is available).
+
+The manager never implements a delegated task. Only the manager merges. Only
+you promote a task to `Done`: `board set <task> done` requires
+`--confirmed-by-user`.
+
+**Two lighter tiers**, when a board is overkill: native subagents (Claude only,
+no board) and agent teams (Claude Code teammates that message each other,
+experimental, needs `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`).
+
+## What the tools already do, and what Playmaker adds
+
+The native multi-agent features start agents of their own provider: Codex
+subagents inherit the session's provider, and Claude Code agent teams only start
+Claude teammates. With Bash allowed, either one can call another CLI and use it
+as a worker. Playmaker does not create that ability, it organises it: a task
+board, collision-free batches, one worktree and branch per worker, background
+execution, gates run by the manager, merges that never rewrite history, retries
+and `ReFix`.
+
+## Quick start
+
+Requires Node 22 or newer and git.
+
+### 1. Claude Code plugin (recommended)
+
+```bash
+claude plugin marketplace add sinteselabs/Playmaker
+claude plugin install playmaker@sinteselabs-playmaker
+```
+
+From inside a session: `/plugin marketplace add sinteselabs/Playmaker`, then
+`/plugin install playmaker@sinteselabs-playmaker`. This is the only way that
+brings the hooks, so it is the only way the agent offers a parallel run on its
+own.
+
+On install it asks two things (also under `/config`):
+
+- **Proactive offers**: turns the automatic nudge on or off. With it off the
+  skills still work on demand (`/playmaker:orchestrate`, `/playmaker:run`).
+- **Open tasks before nudging**: how many open tasks trigger the note (2 to 20).
+
+### 2. claude.ai, the desktop app and Cowork
+
+Open **[Customize → Plugins](https://claude.ai/customize/plugins)**, then
+**Add → Add marketplace**, and paste:
+
+```
+sinteselabs/Playmaker
+```
+
+### 3. The CLI, in one project folder
+
+For Codex, Antigravity or any agent that reads skills from the project:
+
+```bash
+npx playmakerlabs init
+```
+
+It copies the two skills as `playmaker-orchestrate` and `playmaker-run` into
+`.claude/skills/` and `.agents/skills/` (`--agent claude|codex|antigravity` for
+one only, `--dry-run` to see what it would write). It never overwrites a file
+that is already there. The copies call the board through
+`npx playmakerlabs@<version>`, pinned to the version that wrote them. Hooks are
+a Claude Code plugin feature, so with the CLI the skills work on demand only.
+
+## Board commands
+
+From the plugin they are `node "${CLAUDE_PLUGIN_ROOT}/scripts/board.mjs" ...`;
+from the CLI, `npx playmakerlabs board ...`.
+
+```
+board validate                 checks the board (ids, deps, cycles, ownership collisions)
+board show [--json]            state of every task
+board ready [--json]           what runs now, and why the rest is held
+board start [--dry-run]        starts the batch
+board wait [--timeout-min N]   waits for a delivery or a failure (run it in the background)
+board integrate <task>         rebase, gates, ff-only merge
+board set <task> <status> [--note ".."] [--confirmed-by-user]
+board report [--json]          summary for the final report
+status [run] [--json] [--overlap]   per-worker view
+detect                         which agent CLIs are installed
+```
+
+The board format is in
+[`skills/orchestrate/references/board.md`](skills/orchestrate/references/board.md).
+Statuses: Not started, In progress, To test, ReFix, Done, Postpone, plus
+`delivered` (worker finished, not integrated yet) and `rework` (failed round,
+will be retried).
+
+`spawn --plan plan.json` is still there as a single-batch launcher, with no
+board and no integration (at most 6 workers).
+
+## Safety that is already in the code
+
+- **No CLI starts with a bypass flag**: no `--yolo`,
+  `--dangerously-skip-permissions`, `danger-full-access` or `--allow-all-tools`.
+  Each CLI's default mode lets the worker edit files in its worktree. If you want
+  one of those flags for a task, you name it and it goes in that task's
+  `extraArgs`.
+- **30-minute timeout per worker**, configurable per board and per task.
+- **Integration refuses to run** if the main worktree is not on the base branch
+  or has uncommitted changes.
+- **The brief never goes on the command line**, only a short prompt telling the
+  worker to read `.playmaker/brief.md`. That avoids quoting and length problems
+  on Windows.
+- **Everything lives in `.playmaker/`**, excluded from git through
+  `.git/info/exclude`. No worktree or branch is left behind after a merge.
+- **Nothing is pushed** to a remote unless you ask.
+
+The command line of each CLI and its caveats are in
+[`skills/orchestrate/references/providers.md`](skills/orchestrate/references/providers.md).
+
+## Lore, optional
+
+[Lore](https://github.com/akitaonrails/ai-memory) is used as shared memory on top
+of files and git, never as a requirement. When a run starts, the `run` skill
+looks for a `parallel-run` rule with `memory_query` and follows the team's live
+rule where it differs from the plugin's defaults. With your "yes", it can also
+record the run's plan as a page that expires, leave a handoff if the session
+ends before the workers do, and use the inbox when a task belongs to another
+repository. The details are in
+[`skills/orchestrate/references/coordination.md`](skills/orchestrate/references/coordination.md).
+
+Lore messages go between **projects** and are delivered once, so they are not
+part of the loop: the workers of a run belong to the same project and only talk
+to the manager.
+
+## Known limits
+
+- **Gates in a fresh worktree.** Gates run in a newly created worktree, so they
+  must include installing dependencies (for example `npm ci && npm test`).
+  Without it, every integration fails.
+- **No board writes during `wait`.** Do not run `integrate`, `start` or `set`
+  while a `wait` is active. Read-only commands (`show`, `ready`, `report`) are
+  fine.
+- **Windows.** The code handles the `.cmd` shims of npm-installed CLIs, but the
+  end-to-end tests run on macOS and Linux (the fake CLIs are shell scripts). Run
+  `board start --dry-run` on your machine before the first real run.
+- **Flags not yet verified in a real run**: Gemini `--approval-mode` values
+  other than `auto_edit`, the quoting of Copilot `shell(...)` rules on Windows,
+  and Antigravity permission rules. They are marked in `providers.md`.
+- **Merge policy and autonomous mode** are followed by the manager (they are in
+  the board and the skill), not enforced by the script.
+- **A per-provider "unsafe" option** does not exist yet. The bypass flag is per
+  task, in `extraArgs`.
+- **Codex.** The skills follow the Agent Skills format and install with
+  `npx playmakerlabs init`, but the hooks are Claude Code only, and the Codex
+  side has not been tested end to end.
+
+## Tests
+
+```bash
+npm test             # the CLI: init, passthrough, help, version (Windows, macOS, Linux)
+npm run test:e2e     # the full loop and the launcher (macOS, Linux)
+```
+
+The end-to-end board test brings up fake CLIs, runs six tasks with
+dependencies, a collision and a shared file, makes a gate fail and the task get
+redone, and checks that at the end everything is at `To test`, main is clean and
+no worktree or branch is left. The smoke test covers the single-batch launcher,
+the hooks (silent below the threshold, one note per session, off by
+configuration) and the validation errors.
+
+Before a release, also run `claude plugin validate .`.
+
+## Layout
+
+```
+.claude-plugin/plugin.json          manifest and options
+hooks/hooks.json                    SessionStart and PostToolUse
+skills/orchestrate/                 when to offer, how to offer, how to build the board
+skills/orchestrate/references/      board, brief, providers, coordination and Lore
+skills/run/                         the manager loop
+scripts/board.mjs                   board: ready, start, wait, integrate, set, report
+scripts/spawn.mjs                   worker supervisor and single-batch launcher
+scripts/status.mjs                  worker state and file overlap
+scripts/detect-agents.mjs           detects installed CLIs
+scripts/task-watch.mjs              counts open tasks and gives the nudge
+scripts/lib/launch.mjs              worktree, brief and start of each worker
+scripts/lib/providers.mjs           how each CLI is started
+cli/playmaker.mjs                   the npm CLI: init and the scripts above
+tests/                              end-to-end and CLI tests
+```
+
+## License
+
+[MIT](LICENSE), by Síntese Labs.

package/cli/playmaker.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// The Playmaker CLI, for agents that load skills from a project folder instead of a plugin.
+//   playmaker init [--dry-run] [--agent claude|codex|antigravity]
+//   playmaker board|status|spawn|detect [args]   the plugin's scripts, unchanged
+//
+// `init` copies the skills where each agent reads them. Inside the plugin the skills call
+// `node "${CLAUDE_PLUGIN_ROOT}/scripts/<name>.mjs"`; the copies call this CLI instead,
+// pinned to the version that wrote them, so skills and scripts never drift apart.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { name: PACKAGE_NAME, version } = JSON.parse(fs.readFileSync(path.join(PACKAGE, 'package.json'), 'utf8'));
+
+const SCRIPTS = { board: 'board.mjs', status: 'status.mjs', spawn: 'spawn.mjs', detect: 'detect-agents.mjs' };
+const AGENTS = { claude: '.claude/skills', codex: '.agents/skills', antigravity: '.agents/skills' };
+const SKILLS = ['orchestrate', 'run'];
+
+const usage = `playmaker ${version}
+
+Usage: playmaker <command> [options]
+
+  init      copy the Playmaker skills into this project
+              --dry-run   say what would be written, write nothing
+              --agent     claude, codex or antigravity (default: all)
+  board     the task board: validate, show, ready, start, wait, integrate, set, report
+  status    state of the workers of a run [run] [--json] [--overlap]
+  spawn     one-batch launcher: --plan plan.json [--dry-run]
+  detect    which agent CLIs are installed
+
+  --help    this text
+  --version the version
+
+Installed as a Claude Code plugin, Playmaker needs none of this: the plugin
+carries the skills, the scripts and the hooks.`;
+
+/** Skill text as it should read outside the plugin: prefixed names, scripts called through this CLI. */
+export function forProject(text) {
+  const cli = `npx -y ${PACKAGE_NAME}@${version}`;
+  const command = Object.fromEntries(Object.entries(SCRIPTS).map(([cmd, file]) => [file, cmd]));
+  return text
+    .replace(/^name: (orchestrate|run)(?=\r?$)/m, 'name: playmaker-$1')
+    .replace(/playmaker:(orchestrate|run)\b/g, 'playmaker-$1')
+    .replace(/node "\$\{CLAUDE_PLUGIN_ROOT\}\/scripts\/([a-z-]+\.mjs)"/g, (match, file) => (command[file] ? `${cli} ${command[file]}` : match));
+}
+
+function filesUnder(dir) {
+  const found = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const here = path.join(dir, entry.name);
+    if (entry.isDirectory()) found.push(...filesUnder(here));
+    else if (entry.isFile()) found.push(here);
+  }
+  return found;
+}
+
+export function init(argv, folder, write) {
+  let pretend = false;
+  let agent = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--dry-run') pretend = true;
+    else if (argv[i] === '--agent') {
+      agent = (argv[++i] || '').toLowerCase();
+      if (!AGENTS[agent]) {
+        write(`--agent takes one of: ${Object.keys(AGENTS).join(', ')}`);
+        return 2;
+      }
+    } else {
+      write(`unknown option ${argv[i]}\n\n${usage}`);
+      return 2;
+    }
+  }
+
+  const targets = [...new Set((agent ? [agent] : Object.keys(AGENTS)).map((a) => AGENTS[a]))];
+  let created = 0;
+  let kept = 0;
+  for (const target of targets) {
+    for (const skill of SKILLS) {
+      const from = path.join(PACKAGE, 'skills', skill);
+      for (const file of filesUnder(from)) {
+        const rel = path.join(...target.split('/'), `playmaker-${skill}`, path.relative(from, file));
+        const dest = path.join(folder, rel);
+        if (fs.existsSync(dest)) {
+          kept += 1;
+          continue;
+        }
+        created += 1;
+        write(`  ${pretend ? 'would create' : 'created'}  ${rel.split(path.sep).join('/')}`);
+        if (pretend) continue;
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, forProject(fs.readFileSync(file, 'utf8')));
+      }
+    }
+  }
+  if (kept) write(`  kept     ${kept} file${kept === 1 ? '' : 's'} that were already there`);
+  write(pretend ? `\nPlaymaker ${version}: ${created} file(s) would be written. Nothing was written.` : `\nPlaymaker ${version}: ${created} file(s) written.`);
+  if (!pretend) write('The skills are playmaker-orchestrate and playmaker-run. The hooks that offer a parallel run on their own come only with the Claude Code plugin.');
+  return 0;
+}
+
+export function run(argv, folder, write) {
+  const [command, ...rest] = argv;
+  if (!command || ['--help', '-h', 'help'].includes(command)) {
+    write(usage);
+    return command ? 0 : 2;
+  }
+  if (command === '--version' || command === '-v') {
+    write(version);
+    return 0;
+  }
+  if (command === 'init') return init(rest, folder, write);
+  if (SCRIPTS[command]) {
+    const args = command === 'detect' && !rest.length ? ['--print'] : rest;
+    const child = spawnSync(process.execPath, [path.join(PACKAGE, 'scripts', SCRIPTS[command]), ...args], { cwd: folder, stdio: 'inherit' });
+    return child.status ?? 1;
+  }
+  write(`unknown command ${command}\n\n${usage}`);
+  return 2;
+}
+
+// Run only when called, not when a test imports it. realpath because npm links the bin.
+if (process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  process.exitCode = run(process.argv.slice(2), process.cwd(), (line) => process.stdout.write(`${line}\n`));
+}

package/hooks/hooks.json

@@ -0,0 +1,30 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/detect-agents.mjs", "--hook"],
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "TaskCreate|TaskUpdate|TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/task-watch.mjs"],
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "playmakerlabs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Parallel multi-agent orchestration: one manager agent runs workers on the CLIs you already have (Claude Code, Codex, Gemini, Antigravity, Copilot) in isolated git worktrees.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "playmaker": "cli/playmaker.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    ".claude-plugin/",
+    "cli/",
+    "hooks/",
+    "scripts/",
+    "skills/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node tests/cli.mjs",
+    "test:e2e": "node tests/board.mjs && node tests/smoke.mjs"
+  },
+  "author": "Síntese Labs",
+  "homepage": "https://github.com/sinteselabs/Playmaker#readme",
+  "bugs": {
+    "url": "https://github.com/sinteselabs/Playmaker/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sinteselabs/Playmaker.git"
+  },
+  "keywords": [
+    "agent-skills",
+    "multi-agent",
+    "orchestration",
+    "parallel",
+    "git-worktree",
+    "claude-code",
+    "codex",
+    "gemini",
+    "antigravity",
+    "copilot"
+  ]
+}