diff --git a/AGENTS.md b/AGENTS.md index ae2ff3c81e..a5eb84c9e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -215,6 +215,25 @@ Shared skills describe *process* and resolve the *who/how* from this contract: a bad change here takes down the whole fleet; a human reviews those merges. - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config). +- **Session self-naming (ao-hosted sessions):** keep your session's name in + sync with your current work item so the dashboard and the Claude Code + session list read like a live work log. Workers set both surfaces on + claiming a work item and again on every queue item transition. Your ao + session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"` + (ao injects the env var; tmux is the fallback). Derive `` from the + issue title: lowercase `[a-z0-9-]` only, everything else stripped — never + interpolate a raw title into a shell command. + - ao display name: `ao session rename "$SID" "# "` — 20-char + cap (enforced at spawn/API; the CLI rename path currently skips the + check, so never rely on a longer name sticking). Visible in the + dashboard and `ao session get`; the `ao session ls` table doesn't show + it yet (gap tracked in GH #28). + - Claude Code session title (claude-code harness only): + `tmux send-keys -t "$SID" -l '/rename # '` then + `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other + harnesses have no title surface; ao display name only. + - Never rename the tmux session itself — its name IS the ao session id and + ao addresses the pane by it. ## Orchestrator standing policy @@ -263,9 +282,20 @@ worker on a deploy. ### Fleet caps + naming -Hard cap: **4 concurrent workers per project** (check `ao session ls` before -every spawn; queue the rest). Every spawn gets `--name "# "` so -the dashboard reads like a work log. +Hard cap: **8 concurrent workers per project** (raised from 4 by Nick, +2026-07-06; check `ao session ls` before every spawn; queue the rest). + +The dashboard and Claude Code session list are the work log — three naming +duties: +- **Yourself, at startup:** `ao session rename + "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"` + (shortened for the 20-char ao cap), and set the full + "AO Master Orchestrator" as your Claude Code session title via the + send-keys `/rename` mechanics in Repo extensions → Session self-naming. +- **Every spawn** gets `--name "# "` (≤20 chars). +- **Every spawn prompt** instructs the worker to self-rename per Session + self-naming (Repo extensions): on claiming its work item, and again on + every queue item transition. ### Always-running supervision diff --git a/AGENTS.shared.md b/AGENTS.shared.md index 1116b8855b..3d4a4e7f8e 100644 --- a/AGENTS.shared.md +++ b/AGENTS.shared.md @@ -215,6 +215,25 @@ Shared skills describe *process* and resolve the *who/how* from this contract: a bad change here takes down the whole fleet; a human reviews those merges. - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config). +- **Session self-naming (ao-hosted sessions):** keep your session's name in + sync with your current work item so the dashboard and the Claude Code + session list read like a live work log. Workers set both surfaces on + claiming a work item and again on every queue item transition. Your ao + session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"` + (ao injects the env var; tmux is the fallback). Derive `` from the + issue title: lowercase `[a-z0-9-]` only, everything else stripped — never + interpolate a raw title into a shell command. + - ao display name: `ao session rename "$SID" "# "` — 20-char + cap (enforced at spawn/API; the CLI rename path currently skips the + check, so never rely on a longer name sticking). Visible in the + dashboard and `ao session get`; the `ao session ls` table doesn't show + it yet (gap tracked in GH #28). + - Claude Code session title (claude-code harness only): + `tmux send-keys -t "$SID" -l '/rename # '` then + `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other + harnesses have no title surface; ao display name only. + - Never rename the tmux session itself — its name IS the ao session id and + ao addresses the pane by it. ## Orchestrator standing policy @@ -263,9 +282,20 @@ worker on a deploy. ### Fleet caps + naming -Hard cap: **4 concurrent workers per project** (check `ao session ls` before -every spawn; queue the rest). Every spawn gets `--name "# "` so -the dashboard reads like a work log. +Hard cap: **8 concurrent workers per project** (raised from 4 by Nick, +2026-07-06; check `ao session ls` before every spawn; queue the rest). + +The dashboard and Claude Code session list are the work log — three naming +duties: +- **Yourself, at startup:** `ao session rename + "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"` + (shortened for the 20-char ao cap), and set the full + "AO Master Orchestrator" as your Claude Code session title via the + send-keys `/rename` mechanics in Repo extensions → Session self-naming. +- **Every spawn** gets `--name "# "` (≤20 chars). +- **Every spawn prompt** instructs the worker to self-rename per Session + self-naming (Repo extensions): on claiming its work item, and again on + every queue item transition. ### Always-running supervision diff --git a/CLAUDE.md b/CLAUDE.md index 246da67f2c..35b47e32fd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -215,6 +215,25 @@ Shared skills describe *process* and resolve the *who/how* from this contract: a bad change here takes down the whole fleet; a human reviews those merges. - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config). +- **Session self-naming (ao-hosted sessions):** keep your session's name in + sync with your current work item so the dashboard and the Claude Code + session list read like a live work log. Workers set both surfaces on + claiming a work item and again on every queue item transition. Your ao + session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"` + (ao injects the env var; tmux is the fallback). Derive `` from the + issue title: lowercase `[a-z0-9-]` only, everything else stripped — never + interpolate a raw title into a shell command. + - ao display name: `ao session rename "$SID" "# "` — 20-char + cap (enforced at spawn/API; the CLI rename path currently skips the + check, so never rely on a longer name sticking). Visible in the + dashboard and `ao session get`; the `ao session ls` table doesn't show + it yet (gap tracked in GH #28). + - Claude Code session title (claude-code harness only): + `tmux send-keys -t "$SID" -l '/rename # '` then + `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other + harnesses have no title surface; ao display name only. + - Never rename the tmux session itself — its name IS the ao session id and + ao addresses the pane by it. ## Orchestrator standing policy @@ -263,9 +282,20 @@ worker on a deploy. ### Fleet caps + naming -Hard cap: **4 concurrent workers per project** (check `ao session ls` before -every spawn; queue the rest). Every spawn gets `--name "# "` so -the dashboard reads like a work log. +Hard cap: **8 concurrent workers per project** (raised from 4 by Nick, +2026-07-06; check `ao session ls` before every spawn; queue the rest). + +The dashboard and Claude Code session list are the work log — three naming +duties: +- **Yourself, at startup:** `ao session rename + "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"` + (shortened for the 20-char ao cap), and set the full + "AO Master Orchestrator" as your Claude Code session title via the + send-keys `/rename` mechanics in Repo extensions → Session self-naming. +- **Every spawn** gets `--name "# "` (≤20 chars). +- **Every spawn prompt** instructs the worker to self-rename per Session + self-naming (Repo extensions): on claiming its work item, and again on + every queue item transition. ### Always-running supervision diff --git a/GEMINI.md b/GEMINI.md index 3a0a86e160..8a616b2304 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -215,6 +215,25 @@ Shared skills describe *process* and resolve the *who/how* from this contract: a bad change here takes down the whole fleet; a human reviews those merges. - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config). +- **Session self-naming (ao-hosted sessions):** keep your session's name in + sync with your current work item so the dashboard and the Claude Code + session list read like a live work log. Workers set both surfaces on + claiming a work item and again on every queue item transition. Your ao + session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"` + (ao injects the env var; tmux is the fallback). Derive `` from the + issue title: lowercase `[a-z0-9-]` only, everything else stripped — never + interpolate a raw title into a shell command. + - ao display name: `ao session rename "$SID" "# "` — 20-char + cap (enforced at spawn/API; the CLI rename path currently skips the + check, so never rely on a longer name sticking). Visible in the + dashboard and `ao session get`; the `ao session ls` table doesn't show + it yet (gap tracked in GH #28). + - Claude Code session title (claude-code harness only): + `tmux send-keys -t "$SID" -l '/rename # '` then + `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other + harnesses have no title surface; ao display name only. + - Never rename the tmux session itself — its name IS the ao session id and + ao addresses the pane by it. ## Orchestrator standing policy @@ -263,9 +282,20 @@ worker on a deploy. ### Fleet caps + naming -Hard cap: **4 concurrent workers per project** (check `ao session ls` before -every spawn; queue the rest). Every spawn gets `--name "# "` so -the dashboard reads like a work log. +Hard cap: **8 concurrent workers per project** (raised from 4 by Nick, +2026-07-06; check `ao session ls` before every spawn; queue the rest). + +The dashboard and Claude Code session list are the work log — three naming +duties: +- **Yourself, at startup:** `ao session rename + "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"` + (shortened for the 20-char ao cap), and set the full + "AO Master Orchestrator" as your Claude Code session title via the + send-keys `/rename` mechanics in Repo extensions → Session self-naming. +- **Every spawn** gets `--name "# "` (≤20 chars). +- **Every spawn prompt** instructs the worker to self-rename per Session + self-naming (Repo extensions): on claiming its work item, and again on + every queue item transition. ### Always-running supervision diff --git a/agent-instructions/README.md b/agent-instructions/README.md new file mode 100644 index 0000000000..d21a40659c --- /dev/null +++ b/agent-instructions/README.md @@ -0,0 +1,22 @@ +# agent-instructions + +Source fragments for the generated agent instruction files at the repo root +(`AGENTS.md`, `AGENTS.shared.md`, `CLAUDE.md`, `GEMINI.md`). Never edit the +generated files — edit the fragments, then regenerate: + +```bash +npm run agents # rebuild the four repo-root files + length report +npm run agents:check # CI-style drift check (exit 1 if generated files are stale) +npm run agents:system # rebuild the global $HOME instruction files — see note +``` + +Layout (assembled in this order by `scripts/polyscribe.sh`): + +- `source/NN-*.md` — shared body fragments, concatenated in numeric order. + `30-polypowers.md` is `@sx-managed` (refreshed by nickify) — don't hand-edit. +- `agent-overrides/{codex,claude,agy}.md` — the per-agent identity appended to + that agent's file only. +- `system/` — **not committed in this repo.** It is seeded by the agent-vault + tooling on provisioned accounts; `npm run agents:system` fails on a bare + checkout with `missing .../agent-instructions/system` — that's expected, not + a bug. The other two scripts work on any checkout. diff --git a/agent-instructions/source/55-extensions.md b/agent-instructions/source/55-extensions.md index c6bb54eaa1..6577d727b7 100644 --- a/agent-instructions/source/55-extensions.md +++ b/agent-instructions/source/55-extensions.md @@ -10,3 +10,22 @@ a bad change here takes down the whole fleet; a human reviews those merges. - **Env:** sessions run with `POLYPOWERS_AUTOMERGE=1` and `POLYPOWERS_REPO=polymath-ventures/agent-orchestrator` (project config). +- **Session self-naming (ao-hosted sessions):** keep your session's name in + sync with your current work item so the dashboard and the Claude Code + session list read like a live work log. Workers set both surfaces on + claiming a work item and again on every queue item transition. Your ao + session id is `SID="${AO_SESSION_ID:-$(tmux display-message -p '#S')}"` + (ao injects the env var; tmux is the fallback). Derive `` from the + issue title: lowercase `[a-z0-9-]` only, everything else stripped — never + interpolate a raw title into a shell command. + - ao display name: `ao session rename "$SID" "# "` — 20-char + cap (enforced at spawn/API; the CLI rename path currently skips the + check, so never rely on a longer name sticking). Visible in the + dashboard and `ao session get`; the `ao session ls` table doesn't show + it yet (gap tracked in GH #28). + - Claude Code session title (claude-code harness only): + `tmux send-keys -t "$SID" -l '/rename # '` then + `tmux send-keys -t "$SID" Enter` — verified safe mid-turn. Other + harnesses have no title surface; ao display name only. + - Never rename the tmux session itself — its name IS the ao session id and + ao addresses the pane by it. diff --git a/agent-instructions/source/60-orchestrator.md b/agent-instructions/source/60-orchestrator.md index 85d3c915df..85b31c1ad1 100644 --- a/agent-instructions/source/60-orchestrator.md +++ b/agent-instructions/source/60-orchestrator.md @@ -45,9 +45,20 @@ worker on a deploy. ### Fleet caps + naming -Hard cap: **4 concurrent workers per project** (check `ao session ls` before -every spawn; queue the rest). Every spawn gets `--name "# "` so -the dashboard reads like a work log. +Hard cap: **8 concurrent workers per project** (raised from 4 by Nick, +2026-07-06; check `ao session ls` before every spawn; queue the rest). + +The dashboard and Claude Code session list are the work log — three naming +duties: +- **Yourself, at startup:** `ao session rename + "${AO_SESSION_ID:-$(tmux display-message -p '#S')}" "AO Master Orch"` + (shortened for the 20-char ao cap), and set the full + "AO Master Orchestrator" as your Claude Code session title via the + send-keys `/rename` mechanics in Repo extensions → Session self-naming. +- **Every spawn** gets `--name "# "` (≤20 chars). +- **Every spawn prompt** instructs the worker to self-rename per Session + self-naming (Repo extensions): on claiming its work item, and again on + every queue item transition. ### Always-running supervision diff --git a/package.json b/package.json index fa4a701a64..08a9503cce 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,9 @@ "name": "agent-orchestrator", "private": true, "scripts": { + "agents": "bash scripts/polyscribe.sh", + "agents:check": "bash scripts/polyscribe.sh --check", + "agents:system": "bash scripts/polyscribe.sh --system", "lint": "cd backend && go test ./... && go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 run --path-mode=abs", "frontend:typecheck": "npm --prefix frontend run typecheck", "sqlc": "cd backend && go run github.com/sqlc-dev/sqlc/cmd/sqlc@v1.31.1 generate",