@osfactory/har 0.34.0 → 0.36.0

package/dist/templates/AGENT.md.template

@@ -25,9 +25,14 @@ Run `har env init` or `har env maintain` to create or refresh it.
 
 ## Harness workflow
 
-Prefer **HAR MCP tools** (Cursor) or **`har env launch/verify/teardown`** — they persist run history under `.har/runs/`.
+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 before `har env complete <id>` /
+`har_complete_environment` (recommended finish: validation + teardown, branch kept),
+push, or opening a PR. 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/`).

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

@@ -55,8 +55,8 @@ Validate through the harness — do not skip verification or substitute ad-hoc n
 
 - `har_run_verification` with `agentId: 1` — fast loop (typecheck + unit tests)
 - `har_run_verification` with `agentId: 1, full: true` — required before declaring work done
-- `har_complete_environment` with `agentId: 1` — when the work is done: full verify + validation record + teardown, **keeping the session branch** so the user can push it / open a PR
-- `har_teardown_environment` with `agentId: 1` — plain cleanup (also keeps the branch; `deleteBranch: true` to drop it)
+- `har_complete_environment` with `agentId: 1` — **recommended finish** (full verify + validation record + teardown, branch kept). **Propose and wait for user approval** before invoking — never run autonomously
+- `har_teardown_environment` with `agentId: 1` — plain cleanup only (also keeps the branch; `deleteBranch: true` to drop it). Prefer `complete` when the work succeeded
 
 ### 2. HAR CLI (when `har` is installed)
 
@@ -88,8 +88,53 @@ When the Playwright stage is installed (`.har/stages/browser-e2e.sh` exists), ad
 - Full verification returns pass (`har env verify 1 --full`, MCP `har_run_verification` with `full: true`, or `./.har/verify.sh 1 --full`)
 - All edits live in the session worktree (main checkout untouched: `git status` clean there)
 - New behavior has automated test coverage
+- Changes committed in the session worktree
 - Show the user the slot preview URLs so they can test the app themselves
 - Do not declare work complete without running full verify
+- **Present session handoff and wait for the user's next instruction** — do not end the session without the handoff prompt
+
+## Session handoff (required)
+
+After full verify passes and changes are committed, **stop and hand off**. Never
+autonomously run `complete`, `teardown`, `git push`, or create a pull request.
+
+Present a handoff that includes:
+
+1. **Summary** of what changed
+2. **Session branch** name (from launch / `.har/slots/agent-<id>.json`)
+3. **Preview URLs** when the slot has a running app
+4. **Numbered next-step options** — then wait for the user
+
+Options to offer:
+
+1. **Complete the slot** (recommended) — `har env complete <id>` / MCP
+   `har_complete_environment`: full verify + validation record + worktree/runtime
+   teardown; **branch kept**. Prefer this over bare `teardown` when the work
+   succeeded.
+2. **Open a PR** — only if `gh` CLI or GitHub MCP is available. Create the PR
+   **only after explicit user approval**.
+3. **Keep the branch only** — if PR tooling is unavailable, report the session
+   branch and how to push manually. The branch already exists from launch.
+
+Canonical handoff shape:
+
+```markdown
+## Session handoff
+
+**Summary:** …
+**Branch:** `<session-branch>` (session worktree)
+**Preview:** … (if applicable)
+
+Next steps — tell me which you want:
+1. **Complete the slot** — I'll run `har env complete <id>` (full verify + validation record + teardown; branch kept)
+2. **Open a PR** — I can create one with `gh`/GitHub MCP (requires your approval)
+3. **Something else** — e.g. keep the slot running, more changes, or push only
+
+I'll wait for your instruction before running complete, teardown, push, or PR.
+```
+
+Omit option 2 when neither `gh` nor GitHub MCP is available; replace it with push
+instructions for the session branch.
 
 ## Commit gate
 

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

@@ -43,7 +43,17 @@ is alive; it does not automatically mean an agent can use the app.
 - [ ] New behavior has automated test coverage (unit and/or browser as appropriate)
 - [ ] Changes committed **in the session worktree** with a clear message
 - [ ] The user got the preview URLs to test the app themselves
-- [ ] Finish with `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — records the validation and tears down while **keeping the session branch** for the user to push / open a PR
+- [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
+- [ ] On user approval: `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+
+### Session handoff
+
+After full verify and commit, stop and propose next steps. Never autonomously run
+`complete`, `teardown`, `git push`, or open a PR. Prefer `complete` over bare
+`teardown` when the work succeeded. Offer a PR only if `gh` or GitHub MCP is
+available (and only after explicit approval); otherwise report the session branch
+for a manual push. See `.cursor/rules/har-workflow.mdc` for the canonical handoff
+template.
 
 Quick loop during development: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}` (smoke + health only; `--full` adds the registered verification stages).
 

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

@@ -29,7 +29,17 @@ workflow, document the required credentials/default data and wire a smoke into
 - [ ] Full verify runs every registered stage in `stages.json` `verificationStages` (Playwright, custom checks, …) — when `stages/browser-e2e.sh` exists, adapt specs under `tests/` for UI changes
 - [ ] New behavior has automated test coverage
 - [ ] Changes committed **in the session worktree** with a clear message
-- [ ] Finish with `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — records the validation and tears down while **keeping the session branch** for the user to push / open a PR
+- [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
+- [ ] On user approval: `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+
+### Session handoff
+
+After full verify and commit, stop and propose next steps. Never autonomously run
+`complete`, `teardown`, `git push`, or open a PR. Prefer `complete` over bare
+`teardown` when the work succeeded. Offer a PR only if `gh` or GitHub MCP is
+available (and only after explicit approval); otherwise report the session branch
+for a manual push. See `.cursor/rules/har-workflow.mdc` for the canonical handoff
+template.
 
 Quick loop: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}`
 

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

@@ -31,7 +31,17 @@ seeded data, or a simulator flow, document it here and wire the smoke into
 - [ ] When `stages/rocketsim-flows.sh` exists, full verify includes user-flow validation — add or update flow scripts in `flows/` for UI changes
 - [ ] New behavior has automated test coverage (unit tests via XCTest)
 - [ ] Changes committed **in the session worktree** with a clear message
-- [ ] Finish with `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — records the validation and tears down while **keeping the session branch** for the user to push / open a PR
+- [ ] Present session handoff (summary, branch, preview URLs) and **wait for user** before `complete`, push, or PR
+- [ ] On user approval: `har env complete ${AGENT_ID}` (or MCP `har_complete_environment`) — full verify + validation + teardown, branch kept
+
+### Session handoff
+
+After full verify and commit, stop and propose next steps. Never autonomously run
+`complete`, `teardown`, `git push`, or open a PR. Prefer `complete` over bare
+`teardown` when the work succeeded. Offer a PR only if `gh` or GitHub MCP is
+available (and only after explicit approval); otherwise report the session branch
+for a manual push. See `.cursor/rules/har-workflow.mdc` for the canonical handoff
+template.
 
 Quick loop: MCP `har_run_verification`, `har env verify ${AGENT_ID}`, or `./.har/verify.sh ${AGENT_ID}`
 

package/dist/templates/plugins/playwright/.har/stages/PLAYWRIGHT.md

@@ -18,4 +18,25 @@ After `./.har/launch.sh <id>`:
 ./.har/verify.sh <id> --full
 ```
 
-Replace TODO selectors and paths in the scaffold specs during harness adaptation.
+Adapt selectors and paths in the scaffold specs during harness adaptation.
+
+## New UI features
+
+Add or update Playwright specs so `browser-e2e` covers the change. Prefer one file per feature under `tests/frontend/<feature>.spec.js`. Full verification (`verify --full`) must pass before done.
+
+See the header comment in `playwright.config.js` for harness env vars, artifact paths, and the quick vs full verify contract.
+
+## Plugin updates
+
+When HAR ships a new plugin template version, merge drift from:
+
+```bash
+har env maintain
+# review .har/maintain/plugins/playwright/
+```
+
+Or refresh all plugin-owned files:
+
+```bash
+har env add-plugin playwright --force
+```

package/dist/templates/plugins/playwright/playwright.config.js

@@ -1,8 +1,48 @@
-// Playwright config tuned for HAR agent slots and CI.
+// Playwright config for the HAR `browser-e2e` verification stage.
+//
+// Harness integration
+// -------------------
+// - Stage id: `browser-e2e` (`.har/stages/browser-e2e.sh`, registered in `stages.json`).
+// - Runs automatically on FULL verify only — not on quick verify:
+//     ./.har/verify.sh <id> --full
+//     har env verify <id> --full
+//     har env complete <id>          # always full; required before declaring done
+// - Quick verify (`verify.sh <id>`) stops at typecheck / unit tests / api-health.
+//
+// Prerequisites
+// -------------
+// 1. Launch a slot first:     ./.har/launch.sh <id>
+// 2. Install browsers once:     npx playwright install chromium
+//
+// Environment (injected by browser-e2e.sh — never hardcode slot ports in specs)
+// ------------------------------------------------------------------------------
+// BASE_URL       Frontend origin for page.goto('/') and UI specs
+// API_URL        API origin for tests/api (defaults to BASE_URL when FE/API share a port)
+// PW_SCREENSHOT  Playwright screenshot mode (default: on)
+// CI             Set in CI for retries, worker cap, and forbidOnly
+//
+// Test layout — agents must add or update specs for every UI change
+// ------------------------------------------------------------------
+// tests/frontend/<feature>.spec.js   UI flows (prefer one file per feature)
+// tests/api/                         HTTP checks via the request fixture
+// tests/a11y/                        axe-core on key routes
+//
+// Full verify only proves existing specs pass. New UI behavior needs new or
+// updated specs here — the harness does not auto-generate flows per feature.
+//
+// Artifacts (gitignored under .har/artifacts/)
+// --------------------------------------------
+// browser-e2e/playwright-report/   HTML report after full verify
+// browser-e2e/test-results/        traces, screenshots, videos on failure
+//
+// Local-only (without browser-e2e.sh):  npm run test:e2e
+// Set BASE_URL (and API_URL if split) when the app is not on the default below.
 const { defineConfig, devices } = require('@playwright/test');
 
+const baseURL = process.env.BASE_URL || 'http://localhost:3000';
+const apiURL = process.env.API_URL || baseURL;
+
 module.exports = defineConfig({
-  testDir: './tests',
   timeout: 30 * 1000,
   expect: { timeout: 5000 },
   fullyParallel: true,
@@ -15,15 +55,26 @@ module.exports = defineConfig({
   ],
   outputDir: '.har/artifacts/browser-e2e/test-results',
   use: {
-    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    baseURL,
     headless: true,
-    screenshot: 'only-on-failure',
+    screenshot: process.env.PW_SCREENSHOT || 'on',
     video: 'retain-on-failure',
     trace: 'on-first-retry',
   },
   projects: [
     {
-      name: 'chromium',
+      name: 'frontend',
+      testDir: './tests/frontend',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'api',
+      testDir: './tests/api',
+      use: { baseURL: apiURL },
+    },
+    {
+      name: 'a11y',
+      testDir: './tests/a11y',
       use: { ...devices['Desktop Chrome'] },
     },
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osfactory/har",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "LLM-powered CLI for reproducible agent development environments",
   "keywords": [
     "har",