From 3cbd929901c5f4dd00bcaf033046dcc7ad7c7548 Mon Sep 17 00:00:00 2001 From: Giancarmine Salucci Date: Thu, 10 Sep 2026 03:20:37 +0200 Subject: [PATCH] feat(conductor): consolidate all operations behind single entry point - add OPERATIONS table to conductor.agent.md (init, doctor, onboard, index, memory, telemetry, design, plan, build, verify, integrate, fast-track) so the conductor agent runs any named operation directly instead of only the full pipeline - thin every skill file to a one-line pointer into conductor's OPERATIONS table, removing duplicated procedure text (contributor rule: no duplicated behavior in prompts/skills) - document the operations table in README.md and AGENTS.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/conductor.agent.md | 30 ++++++++++++++++++++++++++++++ .github/skills/build/SKILL.md | 10 +++------- .github/skills/design/SKILL.md | 12 +++--------- .github/skills/doctor/SKILL.md | 9 +++------ .github/skills/fast-track/SKILL.md | 12 ++++-------- .github/skills/index/SKILL.md | 9 +++------ .github/skills/init/SKILL.md | 9 +++------ .github/skills/integrate/SKILL.md | 10 +++------- .github/skills/memory/SKILL.md | 9 +++------ .github/skills/onboard/SKILL.md | 9 +++------ .github/skills/plan/SKILL.md | 9 +++------ .github/skills/telemetry/SKILL.md | 9 +++------ .github/skills/verify/SKILL.md | 10 +++------- AGENTS.md | 26 +++++++++++++++++++++++--- README.md | 27 +++++++++++++++++++++++++-- 15 files changed, 115 insertions(+), 85 deletions(-) diff --git a/.github/agents/conductor.agent.md b/.github/agents/conductor.agent.md index ea72beb..cd5687a 100644 --- a/.github/agents/conductor.agent.md +++ b/.github/agents/conductor.agent.md @@ -16,8 +16,38 @@ Copilot CLI are stateless (they run to completion and return one final result; t pause mid-task for a live human reply). Any question that needs a real answer must be asked directly, in conductor's own foreground turn, never through the `agent` tool. +## OPERATIONS + +Every action this harness performs is reachable through this one agent — pick the operation +that matches the user's request, run only its steps, then stop and report. Recognize the +operation from an explicit name (`onboard`, `doctor`, `init`, `index`, `memory`, `telemetry`, +`design`, `plan`, `build`, `verify`, `integrate`, `fast-track`) or from plain language +(for example "get me up to speed here" → `onboard`, "is my setup broken" → `doctor`, "just fix +this one small bug" → `fast-track`). When the request describes new product work with no +named operation, run the FULL PIPELINE (`PROCEDURE` below) end to end. + +| Operation | Trigger | Steps | +| --- | --- | --- | +| `init` | Repair or create harness baseline | `lh init --yes` → confirm `.agents/harness.config.json` and `.agents/memory/INDEX.md` exist → `lh doctor` → report created paths and blockers only. | +| `doctor` | Check environment, config, host capability | `lh doctor` → `lh host` if orchestration capability matters → `lh graph` if repo structure matters → report failures with exact commands and exit status → suggest the smallest next fix. Never mutate state unless asked to repair. | +| `onboard` | New contributor/agent needs a map of harness state | `lh doctor` → `lh index --stats --budget 4000` → read `.agents/memory/INDEX.md` only → `lh graph` → summarize commands, state paths, conventions, blockers. Pull shards only if asked for deeper history. | +| `index` | Repo understanding under a token budget | `lh index --budget --focus ` (default budget 4000, focus `.`) → add `--stats` when sizing/onboarding → `lh graph` when structure matters → return paths and facts, never dumps. | +| `memory` | Read, write, or compact memory shards | `lh memory list` to inspect → `lh memory get --shard ` to read one → `lh memory put --shard ` to write durable facts → `lh memory scan` before any risky write → `lh memory compact` when a shard grows noisy. Never write secrets. | +| `telemetry` | Start/record/end a run, or report on one | `lh run start` → `lh run event` per phase transition → `lh run end` → read `.agents/runs//board.md` for live state → `lh report ` for a markdown summary. | +| `design` | Decisions are missing or incomplete | Run inline yourself — see `DESIGN PHASE` below. Never delegate. | +| `plan` | Decisions are complete, need spec + DAG | Read `decisions.md` → invoke `architect` for `spec.md` → invoke `splitter` for `plan.dag.json` → `lh graph` → report spec path, DAG path, acceptance ids, blockers. | +| `build` | Lanes are planned, ready to execute | `lh host` for strategy → `lh lane create` per write lane → run builder ⇄ verifier Ralph loop per lane → record failures with `lh memory put --shard failures`. | +| `verify` | Check commands, gates, acceptance, scope only | Invoke `verifier` for command checks → run configured verify commands → `lh graph` → check acceptance ids individually → check scope globs → return a terse pass/fail table only. Never edit files. | +| `integrate` | Lane branches are complete, need merge | Invoke `integrator` → `lh lane merge` one lane at a time → resolve safe local conflicts, escalate conflicting acceptance criteria → one final full verify → request reviewer approval. Never merge lanes in parallel. | +| `fast-track` | Small, unambiguous, brownfield change | Confirm it is small and brownfield (escalate to full pipeline if not) → single write lane → same Ralph loop (builder ⇄ verifier) → same journal (`.agents/runs//journal.md`) → `lh graph` → request reviewer approval before completion. | +| *(none named)* | New feature/change, decisions not yet gated | Run the FULL PIPELINE: `PROCEDURE` steps below, start to finish. | + ## PROCEDURE +Run this full sequence only when no single operation above covers the request (a new feature +or cross-cutting change). Otherwise run just the matched operation's steps from the table +above and report — do not run the rest of this procedure. + 1. Run `lh doctor`. 2. If it reports `config not initialised`, run `lh init --yes` (non-interactive defaults), then run `lh doctor` again. 3. Do not proceed past a `lh doctor` failure you cannot self-heal (for example missing `verify.commands`); report the exact failing check and stop. diff --git a/.github/skills/build/SKILL.md b/.github/skills/build/SKILL.md index 34b933c..abe7851 100644 --- a/.github/skills/build/SKILL.md +++ b/.github/skills/build/SKILL.md @@ -5,11 +5,7 @@ description: Use when executing planned read and write lanes through lh host and # build skill -1. Invoke `.github/agents/conductor.agent.md`. -2. Run `lh host` first through the conductor. -3. Obey parallel or sequential strategy printed by `lh host`. -4. Use `lh lane create` for write lanes. -5. Run builder ⇄ verifier Ralph loops. -6. Record failures with `lh memory put --shard failures`. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `build` operation. +2. Conductor runs only the `build` row of its OPERATIONS table and reports the result. -Stop on max Ralph iterations and escalate. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/design/SKILL.md b/.github/skills/design/SKILL.md index cb8c9c2..acbf45c 100644 --- a/.github/skills/design/SKILL.md +++ b/.github/skills/design/SKILL.md @@ -5,13 +5,7 @@ description: Use when starting gated design discovery before planning, especiall # design skill -1. Invoke `.github/agents/conductor.agent.md` and run only its DESIGN PHASE section. -2. Require numbered questions with numbered recommended answers, asked directly in the - agent's own turn — never delegated to a subagent. -3. Mark one answer as recommended. -4. Always include a freeform `Other:` option. -5. Persist final answers to `.agents/specs//decisions.md`. -6. Stop until every required question is answered. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `design` operation. +2. Conductor runs only the `design` row of its OPERATIONS table and reports the result. -Do not infer decisions. Do not start planning before the user gate. Do not write an "open -assumptions" section or any equivalent. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/doctor/SKILL.md b/.github/skills/doctor/SKILL.md index 6375290..6a72f19 100644 --- a/.github/skills/doctor/SKILL.md +++ b/.github/skills/doctor/SKILL.md @@ -5,10 +5,7 @@ description: Use when checking harness environment, configuration, host capabili # doctor skill -1. Run `lh doctor`. -2. Run `lh host` when orchestration capability matters. -3. Run `lh graph` when repository structure matters. -4. Report failures with exact commands and exit status. -5. Suggest the smallest next fix. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `doctor` operation. +2. Conductor runs only the `doctor` row of its OPERATIONS table and reports the result. -Do not mutate project state unless the user asked for repair. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/fast-track/SKILL.md b/.github/skills/fast-track/SKILL.md index 7352719..09db1dc 100644 --- a/.github/skills/fast-track/SKILL.md +++ b/.github/skills/fast-track/SKILL.md @@ -3,13 +3,9 @@ name: fast-track description: Use for a small brownfield change that can skip spec and DAG but still needs Ralph and journal discipline. --- -# fast-track skill +# fast track skill -1. Confirm the change is small and brownfield. -2. Use a single write lane. -3. Keep the same Ralph loop: builder ⇄ verifier. -4. Keep the same journal in `.agents/runs//journal.md`. -5. Run `lh graph`. -6. Request reviewer approval before completion. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `fast-track` operation. +2. Conductor runs only the `fast-track` row of its OPERATIONS table and reports the result. -Do not fast-track ambiguous or cross-cutting work. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/index/SKILL.md b/.github/skills/index/SKILL.md index 5273fa8..0a57ba8 100644 --- a/.github/skills/index/SKILL.md +++ b/.github/skills/index/SKILL.md @@ -5,10 +5,7 @@ description: Use when needing repository understanding under a token budget befo # index skill -1. Run `lh index --budget --focus `. -2. Add `--stats` when onboarding or sizing work. -3. Prefer index output before raw reads. -4. Follow with `lh graph` when structure matters. -5. Read files by hand only after narrowing scope. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `index` operation. +2. Conductor runs only the `index` row of its OPERATIONS table and reports the result. -Return paths and facts, not dumps. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/init/SKILL.md b/.github/skills/init/SKILL.md index 0000d7e..4f238b1 100644 --- a/.github/skills/init/SKILL.md +++ b/.github/skills/init/SKILL.md @@ -5,10 +5,7 @@ description: Use when initializing lean harness state in a repository or repairi # init skill -1. Invoke `lh init`. -2. Confirm `.agents/harness.config.json` exists. -3. Confirm `.agents/memory/INDEX.md` exists. -4. Run `lh doctor` after initialization. -5. Report created paths and blockers only. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `init` operation. +2. Conductor runs only the `init` row of its OPERATIONS table and reports the result. -Delegate orchestration to `.github/agents/conductor.agent.md` when initialization is part of a full run. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/integrate/SKILL.md b/.github/skills/integrate/SKILL.md index 5ec73cc..9615b82 100644 --- a/.github/skills/integrate/SKILL.md +++ b/.github/skills/integrate/SKILL.md @@ -5,11 +5,7 @@ description: Use when planned lane branches are complete and must be merged sequ # integrate skill -1. Invoke `.github/agents/integrator.agent.md`. -2. Merge lanes one at a time with `lh lane merge`. -3. Resolve local conflicts only when safe. -4. Escalate conflicting acceptance criteria. -5. Run one final full verify. -6. Request final reviewer approval. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `integrate` operation. +2. Conductor runs only the `integrate` row of its OPERATIONS table and reports the result. -Never merge lanes in parallel. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/memory/SKILL.md b/.github/skills/memory/SKILL.md index 0eaf399..0e7bd48 100644 --- a/.github/skills/memory/SKILL.md +++ b/.github/skills/memory/SKILL.md @@ -5,10 +5,7 @@ description: Use when retrieving, writing, compacting, or scanning lean harness # memory skill -1. Use `lh memory list` to inspect shards. -2. Use `lh memory get --shard ` to read one shard. -3. Use `lh memory put --shard ` to write durable facts. -4. Use `lh memory scan` before risky writes. -5. Use `lh memory compact` when shards grow noisy. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `memory` operation. +2. Conductor runs only the `memory` row of its OPERATIONS table and reports the result. -Never write secrets to memory. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/onboard/SKILL.md b/.github/skills/onboard/SKILL.md index 8c47550..ad9d685 100644 --- a/.github/skills/onboard/SKILL.md +++ b/.github/skills/onboard/SKILL.md @@ -5,10 +5,7 @@ description: Use when a new contributor or agent needs a concise map of harness # onboard skill -1. Run `lh doctor`. -2. Run `lh index --stats --budget 4000`. -3. Read `.agents/memory/INDEX.md` only. -4. Run `lh graph`. -5. Summarize commands, state paths, conventions, and blockers. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `onboard` operation. +2. Conductor runs only the `onboard` row of its OPERATIONS table and reports the result. -Pull shards only when the user asks for deeper history. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/plan/SKILL.md b/.github/skills/plan/SKILL.md index 7d38e4c..66d146b 100644 --- a/.github/skills/plan/SKILL.md +++ b/.github/skills/plan/SKILL.md @@ -5,10 +5,7 @@ description: Use when decisions are complete and the harness must produce a spec # plan skill -1. Read `.agents/specs//decisions.md`. -2. Invoke `.github/agents/architect.agent.md` for `.agents/specs//spec.md`. -3. Invoke `.github/agents/splitter.agent.md` for `.agents/specs//plan.dag.json`. -4. Run `lh graph`. -5. Report spec path, DAG path, acceptance ids, and blockers. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `plan` operation. +2. Conductor runs only the `plan` row of its OPERATIONS table and reports the result. -Do not build before the DAG passes structural gates. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/telemetry/SKILL.md b/.github/skills/telemetry/SKILL.md index 74818b6..d1b2af4 100644 --- a/.github/skills/telemetry/SKILL.md +++ b/.github/skills/telemetry/SKILL.md @@ -5,10 +5,7 @@ description: Use when starting, recording, ending, or reporting a harness run an # telemetry skill -1. Start with `lh run start`. -2. Record phase changes with `lh run event`. -3. End with `lh run end`. -4. Read `.agents/runs//board.md` for current state. -5. Run `lh report ` for a markdown summary. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `telemetry` operation. +2. Conductor runs only the `telemetry` row of its OPERATIONS table and reports the result. -Keep event messages short and machine-readable. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/.github/skills/verify/SKILL.md b/.github/skills/verify/SKILL.md index 53595d9..735eb82 100644 --- a/.github/skills/verify/SKILL.md +++ b/.github/skills/verify/SKILL.md @@ -5,11 +5,7 @@ description: Use when checking configured commands, lh graph, acceptance criteri # verify skill -1. Invoke `.github/agents/verifier.agent.md` for command checks. -2. Run configured verify commands. -3. Run `lh graph`. -4. Check acceptance ids individually. -5. Check scope globs. -6. Return a terse pass/fail table only. +1. Invoke `.github/agents/conductor.agent.md` and ask for the `verify` operation. +2. Conductor runs only the `verify` row of its OPERATIONS table and reports the result. -Do not edit files during verification. +Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure. diff --git a/AGENTS.md b/AGENTS.md index 4425689..d265902 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,10 +41,30 @@ planned around. | `integrator` | strong | no | Sequential merge, conflict resolution, full verify. | | `scribe` | cheap | no | Journal, ADRs, living spec, conventions. | -## Skills +## Operations (all behind `conductor`) -`init` `design` `plan` `build` `verify` `integrate` `onboard` `memory` `index` -`telemetry` `fast-track` `doctor` +Select `conductor` once, then name the operation in plain language. Conductor runs only that +operation's steps — full step lists live in `conductor.agent.md` § OPERATIONS. + +| Operation | Use when | +| --- | --- | +| `init` | Harness state missing or `.agents/` baseline needs repair. | +| `doctor` | Checking environment, config, or host capability. | +| `onboard` | New contributor/agent needs a map of harness state. | +| `index` | Need repo understanding under a token budget. | +| `memory` | Reading, writing, or compacting memory shards. | +| `telemetry` | Starting/recording/ending a run, or reporting on one. | +| `design` | Decisions are missing or incomplete (gated Q&A). | +| `plan` | Decisions complete, need spec + DAG. | +| `build` | Lanes planned, ready to execute (Ralph loop). | +| `verify` | Checking commands, gates, acceptance, scope only. | +| `integrate` | Lane branches complete, need sequential merge. | +| `fast-track` | Small, unambiguous, brownfield change. | +| *(none named)* | New feature/change — runs the full pipeline end to end. | + +`.github/skills/` still ships one thin skill file per operation (`init` `design` `plan` `build` +`verify` `integrate` `onboard` `memory` `index` `telemetry` `fast-track` `doctor`) — each is a +one-line pointer into `conductor.agent.md`, not a separate implementation. ## `lh` commands diff --git a/README.md b/README.md index 87d1da6..c200e42 100644 --- a/README.md +++ b/README.md @@ -183,18 +183,41 @@ human reply), so any question that needs a real answer is asked directly, never > **brand-new** `copilot` session — an already-running session keeps the plugin snapshot it > loaded at startup and won't pick up the update until restarted. +Every operation this harness performs is reachable through `conductor` — select it once, then +name what you want in plain language: + +| Say to `conductor` | It runs | +| --- | --- | +| `onboard` | env check → repo index → memory index → graph → summary | +| `doctor` | environment/config/host capability check, no mutation | +| `init` | `lh init --yes` + baseline confirmation | +| `index` | token-budgeted repo map | +| `memory` | shard list/get/put/scan/compact | +| `telemetry` | run start/event/end + report | +| `design` | gated Q&A, one question per turn | +| `plan` | spec + lane DAG | +| `build` | worktree lanes, Ralph loop | +| `verify` | commands + `lh graph` + acceptance/scope check, no edits | +| `integrate` | sequential lane merge + final verify | +| `fast-track` | small brownfield change, single lane, same Ralph/journal discipline | +| *(anything else)* | the full pipeline, start to finish | + For a small brownfield change, skip the ceremony: ``` -/fast-track fix the off-by-one in pagination +Use the conductor agent: fast-track — fix the off-by-one in pagination ``` To learn an unfamiliar codebase first: ``` -/onboard +Use the conductor agent to onboard me on this repo ``` +`.github/skills/` still ships one thin skill (`/fast-track`, `/onboard`, etc.) per operation for +convenience — each is a one-line pointer into `conductor.agent.md` § OPERATIONS, not a separate +implementation, so behaviour never drifts between the two entry points. + ## Onboarding a new project Before the plugin is published to a marketplace (or if you want to try it against a local repo