agentleFS
SensorsIotSensorsIot/Embedded-AI-Harness/.claude/skills/harness/SKILL.md

harness

Skill235 starsChanged 3 months agoMITView on GitHub

Phase 1 of AI Closed-Loop Programming — harness the AI for a project: the one-time setup that straps the AI to this particular load so the loop can run. Sequences Definition (via /define) when no FSD exists, then installs the three planes, the testing standard, the test plan seeded with the journey tests, declared testbench capabilities, firmware integration, CI with release verification, and the devcontainer with its per-repo runner. Use this skill for a new project, "set up this project", "harness this project", "integrate with the testbench", or when a project has an FSD but none of the machinery to build against it. Exit gate: AI harnessed.

36 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use retro, verify and 2 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AWSSkill

    retro

    Conduct a retrospective on a coding session.

    Also in 3 projects that use this

  • Microsoft AzureSkill

    verify

    End-to-end app testing pipeline for browser-based web apps on cloud browsers via Azure Playwright Workspaces: verify the live app, author tests for working flows, heal failing tests, then re-run with video and produce one consolidated report. Three phases (app verification, test authoring, test healing) plus a scoped final sanity run; each phase emits a sub-report. Use when asked to "verify my app", "make sure my app works and has good test coverage", "do a full QA pass", "add tests where I'm missing coverage", "fix failing tests and add new ones", "smoke test before deploy", "QA my deployment", or any combined verify-and-test ask. Requires Azure CLI (`az login`) and a Playwright Workspace resource ID — bootstraps configs on first invocation. Browser-based web apps with Playwright only — not for unit/API tests, native mobile/desktop, load/perf, or full accessibility audits.

    Also in 3 projects that use this

  • GoogleSkill

    code-review

    Adversarial systems, concurrency, memory-model, and architecture code review protocol. Use this skill whenever asked to review code, PRs, diffs, or branches in Filament.

    Also in 4 projects that use this

  • SentrySkill

    skill-creator

    Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, writing, registration, and verification.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 24 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

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

    The DUT is completely out of Phase 1: Not flashed, not reset, not read.

    line 38
  2. Distinctive:

    If it can — the plan is readable, the capabilities are declared, the agenda exists — the AI is harnessed.

    line 128
  3. Very specific:

    The gate loops, it does not wave through: If the checker returns SHUT, go back to the step above that owns each finding, fix it, and re-run …

    line 138

“Common” is measured: kept by at least 6 in 10 of the 24 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.

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

Harness — Phase 1 sequencer

Runs once per project. This skill owns only the order and the checklist of what "harnessed" means; every step delegates to the skill that does the work. A harness is the coupling between horse and load: after this phase, a /build session can open, state its position, and act.

The sequence

#StepDelegate to
1Definition first. No FSD → run Phase 0 now: /define (grill → create). FSD exists → verify every Must/Should carries a verification contract; missing ones are the first act/define
2Three planes installed or bound: FSD home, docs/Method/, docs/UserDocumentation/ + docs/00-Overview.md at the docs root/define planes mode
3Testing standard stamped (setup/teardown/evidence rules + shared procedures, one file)/define templates
4testing/test-plan.yaml created; capabilities declared — bench capabilities copied from what the bench reports (available: yes as declared — a project never proves them), plus this project's own peers and equipment. Blocked is computed from these, never typedthis skill
5Firmware integration — only the modules the FSD requires. UDP logging always (the loop's eyes inside the DUT); WiFi provisioning, OTA, BLE hooks only when the FSD carries the corresponding requirements. A module the spec never asked for is silent pack adoptiontestbench-integration
6CI: build on push, release on tag plus the release-verify job (flash the released artifact to the testbench, run the journey; red journey = no release)setup-action
7Devcontainer and toolchain, with the GitHub Actions runner inside it — see belowesp-idf-handling / esp-pio-handling (project + toolchain setup)
8Generate this project's gate checks — one file per gate under testing/gates/, filled with this project's paths, ids, DUT, capabilities, markers and CI. A generic checklist cannot catch a project-specific omissionthis skill · ../build/references/gate-checks.md
9Close with the two questions only the user can answer — see belowthis skill

Step 5 — a skeleton, and the DUT is not touched

The DUT is completely out of Phase 1. Not flashed, not reset, not read. No chip/info, no serial monitor, no esptool, no slot claimed. The board belongs to /commission, which discovers it, verifies it is the unit the FSD names, and proves the forward path to it. A harness session that has touched the DUT has done Phase 2's work without Phase 2's gate watching.

The firmware is a skeleton that proves the pipeline, nothing more. It compiles, it produces an artifact, and it emits one marker. It implements no requirement and verifies no requirement — those are /build's waves, run against the journey. The gate asks only that CI went green once and that no module exists which the FSD never asked for; both are satisfied by a composition root and a printed marker.

The pull that breaks this is always the same shape: the skeleton needs a hardware fact to compile. Flash size, partition offsets, a pin, a clock. The answer is never to go and read it off the chip — that is Phase 2 arriving early because Phase 0 left a hole. Send it back to /define: a constraint the build depends on belongs in the FSD, and a spec that omits one will pull hardware work forward into whichever phase first hits the wall.

Symptoms that Phase 1 has drifted:

  • a capability whose observed: evidence could only have come from the board
  • a host test that asserts product behaviour rather than that the tier runs
  • a build fixed by measuring the hardware instead of by amending the spec

Step 7 — the runner lives in the project's devcontainer

One project, one container — no separate infrastructure. The devcontainer already holds the pytest bench tier, TestbenchDriver, discovery, and slot config, which is everything the verify job needs (it downloads an artifact and speaks HTTP; it never builds). Installation is automated; registration is a human grant — a registered runner accepts and executes workflow code that then physically drives the bench, a standing outward-facing authority like the release tag itself. This skill installs the runner and the registration script, states what registering means, and waits for the user's yes. Register per-repo, labels [self-hosted, testbench], ephemeral registration in a restart loop, verify job triggered by tag push only, approval required for outside contributors. Declare it as a capability:

release-verification:
  what:      tag-triggered journey run against the released artifact
  available: yes   # the container runs 24/7; the bench may not — an absent
                   # bench at verify time is an unmet precondition (not done)

Step 9 — the two unharvestable questions

Asked at the end, when the user knows the system's shape — and never harvestable from any document:

  1. What has to be debugged before testing starts? Which project-side parts — this board, its wiring, its peers and simulators — have never been observed doing their job here. Becomes the debugging agenda that /commission burns down. The testbench is not on this list: a project depends on its quality, never proves it (../commission/SKILL.md).
  2. What does one ordinary successful run look like, end to end? Ordered steps, an observable at each. Becomes the journey tests — one test per step, seeded into the plan as the gate every hardware session runs behind, and the first tests of Wave 1 (Build the running prototype — ../build/references/test-design.md §5).

These two answers are worth more than everything else typed this month; take them slowly. Full rationale: ../build/references/test-design.md §5.

Exit — AI harnessed

Deliverables

DeliverableContent
Test plantesting/test-plan.yaml — capabilities (bench as declared, project equipment own-state), the journey tests seeded from question 2, phase/wave fields
Debugging agendathe project-side parts from question 1, each with unproven because and proven by
Testing standardone file: setup/teardown/evidence rules plus shared procedures
Firmware hooksonly the modules the FSD requires; UDP logging always
CIbuild on push, release on tag, release-verify job present
Devcontainer + runnertoolchain builds; runner installed, registration awaiting the user's grant
Gate checkstesting/gates/ — one generated file per gate, project-specific, run by a fresh checker at each gate

The check — a dry run of the next session

test -f testing/test-plan.yaml && test -f testing/debugging-agenda.md
ls .github/workflows/                       # build + release-verify present
gh run list -L 1                            # CI has actually run green once

Then the only check that matters: open a /build session and see whether it can state its position and name the next act without asking you anything. If it can — the plan is readable, the capabilities are declared, the agenda exists — the AI is harnessed. If it stalls, the missing input is the finding, and it belongs to whichever step above left it out.

Run the check in a fresh checker, not in this session — the session that built the harness is the worst judge of whether it landed (../build/references/gate-checks.md). Spawn it with testing/gates/ and the repo, nothing else — never memory, transcripts, or a summary of what this session did: a checker told what was decided will confirm it was done.

The gate loops, it does not wave through. If the checker returns SHUT, go back to the step above that owns each finding, fix it, and re-run the whole check with a new checker. Commissioning does not start on a partial harness.

AI harnessed — derived, never declared. The next session starts with /commission.

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.