About harness
Harness is a repository-centered skill for preserving project state and guiding work across development sessions. It uses progress and feature files to track priorities, verification evidence, and handoffs, while keeping repository rules authoritative.
Key features
- 01Record progress in repository files
- 02Track features and verification evidence
- 03Resume work from session state
- 04Follow repository-specific rules
- 05Check completion claims independently
Use cases
- 01Set up persistent project tracking
- 02Resume unfinished work in a new session
- 03Verify feature completion with recorded evidence
Install
Copy the command and run it in a terminal.
npx skills add https:/ / github.com/ tomgrv/ devcontainer-features --skill harnessAfter installing, type/harnessin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
templates/clean-state-checklist.mdsession-handoff.mdprogress.mdfeatures.jsonDetails
From the project READMEThe repository is the system of record. Chat is not. State that must survive a session lives in files; a fresh session recovers it by reading them, not by guessing. Based on Learn Harness Engineering.
Init (once per repo, skip files that already exist)
Copy from templates/ next to this file, then adapt — never leave placeholders:
.agents/progress.md— session log + current verified state..agents/features.json— every user-visible feature withid,priority,status,verificationsteps andevidence. Write real features from the repo's README/issues/code; all startnot_started.- Optional for large sessions:
templates/session-handoff.md→.agents/handoff.md.
Dependencies are installed by the devcontainer features, not here; the baseline is the CI status on the repo's dev forge (GitHub, GitLab, Azure DevOps), which the hook prints. Put each feature's real verification steps in .agents/features.json. Commit the files as one change. Once .agents/progress.md or .agents/features.json exists, the SessionStart hook prints the state and the Stop hook checks the handoff.
Session start
pwd— confirm the repo root.- Read the repo's own rules:
CLAUDE.md,AGENTS.md,.agents/instructions/*.instructions.md(theSessionStarthook lists which exist). They stay authoritative for commit format, PR base/title, scope limits and tooling; the harness adds the loop around them, it never overrides them. - Read
.agents/progress.md, then.agents/features.json. git log --oneline -5. TheSessionStarthook already printed the state and the forge CI status of the branch.- CI red on the branch? That is the baseline: fix it first. No new work on a broken start.
- Pick the highest-priority unfinished feature. Set it
in_progress. One at a time.
While working
- Follow the repo's rules while working (minimal-change discipline, commit/PR format, CI naming). A rule conflict with the harness: the repo rule wins; record it in the progress log.
- Stay inside the selected feature. A blocker may justify one narrow supporting fix.
passingneeds the feature'sverificationsteps actually run, with evidence recorded (command + result, not "looks fine").- Never reword, delete or weaken a feature or test to make it pass. Never loosen verification mid-feature.
- Declared done? Run the
harness-evaluatoragent: fresh context, tries to refute the claim.
Session end
- Update
.agents/progress.md: verified state, what ran, evidence, known risk, next best step. - Update
.agents/features.jsonstatuses and evidence. - Walk
templates/clean-state-checklist.md. - Commit once the repo is safe to resume, using the repo's commit and PR conventions from its rules. CI on the branch must be green or explained in the progress log; the next session must start without manual repair.
Boundaries
Do not invent features, evidence or verification results. Do not mark passing without a run. Do not hide unfinished work by editing the list.