From 099001728cbf078a088fb3c20f6d0217496e9b8e Mon Sep 17 00:00:00 2001 From: Giancarmine Salucci Date: Thu, 10 Sep 2026 02:33:22 +0200 Subject: [PATCH] fix(agents): document exact lh CLI flags in every agent profile Every agent's PROCEDURE/OUTPUTS referenced lh subcommands vaguely (e.g. 'Run lh run event', 'lh memory get --shard failures'), forcing models to guess flags at runtime instead of following the profile. Two real bugs found this way: - 'lh memory get --shard X' silently ignores --shard (it's a positional arg on get, not a flag) and returns the whole INDEX.md instead of the targeted shard. Fixed to 'lh memory get X' everywhere. - lh run event/lane create calls had no required --type/--status/--id/ --kind/--scope documented, so agents had to trial-and-error discover them. Added full, exact invocation syntax inline for every command each agent actually issues (run event, lane create, memory get/put, host --strategy, graph). --- .github/agents/architect.agent.md | 4 ++-- .github/agents/builder.agent.md | 12 ++++++------ .github/agents/conductor.agent.md | 4 ++-- .github/agents/integrator.agent.md | 4 ++-- .github/agents/interrogator.agent.md | 2 +- .github/agents/reviewer.agent.md | 2 +- .github/agents/scout.agent.md | 2 +- .github/agents/scribe.agent.md | 8 ++++---- .github/agents/splitter.agent.md | 2 +- .github/agents/verifier.agent.md | 2 +- 10 files changed, 21 insertions(+), 21 deletions(-) diff --git a/.github/agents/architect.agent.md b/.github/agents/architect.agent.md index 0bebc4c..9d796ef 100644 --- a/.github/agents/architect.agent.md +++ b/.github/agents/architect.agent.md @@ -16,14 +16,14 @@ Write the spec. Make every acceptance criterion checkable. 1. Read `.agents/specs//decisions.md` first. 2. Stop if decisions are missing or incomplete. 3. Run `lh index --budget 6000 --focus `. -4. Run `lh graph`. +4. Run `lh graph` (add `--json` for structured output; exit code 0 means no violations). 5. Delegate focused read-only reconnaissance to `scout` when needed. 6. Consult Context7 before using any external library or framework API. 7. Use `resolve-library-id` before `query-docs`. 8. If `CONTEXT7_API_KEY` is missing, tell the user how to export it and stop library work. 9. Read `.agents/architecture.md` when present. 10. Read `.agents/conventions.md` when present. -11. Pull relevant memory shards with `lh memory get`. +11. Pull relevant memory shards with `lh memory get [--query ] [--limit N]` (omit `` to read the index; omit `--query`/`--limit` for the full shard). 12. Draft `.agents/specs//spec.md`. 13. Include goal, non-goals, decisions, constraints, risks, and rollout notes. 14. Write acceptance criteria as numbered ids: `AC-001`, `AC-002`, `AC-003`. diff --git a/.github/agents/builder.agent.md b/.github/agents/builder.agent.md index 6a8fbfc..6b2ce06 100644 --- a/.github/agents/builder.agent.md +++ b/.github/agents/builder.agent.md @@ -18,14 +18,14 @@ Implement one lane. Stay inside worktree and scope. 4. Read `.agents/specs//spec.md`. 5. Read `.agents/specs//plan.dag.json`. 6. Read `.agents/memory/INDEX.md`. -7. Pull relevant failures with `lh memory get --shard failures`. -8. Pull relevant conventions with `lh memory get --shard conventions`. +7. Pull relevant failures with `lh memory get failures` (shard name is a positional argument, not `--shard`). +8. Pull relevant conventions with `lh memory get conventions`. 9. Inspect only files matched by the lane scope globs. 10. Change only files matched by the lane scope globs. 11. Keep changes minimal and complete for assigned acceptance ids. 12. Run targeted verify commands for the lane. 13. Return `READY_FOR_VERIFIER` with lane id, scope, acceptance ids, and verify commands. -14. If verifier fails, record failure with `lh memory put --shard failures`. +14. If verifier fails, record failure with `lh memory put --shard failures --title "" --body ""`. 15. Fix verifier failures inside scope. 16. Repeat Ralph loop until pass or max iterations. 17. Request `reviewer` only after verifier passes when caller requires review. @@ -45,14 +45,14 @@ Implement one lane. Stay inside worktree and scope. - Read `.agents/specs//spec.md`. - Read `.agents/specs//plan.dag.json`. - Read `.agents/memory/INDEX.md`. -- Read `.agents/memory/failures.md` through `lh memory get --shard failures`. +- Read `.agents/memory/failures.md` through `lh memory get failures`. - Read files inside assigned worktree and scope globs. ## OUTPUTS - Write only files inside assigned worktree and scope globs. -- Write `.agents/memory/failures.md` through `lh memory put --shard failures`. -- Emit lane events through `lh run event` when a run id exists. +- Write `.agents/memory/failures.md` through `lh memory put --shard failures --title "" --body ""`. +- Emit lane events through `lh run event --type lane --status ok|error --lane --run-id ` when a run id exists. ## STOP CONDITIONS diff --git a/.github/agents/conductor.agent.md b/.github/agents/conductor.agent.md index 8e1d520..b04ca84 100644 --- a/.github/agents/conductor.agent.md +++ b/.github/agents/conductor.agent.md @@ -16,7 +16,7 @@ Run the full lean harness pipeline. Edit no product files. 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. -4. Run `lh host`. +4. Run `lh host --strategy` (prints only the orchestration-strategy text; drop `--strategy` to also see the detection table, or add `--json` for structured output). 5. Read the printed host strategy before any other action. 6. If the strategy permits parallel lanes, use host fan-out. 7. If the strategy says sequential, run every lane one at a time. @@ -39,7 +39,7 @@ Run the full lean harness pipeline. Edit no product files. 24. Re-plan at every checkpoint. 25. Spawn, kill, merge, or re-scope lanes only through updated `plan.dag.json` and `lh lane` commands. 26. For read lanes, run `scout` on the shared checkout. -27. For write lanes, run `lh lane create` before any builder starts. +27. For write lanes, run `lh lane create --id --title "" --kind write --scope [--depends-on ] [--acceptance AC-001,AC-002] --run-id ` before any builder starts. 28. Assign each builder exactly one lane and one worktree. 29. Give each builder its declared scope globs and acceptance ids. 30. Run builder and verifier in the Ralph loop. diff --git a/.github/agents/integrator.agent.md b/.github/agents/integrator.agent.md index 7d93399..5dc9946 100644 --- a/.github/agents/integrator.agent.md +++ b/.github/agents/integrator.agent.md @@ -26,7 +26,7 @@ Merge lanes one at a time. Verify once at the end. 11. Resolve conflicts when resolution is local and preserves all accepted behavior. 12. Escalate conflicts when acceptance criteria conflict or scope must widen. 13. After each merge, run a targeted smoke verify if configured. -14. Record merge event with `lh run event`. +14. Record merge event with `lh run event --type merge --status ok|error --lane --run-id `. 15. After all lane merges, invoke `verifier` for full verify. 16. Full verify must include all configured commands and `lh graph`. 17. Invoke `reviewer` for final integrated review. @@ -44,7 +44,7 @@ Merge lanes one at a time. Verify once at the end. ## OUTPUTS - Write merged files only through `lh lane merge` and conflict resolution. -- Append integration events through `lh run event`. +- Append integration events through `lh run event --type merge --run-id `. - Return final verify and review results. ## STOP CONDITIONS diff --git a/.github/agents/interrogator.agent.md b/.github/agents/interrogator.agent.md index d393834..6be239c 100644 --- a/.github/agents/interrogator.agent.md +++ b/.github/agents/interrogator.agent.md @@ -15,7 +15,7 @@ Ask every required design question. Leave nothing to inference. 1. Receive the task statement and target slug. 2. Run `lh index --budget 4000 --focus .` when repo context is needed. 3. Read `.agents/memory/INDEX.md`. -4. Pull only relevant memory shards with `lh memory get`. +4. Pull only relevant memory shards with `lh memory get [--query ] [--limit N]`. 5. Derive unknowns from the task, AGENTS.md, and existing specs. 6. Group unknowns by product behavior, constraints, validation, risk, and rollout. 7. For every unknown, write one question. diff --git a/.github/agents/reviewer.agent.md b/.github/agents/reviewer.agent.md index e87287c..8b72bac 100644 --- a/.github/agents/reviewer.agent.md +++ b/.github/agents/reviewer.agent.md @@ -50,7 +50,7 @@ Approve or reject. Check every criterion. - Return `APPROVE` or `REJECT`. - Return reasons and required fixes. -- Emit review events through `lh run event` when a run id exists. +- Emit review events through `lh run event --type review --status ok|error --lane --run-id ` when a run id exists. ## STOP CONDITIONS diff --git a/.github/agents/scout.agent.md b/.github/agents/scout.agent.md index e37b73a..8d32123 100644 --- a/.github/agents/scout.agent.md +++ b/.github/agents/scout.agent.md @@ -49,7 +49,7 @@ Recon the repo. Return facts, not dumps. ## OUTPUTS - Return summary text to caller. -- Emit `lh run event` only if caller provided run id. +- Emit `lh run event --type scout --status ok --run-id ` only if caller provided run id. ## STOP CONDITIONS diff --git a/.github/agents/scribe.agent.md b/.github/agents/scribe.agent.md index b0df592..50c3748 100644 --- a/.github/agents/scribe.agent.md +++ b/.github/agents/scribe.agent.md @@ -24,9 +24,9 @@ Document continuously. Never block the pipeline. 10. Append ADR notes inside `.agents/architecture.md` only when durable architectural decisions appear. 11. Update `.agents/specs//spec.md` only for accepted living-spec deltas. 12. Update `.agents/conventions.md` only for durable project conventions. -13. Write memory shards through `lh memory put` when events reveal reusable facts. -14. Use shards: failures, corrections, insights, conventions, quirks. -15. Run `lh memory scan` before writing memory if secrets may appear. +13. Write memory shards through `lh memory put --shard --title "" --body "" [--tags a,b]` when events reveal reusable facts. +14. Use shard names: `failures`, `corrections`, `insights`, `conventions`, `quirks`. +15. Run `lh memory scan` (scans all shards; pass filenames as positional args to scan specific files) before writing memory if secrets may appear. 16. Keep every entry short and dated. 17. If write conflicts occur, emit a note and continue later. 18. Return latest journal path and any skipped updates. @@ -46,7 +46,7 @@ Document continuously. Never block the pipeline. - Write `.agents/architecture.md` when ADRs change. - Write `.agents/specs//spec.md` when living spec changes. - Write `.agents/conventions.md` when conventions change. -- Write memory shards through `lh memory put`. +- Write memory shards through `lh memory put --shard --title "" --body ""`. ## STOP CONDITIONS diff --git a/.github/agents/splitter.agent.md b/.github/agents/splitter.agent.md index a0ba28a..e303157 100644 --- a/.github/agents/splitter.agent.md +++ b/.github/agents/splitter.agent.md @@ -58,7 +58,7 @@ Emit the lane DAG. Keep write scopes disjoint. ## OUTPUTS - Write `.agents/specs//plan.dag.json`. -- Emit graph status through `lh run event` when a run id exists. +- Emit graph status through `lh run event --type graph --status ok|error --run-id ` when a run id exists. ## STOP CONDITIONS diff --git a/.github/agents/verifier.agent.md b/.github/agents/verifier.agent.md index d036825..ee9431e 100644 --- a/.github/agents/verifier.agent.md +++ b/.github/agents/verifier.agent.md @@ -46,7 +46,7 @@ Verify. Return table only. ## OUTPUTS - Return a terse pass/fail table. -- Emit verify events through `lh run event` when a run id exists. +- Emit verify events through `lh run event --type verify --status ok|error --lane --run-id ` when a run id exists. ## STOP CONDITIONS