new-plugin
Skill133 starsChanged 3 months agoApache-2.0View on GitHub
Factory line for adding a new HAR verification plugin (like playwright or rocketsim) for any framework — research the framework docs, build the template under src/templates/plugins/, register it everywhere, validate on a real repository, and open a PR. Use when asked to add/create a plugin, plugin template, or framework integration (e.g. "add a Cypress plugin", "support Maestro", "new plugin for vitest browser mode").
- Reads credentials
4 other projects use a version of this.
Adopted by
Most recently taken up by
- clidey/whodbtheir own version, first seen Nov 15, 2026
- gastonlarap-a11y/claude-code-setuptheir own version, first seen Oct 11, 2026
- chewygumxx/claude-librarytheir own version, first seen Oct 8, 2026
- langburd/agent-skillstheir own version, first seen Jun 8, 2026
Other versions4 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 4
- clidey/whodb★ 5.1ksame name
- langburd/agent-skills★ 4same name
- gastonlarap-a11y/claude-code-setup★ 1same name
- chewygumxx/claude-library★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- control/AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- .cursor/rules/har-workflow.mdcCursor rule
- factory-lineSkill
- v1-milestoneSkill
The file
We split this skill into the rules it gives an agent
4 rules. 0 are common, 1 is distinctive, and 3 are very specific to this project.
0
Common
Most of the 4 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
Do this before writing any template file.
- Very specific: line 92
Write all artifacts under .har/artifacts/<stage-id>/ (main repo root, not worktree).
- Very specific: line 104
If npm-based: package.fragment.json with scripts + pinned devDependencies.
- Very specific: line 142
Follow the manifest's own nextSteps verbatim: install deps, har env launch 1, run ./.har/stages/<stage-id>.sh 1.
“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
New HAR plugin factory line
Instance of the factory-line template. Program data:
new-plugin.line.json. Stations here are sequential phases, not GitHub issues. The product is a plugin, not a runtime migration — that is why this line exists as a second instance.
Ship a new verification plugin <id> for framework <framework> end-to-end:
research → template → registration → local validation → real-repo validation → PR.
A plugin is an installable bundle under src/templates/plugins/<id>/ applied by
har env add-plugin <id>. It registers generic stage kinds (test, verify,
custom, …) in the target repo's .har/stages.json. Philosophy (AGENTS.md):
plugins install stages; agents only talk to the stage registry. Never add
stack-specific MCP tools or core stages.
Reference implementations: src/templates/plugins/playwright/ (web e2e, package.json
merge, CI workflow) and src/templates/plugins/rocketsim/ (external-tool flows,
no package merge). Pick whichever is closer to <framework> as your baseline.
Phase 0 — Inputs
Establish before doing anything (ask the user only if not inferable):
- Plugin id — short lowercase slug (
cypress,maestro,k6). - Framework — what it tests and on which stack (web, iOS, API, load…).
- Stage id — what the stage does, not the brand (
browser-e2e,mobile-flows,load-test). Brand goes in the description and docs filename. - Validation repo — a real repository that uses
<framework>to prove the plugin works (Phase 5). An existing example/OSS repo, or a minimal app you scaffold.
Phase 1 — Research the framework
Do this before writing any template file. Use WebSearch/WebFetch on the framework's official docs and answer:
- Headless CLI invocation — exact command to run tests non-interactively in CI
(e.g.
npx cypress run,maestro test flows/). Flags for reporter/output dir. - Config file — name, format, and the minimal config needed; how to inject
BASE_URL/ports via env vars (HAR slots compute ports per agent id). - Artifacts — where reports/screenshots/videos land and how to redirect them
into
.har/artifacts/<stage-id>/. - Install — npm devDependencies (+ current stable version) or external binary (then document a doctor/preflight check instead of a package merge).
- CI recipe — official GitHub Actions setup, for the optional workflow file.
- Exit codes — how failure is signaled so the stage script can pass it through.
Also read both existing plugins in full (template.manifest.json, stage script,
stage .md doc, README) — copy their structure, don't reinvent.
Phase 2 — Launch a HAR session
This repo dogfoods HAR. Follow .har/README.md: launch first, edit only under the
session work dir, verify before done.
har env launch 1 # profile cli (.har/ at repo root owns src/, tests/, docs/)Bind --work-id/--work-source/--work-url/--work-title if the task names a ticket.
Phase 3 — Build the template
Create src/templates/plugins/<id>/ containing:
3a. template.manifest.json (required — validated by PluginManifestSchema in src/harness/plugins.ts)
Fields: id, stageId, verificationStages (existing stage ids + the new one —
copy the profile's defaults, e.g. typecheck/unit-tests/lint + <stage-id>),
stage (a full HarnessStageSchema object: id, kind (usually "test"),
description, script: "stages/<stage-id>.sh", requiresAgentId: true,
artifacts), files (src→dest copies; stage script gets "executable": true),
optional optionalFiles (CI workflow with "skipFlag": "skipCi"), optional
merge: { "package.json": "package.fragment.json" }, nextSteps (install →
launch → run stage → view artifacts), and docsPath (.har/stages/<STAGE>.md).
3b. .har/stages/<stage-id>.sh (required)
Model it on playwright/.har/stages/browser-e2e.sh. Hard conventions (unit-tested):
#!/usr/bin/env bash+set -euo pipefail; JSON result to stdout, progress to stderr.- Take
<agent-id>as$1,validate_agent_id, sourceharness.env+agent-slot.sh, resolve.env.agent.<id>and the agent work dir. - Derive ports from
HARNESS_*_BASE_PORT + AGENT_ID * 10; export the framework's base-URL env vars from them. - Write all artifacts under
.har/artifacts/<stage-id>/(main repo root, not worktree). - Timing: use
$(now_ms); neverdate +%s%3N(GNU-only). - No
mapfile/readarray(absent in macOS bash 3.2); usewhile readloops. - Capture the framework's exit code with
set +e … set -eand propagate it.
3c. Docs + scaffold
.har/stages/<STAGE>.md— agent-facing authoring/adaptation guide (what to adapt per repo, env vars, artifact layout). This isdocsPath.- Minimal working example tests/flows/config the framework actually runs
(playwright ships smoke specs; rocketsim ships
flows/example-smoke.sh). README.mdfor humans.- If npm-based:
package.fragment.jsonwithscripts+ pinneddevDependencies. - Optional
.github/workflows/<id>.ymlfrom the official CI recipe.
Phase 4 — Register everywhere (checklist)
| Where | What |
src/templates/plugins/<id>/ | Bundle with valid template.manifest.json — discovered automatically after npm run build (no PLUGIN_IDS edit) |
tests/plugins.test.ts | Add an applies <id> plugin to a scaffolded harness case (mirror the rocketsim one: files exist, executable bit, stage registered, verificationStages, .har/plugins.json ledger) |
tests/onboarding.test.ts | Extend the ids expectation to contain <id> |
tests/verify-shell-timing.test.ts | Add the stage script path to verifyPaths (and a mapfile check if it does list processing) |
docs/src/content/docs/docs/guides/plugins.md | New section: install command, what it adds, adaptation notes |
docs/src/content/docs/docs/reference/cli.md | Extend --plugins / add-plugin examples |
docs/src/pages/index.astro + docs/public/assets/logo-<id>.(svg|png) | Landing card with framework logo (fetch an official logo asset) |
docs/src/data/plugins.ts | Marketplace catalog entry |
src/harness/adaptation-prompt.ts | Mention the plugin if it's the natural fit for a profile (like rocketsim ↔ ios) |
src/templates/har-boilerplate*/STAGES.md | Mention in the plugins list where the existing ones are mentioned |
Phase 5 — Validate locally, then on a real repository
Local (fixture):
npm run build # templates are copied to dist/ — required before add-plugin sees it
har env verify 1 # typecheck + unit tests
mkdir -p <scratchpad>/fixture && cd <scratchpad>/fixture
git init -q && npm init -y # if the plugin merges package.json
node <repo>/dist/index.js env init --profile default --yes
node <repo>/dist/index.js env add-plugin <id>
cat .har/stages.json # stage + verificationStages present
bash -n .har/stages/<stage-id>.sh # syntax checkReal repo (required — the plugin must be proven to work):
- Clone/scaffold the validation repo from Phase 0 into the scratchpad — a repo
that genuinely uses
<framework>(e.g. the framework's official example app). har env initthere (pick the right profile), thenhar env add-plugin <id>.- Follow the manifest's own
nextStepsverbatim: install deps,har env launch 1, run./.har/stages/<stage-id>.sh 1. - The stage must pass and populate
.har/artifacts/<stage-id>/. If external hardware/tooling is unavailable (e.g. iOS simulator on Linux), validate as far as the environment allows and state exactly what was and wasn't executed — never claim it works untested. - Fold every adaptation you needed back into the template or the
<STAGE>.mdadaptation guide, rebuild, and re-run untilnextStepssucceed as written.
Phase 6 — Verify and hand off
har env verify 1 --full # typecheck + unit tests + lint + build — requiredThen present a session handoff (per .har/README.md) and wait for approval —
never run complete, push, or open a PR autonomously. On approval:
- Branch
feat/plugin-<id>, commit/PR titlefeat: add <framework> plugin(this releases a minor — intended for a new plugin). - PR body: what the plugin installs, the registration checklist, and validation evidence — the real repo used, the stage run output/artifacts, and anything not executable in this environment.
har env complete 1after the PR is up.
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
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.

