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>
This commit is contained in:
@@ -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
|
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.
|
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 <N> --focus <glob>` (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 <name>` to read one → `lh memory put --shard <name>` 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/<id>/board.md` for live state → `lh report <runId>` 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/<id>/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
|
## 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`.
|
1. Run `lh doctor`.
|
||||||
2. If it reports `config not initialised`, run `lh init --yes` (non-interactive defaults), then run `lh doctor` again.
|
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.
|
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.
|
||||||
|
|||||||
@@ -5,11 +5,7 @@ description: Use when executing planned read and write lanes through lh host and
|
|||||||
|
|
||||||
# build skill
|
# build skill
|
||||||
|
|
||||||
1. Invoke `.github/agents/conductor.agent.md`.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `build` operation.
|
||||||
2. Run `lh host` first through the conductor.
|
2. Conductor runs only the `build` row of its OPERATIONS table and reports the result.
|
||||||
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`.
|
|
||||||
|
|
||||||
Stop on max Ralph iterations and escalate.
|
Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure.
|
||||||
|
|||||||
@@ -5,13 +5,7 @@ description: Use when starting gated design discovery before planning, especiall
|
|||||||
|
|
||||||
# design skill
|
# design skill
|
||||||
|
|
||||||
1. Invoke `.github/agents/conductor.agent.md` and run only its DESIGN PHASE section.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `design` operation.
|
||||||
2. Require numbered questions with numbered recommended answers, asked directly in the
|
2. Conductor runs only the `design` row of its OPERATIONS table and reports the result.
|
||||||
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/<slug>/decisions.md`.
|
|
||||||
6. Stop until every required question is answered.
|
|
||||||
|
|
||||||
Do not infer decisions. Do not start planning before the user gate. Do not write an "open
|
Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure.
|
||||||
assumptions" section or any equivalent.
|
|
||||||
|
|||||||
@@ -5,10 +5,7 @@ description: Use when checking harness environment, configuration, host capabili
|
|||||||
|
|
||||||
# doctor skill
|
# doctor skill
|
||||||
|
|
||||||
1. Run `lh doctor`.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `doctor` operation.
|
||||||
2. Run `lh host` when orchestration capability matters.
|
2. Conductor runs only the `doctor` row of its OPERATIONS table and reports the result.
|
||||||
3. Run `lh graph` when repository structure matters.
|
|
||||||
4. Report failures with exact commands and exit status.
|
|
||||||
5. Suggest the smallest next fix.
|
|
||||||
|
|
||||||
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.
|
||||||
|
|||||||
@@ -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.
|
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.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `fast-track` operation.
|
||||||
2. Use a single write lane.
|
2. Conductor runs only the `fast-track` row of its OPERATIONS table and reports the result.
|
||||||
3. Keep the same Ralph loop: builder ⇄ verifier.
|
|
||||||
4. Keep the same journal in `.agents/runs/<id>/journal.md`.
|
|
||||||
5. Run `lh graph`.
|
|
||||||
6. Request reviewer approval before completion.
|
|
||||||
|
|
||||||
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.
|
||||||
|
|||||||
@@ -5,10 +5,7 @@ description: Use when needing repository understanding under a token budget befo
|
|||||||
|
|
||||||
# index skill
|
# index skill
|
||||||
|
|
||||||
1. Run `lh index --budget <N> --focus <glob>`.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `index` operation.
|
||||||
2. Add `--stats` when onboarding or sizing work.
|
2. Conductor runs only the `index` row of its OPERATIONS table and reports the result.
|
||||||
3. Prefer index output before raw reads.
|
|
||||||
4. Follow with `lh graph` when structure matters.
|
|
||||||
5. Read files by hand only after narrowing scope.
|
|
||||||
|
|
||||||
Return paths and facts, not dumps.
|
Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure.
|
||||||
|
|||||||
@@ -5,10 +5,7 @@ description: Use when initializing lean harness state in a repository or repairi
|
|||||||
|
|
||||||
# init skill
|
# init skill
|
||||||
|
|
||||||
1. Invoke `lh init`.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `init` operation.
|
||||||
2. Confirm `.agents/harness.config.json` exists.
|
2. Conductor runs only the `init` row of its OPERATIONS table and reports the result.
|
||||||
3. Confirm `.agents/memory/INDEX.md` exists.
|
|
||||||
4. Run `lh doctor` after initialization.
|
|
||||||
5. Report created paths and blockers only.
|
|
||||||
|
|
||||||
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.
|
||||||
|
|||||||
@@ -5,11 +5,7 @@ description: Use when planned lane branches are complete and must be merged sequ
|
|||||||
|
|
||||||
# integrate skill
|
# integrate skill
|
||||||
|
|
||||||
1. Invoke `.github/agents/integrator.agent.md`.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `integrate` operation.
|
||||||
2. Merge lanes one at a time with `lh lane merge`.
|
2. Conductor runs only the `integrate` row of its OPERATIONS table and reports the result.
|
||||||
3. Resolve local conflicts only when safe.
|
|
||||||
4. Escalate conflicting acceptance criteria.
|
|
||||||
5. Run one final full verify.
|
|
||||||
6. Request final reviewer approval.
|
|
||||||
|
|
||||||
Never merge lanes in parallel.
|
Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure.
|
||||||
|
|||||||
@@ -5,10 +5,7 @@ description: Use when retrieving, writing, compacting, or scanning lean harness
|
|||||||
|
|
||||||
# memory skill
|
# memory skill
|
||||||
|
|
||||||
1. Use `lh memory list` to inspect shards.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `memory` operation.
|
||||||
2. Use `lh memory get --shard <name>` to read one shard.
|
2. Conductor runs only the `memory` row of its OPERATIONS table and reports the result.
|
||||||
3. Use `lh memory put --shard <name>` to write durable facts.
|
|
||||||
4. Use `lh memory scan` before risky writes.
|
|
||||||
5. Use `lh memory compact` when shards grow noisy.
|
|
||||||
|
|
||||||
Never write secrets to memory.
|
Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure.
|
||||||
|
|||||||
@@ -5,10 +5,7 @@ description: Use when a new contributor or agent needs a concise map of harness
|
|||||||
|
|
||||||
# onboard skill
|
# onboard skill
|
||||||
|
|
||||||
1. Run `lh doctor`.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `onboard` operation.
|
||||||
2. Run `lh index --stats --budget 4000`.
|
2. Conductor runs only the `onboard` row of its OPERATIONS table and reports the result.
|
||||||
3. Read `.agents/memory/INDEX.md` only.
|
|
||||||
4. Run `lh graph`.
|
|
||||||
5. Summarize commands, state paths, conventions, and blockers.
|
|
||||||
|
|
||||||
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.
|
||||||
|
|||||||
@@ -5,10 +5,7 @@ description: Use when decisions are complete and the harness must produce a spec
|
|||||||
|
|
||||||
# plan skill
|
# plan skill
|
||||||
|
|
||||||
1. Read `.agents/specs/<slug>/decisions.md`.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `plan` operation.
|
||||||
2. Invoke `.github/agents/architect.agent.md` for `.agents/specs/<slug>/spec.md`.
|
2. Conductor runs only the `plan` row of its OPERATIONS table and reports the result.
|
||||||
3. Invoke `.github/agents/splitter.agent.md` for `.agents/specs/<slug>/plan.dag.json`.
|
|
||||||
4. Run `lh graph`.
|
|
||||||
5. Report spec path, DAG path, acceptance ids, and blockers.
|
|
||||||
|
|
||||||
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.
|
||||||
|
|||||||
@@ -5,10 +5,7 @@ description: Use when starting, recording, ending, or reporting a harness run an
|
|||||||
|
|
||||||
# telemetry skill
|
# telemetry skill
|
||||||
|
|
||||||
1. Start with `lh run start`.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `telemetry` operation.
|
||||||
2. Record phase changes with `lh run event`.
|
2. Conductor runs only the `telemetry` row of its OPERATIONS table and reports the result.
|
||||||
3. End with `lh run end`.
|
|
||||||
4. Read `.agents/runs/<id>/board.md` for current state.
|
|
||||||
5. Run `lh report <runId>` for a markdown summary.
|
|
||||||
|
|
||||||
Keep event messages short and machine-readable.
|
Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure.
|
||||||
|
|||||||
@@ -5,11 +5,7 @@ description: Use when checking configured commands, lh graph, acceptance criteri
|
|||||||
|
|
||||||
# verify skill
|
# verify skill
|
||||||
|
|
||||||
1. Invoke `.github/agents/verifier.agent.md` for command checks.
|
1. Invoke `.github/agents/conductor.agent.md` and ask for the `verify` operation.
|
||||||
2. Run configured verify commands.
|
2. Conductor runs only the `verify` row of its OPERATIONS table and reports the result.
|
||||||
3. Run `lh graph`.
|
|
||||||
4. Check acceptance ids individually.
|
|
||||||
5. Check scope globs.
|
|
||||||
6. Return a terse pass/fail table only.
|
|
||||||
|
|
||||||
Do not edit files during verification.
|
Do not duplicate conductor's steps here -- see `conductor.agent.md` section OPERATIONS for the authoritative procedure.
|
||||||
|
|||||||
@@ -41,10 +41,30 @@ planned around.
|
|||||||
| `integrator` | strong | no | Sequential merge, conflict resolution, full verify. |
|
| `integrator` | strong | no | Sequential merge, conflict resolution, full verify. |
|
||||||
| `scribe` | cheap | no | Journal, ADRs, living spec, conventions. |
|
| `scribe` | cheap | no | Journal, ADRs, living spec, conventions. |
|
||||||
|
|
||||||
## Skills
|
## Operations (all behind `conductor`)
|
||||||
|
|
||||||
`init` `design` `plan` `build` `verify` `integrate` `onboard` `memory` `index`
|
Select `conductor` once, then name the operation in plain language. Conductor runs only that
|
||||||
`telemetry` `fast-track` `doctor`
|
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
|
## `lh` commands
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
> **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.
|
> 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:
|
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:
|
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
|
## Onboarding a new project
|
||||||
|
|
||||||
Before the plugin is published to a marketplace (or if you want to try it against a local repo
|
Before the plugin is published to a marketplace (or if you want to try it against a local repo
|
||||||
|
|||||||
Reference in New Issue
Block a user