mozempk/redsen-lean-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarify manual vs automatic lh usage; lead with plugin install

Browse Source 
- Add exhaustive table of every lh subcommand: who runs it automatically
  (agents, per their own instructions) vs what you run yourself (init,
  doctor, report).
- Reorder quickstart to lead with copilot plugin install (marketplace
  path, verified end-to-end on this machine), with onboarding script and
  clone+link as alternatives and explicit guidance on when to use each.
- Clarify the two-layer install model: plugin install only adds the
  behaviour layer; lh CLI (determinism layer) is a separate step until
  published to npm.
- README install section and troubleshooting table updated to match.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
mozempk
2026-09-10 00:46:17 +02:00
co-authored by Copilot
parent 5ab8b59861
commit cadbec5797
2 changed files with 93 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+19 -6
View File
@@ -44,14 +44,18 @@ Three layers, one hard boundary — **we never reimplement an agent runtime**
### GitHub Copilot CLI
```bash
# direct from the repo
copilot plugin install redsentech/lean-harness
# or via the marketplace
# preferred: via the marketplace this repo publishes (verified end-to-end, no warning)
copilot plugin marketplace add redsentech/lean-harness
copilot plugin install redsen-lean-harness@redsen
# also works, but Copilot CLI prints a deprecation warning for direct-source installs
copilot plugin install redsentech/lean-harness
```
Either form installs only the **behaviour layer** (agents, skills, instructions, MCP config),
host-wide across every repo you open with that Copilot CLI account. You still need the `lh`
CLI on `PATH` separately — see below.
### VS Code Copilot
Clone the repo and point VS Code's Copilot customization settings at it, or copy the `.github/`
@@ -63,11 +67,19 @@ read by both hosts.
### The `lh` CLI
The behaviour layer above only works if the agents can actually call `lh` — it's what runs
`lh init`/`lh doctor`/`lh graph`/etc. under the hood. Not yet on the npm registry, so today:
```bash
npm install -g @redsen/lean-harness # or: npx @redsen/lean-harness <command>
git clone git@github.com:redsentech/lean-harness.git && cd lean-harness && npm install
npm link # puts `lh` on PATH globally
# once published: npm install -g @redsen/lean-harness (or: npx @redsen/lean-harness <command>)
lh doctor # verify the environment
```
`scripts/onboard.mjs` (see [Onboarding a new project](#onboarding-a-new-project)) does the
clone-free equivalent of `npm link`, scoped to one target repo, in a single command.
### Context7
Mandatory before any external-library work. The key is read from the environment **only** — the
@@ -79,7 +91,8 @@ export CONTEXT7_API_KEY="<your key>" # add to ~/.bashrc or ~/.zshrc
## Quick start
> Full walkthrough with troubleshooting: [docs/QUICKSTART.md](docs/QUICKSTART.md)
> Full walkthrough — install paths compared, troubleshooting, and exactly when you (vs. the
> agents) need to run `lh` yourself: [docs/QUICKSTART.md](docs/QUICKSTART.md)
```bash
cd your-repo
docs/QUICKSTART.md
+74 -31
View File
@@ -19,36 +19,59 @@ The harness never writes this key to disk. It is read from the environment only.
## 1. Get the harness into your project
Pick one path.
The harness has **two layers you install separately**: the *behaviour* layer
(`.github/agents`, `skills`, `instructions`, `prompts`, `mcp.json` — markdown, read by the
host) and the *determinism* layer (the `lh` CLI — Node, called by the agents). Every install
path below gets you the behaviour layer; only B and C also give you `lh` on `PATH` in one step.
### A. Fresh clone, working inside this repo
### A. Copilot CLI plugin (recommended — start here)
This is the primary distribution path for **GitHub Copilot CLI** users. It registers the
agents/skills/instructions host-wide, so every repo you open in that Copilot CLI account can
use `@conductor`, `/fast-track`, etc. — verified end-to-end on this machine:
```bash
# preferred: via the marketplace this repo publishes (no npm publish required, no deprecation warning)
copilot plugin marketplace add redsentech/lean-harness
copilot plugin install redsen-lean-harness@redsen
# also works, but Copilot CLI prints a deprecation warning for direct-source installs:
copilot plugin install redsentech/lean-harness
```
Use this when: you're a day-to-day Copilot CLI user who wants the harness available across
multiple projects and doesn't need to modify the harness itself.
Limitation: this installs the *behaviour* layer only. You still need `lh` on `PATH` (see
below) for `lh init`/`lh doctor` and everything the agents call automatically — the package
isn't on the npm registry yet, so today that means step B or C, not `npm install -g` (the
README's `npm install -g @redsen/lean-harness` line is the path once it's published).
### B. Bootstrap an existing repo with the onboarding script
Use this when: you're on **VS Code Copilot** (which has no plugin installer and reads
`.github/` directly), you want to try the harness against one specific repo before deciding to
install it host-wide, or you want `lh` linked in one shot without a separate npm step.
```bash
git clone git@github.com:redsentech/lean-harness.git # one-time, holds the source of scripts/onboard.mjs
cd lean-harness && npm install
node scripts/onboard.mjs /path/to/your-project --dry-run # preview only
node scripts/onboard.mjs /path/to/your-project --yes # do it
```
This copies the behaviour layer into `/path/to/your-project`, `npm link`s the `lh` CLI onto
`PATH` there, and runs `lh init` + `lh doctor` for you. Safe to re-run.
### C. Clone and work inside this repo directly
Use this when: you're contributing to the harness itself (fixing an agent, a skill, or `lh`).
```bash
git clone git@github.com:redsentech/lean-harness.git
cd lean-harness
npm install
```
### B. Bootstrap an existing repo (recommended for most users)
From inside a checkout of this repo, point the onboarding script at any target repo:
```bash
node scripts/onboard.mjs /path/to/your-project --dry-run # preview only
node scripts/onboard.mjs /path/to/your-project --yes # do it
```
This copies the behaviour layer (`.github/agents`, `skills`, `instructions`, `prompts`,
`mcp.json`, `copilot-instructions.md`, `AGENTS.md`) into your project, `npm link`s the `lh`
CLI onto `PATH` there, and runs `lh init` + `lh doctor` for you. Safe to re-run.
### C. Install as a Copilot CLI plugin
```bash
copilot plugin install redsentech/lean-harness
# or, once published to a marketplace:
copilot plugin marketplace add redsentech/lean-harness
copilot plugin install redsen-lean-harness@redsen
npm link # puts `lh` on PATH globally, pointing at this checkout
```
## 2. Initialize and verify the environment
@@ -104,14 +127,32 @@ sequentially, and `scribe` journals everything as it happens.
/onboard
```
## 4. Watch it work
## 4. When do *you* need to type `lh` yourself?
- `lh run` writes NDJSON telemetry as the pipeline executes; `lh report` turns that into a
markdown summary.
- `lh graph` is the structural gate (duplicates, orphans, unresolved calls) — it must pass
before any lane is considered done.
- Every lane runs inside its own git worktree (`lh lane`) with a file-scope lease, so parallel
lanes can't step on each other's files.
Short answer: **almost never during a normal pipeline run.** Every agent's instructions
require it to call the relevant `lh` subcommand itself, at a specific point, every time —
you don't ask for it and you can't opt it out. The table below is exhaustive: every `lh`
subcommand, who calls it, and when.
| Command | Who runs it | When |
| --- | --- | --- |
| `lh index` | `interrogator`, `scout`, `architect`, `splitter` | Automatically, before reading files, to build token-budgeted context |
| `lh host` | `conductor` | Automatically, first thing, to pick parallel-vs-sequential strategy |
| `lh run start/event/end` | `conductor` (start/end), every agent (event) | Automatically, for every phase transition — never skipped |
| `lh lane create/status/merge` | `conductor`, `builder`, `integrator` | Automatically, before a write lane starts and when it merges |
| `lh memory get/put/scan` | `interrogator`, `architect`, `builder`, `scribe` | Automatically, to pull relevant shards before work and record facts/failures after |
| `lh graph` | `verifier` (always), plus `architect`/`splitter`/`conductor`/`reviewer`/`scout`/`integrator` at their own checkpoints | Automatically — it's exit criterion #3, never skipped |
| `lh init` | You (or `scripts/onboard.mjs` on your behalf) | Once per repo, at setup, or to repair a missing `.agents/` baseline |
| `lh doctor` | You | Whenever you want to check the environment yourself — before starting, after upgrading Node/git/the plugin, or to diagnose a stuck run. Also run once automatically right after `lh init` |
| `lh report <run-id>` | You | After a run, when you want a human-readable markdown summary instead of raw NDJSON. No agent generates this for you |
So the only commands you are expected to type by hand in everyday use are `lh init` (setup),
`lh doctor` (diagnostics), and `lh report` (reading a past run's summary). Everything else —
`lh index`, `lh host`, `lh run`, `lh lane`, `lh memory`, `lh graph` — is invoked by the agents
as a scripted, mandatory step in their own instructions. You'd only run one of those manually
if you're debugging outside the agent flow (e.g. `lh graph` on its own to check structure
before opening Copilot at all, or `lh memory get --shard failures` to read what the harness has
learned).
## 5. Know when it's actually done
@@ -147,6 +188,8 @@ Everything the harness does is self-documenting — nothing lives only in a chat
| `lh doctor` warns "no verify command" | Add a test/build/lint command to `harness.config.json` |
| `lh init` refuses to run again | Expected — it won't clobber an existing config. Use `lh init --force` to reset |
| `lh` not found after onboarding | Re-run without `--no-npm-link`, or invoke via the absolute path the script prints |
| Agents/skills installed via `copilot plugin install` but `lh init`/`lh doctor` fail with "command not found" | Expected — plugin install only adds the behaviour layer. Run `npm link` from a clone (path C) or `scripts/onboard.mjs` (path B) to get `lh` on `PATH` |
| `copilot plugin install owner/repo` prints a deprecation warning | Expected for direct-source installs. Use `copilot plugin marketplace add` + `copilot plugin install name@marketplace` instead (path A) |
| Pipeline stuck at design gate | `interrogator` is waiting on your answers — this is intentional, answer the questions |
## Next steps