agentleFS
os-factoryos-factory/har/AGENTS.md

har

AGENTS.md133 starsChanged 3 months agoApache-2.0View on GitHub

Guide for coding agents working on this repository (@osfactory/har — the CLI and MCP control plane). For setup, testing fixtures, and PR workflow, see CONTRIBUTING.md. This repo dogfoods HAR — .har/ at the repo root defines how coding agents validate changes here. 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…

  • Reads credentials
  • Installs packages
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository6 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

14 rules. About 0 are common, 1 is distinctive, and 13 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 13

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run harness commands from the directory that owns the harness (e.g.

    line 49
  2. Very specific:

    When the task names a tracker issue or ticket, bind at launch with a short --work-id, plus --work-source, --work-url, and --work-title when …

    line 60
  3. Very specific:

    Add secondary links (GitHub issue, PR, Bitbucket) with repeatable --work-link source|url|label at launch, or later via har env work-link …

    line 62
  4. Very specific:

    Default recommendation is complete + open a PR when tooling is available (still requires approval).

    line 67
  5. Very specific:

    Run records are stored under the main checkout .har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json (local date/time).

    line 84
  6. Very specific:

    If your IDE workspace is a worktree, pass --repo /path/to/main/checkout to har env commands (MCP config already points at the main …

    line 89
  7. Very specific:

    Do not use har env init --force on an adapted harness — it wipes customizations.

    line 100
  8. Very specific:

    When the workspace has a .cursor/ directory and no rule yet, the CLI prompts.

    line 111
  9. Very specific:

    When unsure: put domain logic in harness/ or core/, never in an adapter.

    line 163
  10. Very specific:

    Every environment operation is available on both surfaces unless listed here as an intentional hole.

    line 189
  11. Very specific:

    When CLI and core share a code path, keep parity tests (see tests/run-service-parity.test.ts)

    line 239
  12. Distinctive:

    After changes: run the harness verify stage (see below)

    line 240
  13. Very specific:

    Do not end the session without a handoff prompt.

    line 295
  14. Very specific:

    If you changed src/templates/: npm run build, then har env init --force --profile cli on a fixture (or --profile default for web apps).

    line 297

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

HAR — Agent Development Guide

Guide for coding agents working on this repository (@osfactory/har — the CLI and MCP control plane).

For setup, testing fixtures, and PR workflow, see CONTRIBUTING.md.

This repo dogfoods HAR — .har/ at the repo root defines how coding agents validate changes here.

<!-- har:agent-environment:start -->

HAR / agent environment

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.
  4. All slots taken? Occupied slots always block a launch, and you never free one yourself. Run har env status, then show the user every slot — branch, work unit, what it achieves, last verify, and whether its commits are merged, pushed or unpushed — and recommend which to close: merged or abandoned work with nothing left to do first; never one with unpushed commits. On approval: complete / teardown <id>, 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 and .har/stages.json.

<!-- har:agent-environment:end -->

Harnesses in this repo

This is a monorepo with three harnesses — pick the one that owns the files you are changing:

PathProfileRunsUse when changingDocs
.har/cli@osfactory/har (typecheck, build, unit tests, lint)src/, packages/, tests/.har/README.md
control/.har/defaultMission Control (Next.js + SQLite, browser-e2e)control/control/.har/README.md
docs/.har/defaultDocs / marketing site (Astro + Playwright screenshots)docs/docs/.har/README.md

Run harness commands from the directory that owns the harness (e.g. cd docs && har env launch 1). See control/AGENTS.md and docs/AGENTS.md for project guides.

The harness is how you run each project — to see Mission Control or the docs site live (manual testing, browser, screenshots), launch the matching slot; never hand-roll docker/dev-server startup. If a harness command fails, fix the harness or report it — don't silently fall back to ad-hoc commands.

Docs UI work: use docs/.har/ so full verify produces before/after screenshots under docs/.har/artifacts/browser-e2e/screenshots/. The root CLI harness may still run docs contract checks (drift / build) when changing product surfaces that the docs describe — that does not replace launching the docs harness for landing-page or Starlight UI changes.

Harness workflow (dogfooding)

Follow .cursor/rules/har-workflow.mdc and .har/README.md: launch first, edit only under the session work dir, full-verify before done, then present a session handoff and wait for approval. When the task names a tracker issue or ticket, bind at launch with a short --work-id, plus --work-source, --work-url, and --work-title when known. Add secondary links (GitHub issue, PR, Bitbucket) with repeatable --work-link source|url|label at launch, or later via har env work-link --work-id <id> --link … / MCP har_add_work_unit_link. Bind the planning tracker (Jira/Linear) as --work-url; attach code-host links as related links. Include any remaining links in session handoff until attached. Default recommendation is complete + open a PR when tooling is available (still requires approval); never run complete, push, or PR autonomously.

Configure Cursor MCP from .cursor/mcp.json.example (see CONTRIBUTING.md). All three surfaces are equivalent in 1.0 — prefer MCP or har env … for the richer structured output. Use har env launch 1 --no-worktree only when you must use the repo root checkout.

Run history

CLI and MCP execute the same packaged runtime and write the same records:

Entry pointWrites .har/runs/?
har env launch/verify/...Yes
MCP har_run_*Yes

Run records are stored under the main checkout .har/runs/YYYY-MM-DD/HH-mm-ss_<stageId>_agent-<id>.json (local date/time). With worktree slots, tests run in the worktree but run JSON stays in the main repo; each record includes a workDir field.

The commit gate is therefore satisfiable from either surface. Prefer MCP or har env … for structured output and tracker binding.

If your IDE workspace is a worktree, pass --repo /path/to/main/checkout to har env commands (MCP config already points at the main checkout).

Upgrading HAR

npm install -g @osfactory/har@latest    # updates CLI/MCP/run storage only
har env maintain                  # drift report + adaptation prompt
# apply updates via your coding agent (paste .har/ADAPT-PROMPT.md)
har env verify 1 --full

Do not use har env init --force on an adapted harness — it wipes customizations. See CONTRIBUTING.md.

Cursor rule

har onboard, har_init_harness, and har env maintain optionally scaffold .cursor/rules/har-workflow.mdc in the target repo — a Cursor rule that injects the harness read-before-change / verify-before-done workflow into every agent session.

har env maintain --cursor-rule     # force-write without prompting
har env maintain --no-cursor-rule  # skip Cursor rule scaffolding

When the workspace has a .cursor/ directory and no rule yet, the CLI prompts. In CI or with --yes, it writes silently. The rule is refreshed automatically on every maintain run when it already exists.

Architecture

HAR is a layered CLI + MCP control plane. Business logic lives in core/ and harness/. cli/ and mcp/ are thin adapters: parse input, call core, format output.

cli/  mcp/          ← adapters (flags, JSON, MCP tool schemas)
  ↓
core/               ← orchestration, public execution API
  ↓
harness/            ← .har/ contract, schemas, manifest/stages I/O
  ↓
utils/              ← generic helpers (shell, paths, logging)

templates/ holds scaffold assets copied into target repos — not runtime logic.

Dependency rules

These are non-negotiable. Do not introduce imports that violate them.

LayerMay importMust not import
cli/, mcp/core/, harness/, utils/each other
core/harness/, utils/cli/, mcp/
harness/utils/core/, cli/, mcp/
utils/other utils/anything with HAR domain concepts

Where to put changes

ChangeLocation
Schema, stage kinds, result shapessrc/harness/schema.ts
Manifest / stages.json I/Osrc/harness/manifest.ts, stages.ts
Scaffold copy, boilerplate wiringsrc/harness/generator.ts
Init / maintain / describe orchestrationsrc/core/harness.ts
Run orchestration (launch, verify, teardown)src/core/run-service.ts
Local bash/script executionsrc/core/local-executor.ts
Run history (.har/runs/)src/core/runs.ts
Shared execution types, StageExecutorsrc/core/types.ts
CLI subcommand or flagsrc/cli/commands/
MCP tool handler or JSON Schemasrc/mcp/server.ts, schemas.ts
Files copied into target .har/src/templates/har-boilerplate/
Optional verification pluginssrc/templates/plugins/ (applied via har env add-plugin)
Factory line schemas (program + bundle manifest)packages/schemas/src/line.ts
Line apply / scaffold / ledgersrc/harness/lines.ts, line-create.ts, line-ledger.ts
Line status + cumulative gate orchestrationsrc/core/lines.ts
Bundle install channels shared by plugins and linessrc/harness/bundle-resolve.ts
Bundled example line (seed for os-factory/har-line)src/templates/lines/example-line/
Generic shell/path/logging helpersrc/utils/

When unsure: put domain logic in harness/ or core/, never in an adapter.

Public API

Adapters and tests import execution from src/core/run-service.ts (or the run.ts re-export). Do not import local-executor.ts from outside core/.

Canonical schemas live in src/harness/schema.ts. Parse CLI and MCP inputs at the boundary with Zod (.parse() / .safeParse()); infer types with z.infer.

Const arrays like HAR_STAGE_KINDS are the single source of truth — use them for Zod enums, MCP JSON Schema, and tests.

Extension points

Design for a closed core with open seams. Plugins are first-class installable bundles under src/templates/plugins/ (har env add-plugin). Bundled plugins are discovered from disk; out-of-tree installs use path/npm/git specs. A remote community plugin marketplace can wait until there is a concrete external publisher — naming plugins ≠ shipping a marketplace.

  • StageExecutor (src/core/types.ts) — swap local vs cloud execution by injecting a different executor into RunService. local-executor.ts is the current implementation.
  • Project-owned stages — runtime behavior lives in the target repo's .har/ scripts and stages.json, not as hardcoded tool APIs in core.
  • Factory lines — installable programs (har line add <id|path|npm|git>), resolved through the same channels as plugins (bundle-resolve.ts) but with an apply path that registers stages and never touches verificationStages. har line gate <station> runs the cumulative set through RunService; there is no second stage runner. Poka-yoke both ways: add-plugin refuses kind: line, line add refuses a plugin manifest, and doctor fails if a line stage reaches the verify plan.
  • Plugins — optional bundles applied with har env add-plugin <id|path|npm|git> (e.g. playwright → browser-e2e stage + test scaffold). Discovered from src/templates/plugins/*/template.manifest.json (no closed enum). Installs are recorded in .har/plugins.json. They compile down to generic stage kinds (setup, launch, verify, test, custom, etc.). Do not add stack-specific MCP tools like run_playwright. Philosophy: plugins install stages; agents only talk to the stage registry.
  • Profiles — ordered runtime bundles (src/templates/profiles/<id>/profile.manifest.json), not forked logic in core. Stack capabilities (PM2, Simulator, ports) are detected via src/harness/capabilities.ts marker files.

Operation × surface matrix (CLI ↔ MCP)

Every environment operation is available on both surfaces unless listed here as an intentional hole. Both surfaces delegate to the same core/run-service.ts / core/harness.ts code paths; status is one structured implementation (collectEnvironmentStatus) with text rendered on top, the launch guard runs exactly once inside run-service, and status is a pure read (no run records) on every surface.

First-run scaffold: humans use har onboard; agents use har_init_harness. har env init is the mechanical CLI primitive (fixtures, --force) — same initHarness core. There is no har_onboard MCP tool.

OperationCLIMCP
describe / init / maintain / add-pluginhar env init, maintain, add-pluginhar_describe_project, har_init_harness, har_maintain, har_add_plugin
launch / recover / preflighthar env launch, recover, preflighthar_launch_environment, har_recover_environment, har_preflight_environment
verify / run-stage / logs / status / artifactshar env verify, run-stage, logs, status, artifactshar_run_verification, har_run_stage, har_get_logs, har_get_status, har_list_artifacts
doctorhar env doctor (also auto-runs in maintain and before launch)har_doctor
complete / teardownhar env complete, teardownhar_complete_environment, har_teardown_environment
runs / work linkshar env runs list|get, work-linkhar_list_runs, har_get_run, har_add_work_unit_link
factory lineshar line create|add|status|gate|listhar_line_create, har_add_line, har_line_status, har_run_line_gate
Mission Controlhar control uphar_control_up

Intentional holes (human-only, no MCP tool):

  • har env cleanup — cross-repo destructive teardown with interactive confirmation; an agent must free its own slot with complete/teardown instead.
  • har env add-stage --custom — authoring a project stage is an adaptation task done in the checkout, not a tool call; agents edit .har/stages.json + stages/ directly.
  • har env eject / har env adopt — taking (or returning) ownership of the runtime scripts is a deliberate human policy decision with an interactive confirmation.
  • Hooks / commit-gate onboarding (har hooks …, init/maintain onboarding prompts) — installs git hooks and records user policy preferences; a policy decision for humans.
  • Onboarding/preferences, telemetry toggles, and portal login (har onboard, har preferences, har telemetry, har hq) — account- and machine-level state.

Anti-patterns

  • Orchestration logic in mcp/server.ts or cli/commands/ — adapters delegate to core/
  • Stack-specific stages or MCP tools in core (Playwright, Cypress, migrations, etc.)
  • Implementing line apply by calling applyPlugin / patchStageRegistry — those exist to widen verificationStages; a line must never
  • Adding a line's gate stages to verificationStages (that is a verification plugin, not a line)
  • harness/ importing from core/ — keeps the contract layer independent
  • Domain types or HAR concepts in utils/
  • Deep barrel re-exports inside src/ — prefer explicit imports; public surface is run-service.ts / run.ts
  • Weakening strict: true or using any instead of unknown + Zod narrowing

Tests

  • Unit tests in tests/*.test.ts; fixtures under tests/fixtures/
  • Mock .har/ layouts with fixtures — avoid real Docker in unit tests
  • When CLI and core share a code path, keep parity tests (see tests/run-service-parity.test.ts)
  • After changes: run the harness verify stage (see below)

Branch names, CI, and releases

Git branch names do not skip CI or releases. Name the base branch for clarity, then match the commit / squash-merge title to CONTRIBUTING.md (that title becomes the commit on main).

Recommended base-branch prefixes

WorkBase branchCommit / PR title
Docs site or markdown only (docs/**, *.md)docs/<short-topic>docs: …
CI / workflows onlyci/<short-topic>ci: …
Benchmarks onlybenchmark/<short-topic>any type with (benchmark) scope, e.g. chore(benchmark): …
Product changesfeat/…, fix/…, etc.feat: / fix: (these do release)

HAR session branches are derived from whatever base you launch from (docs-…-har-agent-…). Prefer starting from a docs/… or ci/… base when the change is non-releasing.

What actually avoids a release

semantic-release cuts a version from Conventional Commits on main. Matching CONTRIBUTING.md:

Commit prefixRelease
fix:Patch
feat:Minor
feat!: / fix!: (! on any type) or a BREAKING CHANGE: footerMajor
chore:, docs:, test:, refactor:, ci:No release
feat(benchmark):, *(ci):, docs(*):No release (release.config.cjs rules)

Explicit analyzer rules in release.config.cjs: type ci, type docs, scope ci, and scope benchmark all set release: false. The analyzer uses the conventionalcommits preset so ! alone marks a breaking change (#311) — put it in the squash-merge title, since a squash drops BREAKING CHANGE: footers written in commit bodies. Prefer type ci: / docs: for those-only PRs — not feat(docs): or fix(docs): (type feat/fix still releases unless the scope is ci or benchmark). Squash-merge PR titles must follow the same format.

What actually skips CI jobs

WorkflowWhen it runsHow to skip / limit
TestEvery PR → mainNot skipped by branch name or docs: / ci: commits today
ReleasePush to mainAdd [skip ci] to the merge commit message to skip verify + release jobs
DocsPush/PR touching docs/** (and related paths)Path-filtered — only runs when those paths change

For docs-only updates: branch docs/<topic>, title docs: …. For CI-only updates: branch ci/<topic>, title ci: …. To also skip the Release workflow after merge, add [skip ci] to the squash message (e.g. docs: refresh landing copy [skip ci]). The Docs workflow may still run when docs/** changes — that is intentional.

Before finishing

har env launch 1                # if not already launched this session
har env verify 1                # typecheck + build + docs check/build
har env verify 1 --full         # + unit tests, lint, docs-drift — required before declaring done
# then: session handoff → wait for user → on approval of default (complete + PR):
# push + open PR, then:
har env complete 1              # reuse last passing full validation + teardown; branch kept
# har env complete 1 --verify   # re-run full verify first if the tree may have changed

Or use MCP har_run_verification / har_complete_environment (preferred in Cursor). Prefer complete over bare teardown — it closes the work attempt.

Do not end the session without a handoff prompt. Never autonomously run complete, push, or open a PR. The default handoff recommendation is complete + PR when tooling is available.

If you changed src/templates/: npm run build, then har env init --force --profile cli on a fixture (or --profile default for web apps).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.