repo-harness-assessment

Repo Harness Assessment

Overview

Assess how well a repository lets an agent find its rules, make safe changes, verify them, and produce reviewable evidence.

This is the default router for existing repositories. It also owns agent-entrypoint design because entrypoints are the navigation layer of the assessment, not a separate harness system. For shared vocabulary and neutral artifact names, see ../../references/harness-patterns.md; when expected harness files are missing, use references/build-when-missing.md; for canonical entrypoints, mirrors, and drift prevention, use references/entrypoint-policy.md.

When To Use

• The user asks what harness pieces a repository is missing.
• The user wants to create, shrink, reconcile, or diagnose AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, or GitHub instructions.
• You need to compare entrypoints, validation commands, runtime evidence, delivery records, or quality gates across repositories.
• You need to decide whether the next smallest improvement is an entrypoint, validation script, artifact bundle, ledger, contract check, or quality gate.

Inputs Needed

• Repository root path.
• User scope: whole repository, one surface, docs-only work, runtime behavior, CI, or delivery flow.
• Any expected harness shape or maturity target the user names.
• Existing agent instruction files and whether mirrors, generation, or subtree overrides are required.

Execution Order

• First: Read repository entrypoints and source-of-truth files, including agent instructions, README, architecture or reliability docs, indexes, CI, and scripts.
• Then: Map existing surfaces to harness roles and check entrypoint precedence, mirrors, validation, evidence, work state, delivery, contracts, and quality.
• Finally: Report maturity, entrypoint actions, the smallest useful improvement slice, and what not to build yet.

Step-by-Step Process

1. Use rg --files or find to list agent instruction files, docs, scripts, CI, work-state surfaces, ledgers, reports, and runtime artifacts.
2. Identify one canonical entrypoint and classify every other agent instruction file as a subtree override, symlink, generated mirror, or short pointer.
3. Keep the root entrypoint to scope, source-of-truth navigation, hard boundaries, and minimum commands; move detailed procedures to linked docs.
4. Map current artifacts to entrypoint, work-state, ledger, contracts, validation, runtime-evidence, and quality roles before proposing new files.
5. Check for a stable validation matrix and whether failures connect to run IDs, request IDs, logs, screenshots, JSON/JUnit output, reviews, or commits.
6. If a required role is absent, define the minimum bootstrap artifact from references/build-when-missing.md; do not scaffold optional roles by default.
7. Add a mirror or pointer drift check when multiple agent instruction surfaces must stay aligned.
8. Compress gaps into no more than three next steps, ordered by value and risk.

Checks

• Entrypoint: an agent can find first-read docs, edit boundaries, and the minimum validation command within one minute.
• Consistency: mirrors cannot silently drift, and instruction precedence is explicit.
• Structure: there is a clear source of truth, directory boundary model, and no-new-drift rule.
• Validation: there is one local minimum command and one CI gate command.
• Evidence: a failure can be connected to logs, traces, screenshots, or runtime artifacts.
• Overbuild: do not recommend a full platform, broad scaffold, or cross-environment deployment system before the minimum slice is justified.

Output Format

# Repo Harness Assessment

## Detected Mapping
- entrypoint:
- mirrors / subtree overrides:
- work-state:
- ledger:
- contracts:
- validation:
- runtime-evidence:
- quality:

## Entrypoint Decision
- canonical file:
- navigation changes:
- drift prevention:

## Current State
- Agent entrypoint:
- Source-of-truth docs:
- Validation surface:
- Runtime evidence:
- Delivery/ledger:

## Gaps
1.
2.
3.

## Recommended Minimum Slice
- First:
- Then:
- Finally:

## Do Not Build Yet
-

## Validation Needed
-

Common Mistakes

• Reducing harness maturity to "there are tests."
• Reading only README while ignoring scripts, CI, and real artifacts.
• Copying rules into every agent-specific file instead of choosing one canonical source.
• Turning the root entrypoint into a project encyclopedia.
• Copying environment variables, ports, accounts, or private workflow details from one implementation into another.
• Producing a long wish list instead of a small, implementable improvement slice.

Example Prompts

• "Assess what harness pieces this repository is missing."
• "Reconcile AGENTS.md, CLAUDE.md, and GEMINI.md without duplicating rules."
• "Compare this repository against a mature run-artifact pattern."
• "Can an agent safely take over this project as it stands?"