@osfactory/har 0.43.2 → 0.45.0

package/dist/templates/AGENTS.md.template

@@ -0,0 +1,78 @@
+# Agent Environment
+
+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.
+<!-- har:agent-environment:end -->
+
+## Project-specific notes
+
+<!-- Adapt when customizing the harness (see .har/ADAPT-PROMPT.md) -->

package/dist/templates/CLAUDE.md.template

@@ -1,5 +1,5 @@
 # __PROJECT_DISPLAY_NAME__
 
-Read [AGENT.md](./AGENT.md) and [.har/README.md](./.har/README.md) before changing this project.
+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`).

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

@@ -167,14 +167,18 @@ Onboarding may set an initial `agentSlots.max` in `.har/stages.json`. After you
 ### Git worktree
 `launch.sh` creates an isolated session worktree at `~/worktrees/<base>-<sha4>-har-agent-<id>-<rand4>` by default (`HARNESS_USE_WORKTREE=true`) and records it in `.har/slots/agent-<id>.json`. Agents should commit from that worktree, not the main checkout.
 
-## Step 3 — Update repo-root `AGENT.md`
+## Step 3 — Update repo-root `AGENTS.md`
 
 Coding agents discover the harness through two files:
 
-1. **`AGENT.md`** (repo root) — short pointer, always read first
+1. **`AGENTS.md`** (repo root) — shared agent instructions (Codex auto-loads this; Claude via `CLAUDE.md` pointer)
 2. **`.har/README.md`** — full index of what's in the harness
 
-If **no `AGENT.md` exists**, create one at the repo root using this structure:
+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 **no `AGENTS.md` exists**, create one at the repo root using this structure:
 
 - Link to `.har/README.md` and `.har/CLAUDE.agent.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)
@@ -183,14 +187,16 @@ If **no `AGENT.md` exists**, create one at the repo root using this structure:
 - Rules (no hardcoded ports, use `./.har/agent-cli.sh`, do not touch other agents' resources)
 - Project-specific notes (stack, credentials, definition of done)
 
-If **`AGENT.md` already exists**, add or update a concise **HAR / agent environment** section — do not replace unrelated content.
+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`.
 
 ### Monorepos / multiple harnesses
 
 If this repository contains **more than one project or `.har` harness** (check for `.har/` directories above or below this one):
 
-- Maintain a **"Harnesses in this repo"** table in the ROOT `AGENT.md` — one row per harness: path, profile, what it runs, launch/verify commands, link to its `.har/README.md`. Lead with "pick the harness that owns the files you are changing."
-- Keep a small `AGENT.md` (and `CLAUDE.md` pointer) **inside each project directory** for local discovery, with a back-link to the root index.
+- Maintain a **"Harnesses in this repo"** table in the ROOT `AGENTS.md` — one row per harness: path, profile, what it runs, launch/verify commands, link to its `.har/README.md`. Lead with "pick the harness that owns the files you are changing."
+- Keep a small `AGENTS.md` (and `CLAUDE.md` pointer) **inside each project directory** for local discovery, with a back-link to the root index.
 - Keep ONE Cursor rule at the repo root (`.cursor/rules/har-workflow.mdc`) listing all harnesses — not one rule per project.
 
 Include a **Run history** subsection:

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

@@ -64,6 +64,16 @@ and the repo-specific definition of "agent usable."
 
 When upgrading `@osfactory/har` or adopting new harness standards:
 
+**Generator 0.5.0 — `AGENTS.md` (canonical agent guide):**
+
+- Repo-root **`AGENTS.md`** is now the shared HAR workflow contract (Codex auto-loads it). Do **not** create or keep **`AGENT.md`** (singular).
+- If **`AGENT.md` exists**: merge any unique project notes into `AGENTS.md`, ensure a **HAR / agent environment** section is present, then **delete `AGENT.md`**.
+- If **`AGENTS.md` is missing**: create it (HAR may already have scaffolded a managed section during `maintain` — fill **Project-specific notes** and keep the marked HAR section).
+- If **`AGENTS.md` already exists**: add or refresh the managed **HAR / agent environment** section only — do not wipe unrelated project guidance.
+- Keep **`CLAUDE.md`** as a **thin pointer** to `AGENTS.md` (Claude Code auto-loads `CLAUDE.md`). Never paste the full Cursor-rule / HAR workflow into `CLAUDE.md`.
+- Update links in `.har/CLAUDE.agent.md` and `.har/README.md` from `AGENT.md` → `AGENTS.md` if they still point at the legacy name.
+- Cursor still uses `.cursor/rules/har-workflow.mdc` (always-on); that rule should also say `AGENTS.md`.
+
 **Generator 0.4.0 — primary app & shared infra services:**
 
 - Migrate `harness.env` from boolean `HARNESS_INFRA_*` flags to the `HARNESS_INFRA_SERVICES` list (space-separated compose service names, e.g. `"db mailpit"`) and add the `har_infra_enabled()` helper — copy both from `.har/maintain/templates/harness.env`. Update every script that still tests `HARNESS_INFRA_POSTGRES`-style flags (`setup-infra.sh`, `launch.sh`, `teardown.sh`, `agent-cli.sh`) to use `har_infra_enabled <service>`.
@@ -74,17 +84,17 @@ When upgrading `@osfactory/har` or adopting new harness standards:
 
 **Earlier standards:**
 
-- Add **Run history** section to repo-root `AGENT.md` if missing (shell vs `har env`, worktree vs runs location)
-- Ensure `AGENT.md` / `CLAUDE.agent.md` frame the harness as **how you run the project** (launch for manual testing/browser/screenshots; fix — don't work around — failing harness commands)
+- Add **Run history** section to repo-root `AGENTS.md` if missing (shell vs `har env`, worktree vs runs location)
+- Ensure `AGENTS.md` / `CLAUDE.agent.md` frame the harness as **how you run the project** (launch for manual testing/browser/screenshots; fix — don't work around — failing harness commands)
 - Ensure `launch.sh` installs dependencies in fresh worktrees and resolves the project subdirectory inside the worktree (`git rev-parse --show-prefix`) for monorepos
-- If the repo has multiple projects/harnesses, maintain the **"Harnesses in this repo"** table in root `AGENT.md`, per-project pointer docs, and a single root Cursor rule
+- If the repo has multiple projects/harnesses, maintain the **"Harnesses in this repo"** table in root `AGENTS.md`, per-project pointer docs, and a single root Cursor rule
 - Remove dead boilerplate files (CLI profile: `ecosystem.agent.template.cjs`, `env.template`, `attach.sh`)
 - Align `launch.sh` / `harness.env` with worktree-default standard (`HARNESS_USE_WORKTREE=true`)
 - Do **not** blindly overwrite customized `verify.sh`
 
-## Step 3 — Refresh repo-root `AGENT.md`
+## Step 3 — Refresh repo-root `AGENTS.md`
 
-If harness commands, rules, or workflow changed, update the **HAR / agent environment** section in repo-root `AGENT.md`:
+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`
 - Preferred: HAR MCP tools or `har env …` (persists run history)
@@ -93,7 +103,9 @@ If harness commands, rules, or workflow changed, update the **HAR / agent enviro
 - Agent rules (ports, agent-cli.sh, isolation)
 - Project-specific notes
 
-If `AGENT.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.
+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`.
 
 ## Rules
 

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

@@ -12,7 +12,7 @@ This compares the harness against the current templates and repository, refreshe
 
 ## 2. Perform the adaptation yourself
 
-Read `.har/ADAPT-PROMPT.md` and execute its instructions now, in this session: reconcile `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENT.md` with the repository's current stack, ports, and commands. Preserve intentional project-specific customizations — fix drift, don't blindly reset.
+Read `.har/ADAPT-PROMPT.md` and execute its instructions now, in this session: reconcile `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENTS.md` with the repository's current stack, ports, and commands. Preserve intentional project-specific customizations — fix drift, don't blindly reset.
 
 Also check stage drift: compare the repository's current check commands (package.json scripts, Makefile, CI) against the stages registered in `.har/stages.json`. Register missing checks (`har env add-stage <id> --custom --command "..." --verification`), and remove or fix stages whose commands no longer exist. `.har/STAGES.md` documents the contract.
 
@@ -31,6 +31,6 @@ Fix the harness until launch and full verify pass. Tear down afterwards if the s
 After the user confirms:
 
 ```bash
-git add .har/ AGENT.md
+git add .har/ AGENTS.md
 git commit -m "chore: maintain har harness"
 ```

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

@@ -21,11 +21,16 @@ har env launch <id>   # or ./.har/launch.sh <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.
 
-If the task already has a stable issue or ticket ID, bind it without changing the
-methodology that produced it:
+If the task already has a stable issue or ticket, bind it without changing the
+methodology that produced it. Use a short repo-scoped id; put the provider and
+canonical URL in separate fields:
 
 ```bash
-har env launch <id> --work-id "<provider-neutral-id>" --work-title "<title>"
+har env launch <id> \
+  --work-id "widget-123" \
+  --work-source github \
+  --work-url "https://github.com/acme/widget/issues/123" \
+  --work-title "<title>"
 ```
 
 External planning/TDD/review skills remain in control of implementation strategy.

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

@@ -36,7 +36,7 @@ If `.har/` already exists, stop and suggest `/har-maintain` instead.
 
 ## 4. 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 `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENT.md` to this repository's real stack, ports, and commands. Do not use `--auto` and do not ask the user to paste anything.
+`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 `.har/` scripts (`launch.sh`, `verify.sh`, `setup-infra.sh`, `harness.env`, `stages.json`) and `AGENTS.md` to this repository's real stack, ports, and commands.
 
 ## 5. Register the project's checks as stages
 
@@ -63,7 +63,7 @@ Fix the harness scripts until both pass. Then tear down or keep the slot as the
 After the user confirms, commit the harness:
 
 ```bash
-git add .har/ AGENT.md CLAUDE.md .claude/ .cursor/ 2>/dev/null || git add .har/ AGENT.md
+git add .har/ AGENTS.md CLAUDE.md .claude/ .cursor/ 2>/dev/null || git add .har/ AGENTS.md
 git commit -m "chore: add har agent harness"
 ```
 

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

@@ -18,8 +18,9 @@ startup. If a harness command fails, fix the harness or surface the failure.
 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 with `workUnitId`/`title` or `--work-id`/`--work-title` when needed.
-3. Read `AGENT.md`, `.har/README.md`, `.har/stages.json`, then
+   **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).

package/dist/templates/har-boilerplate/CLAUDE.agent.md

@@ -1,6 +1,6 @@
 # Agent ${AGENT_ID} — Development Environment
 
-> [`AGENT.md`](../AGENT.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
+> [`AGENTS.md`](../AGENTS.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
 
 ## Environment
 

package/dist/templates/har-boilerplate/README.md

@@ -103,7 +103,7 @@ With git worktree slots, verification runs code in the worktree but run JSON sta
 
 ## For coding agents
 
-1. Read repo [`AGENT.md`](../AGENT.md)
+1. Read repo [`AGENTS.md`](../AGENTS.md)
 2. Read this file and `stages.json`
 3. After launch, read `.har/CLAUDE.agent.md` for slot URLs and definition of done
 

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

@@ -9,6 +9,8 @@ artifacts/
 state/
 maintain/
 ADAPT-PROMPT.md
+AGENTS.md.proposed
+AGENTS.md.proposed.meta.json
 AGENT.md.proposed
 AGENT.md.proposed.meta.json
 slots/

package/dist/templates/har-boilerplate-cli/CLAUDE.agent.md

@@ -1,6 +1,6 @@
 # Agent ${AGENT_ID} — Development Environment
 
-> [`AGENT.md`](../AGENT.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
+> [`AGENTS.md`](../AGENTS.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
 
 ## Environment
 

package/dist/templates/har-boilerplate-cli/README.md

@@ -89,7 +89,7 @@ With worktree slots, tests run in the worktree; run JSON lives in the main repo.
 
 ## For coding agents
 
-**Start here:** read [`AGENT.md`](../AGENT.md) at the repo root for a short pointer, then [`.har/CLAUDE.agent.md`](./CLAUDE.agent.md) for full instructions.
+**Start here:** read [`AGENTS.md`](../AGENTS.md) at the repo root for a short pointer, then [`.har/CLAUDE.agent.md`](./CLAUDE.agent.md) for full instructions.
 
 Prefer HAR MCP tools or `har env …` for launch, verify, and teardown. Use `./.har/*.sh` only when the CLI is not installed.
 

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

@@ -9,6 +9,8 @@ artifacts/
 state/
 maintain/
 ADAPT-PROMPT.md
+AGENTS.md.proposed
+AGENTS.md.proposed.meta.json
 AGENT.md.proposed
 AGENT.md.proposed.meta.json
 slots/

package/dist/templates/har-boilerplate-ios/ADAPT-PROMPT.md

@@ -5,7 +5,7 @@ structure, then make the changes listed below. Commit when done.
 
 ## 1 — Read before editing
 
-- `AGENT.md` at the repo root (overview and do-nots)
+- `AGENTS.md` at the repo root (overview and do-nots)
 - `.har/README.md` (harness index)
 - `.har/harness.env` (all config vars)
 - `.har/stages.json` (stage registry)
@@ -41,7 +41,7 @@ har env add-plugin rocketsim
 Then adapt `flows/example-smoke.sh` to navigate to your app's main screen and verify it loads.
 Read `.har/stages/ROCKETSIM.md` for the full authoring guide.
 
-## 5 — Update `AGENT.md` (repo root)
+## 5 — Update `AGENTS.md` (repo root)
 
 Replace the TODO section with:
 - Which Xcode scheme and simulator are used

package/dist/templates/har-boilerplate-ios/CLAUDE.agent.md

@@ -1,6 +1,6 @@
 # Agent ${AGENT_ID} — iOS Development Environment
 
-> [`AGENT.md`](../AGENT.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
+> [`AGENTS.md`](../AGENTS.md) · [`.har/README.md`](./README.md) · [`stages.json`](./stages.json)
 
 ## Environment
 

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

@@ -6,6 +6,8 @@ work-units/
 work-attempts/
 validation-bindings/
 artifacts/
+AGENTS.md.proposed
+AGENTS.md.proposed.meta.json
 AGENT.md.proposed
 AGENT.md.proposed.meta.json
 maintain/

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@osfactory/har",
-  "version": "0.43.2",
-  "description": "LLM-powered CLI for reproducible agent development environments",
+  "version": "0.45.0",
+  "description": "Open harness for reproducible multi-agent coding workflows",
   "keywords": [
     "har",
     "cli",
     "mcp",
     "agent",
     "harness",
-    "llm",
     "devops"
   ],
   "bin": {
@@ -21,7 +20,7 @@
     "control/docker-compose.build.yml"
   ],
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --target=node20 --outfile=dist/index.js --banner:js='#!/usr/bin/env node' && rm -rf dist/templates dist/prompts && cp -r src/templates dist/templates && mkdir -p dist/prompts && cp src/llm/prompts/*.md dist/prompts/",
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node20 --outfile=dist/index.js --banner:js='#!/usr/bin/env node' && rm -rf dist/templates && cp -r src/templates dist/templates",
     "dev": "tsx src/index.ts",
     "test": "jest",
     "test:watch": "jest --watch",
@@ -32,7 +31,6 @@
     "release": "semantic-release"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.27.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@pydantic/genai-prices": "^0.0.73",
     "chalk": "^5.3.0",

package/dist/prompts/system-authoring.md

@@ -1,155 +0,0 @@
-# Harness Authoring Agent
-
-You are a harness authoring agent. Your job is to adapt a copied `.har/` boilerplate to match a specific software repository, so AI coding agents can run the project in isolated development environments.
-
-## Your Mission
-
-Explore the target repository, then edit files in `.har/` directly to make the harness runnable for this project. When done, call `finishAuthoring` with a summary.
-
-**Do NOT** create a YAML config or JSON mapping file for runtime behavior. Put behavior directly in the harness scripts and templates.
-
-## Discovery for coding agents
-
-Coding agents discover the harness through two files:
-
-1. **`AGENT.md`** (repo root) — short pointer, always read first. Propose via `proposeAgentMd` — never write it directly.
-2. **`.har/README.md`** — full index of what's in the harness. **You must maintain this** on every init/maintain run.
-
-## Tools Available
-
-**Repository exploration:**
-- `readRepoFile(path)` — read files from the target repo
-- `listRepoDir(path)` — list repo directories
-
-**Harness editing (.har/):**
-- `readHarnessFile(path)` — read files in .har/
-- `listHarnessDir(path)` — list .har/ contents
-- `writeHarnessFile(path, content)` — full file rewrite
-- `editHarnessFile(path, old_string, new_string)` — targeted edit
-- `deleteHarnessFile(path)` — remove unnecessary files
-
-**Root agent guide:**
-- `proposeAgentMd(content, rationale)` — propose AGENT.md changes for user approval
-
-**Other:**
-- `ask(question, options?)` — ask user when genuinely ambiguous
-- `finishAuthoring(summary, language?, packageManager?, database?)` — submit when done
-
-## Primary application & shared services (decide FIRST)
-
-Identify the **primary application** — the ONE app coding agents modify and run per-slot. Everything else runs once, shared by all slots:
-
-- **Primary app** → `HARNESS_PRIMARY_APP` in `harness.env`; only its dev processes go in `ecosystem.agent.template.cjs`.
-- **External dependencies** (database, cache, mail, ...) → services in `docker-compose.agent.yml`, listed in `HARNESS_INFRA_SERVICES` (e.g. `"db redis"`), started once by `setup-infra.sh` on fixed ports. Delete unused menu services.
-- **Internal supporting services** of a monolith/monorepo (needed but not modified) → shared as compose services, or PM2 processes in optional `.har/ecosystem.shared.config.cjs` (`har-shared-<name>`, auto-started by `setup-infra.sh`). Never per-slot.
-
-## Files to adapt
-
-### `.har/README.md` (required — maintain every run)
-Clear index of the harness: what each file does, quick start, architecture, how to maintain.
-Update when anything in the harness changes.
-
-### `.har/harness.env`
-Primary app, ports, `HARNESS_INFRA_SERVICES`, migrate/seed commands, health check path.
-
-### `.har/ecosystem.agent.template.cjs`
-PM2 processes for the primary application only, matching how it runs in dev.
-
-### `.har/verify.sh`
-Real typecheck, lint, test, and health check commands — replace all TODOs.
-
-## Readiness vs liveness (required)
-Do not treat a passing health check as adaptation complete. A usable agent
-environment has layered readiness:
-
-1. **Infra ready** — shared services and template data stores exist.
-2. **Slot data ready** — every per-slot data store is created or cloned.
-3. **Process ready** — primary app processes are online and health passes.
-4. **Agent usable** — documented credentials/workflows work, required default
-   data exists, and UI/API smoke is not blocked by asset/dev-server issues.
-
-Compare the harness against the repository's full local-dev setup. If you skip
-heavy steps such as full seed, optional services, asset compilation modes, or
-background daemons, add the minimum substitute in `.har/` scripts or document
-why no substitute is needed. If the app has multiple databases/stores, provision
-all per-slot state. If launch generates config, validate the nested keys the app
-actually reads. Put agent-usability checks in full verify, a project-owned
-readiness script, or documented smoke URLs. Health alone is not sufficient for
-UI/auth apps.
-
-Ensure `launch.sh` writes the slot registry before slow or fragile steps, and
-`verify.sh` resolves env/work dir through `agent-slot.sh` so partial launches are
-recoverable.
-
-### `.har/CLAUDE.agent.md`
-Detailed agent instructions: commands, credentials, architecture, definition of done.
-
-### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
-As needed for the project's infra.
-
-### `AGENT.md` (repo root — via proposeAgentMd only)
-Short pointer document. Structure:
-- Link to `.har/README.md` and `.har/CLAUDE.agent.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; fix or report a failing harness command instead of working around it
-- Preferred: HAR MCP tools or `har env launch/verify/teardown`
-- Fallback: `./.har/launch.sh`, `./.har/verify.sh`, etc. (when CLI is not installed)
-- Rules (no hardcoded ports, use agent-cli.sh)
-- Project-specific notes section
-
-If AGENT.md already exists, read it first and propose minimal updates — don't replace unrelated content.
-
-### Monorepos / multiple harnesses
-If the repository contains more than one project or `.har` harness (check for `.har/` directories above or below the one you are adapting):
-- Propose a **"Harnesses in this repo"** table for the ROOT `AGENT.md` — one row per harness: path, profile, what it runs, launch/verify commands, link to its `.har/README.md`. Lead with "pick the harness that owns the files you are changing."
-- Keep a small `AGENT.md` / `CLAUDE.md` pointer inside each project directory (local discovery), back-linking to the root index.
-- One Cursor rule at repo root listing all harnesses — never one rule per project.
-
-## Port allocation & shared services
-
-Document ports in `.har/README.md` and configure them in `.har/harness.env`. Resolved values land in `.env.agent.<id>` and `.har/slots/agent-<id>.json` at launch — never hardcode defaults in app code or tests.
-
-### Per-slot app ports (default / PM2 profile)
-
-| Layer | Scope | Rule | On conflict |
-|-------|-------|------|-------------|
-| Frontend | Per slot | `HARNESS_FE_BASE_PORT + (AGENT_ID × HARNESS_PORT_STEP)` | Scan `STEP` increments within the slot lane |
-| API | Per slot | `HARNESS_API_BASE_PORT + (AGENT_ID × STEP)` | Same scan policy |
-| Node debug | Per slot | `9200 + (AGENT_ID × STEP)` | Same scan policy |
-
-### Shared infra ports (when listed in `HARNESS_INFRA_SERVICES`)
-
-| Service | Default var | On conflict |
-|---------|-------------|-------------|
-| Postgres | `HARNESS_DB_PORT_DEFAULT` | Scan `HARNESS_DB_PORT_SCAN_START..END` |
-| MinIO | `HARNESS_MINIO_PORT_DEFAULT` (+ console) | Scan configured ranges in `harness.env` |
-| Mailpit | `HARNESS_MAILPIT_*_PORT_DEFAULT` | Scan configured ranges |
-| Headless browser | `HARNESS_BROWSER_PORT_DEFAULT` | Scan configured ranges |
-
-CLI and iOS profiles typically have no per-slot app ports; optional backends still use the shared-infra model.
-
-Set slot limits in `.har/stages.json` (`agentSlots`) based on machine capacity. `har env maintain --finalize` syncs legacy `HARNESS_AGENT_SLOT_*` exports in `harness.env`.
-
-### Do not
-
-- Hardcode `3000`, `15432`, `3847`, or other defaults in application code, tests, or agent docs
-- Run raw `docker compose` for harness infrastructure — use `setup-infra.sh` / `launch.sh`
-
-## Rules
-
-1. **Edit .har/ files directly** — no YAML runtime config
-2. **Always update README.md** in .har/ to reflect current harness state
-3. **Always call proposeAgentMd** with AGENT.md content (create or update proposal)
-4. **Reuse existing project commands** from package.json, Makefile, etc.
-5. **Replace all TODO placeholders**
-6. **Do not edit manifest.json** — managed by har CLI
-7. **Run the cleanup checklist before finishing** — keep strictly what this repository needs:
-   - compose file has only used services; `HARNESS_INFRA_SERVICES` matches exactly
-   - `harness.env` has port documentation vars for every enabled infra service; `.har/README.md` explains allocation and shared vs per-slot
-   - `env.template` has no blocks for removed services; no dead branches left in scripts
-   - unused harness files deleted (`deleteHarnessFile`), e.g. `attach.sh` when unused
-   - `.har/README.md` file table matches the files that actually exist
-   - `CLAUDE.agent.md` shows only real URLs/ports and commands that run
-   - skipped full-dev setup has a minimal bootstrap or clearly documented limitation
-   - all per-slot data stores are provisioned, not only the primary database
-   - `CLAUDE.agent.md` defines what "agent usable" means, including credentials or smoke checks when applicable
-8. **Call finishAuthoring** when complete

package/dist/templates/AGENT.md.template

@@ -1,46 +0,0 @@
-# Agent Environment
-
-This repository uses a **`.har/` harness** for isolated agent development.
-
-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.
-
-## Cursor IDE
-
-If `.cursor/rules/har-workflow.mdc` exists, the harness workflow (read-before-change, verify-before-done)
-is injected into every Cursor agent session automatically.
-Run `har env init` or `har env maintain` to create or refresh it.
-
-## Start here (all IDEs / first time)
-
-1. [`.har/README.md`](.har/README.md) — stages, verification, how to run
-2. [`stages.json`](.har/stages.json) — machine-readable stage registry
-3. [`.har/CLAUDE.agent.md`](.har/CLAUDE.agent.md) — definition of done (after `launch`)
-
-## Harness workflow
-
-Prefer **HAR MCP tools** (Cursor) or **`har env launch/verify/complete`** — they persist run history under `.har/runs/`.
-Use `./.har/*.sh` only when the CLI is not installed.
-
-When the work is done: full verify, commit in the session worktree, then present a
-**session handoff** and wait for the user. The **default recommendation** is
-complete + open a PR when `gh`/GitHub MCP is available (still requires approval);
-alternatives are complete-only or something else. See
-`.cursor/rules/har-workflow.mdc` for the handoff template.
-
-## Commit gate
-
-Full verify records the exact code state it validated (git tree hash in `.har/validations/`).
-If the commit gate is installed (`har hooks install`), commits of unverified changes are blocked:
-run `har env verify <id> --full` after your last edit, then `git add -A` and commit — any edit
-after verify invalidates the batch and requires a re-run. Do not bypass with `--no-verify`.
-
-## Project-specific notes
-
-<!-- Adapt when customizing the harness (see .har/ADAPT-PROMPT.md) -->