@osfactory/har 1.0.0-rc.2 → 1.1.0

package/dist/templates/AGENTS.md.template

@@ -5,72 +5,25 @@ This repository uses a **`.har/` harness** for isolated agent development.
 <!-- har:agent-environment:start -->
 ## HAR / agent environment
 
-The harness is not just a verification gate — it is **how you run this project**.
-To see the app live (manual testing, browser sessions, screenshots, driving the UI),
-use `har env launch <id>` or `./.har/launch.sh <id>`. It already encodes database
-setup, ports, env vars, and process management — never hand-roll `docker` / dev-server
-startup, and never claim a task "can't be verified live" without launching a slot first.
-
-If a harness command fails, fix the harness (or report the failure) — do not quietly
-fall back to ad-hoc commands.
-
-### Before making changes
-
-1. On the **main checkout**, switch to the intended base (usually `main`) — launch
-   creates a worktree from that HEAD.
-2. **Launch first** — MCP `har_launch_environment` / `har env launch 1`. Use the
-   returned **work dir** for ALL edits (never the main checkout).
-   **Bind tracker work** when the task names a durable issue or ticket (GitHub,
-   Linear, etc.): pass a short repo-scoped `--work-id` / `workUnitId` (e.g.
-   `widget-123`), `--work-source` / `source`, `--work-url` / `sourceUrl`, and
-   `--work-title` / `title` when known. Skip binding for ad-hoc work with no
-   tracker identity.
-3. Read [`.har/README.md`](.har/README.md), [`.har/stages.json`](.har/stages.json), then
-   [`.har/CLAUDE.agent.md`](.har/CLAUDE.agent.md) (slot URLs / definition of done).
-4. Hot-reload usually applies; if not, `./.har/agent-cli.sh <id> restart` (no-op on
-   cli/ios profiles without managed processes).
-
-**Occupied slots always block.** Run `complete` / `teardown`, then `launch`. Resume
-failed/starting launches with `--resume` / `recover`. Prefer a free slot (2+) over
-sharing slot 1 across unrelated chats. Check `har_get_status` / `har env status` first.
-Commit early — teardown keeps the branch, not uncommitted work.
-
-### After making changes
-
-Prefer MCP → CLI → shell. Quick verify for the loop; **full verify before done**.
-
-- MCP: `har_run_verification` / `full: true`; finish with `har_complete_environment`
-  (propose; wait for approval) or `har_teardown_environment`
-- CLI: `har env verify 1`, `har env verify 1 --full`, `complete 1`, `teardown 1`
-- Shell: `./.har/verify.sh 1`, `./.har/verify.sh 1 --full`, `./.har/teardown.sh 1`
-
-Commit in the session worktree. Run JSON stays in the main checkout `.har/runs/`.
-
-### Definition of done
-
-- Full verify passes; edits only in the session worktree; tests cover new behavior;
-  changes committed; show preview URLs; then **session handoff** (below).
-
-### Session handoff (required)
-
-After full verify and commit, stop. Include summary, session branch
-(`.har/slots/agent-<id>.json`), and preview URLs. Wait — never autonomously
-complete, teardown, push, or open a PR. **Default:** when `gh`/GitHub MCP is available,
-recommend **Complete + open a PR** (still needs approval). Alternatives: **Complete only**,
-or **Something else**. Without PR tooling, recommend **Complete only** and give the
-session branch for a manual push.
-
-### Commit gate
-
-Full verify records a tree hash under `.har/validations/`. With `har hooks install`,
-commits must match a passing full verify. Re-verify after any edit; `git add -A`.
-Do not bypass (`--no-verify`, `HAR_SKIP_GATE=1`).
-
-### Cursor IDE
-
-If `.cursor/rules/har-workflow.mdc` exists, the same harness workflow is injected into
-every Cursor agent session automatically. Run `har env init` or `har env maintain` to
-create or refresh it.
+This repository uses a `.har/` harness. It is **how you run and verify this
+project** — launch a slot for live apps, browsers and screenshots; never
+hand-roll docker or dev-server startup. If a harness command fails, fix the
+harness or report it; do not fall back to ad-hoc commands.
+
+1. **Launch first** — `har_launch_environment` / `har env launch <id>`. Make ALL
+   edits under the returned **work dir**, never the main checkout. Bind tracker
+   work with `--work-id` / `--work-url` when the task names an issue.
+2. **Verify before done** — `har_run_verification` (`full: true`) /
+   `har env verify <id> --full`. Commit in the session worktree.
+3. **Stop at handoff** — report summary, session branch and preview URLs, then
+   wait. Never autonomously `complete`, `teardown`, push, or open a PR.
+
+Occupied slots always block: `complete` / `teardown`, then launch. Customize the
+harness only through `harness.env`, `stages.json` + `.har/stages/`, `.har/hooks/`
+and `.har/plugins/` — there is no generated `.har/*.sh` entry-point surface.
+
+Full detail — slot environment, readiness, definition of done, project commands,
+commit gate: [`.har/README.md`](.har/README.md) and [`.har/stages.json`](.har/stages.json).
 <!-- har:agent-environment:end -->
 
 ## Project-specific notes

package/dist/templates/CLAUDE.md.template

@@ -1,5 +1 @@
-# __PROJECT_DISPLAY_NAME__
-
-Read [AGENTS.md](./AGENTS.md) and [.har/README.md](./.har/README.md) before changing this project.
-Harness workflow is enforced automatically in Cursor via `.cursor/rules/har-workflow.mdc`
-(created by `har env init`).
+@AGENTS.md

package/dist/templates/adaptation-prompt-init.md

@@ -5,8 +5,8 @@ Adapt the `.har/` harness in this repository so AI coding agents can run the pro
 Explore this repository, then edit files in `.har/` directly to make the harness runnable for this project.
 
 `.har/` is a **configuration surface** — the runtime machinery lives in the HAR
-package behind the `./.har/*.sh` shims. Never edit the shims or invent new config
-files; every customization has a sanctioned home:
+package. CLI and MCP are the only entry points. Never add lifecycle wrappers
+or invent new config files; every customization has a sanctioned home:
 
 | Customization | Home |
 |---------------|------|
@@ -16,9 +16,9 @@ files; every customization has a sanctioned home:
 | Anything bigger | Plugins (`har env add-plugin`, `har plugin create` for local) |
 | Full runtime ownership (rare) | `har env eject` |
 
-## HAR profiles (pick the right one at init)
+## HAR profiles (pick the right one at scaffold)
 
-`har env init` scaffolds from one of three boilerplate profiles — **choose the profile that matches this repository**:
+The scaffold comes from one of three boilerplate profiles — **choose the profile that matches this repository**:
 
 | Profile | Best for | What you get |
 |---------|----------|--------------|
@@ -26,11 +26,7 @@ files; every customization has a sanctioned home:
 | `cli` | **CLI tools, libraries, test-suite repos** (typical SWE-bench) | Git worktree by default, no PM2; optional Docker for databases; run project commands in isolation |
 | `ios` | **Mobile iOS / Swift** | xcodebuild + iOS Simulator; scheme/project/simulator in `harness.env` |
 
-```bash
-har env init                  # default (SaaS/web)
-har env init --profile cli    # libraries / CLI / polyglot test repos
-har env init --profile ios    # iOS apps
-```
+If you must re-scaffold (destructive): `har env init --force --profile default|cli|ios`.
 
 Do **not** disable worktrees, rewrite launch into repo-root-only mode, or pick the wrong profile unless the project truly requires it.
 
@@ -55,8 +51,8 @@ Replace all TODO placeholders. Key files:
 Identify the **primary application** — the ONE app coding agents will modify and run per-slot. Everything else is shared and runs once for all slots:
 
 1. **Primary app** → set `HARNESS_PRIMARY_APP` in `harness.env`; wire ONLY its dev processes into `ecosystem.agent.template.cjs` (a primary app may still need several processes, e.g. api + frontend of the same app).
-2. **External dependencies** (database, cache, queue, mail, ...) → keep/add them as services in `docker-compose.agent.yml`, delete the menu entries the project doesn't use, and list the needed ones in `HARNESS_INFRA_SERVICES` (e.g. `"db redis"`). They start once via `setup-infra.sh` on fixed ports and serve every slot.
-3. **Internal supporting services** (a monolith/monorepo's other services the agent depends on but is not changing) → do NOT start them per-slot. Run them once and shared: as compose services in `docker-compose.agent.yml`, or as PM2 processes in `.har/ecosystem.shared.config.cjs` (processes named `har-shared-<name>`, started automatically by `setup-infra.sh` when the file exists). Point the primary app at them through `env.template`.
+2. **External dependencies** (database, cache, queue, mail, ...) → keep/add them as services in `docker-compose.agent.yml`, delete the menu entries the project doesn't use, and list the needed ones in `HARNESS_INFRA_SERVICES` (e.g. `"db redis"`). They start once via `har env setup-infra` on fixed ports and serve every slot.
+3. **Internal supporting services** (a monolith/monorepo's other services the agent depends on but is not changing) → do NOT start them per-slot. Run them once and shared: as compose services in `docker-compose.agent.yml`, or as PM2 processes in `.har/ecosystem.shared.config.cjs` (processes named `har-shared-<name>`, started automatically by `har env setup-infra` when the file exists). Point the primary app at them through `env.template`.
 
 Simple single-app repos need none of the extra machinery: one primary app, usually one `db` in `HARNESS_INFRA_SERVICES`, no shared ecosystem file.
 
@@ -76,8 +72,8 @@ Verification is data: `.har/stages.json` lists the pipeline in
 `verificationStages` (execution order), and every id resolves to a registered
 stage with `"tier": "quick" | "full"`. Adapt verification by editing the stage
 entries — commands, tiers, order — or adding stage scripts (see
-`.har/STAGES.md`). **Never edit `.har/verify.sh`**; it is a thin iterator that
-runs the registry. The scaffolded defaults (`typecheck`, `unit-tests`, `lint`,
+`.har/STAGES.md`). Do not add lifecycle wrappers — `har env verify` runs the
+registry. The scaffolded defaults (`typecheck`, `unit-tests`, `lint`,
 `readiness`, plus `api-health` on web profiles) are derived from
 `HARNESS_ECOSYSTEM` — a starting point, not the repo's final contract. Replace
 conventions that do not match this project. Use toolchain variables from
@@ -161,12 +157,13 @@ are user-owned: never drift-checked; `har env doctor` only validates names and
 executability. Use registered stages for verification steps; use hooks for
 lifecycle side effects.
 
-### `.har/CLAUDE.agent.md`
-Detailed agent instructions: commands, credentials, architecture, definition of done.
+### `.har/README.md`
+The harness reference agents read: slot environment, readiness / what "agent
+usable" means here, definition of done, project commands, architecture.
 
 ### `.har/env.template`, `docker-compose.agent.yml`
-Adapt as needed for the project's infra (`setup-infra.sh` is a shim — the
-services it starts come from these two files plus `HARNESS_INFRA_SERVICES`).
+Adapt as needed for the project's infra (`har env setup-infra` starts
+services from these two files plus `HARNESS_INFRA_SERVICES`).
 
 ### Port allocation & shared services
 
@@ -195,7 +192,7 @@ Onboarding may set an initial `agentSlots.max` in `.har/stages.json`. After you
 - [ ] For each service in `HARNESS_INFRA_SERVICES`, a matching lane exists in `HARNESS_INFRA_PORT_LANES` in `harness.env`
 - [ ] `.har/README.md` has a **Port & shared services** section (allocation table, shared vs per-slot, do-not rules)
 - [ ] App code and tests read ports from `.env.agent.<id>` / `agent-cli.sh` / slot registry — no hardcoded `3000`, `15432`, `3847`, etc.
-- [ ] `env.template` and `CLAUDE.agent.md` show resolved ports via variables, not literals
+- [ ] `env.template` and `.har/README.md` show resolved ports via variables, not literals
 - [ ] Monorepos with `har control up`: document slot-1 conflict if the app port overlaps (e.g. Mission Control on 3847)
 
 ### Git worktree
@@ -210,20 +207,19 @@ Coding agents discover the harness through two files:
 
 Do **not** create `AGENT.md` (singular) — that legacy name is obsolete. If `AGENT.md` exists, merge any unique notes into `AGENTS.md` and delete `AGENT.md`.
 
-If **`har env init` already created `AGENTS.md`**, refresh the **HAR / agent environment** section and fill in **Project-specific notes** — do not wipe unrelated content.
+If **the scaffold already created `AGENTS.md`**, refresh the **HAR / agent environment** section and fill in **Project-specific notes** — do not wipe unrelated content.
 
 If **no `AGENTS.md` exists**, create one at the repo root using this structure:
 
-- Link to `.har/README.md` and `.har/CLAUDE.agent.md`
+- Link to `.har/README.md`
 - State plainly: **the harness is how you run this project** — to see the app live (manual testing, browser, screenshots), `launch` a slot; never hand-roll docker/dev-server startup, and never work around a failing harness command with ad-hoc setup (fix or report it instead)
 - Commands: HAR MCP tools or `har env launch/verify/teardown`
-- Shell shims: `./.har/launch.sh`, `./.har/verify.sh`, `./.har/teardown.sh` — same runtime and run records
-- Rules (no hardcoded ports, use `./.har/agent-cli.sh`, do not touch other agents' resources)
+- Rules (no hardcoded ports, use `har env agent <id> …`, do not touch other agents' resources)
 - Project-specific notes (stack, credentials, definition of done)
 
 If **`AGENTS.md` already exists** (project-owned), add or update a concise **HAR / agent environment** section — do not replace unrelated content.
 
-Keep **`CLAUDE.md`** as a thin pointer to `AGENTS.md` (Claude Code auto-loads `CLAUDE.md`). Do not paste the full harness workflow into `CLAUDE.md`.
+Keep **`CLAUDE.md`** as the line `@AGENTS.md` (Claude Code auto-loads `CLAUDE.md` and follows the import). Never paste the harness workflow into it — `AGENTS.md` is the single instruction file.
 
 ### Monorepos / multiple harnesses
 
@@ -235,30 +231,30 @@ If this repository contains **more than one project or `.har` harness** (check f
 
 Include a **Run history** subsection:
 
-- Every entry point (`./.har/*.sh` shims, `har env …`, MCP) writes the same run records to `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json`
+- Every entry point (`har env …`, MCP) writes the same run records to `.har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json`
 - With worktrees, code runs in the worktree but run JSON lives in the main checkout `.har/runs/`
-- The `./.har/*.sh` shims forward to the same runtime — evidence records are identical from any surface
+- CLI and MCP are the only entry points — evidence records are identical from either surface
 
 ## Step 4 — Adaptation completeness (required)
 
 Before finishing, confirm the harness describes this project truthfully — do
-**not** go hunting for machinery to prune (the shims and packaged runtime are
+**not** go hunting for machinery to prune (the packaged runtime is
 not yours to trim, and wholesale deletion just manufactures drift):
 
 - [ ] No `TODO` placeholders remain anywhere in `.har/`
 - [ ] `HARNESS_INFRA_SERVICES` lists exactly the services this project uses, each with a lane in `HARNESS_INFRA_PORT_LANES`
 - [ ] All per-slot data stores are provisioned, not just the primary database
 - [ ] If full seed/setup is skipped, `.har/` provides a minimal bootstrap or documents why none is needed
-- [ ] `.har/CLAUDE.agent.md` defines what "agent usable" means for this repo (credentials, default data, smoke workflow) and shows only real URLs/ports/commands
+- [ ] `.har/README.md` defines what "agent usable" means for this repo (credentials, default data, smoke workflow) and shows only real URLs/ports/commands
 - [ ] `.har/README.md` documents port allocation and the shared-service model
 - [ ] No hardcoded default ports (`3000`, `15432`, `3847`, …) in app code, tests, or harness docs — use agent env / slot registry
 
 ## Rules
 
-1. Customize only through the contract: config in `harness.env`, stages in `stages.json` / `.har/stages/`, hooks in `.har/hooks/`, plugins in `.har/plugins/` — never edit the generated `*.sh` shims
+1. Customize only through the contract: config in `harness.env`, stages in `stages.json` / `.har/stages/`, hooks in `.har/hooks/`, plugins in `.har/plugins/` — never add lifecycle `.sh` wrappers
 2. Always update `.har/README.md` to reflect current harness state
 3. Reuse existing project commands from package.json, Makefile, CI, etc.
 4. Replace all TODO placeholders
 5. Do not edit `.har/manifest.json` — managed by the har CLI
 
-When finished, summarize what you changed, confirm verification commands (`har env verify 1 --full` or `./.har/verify.sh 1 --full`) are correct for this stack, and record the adaptation with `har env maintain --finalize --summary "<what changed>"`.
+When finished, summarize what you changed, confirm verification commands (`har env verify 1 --full`) are correct for this stack, and record the adaptation with `har env maintain --finalize --summary "<what changed>"`.

package/dist/templates/adaptation-prompt-maintain.md

@@ -31,7 +31,7 @@ Prefer targeted edits over full rewrites. Key files to review:
 ### `.har/README.md` (required)
 Keep this accurate — it is the harness index. Update whenever scripts, stages, or workflow change.
 
-### `.har/harness.env`, `stages.json`, `ecosystem.agent.template.cjs`, `CLAUDE.agent.md`
+### `.har/harness.env`, `stages.json`, `ecosystem.agent.template.cjs`, `README.md`
 Align commands and instructions with the current stack. Verify steps must use toolchain paths from `.env.agent.<id>` (`PYTHON_BIN`, `NPM_BIN`, `XCODEBUILD_BIN`, …) — never hardcoded venv or interpreter paths. `NPM_BIN` may be bun, pnpm, or yarn, so Node steps must use `${NPM_BIN:-npm} run <script>` and avoid npm-only flags such as `--prefix`. Replace stock ecosystem conventions that do not match the repository; do not leave npm/pytest/go/cargo/maven/gradle examples in place by accident.
 
 ### `.har/env.template`, `docker-compose.agent.yml`
@@ -62,7 +62,7 @@ Look specifically for drift introduced since the last adaptation:
 - `verificationStages` became health-only and no longer checks the key workflow
   that makes the slot usable.
 
-Update `.har/CLAUDE.agent.md` with skipped setup steps, substitutes, credentials,
+Update `.har/README.md` with skipped setup steps, substitutes, credentials,
 and the repo-specific definition of "agent usable."
 
 ### Custom lifecycle behavior — `.har/hooks/`
@@ -81,7 +81,7 @@ scripts for a lifecycle side effect, move that code into a hook.
 Platform-shape upgrades are **code, not a checklist**: the har CLI carries a
 versioned migration registry keyed on the manifest's `runtimeVersion`.
 `har env maintain` detects an old harness shape, writes `.har/MIGRATE-PROMPT.md`,
-and `har env maintain --migrate` applies the mechanical steps (shims, pure-config
+and `har env maintain --migrate` applies the mechanical steps (delete leftover wrappers, pure-config
 `harness.env` with `HARNESS_INFRA_SERVICES` / `HARNESS_INFRA_PORT_LANES`
 conversions, machinery removal) with backups under `.har/migrate/backup/`.
 
@@ -96,7 +96,7 @@ come back here afterwards. Two standing rules:
 
 If harness commands, rules, or workflow changed, update the **HAR / agent environment** section in repo-root `AGENTS.md`:
 
-- Links to `.har/README.md` and `.har/CLAUDE.agent.md`
+- Links to `.har/README.md`
 - Commands: HAR MCP tools or `har env …`
 - Shell shims: `./.har/*.sh` — thin delegates to `har env`, same run records
 - Run history (worktree runs record to the main checkout `.har/runs/`)
@@ -105,7 +105,7 @@ If harness commands, rules, or workflow changed, update the **HAR / agent enviro
 
 If `AGENTS.md` does not mention HAR yet, add a concise section. If it already has a HAR section, update it minimally — do not replace unrelated content.
 
-Do **not** create `AGENT.md` (singular). If legacy `AGENT.md` exists, merge unique notes into `AGENTS.md` and delete `AGENT.md`. Keep `CLAUDE.md` as a thin pointer to `AGENTS.md`.
+Do **not** create `AGENT.md` (singular). If legacy `AGENT.md` exists, merge unique notes into `AGENTS.md` and delete `AGENT.md`. Keep `CLAUDE.md` as the line `@AGENTS.md`.
 
 ## Rules
 

package/dist/templates/adaptation-prompt-plugin.md

@@ -31,7 +31,7 @@ stage entries in `.har/stages.json`. Never edit the shims.
 ## Prove it green
 
 ```bash
-har env launch 1                # or ./.har/launch.sh 1
+har env launch 1
 har env verify 1 --full         # must pass INCLUDING {{STAGE_IDS}}
 ```
 

package/dist/templates/agent-skills/har-wt.md

@@ -16,7 +16,7 @@ har env status        # or ./.har/agent-cli.sh 1 status
 ## 2. Launch — BEFORE editing any file
 
 ```bash
-har env launch <id>   # or ./.har/launch.sh <id>
+har env launch <id>
 ```
 
 Launch creates a fresh session worktree from HEAD and prints its **work dir** (also recorded in `.har/slots/agent-<id>.json`, path like `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>`). If a previous launch failed partway, retry with `--resume` instead of starting fresh.
@@ -43,7 +43,7 @@ completion to HAR.
 - The main checkout must stay clean (`git status` there shows no changes from you).
 - Edits hot-reload in the running slot; use `./.har/agent-cli.sh <id> restart` if a change doesn't take.
 - Commit early and often on the session branch — teardown keeps the branch, not uncommitted work.
-- After launch, read `.har/CLAUDE.agent.md` in the worktree for slot URLs and the definition of done.
+- After launch, read `.har/README.md` in the worktree for slot URLs and the definition of done.
 
 ## 4. Verify through the harness
 

package/dist/templates/agent-skills/setup-har.md

@@ -42,15 +42,15 @@ Tell the user which profile you picked and why before continuing.
 
 ## 4. Initialize the harness
 
-```bash
-har env init --profile <profile>   # omit --profile for default
-```
+Call `har_init_harness` with the chosen `profile` (`default`, `cli`, or `ios`).
+Do not run `har onboard` (that wizard is for humans) and do not advertise
+`har env init` as the first-run command.
 
 If `.har/` already exists, stop and suggest `/har-maintain` instead.
 
 ## 5. Perform the adaptation yourself
 
-`har env init` prints an adaptation prompt and writes it to `.har/ADAPT-PROMPT.md`. Read that file and **execute its instructions yourself, now, in this session** — tailor the harness configuration surface (`harness.env`, `stages.json` + `.har/stages/`, `.har/hooks/`, `docker-compose.agent.yml`, `env.template`) and `AGENTS.md` to this repository's real stack, ports, and commands. The `./.har/*.sh` files are generated shims over the packaged runtime — never edit them.
+`har_init_harness` writes an adaptation prompt to `.har/ADAPT-PROMPT.md`. Read that file and **execute its instructions yourself, now, in this session** — tailor the harness configuration surface (`harness.env`, `stages.json` + `.har/stages/`, `.har/hooks/`, `docker-compose.agent.yml`, `env.template`) and `AGENTS.md` to this repository's real stack, ports, and commands. The `./.har/*.sh` files are generated shims over the packaged runtime — never edit them.
 
 ## 6. Register the project's checks as stages
 

package/dist/templates/cursor-rule.mdc.template

@@ -1,79 +1,14 @@
 ---
-description: HAR harness workflow — read before change, verify before done
+description: HAR harness workflow — read AGENTS.md before changing anything
 alwaysApply: true
 ---
 
 # HAR Harness Workflow
 
-This repository uses a `.har/` agent harness. Follow this on every change.
+This repository uses a `.har/` agent harness. **Read [`AGENTS.md`](../../AGENTS.md)
+and follow it** — it is the single source of truth for the harness workflow
+(launch a slot first, edit only in the work dir, full verify before done, stop at
+handoff). `.har/README.md` has the harness detail.
 
-The harness is **how you run the project**, not only how you verify it. Launch a
-slot for live apps, browsers, and screenshots — never hand-roll docker/dev-server
-startup. If a harness command fails, fix the harness or surface the failure. Customize
-only via the contract (`harness.env`, `stages.json` + `.har/stages/`, `.har/hooks/`, `.har/plugins/`) — never edit the generated `./.har/*.sh` shims.
-
-## Before making changes
-
-1. On the **main checkout**, switch to the intended base (usually `main`) — launch
-   creates a worktree from that HEAD.
-2. **Launch first** — MCP `har_launch_environment` / `har env launch 1`. Use the
-   returned **work dir** for ALL edits (never the main checkout). Path looks like
-   `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>` (see `.har/slots/agent-<id>.json`).
-   **Bind tracker work** when the task names an issue or ticket — short `--work-id`
-   (e.g. `widget-123`) plus `--work-source` / `--work-url` / `--work-title`. Skip for ad-hoc work.
-3. Read `AGENTS.md`, `.har/README.md`, `.har/stages.json`, then
-   `.har/CLAUDE.agent.md` (slot URLs / definition of done).
-4. Hot-reload usually applies; if not, `./.har/agent-cli.sh <id> restart` (no-op on
-   cli/ios profiles without managed processes).
-
-**Occupied slots always block.** Run `complete` / `teardown`, then `launch`. Resume
-failed/starting launches with `--resume` / `recover`. Prefer a free slot (2+) over
-sharing slot 1 across unrelated chats. Check `har_get_status` / `har env status`
-first. Commit early — teardown keeps the branch, not uncommitted work. Gitignored
-paths are ephemeral. With telemetry on, Mission Control derives session purpose from
-the first captured user prompt.
-
-<!-- Monorepo: if this repository contains multiple .har harnesses, list them here
-     and pick by the files you are changing. Example:
-
-## Harnesses in this repo
-
-| Path | Runs | Use when changing |
-|------|------|-------------------|
-| `.har/` | backend + frontend | `src/`, `packages/` |
-| `apps/admin/.har/` | admin dashboard | `apps/admin/` |
-
-Run harness commands from the directory that owns the harness (e.g. `cd apps/admin`). -->
-
-## After making changes
-
-Prefer MCP → CLI → shell. Quick verify for the loop; **full verify before done**.
-
-- MCP: `har_run_verification` / `full: true`; finish with `har_complete_environment`
-  (propose; wait for approval) or `har_teardown_environment`
-- CLI: `har env verify 1`, `har env verify 1 --full`, `complete 1`, `teardown 1`
-- Shell: `./.har/verify.sh 1`, `./.har/verify.sh 1 --full`, `./.har/teardown.sh 1`
-
-Commit in the session worktree. Run JSON stays in the main checkout `.har/runs/`.
-UI changes with Playwright: update specs under `tests/` (full verify includes browser-e2e).
-
-## Definition of done
-
-- Full verify passes; edits only in the session worktree; tests cover new behavior;
-  changes committed; show preview URLs; then **session handoff** (below).
-
-## Session handoff (required)
-
-After full verify and commit, stop. Include summary, session branch
-(`.har/slots/agent-<id>.json`), and preview URLs. Wait — never autonomously
-complete, teardown, push, or open a PR. **Default (1 is the default):** when
-`gh`/GitHub MCP is available, recommend **Complete + open a PR** — push → open
-PR → `har env complete` / `har_complete_environment` (branch kept). Still needs
-approval. Alternatives: **Complete only**, or **Something else**. Without PR
-tooling, recommend **Complete only** and give the session branch for a manual push.
-
-## Commit gate
-
-Full verify records a tree hash under `.har/validations/`. With `har hooks install`,
-commits must match a passing full verify. Re-verify after any edit; `git add -A`.
-Do not bypass (`--no-verify`, `HAR_SKIP_GATE=1`).
+This rule exists only to guarantee that instruction reaches every Cursor session;
+it deliberately does not restate the workflow, so there is one copy to keep current.

package/dist/templates/har-boilerplate/gitignore.template

@@ -9,12 +9,14 @@ artifacts/
 state/
 maintain/
 ADAPT-PROMPT.md
+migrate/
+MIGRATE-PROMPT.md
 AGENTS.md.proposed
 AGENTS.md.proposed.meta.json
 AGENT.md.proposed
 AGENT.md.proposed.meta.json
 slots/
 
-# Generated by launch.sh (also listed in repo-root .gitignore)
+# Generated at launch (also listed in repo-root .gitignore)
 .env.agent.*
 ecosystem.agent.*.config.cjs

package/dist/templates/har-boilerplate/harness.env

@@ -1,5 +1,5 @@
 # Shared harness configuration — edit to match your project
-# Generated by har env init, maintained over time with har env maintain
+# Generated when the harness is scaffolded, maintained with har env maintain
 #
 # This file is pure KEY=value config (plus comments) and is schema-validated
 # on read. Runtime helpers (har_infra_enabled, har_pg, port resolution) live

package/dist/templates/har-boilerplate/justfile

@@ -2,38 +2,37 @@
 
 set shell := ["bash", "-cu"]
 
+repo := justfile_directory() + "/.."
+
 setup:
-    ./setup-infra.sh
+    har env setup-infra --repo {{repo}}
 
 launch id:
-    ./launch.sh {{id}}
+    har env launch {{id}} --repo {{repo}}
 
 teardown id:
-    ./teardown.sh {{id}}
+    har env teardown {{id}} --repo {{repo}}
 
 verify id:
-    ./verify.sh {{id}}
+    har env verify {{id}} --repo {{repo}}
 
 verify-full id:
-    ./verify.sh {{id}} --full
+    har env verify {{id}} --full --repo {{repo}}
 
 status:
-    #!/usr/bin/env bash
-    for id in 1 2 3 4 5; do
-        ./agent-cli.sh "$id" status 2>/dev/null || true
-    done
+    har env status --repo {{repo}}
 
 launch-all count:
     #!/usr/bin/env bash
     for id in $(seq 1 {{count}}); do
-        ./launch.sh "$id"
+        har env launch "$id" --repo "{{repo}}"
     done
 
 teardown-all:
     #!/usr/bin/env bash
     for id in 1 2 3 4 5; do
-        ./teardown.sh "$id" 2>/dev/null || true
+        har env teardown "$id" --repo "{{repo}}" 2>/dev/null || true
     done
 
 cli id cmd *args:
-    ./agent-cli.sh {{id}} {{cmd}} {{args}}
+    har env agent {{id}} {{cmd}} {{args}} --repo {{repo}}

package/dist/templates/har-boilerplate/stages.json

@@ -13,14 +13,12 @@
     {
       "id": "setup-infra",
       "kind": "setup",
-      "description": "Shared infrastructure (Docker, template DB)",
-      "command": "./.har/setup-infra.sh"
+      "description": "Shared infrastructure (Docker, template DB)"
     },
     {
       "id": "launch",
       "kind": "launch",
       "description": "Launch an isolated agent environment slot",
-      "command": "./.har/launch.sh {agentId}",
       "artifacts": [
         {
           "path": ".env.agent.{agentId}",
@@ -33,7 +31,6 @@
       "id": "verify",
       "kind": "verify",
       "description": "Verification pipeline: runs stages.json verificationStages in order (tier \"quick\" by default; --full runs the whole list)",
-      "command": "./.har/verify.sh {agentId}",
       "acceptsArgs": [
         "--full"
       ],
@@ -49,7 +46,6 @@
       "id": "status",
       "kind": "inspect",
       "description": "Inspect a running agent environment slot",
-      "command": "./.har/agent-cli.sh {agentId} status",
       "artifacts": [
         {
           "path": ".har/logs",
@@ -61,14 +57,12 @@
     {
       "id": "logs",
       "kind": "inspect",
-      "description": "Read recent logs for an agent slot",
-      "command": "./.har/agent-cli.sh {agentId} logs"
+      "description": "Read recent logs for an agent slot"
     },
     {
       "id": "teardown",
       "kind": "teardown",
-      "description": "Stop processes and release agent slot resources",
-      "command": "./.har/teardown.sh {agentId}"
+      "description": "Stop processes and release agent slot resources"
     },
     {
       "id": "typecheck",

package/dist/templates/har-boilerplate-cli/gitignore.template

@@ -9,12 +9,14 @@ artifacts/
 state/
 maintain/
 ADAPT-PROMPT.md
+migrate/
+MIGRATE-PROMPT.md
 AGENTS.md.proposed
 AGENTS.md.proposed.meta.json
 AGENT.md.proposed
 AGENT.md.proposed.meta.json
 slots/
 
-# Generated by launch.sh (also listed in repo-root .gitignore)
+# Generated at launch (also listed in repo-root .gitignore)
 .env.agent.*
 ecosystem.agent.*.config.cjs

package/dist/templates/har-boilerplate-cli/harness.env

@@ -1,5 +1,5 @@
 # CLI / library harness — optional Docker via HARNESS_INFRA_SERVICES, no PM2
-# Generated by har env init --profile cli
+# Generated when the harness is scaffolded (--profile cli)
 #
 # This file is pure KEY=value config (plus comments) and is schema-validated
 # on read. Runtime helpers (har_infra_enabled, har_pg, port resolution) live

package/dist/templates/har-boilerplate-cli/justfile

@@ -2,26 +2,25 @@
 
 set shell := ["bash", "-cu"]
 
+repo := justfile_directory() + "/.."
+
 setup:
-    ./setup-infra.sh
+    har env setup-infra --repo {{repo}}
 
 launch id:
-    ./launch.sh {{id}}
+    har env launch {{id}} --repo {{repo}}
 
 teardown id:
-    ./teardown.sh {{id}}
+    har env teardown {{id}} --repo {{repo}}
 
 verify id:
-    ./verify.sh {{id}}
+    har env verify {{id}} --repo {{repo}}
 
 verify-full id:
-    ./verify.sh {{id}} --full
+    har env verify {{id}} --full --repo {{repo}}
 
 status:
-    #!/usr/bin/env bash
-    for id in 1 2 3; do
-        ./agent-cli.sh "$id" status 2>/dev/null || true
-    done
+    har env status --repo {{repo}}
 
 cli id cmd *args:
-    ./agent-cli.sh {{id}} {{cmd}} {{args}}
+    har env agent {{id}} {{cmd}} {{args}} --repo {{repo}}