Harness Map
Map the repository's actual harness: the mechanical checks, policies, workflows, and artifacts that make change safe.
This skill is narrower than generic codebase research. It is specifically for answering questions like:
- "What is the harness in this repo?"
- "What does
check actually run?"
- "Which layers are local vs CI vs docs vs evidence?"
- "How is architecture enforced here?"
- "What operator surfaces teach agents how to use the harness?"
Core Principle
Map the harness as implemented, not as imagined.
Prefer:
- commands that actually run
- config files that actually enforce policy
- CI workflows that actually gate merges
- docs and playbooks that actually structure investigations
- agent/operator files that actually expose the workflow
Avoid:
- aspirational architecture prose without enforcement
- recommendations before the map exists
- broad codebase summaries that skip the gate structure
What Counts as Harness
A repo harness usually includes some or all of these layers:
- Canonical local command
just check, make check, task check, npm test, etc.
- Architecture boundaries
- Import Linter, dependency-cruiser, Bazel visibility, custom dependency tests
- Structural rules
- ast-grep, semgrep, custom lint rules, codemod rule tests
- Behavioral verification
- unit/integration tests, snapshots, goldens, deterministic checks, build verification
- Docs ratchets
- docs link checks, nav checks, metadata/frontmatter checks, allowlists
- CI decomposition
- matrix jobs or separate workflows that mirror harness gates
- Evidence workflows
- session logs, diff reports, chunk docs, experiment records, replay/debug artifacts
- Operator surface
AGENTS.md, .codex/, environment files, repo-local skills, slash commands
When to Use
Use this skill when the user asks to:
- map or explain the harness
- identify all gate layers in a repo
- compare local checks with CI checks
- document how architectural constraints are enforced
- understand how agents/operators are expected to use the repo safely
Workflow
1. Find the canonical local entrypoint
Inspect common entrypoint files first:
justfile
Makefile
package.json
pyproject.toml
- task runner config files
Capture:
- the canonical command name
- every subcommand it runs
- whether it chains all gates or only a subset
2. Find CI gate execution
Inspect CI workflows:
.github/workflows/*.yml
- other CI configs (
.gitlab-ci.yml, buildkite, etc.)
Capture:
- job names
- matrix dimensions
- whether
fail-fast is enabled
- which local gates are mirrored in CI
- which gates only exist in CI
3. Find architecture enforcement
Look for:
- Import Linter / grimp
- dependency-cruiser
- layering tests
- package-boundary configs
- forbidden import tests
Capture:
- contract names
- source and forbidden modules
- ignore lists / allowed exceptions
- exact config path
4. Find structural rule enforcement
Look for:
sgconfig.yml, ast-grep rule directories
- semgrep configs
- custom lint rule packages
- rule tests and snapshots
Capture:
- rule config files
- rule directories
- test directories
- snapshot/baseline locations
- any custom parser or language extensions
5. Find behavioral verification layers
Look for:
- test commands
- snapshot directories
- golden outputs
- deterministic helpers
- numerical equivalence docs
- build verification steps
Capture:
- exact commands
- test conventions docs
- locations of snapshots/goldens
- special validation steps outside the main test runner
6. Find docs ratchets
Look for:
- docs check scripts
- nav validation
- broken-link validation
- frontmatter/tag checks
- allowlists / baselines
Capture:
- categories of docs failures
- allowlist file paths
- whether the check behaves as a ratchet
7. Find evidence workflows
Look for:
- chunk docs
- debugging session logs
- replay/trace diff playbooks
- benchmark result docs
- evidence indexes
Capture:
- index files
- per-session or per-chunk docs
- required evidence fields
- exact commands recorded in those artifacts
8. Find operator-facing surfaces
Look for:
AGENTS.md
.codex/environments/*
.codex/skills/*
- command docs
- plugin manifests
Capture:
- setup / run / test actions
- repo-local skills that wrap harness flows
- operator instructions that point to real commands
9. Synthesize the harness map
Write the harness map directly to the repository root as:
HARNESS.md
This file serves as the single source of truth for how this repository keeps change safe. Write it in a style that a new developer or agent can use to understand the harness immediately.
Recommended structure:
---
title: "<repo> – Harness Map"
phase: Research
date: "YYYY-MM-DD HH:MM:SS"
owner: "<agent_or_user>"
tags: [research, harness, <repo>]
---
# <repo> – Harness Map
A living map of the mechanical checks, policies, workflows, and artifacts that make change safe in this repository.
## Canonical Entry Point
- `path:line-line` → command and subcommands
## Harness Layers
### Layer 1: Local Checks
| Check | Command | Config | Enforces |
|-------|---------|--------|----------|
| ... | ... | ... | ... |
### Layer 2: Architecture Boundaries
| Contract | Source | Forbidden | Config |
|----------|--------|-----------|--------|
| ... | ... | ... | ... |
### Layer 3: Structural Rules
| Rule Set | Config | Test Location | Notes |
|----------|--------|---------------|-------|
| ... | ... | ... | ... |
### Layer 4: Behavioral Verification
| Test Suite | Command | Snapshot/Golden Location | Notes |
|------------|---------|--------------------------|-------|
| ... | ... | ... | ... |
### Layer 5: Docs Ratchet
| Check | Command | Allowlist | Notes |
|-------|---------|-----------|-------|
| ... | ... | ... | ... |
### Layer 6: CI Matrix
| Job | Triggers | Gate | Config |
|-----|----------|------|--------|
| ... | ... | ... | ... |
### Layer 7: Evidence Workflow
| Artifact | Location | Triggers | Format |
|----------|----------|----------|--------|
| ... | ... | ... | ... |
### Layer 8: Operator Surface
| Surface | Location | Purpose | Usage |
|---------|----------|---------|-------|
| ... | ... | ... | ... |
## Command Chain
Ordered list of checks as executed by the canonical entry point:
1. ...
2. ...
3. ...
## Quick Reference
- **Run all local checks:** `...`
- **Run CI locally:** `...`
- **Add a new check:** ...
## Source Index
| File | What It Contributes |
|------|-------------------|
| `path:line-line` | ... |
Output Requirements
Write the harness map to HARNESS.md in the repository root. This file must:
- identify the single best local entrypoint if one exists
- show where each layer is enforced
- distinguish between enforced config and descriptive docs
- include exact file paths
- include line numbers when they materially improve traceability
- describe what exists before suggesting changes
- use tables for scannable layer summaries
- include a quick reference section for operators
Good Output Example
# myrepo – Harness Map
## Canonical Entry Point
- `justfile:22-29` defines `check *args:` and runs Ruff, Import Linter, ty, docs checks, ast-grep, pytest, and Zig checks.
## Harness Layers
### Layer 2: Architecture Boundaries
| Contract | Source | Forbidden | Config |
|----------|--------|-----------|--------|
| core-api | src/core | src/plugins | pyproject.toml:80-110 |
### Layer 6: CI Matrix
| Job | Triggers | Gate | Config |
|-----|----------|------|--------|
| test | push | all checks | .github/workflows/ci.yml:13-79 |
Bad Output Example
The repo appears to care about quality and uses several tools.
It has some tests and some linting.
Handoff
After generating HARNESS.md:
- commit it to the repo so it stays current
- use
plan-phase if the user wants to add or improve a harness layer
- compare two repos'
HARNESS.md files to understand their differences
1---2name: harness-map-33description: "Map a repository's mechanical harness layers: canonical check command, local and CI gates, architecture boundaries, structural rules, behavioral verification, docs ratchets, evidence workflows, and operator-facing surfaces. Use when you need to understand how a repo keeps change safe."4writes-to: HARNESS.md5allowed-tools:6 - Read7 - Write8 - Edit9 - Bash(find:*)10 - Bash(rg:*)11 - Bash(grep:*)12 - Bash(git:*)13hard-guards:14 - Facts first - identify what exists before making recommendations15 - Include exact file paths and line anchors when applicable16 - Do not modify source code while mapping the harness unless explicitly asked17 - Distinguish local gates, CI gates, policy layers, evidence layers, and operator surfaces18metadata:19 source: https://skillmd.com/skills/alchemiststudiosdotai/harness-map-320---2122# Harness Map2324Map the repository's **actual harness**: the mechanical checks, policies, workflows, and artifacts that make change safe.2526This skill is narrower than generic codebase research. It is specifically for answering questions like:2728- "What is the harness in this repo?"29- "What does `check` actually run?"30- "Which layers are local vs CI vs docs vs evidence?"31- "How is architecture enforced here?"32- "What operator surfaces teach agents how to use the harness?"3334## Core Principle3536**Map the harness as implemented, not as imagined.**3738Prefer:39- commands that actually run40- config files that actually enforce policy41- CI workflows that actually gate merges42- docs and playbooks that actually structure investigations43- agent/operator files that actually expose the workflow4445Avoid:46- aspirational architecture prose without enforcement47- recommendations before the map exists48- broad codebase summaries that skip the gate structure4950## What Counts as Harness5152A repo harness usually includes some or all of these layers:53541. **Canonical local command**55 - `just check`, `make check`, `task check`, `npm test`, etc.562. **Architecture boundaries**57 - Import Linter, dependency-cruiser, Bazel visibility, custom dependency tests583. **Structural rules**59 - ast-grep, semgrep, custom lint rules, codemod rule tests604. **Behavioral verification**61 - unit/integration tests, snapshots, goldens, deterministic checks, build verification625. **Docs ratchets**63 - docs link checks, nav checks, metadata/frontmatter checks, allowlists646. **CI decomposition**65 - matrix jobs or separate workflows that mirror harness gates667. **Evidence workflows**67 - session logs, diff reports, chunk docs, experiment records, replay/debug artifacts688. **Operator surface**69 - `AGENTS.md`, `.codex/`, environment files, repo-local skills, slash commands7071## When to Use7273Use this skill when the user asks to:7475- map or explain the harness76- identify all gate layers in a repo77- compare local checks with CI checks78- document how architectural constraints are enforced79- understand how agents/operators are expected to use the repo safely8081## Workflow8283### 1. Find the canonical local entrypoint8485Inspect common entrypoint files first:8687- `justfile`88- `Makefile`89- `package.json`90- `pyproject.toml`91- task runner config files9293Capture:94- the canonical command name95- every subcommand it runs96- whether it chains all gates or only a subset9798### 2. Find CI gate execution99100Inspect CI workflows:101102- `.github/workflows/*.yml`103- other CI configs (`.gitlab-ci.yml`, `buildkite`, etc.)104105Capture:106- job names107- matrix dimensions108- whether `fail-fast` is enabled109- which local gates are mirrored in CI110- which gates only exist in CI111112### 3. Find architecture enforcement113114Look for:115116- Import Linter / grimp117- dependency-cruiser118- layering tests119- package-boundary configs120- forbidden import tests121122Capture:123- contract names124- source and forbidden modules125- ignore lists / allowed exceptions126- exact config path127128### 4. Find structural rule enforcement129130Look for:131132- `sgconfig.yml`, ast-grep rule directories133- semgrep configs134- custom lint rule packages135- rule tests and snapshots136137Capture:138- rule config files139- rule directories140- test directories141- snapshot/baseline locations142- any custom parser or language extensions143144### 5. Find behavioral verification layers145146Look for:147148- test commands149- snapshot directories150- golden outputs151- deterministic helpers152- numerical equivalence docs153- build verification steps154155Capture:156- exact commands157- test conventions docs158- locations of snapshots/goldens159- special validation steps outside the main test runner160161### 6. Find docs ratchets162163Look for:164165- docs check scripts166- nav validation167- broken-link validation168- frontmatter/tag checks169- allowlists / baselines170171Capture:172- categories of docs failures173- allowlist file paths174- whether the check behaves as a ratchet175176### 7. Find evidence workflows177178Look for:179180- chunk docs181- debugging session logs182- replay/trace diff playbooks183- benchmark result docs184- evidence indexes185186Capture:187- index files188- per-session or per-chunk docs189- required evidence fields190- exact commands recorded in those artifacts191192### 8. Find operator-facing surfaces193194Look for:195196- `AGENTS.md`197- `.codex/environments/*`198- `.codex/skills/*`199- command docs200- plugin manifests201202Capture:203- setup / run / test actions204- repo-local skills that wrap harness flows205- operator instructions that point to real commands206207### 9. Synthesize the harness map208209Write the harness map directly to the repository root as:210211`HARNESS.md`212213This file serves as the single source of truth for how this repository keeps change safe. Write it in a style that a new developer or agent can use to understand the harness immediately.214215Recommended structure:216217```markdown218---219title: "<repo> – Harness Map"220phase: Research221date: "YYYY-MM-DD HH:MM:SS"222owner: "<agent_or_user>"223tags: [research, harness, <repo>]224---225226# <repo> – Harness Map227228A living map of the mechanical checks, policies, workflows, and artifacts that make change safe in this repository.229230## Canonical Entry Point231- `path:line-line` → command and subcommands232233## Harness Layers234235### Layer 1: Local Checks236| Check | Command | Config | Enforces |237|-------|---------|--------|----------|238| ... | ... | ... | ... |239240### Layer 2: Architecture Boundaries241| Contract | Source | Forbidden | Config |242|----------|--------|-----------|--------|243| ... | ... | ... | ... |244245### Layer 3: Structural Rules246| Rule Set | Config | Test Location | Notes |247|----------|--------|---------------|-------|248| ... | ... | ... | ... |249250### Layer 4: Behavioral Verification251| Test Suite | Command | Snapshot/Golden Location | Notes |252|------------|---------|--------------------------|-------|253| ... | ... | ... | ... |254255### Layer 5: Docs Ratchet256| Check | Command | Allowlist | Notes |257|-------|---------|-----------|-------|258| ... | ... | ... | ... |259260### Layer 6: CI Matrix261| Job | Triggers | Gate | Config |262|-----|----------|------|--------|263| ... | ... | ... | ... |264265### Layer 7: Evidence Workflow266| Artifact | Location | Triggers | Format |267|----------|----------|----------|--------|268| ... | ... | ... | ... |269270### Layer 8: Operator Surface271| Surface | Location | Purpose | Usage |272|---------|----------|---------|-------|273| ... | ... | ... | ... |274275## Command Chain276Ordered list of checks as executed by the canonical entry point:2771. ...2782. ...2793. ...280281## Quick Reference282- **Run all local checks:** `...`283- **Run CI locally:** `...`284- **Add a new check:** ...285286## Source Index287| File | What It Contributes |288|------|-------------------|289| `path:line-line` | ... |290```291292## Output Requirements293294Write the harness map to `HARNESS.md` in the repository root. This file must:295296- identify the **single best local entrypoint** if one exists297- show where each layer is enforced298- distinguish between **enforced config** and **descriptive docs**299- include exact file paths300- include line numbers when they materially improve traceability301- describe what exists before suggesting changes302- use tables for scannable layer summaries303- include a quick reference section for operators304305## Good Output Example306307```markdown308# myrepo – Harness Map309310## Canonical Entry Point311- `justfile:22-29` defines `check *args:` and runs Ruff, Import Linter, ty, docs checks, ast-grep, pytest, and Zig checks.312313## Harness Layers314315### Layer 2: Architecture Boundaries316| Contract | Source | Forbidden | Config |317|----------|--------|-----------|--------|318| core-api | src/core | src/plugins | pyproject.toml:80-110 |319320### Layer 6: CI Matrix321| Job | Triggers | Gate | Config |322|-----|----------|------|--------|323| test | push | all checks | .github/workflows/ci.yml:13-79 |324```325326## Bad Output Example327328```markdown329The repo appears to care about quality and uses several tools.330It has some tests and some linting.331```332333## Handoff334335After generating `HARNESS.md`:336337- commit it to the repo so it stays current338- use `plan-phase` if the user wants to add or improve a harness layer339- compare two repos' `HARNESS.md` files to understand their differences