alchemiststudiosdotai/harness-map

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:

1. Canonical local command
   • just check, make check, task check, npm test, etc.
2. Architecture boundaries
   • Import Linter, dependency-cruiser, Bazel visibility, custom dependency tests
3. Structural rules
   • ast-grep, semgrep, custom lint rules, codemod rule tests
4. Behavioral verification
   • unit/integration tests, snapshots, goldens, deterministic checks, build verification
5. Docs ratchets
   • docs link checks, nav checks, metadata/frontmatter checks, allowlists
6. CI decomposition
   • matrix jobs or separate workflows that mirror harness gates
7. Evidence workflows
   • session logs, diff reports, chunk docs, experiment records, replay/debug artifacts
8. 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 a research artifact to:

memory-bank/research/YYYY-MM-DD_HH-MM-SS_<repo>-harness-map.md

Recommended structure:

---
title: "<repo> – Harness Map"
phase: Research
date: "YYYY-MM-DD HH:MM:SS"
owner: "<agent_or_user>"
tags: [research, harness, <repo>]
---

## Canonical Entry Point
- `path:line-line` → command and subcommands

## Harness Layers
### Layer 1: Local checks
### Layer 2: Architecture boundaries
### Layer 3: Structural rules
### Layer 4: Behavioral verification
### Layer 5: Docs ratchet
### Layer 6: CI matrix
### Layer 7: Evidence workflow
### Layer 8: Operator surface

## Source Index
- `path:line-line` → what this file contributes

## Observed Command Chain
- ordered list of checks from the main command

Output Requirements

Your harness map 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

Good Output Example

## Canonical Entry Point
- `justfile:22-29` defines `check *args:` and runs Ruff, Import Linter, ty, docs checks, ast-grep, pytest, and Zig checks.

## Layer 2: Architecture Boundaries
- `pyproject.toml:80-110` defines four Import Linter forbidden contracts.

## Layer 6: CI Matrix
- `.github/workflows/ci.yml:13-79` runs seven matrix tasks with `fail-fast: false`.

Bad Output Example

The repo appears to care about quality and uses several tools.
It has some tests and some linting.

Handoff

Common next steps after this skill:

• generate a condensed harness summary for operators
• compare two repos' harnesses
• use plan-phase if the user wants to add or improve a harness layer