From 017cf1f5a44defe1208418acd6454687147acb15 Mon Sep 17 00:00:00 2001 From: polymath-orchestrator Date: Mon, 6 Jul 2026 03:45:52 +0000 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20sessions=20self-name=20=E2=80=94=20?= =?UTF-8?q?orchestrator=20+=20per-work=20worker=20renames=20(#21)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Orchestration-layer change only (vanilla rule: no ao source touched). - Repo extensions: new "Session self-naming" rules for ao-hosted sessions — ao display name via `ao session rename` (20-char cap) and Claude Code session title via send-keys `/rename` into the session's own pane (verified live, safe mid-turn); never rename the tmux session (it is the ao session id). Workers rename on claim and on every queue item transition. - Orchestrator standing policy: self-name "AO Master Orch" at startup (full "AO Master Orchestrator" on the Claude Code title), keep spawn --name, and require spawn prompts to carry the worker self-rename duty. - Fleet cap corrected 4 -> 8 per Nick's 2026-07-06 directive (doc was stale). Missing ao primitive documented in #28 (displayName -> harness title sync). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XeeHG3EbzwMa4vtpvitrqn --- AGENTS.md | 29 ++++++++++++++++++-- AGENTS.shared.md | 29 ++++++++++++++++++-- CLAUDE.md | 29 ++++++++++++++++++-- GEMINI.md | 29 ++++++++++++++++++-- agent-instructions/source/55-extensions.md | 14 ++++++++++ agent-instructions/source/60-orchestrator.md | 15 ++++++++-- 6 files changed, 130 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ae2ff3c81e..b64e3490c5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -215,6 +215,20 @@ 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 `ao session ls`, 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 + (`SID="$(tmux display-message -p '#S')"` is your ao session id): + - 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). + - 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 +277,18 @@ 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 session lists are the work log — three naming duties: +- **Yourself, at startup:** `ao session rename "$(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..b59e642119 100644 --- a/AGENTS.shared.md +++ b/AGENTS.shared.md @@ -215,6 +215,20 @@ 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 `ao session ls`, 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 + (`SID="$(tmux display-message -p '#S')"` is your ao session id): + - 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). + - 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 +277,18 @@ 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 session lists are the work log — three naming duties: +- **Yourself, at startup:** `ao session rename "$(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..8a7259560f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -215,6 +215,20 @@ 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 `ao session ls`, 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 + (`SID="$(tmux display-message -p '#S')"` is your ao session id): + - 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). + - 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 +277,18 @@ 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 session lists are the work log — three naming duties: +- **Yourself, at startup:** `ao session rename "$(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..709b838689 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -215,6 +215,20 @@ 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 `ao session ls`, 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 + (`SID="$(tmux display-message -p '#S')"` is your ao session id): + - 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). + - 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 +277,18 @@ 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 session lists are the work log — three naming duties: +- **Yourself, at startup:** `ao session rename "$(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/source/55-extensions.md b/agent-instructions/source/55-extensions.md index c6bb54eaa1..795577fc1f 100644 --- a/agent-instructions/source/55-extensions.md +++ b/agent-instructions/source/55-extensions.md @@ -10,3 +10,17 @@ 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 `ao session ls`, 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 + (`SID="$(tmux display-message -p '#S')"` is your ao session id): + - 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). + - 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..670f5355b9 100644 --- a/agent-instructions/source/60-orchestrator.md +++ b/agent-instructions/source/60-orchestrator.md @@ -45,9 +45,18 @@ 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 session lists are the work log — three naming duties: +- **Yourself, at startup:** `ao session rename "$(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 From 3aa6db4940318a8c9a16e06ee693fad9b5db4eae Mon Sep 17 00:00:00 2001 From: polymath-orchestrator Date: Mon, 6 Jul 2026 03:45:52 +0000 Subject: [PATCH 2/3] chore: add the agents/agents:check/agents:system npm scripts The generated-file banner and scripts/polyscribe.sh usage notes both say "npm run agents", but package.json never defined the scripts. Wire them to scripts/polyscribe.sh so the documented regeneration commands work. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XeeHG3EbzwMa4vtpvitrqn --- package.json | 3 +++ 1 file changed, 3 insertions(+) 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", From 4c0bc8ec9518200da291e1f58f68fa14e598a030 Mon Sep 17 00:00:00 2001 From: polymath-orchestrator Date: Mon, 6 Jul 2026 04:00:16 +0000 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20review=20fixes=20=E2=80=94=20AO=5FS?= =?UTF-8?q?ESSION=5FID,=20slug=20hygiene,=20surface=20accuracy?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Prefer ao-injected AO_SESSION_ID over the tmux fallback for the session id (Copilot finding). - Stop implying the rename shows in `ao session ls` — name the real surfaces (dashboard, `ao session get`, Claude Code list) and point at gap #28 (Copilot finding). - Define as lowercase [a-z0-9-] derived from the issue title so raw titles are never interpolated into shell commands (codex-side finding). - Document the assembly layout and the vault-seeded agent-instructions/system/ expectation (agents:system fails on a bare checkout by design). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01XeeHG3EbzwMa4vtpvitrqn --- AGENTS.md | 25 +++++++++++++------- AGENTS.shared.md | 25 +++++++++++++------- CLAUDE.md | 25 +++++++++++++------- GEMINI.md | 25 +++++++++++++------- agent-instructions/README.md | 22 +++++++++++++++++ agent-instructions/source/55-extensions.md | 15 ++++++++---- agent-instructions/source/60-orchestrator.md | 10 ++++---- 7 files changed, 102 insertions(+), 45 deletions(-) create mode 100644 agent-instructions/README.md diff --git a/AGENTS.md b/AGENTS.md index b64e3490c5..a5eb84c9e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -216,13 +216,18 @@ Shared skills describe *process* and resolve the *who/how* from this contract: - **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 `ao session ls`, 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 - (`SID="$(tmux display-message -p '#S')"` is your ao session id): + 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). + 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 @@ -280,10 +285,12 @@ worker on a deploy. 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 session lists are the work log — three naming duties: -- **Yourself, at startup:** `ao session rename "$(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 +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 diff --git a/AGENTS.shared.md b/AGENTS.shared.md index b59e642119..3d4a4e7f8e 100644 --- a/AGENTS.shared.md +++ b/AGENTS.shared.md @@ -216,13 +216,18 @@ Shared skills describe *process* and resolve the *who/how* from this contract: - **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 `ao session ls`, 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 - (`SID="$(tmux display-message -p '#S')"` is your ao session id): + 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). + 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 @@ -280,10 +285,12 @@ worker on a deploy. 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 session lists are the work log — three naming duties: -- **Yourself, at startup:** `ao session rename "$(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 +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 diff --git a/CLAUDE.md b/CLAUDE.md index 8a7259560f..35b47e32fd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -216,13 +216,18 @@ Shared skills describe *process* and resolve the *who/how* from this contract: - **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 `ao session ls`, 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 - (`SID="$(tmux display-message -p '#S')"` is your ao session id): + 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). + 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 @@ -280,10 +285,12 @@ worker on a deploy. 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 session lists are the work log — three naming duties: -- **Yourself, at startup:** `ao session rename "$(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 +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 diff --git a/GEMINI.md b/GEMINI.md index 709b838689..8a616b2304 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -216,13 +216,18 @@ Shared skills describe *process* and resolve the *who/how* from this contract: - **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 `ao session ls`, 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 - (`SID="$(tmux display-message -p '#S')"` is your ao session id): + 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). + 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 @@ -280,10 +285,12 @@ worker on a deploy. 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 session lists are the work log — three naming duties: -- **Yourself, at startup:** `ao session rename "$(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 +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 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 795577fc1f..6577d727b7 100644 --- a/agent-instructions/source/55-extensions.md +++ b/agent-instructions/source/55-extensions.md @@ -11,13 +11,18 @@ - **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 `ao session ls`, 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 - (`SID="$(tmux display-message -p '#S')"` is your ao session id): + 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). + 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 diff --git a/agent-instructions/source/60-orchestrator.md b/agent-instructions/source/60-orchestrator.md index 670f5355b9..85b31c1ad1 100644 --- a/agent-instructions/source/60-orchestrator.md +++ b/agent-instructions/source/60-orchestrator.md @@ -48,10 +48,12 @@ worker on a deploy. 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 session lists are the work log — three naming duties: -- **Yourself, at startup:** `ao session rename "$(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 +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