---
framework: Agentic Engineering Maturity — Factory Edition
version: 2026.06.0
kind: companion-guide
lens: team
title: Team / Project Checklist — Companion Guide
---

# Team / Project Checklist — Companion Guide

**Version `2026.06.0`**

Every item in the checklist, explained — in the same order and wording. Each entry gives the *why*, *what good looks like*, *how to check*, and the *evidence* to look for.

**How to read each entry**

- **Stage · Tags · Concept** — the maturity stage, theme tags, and the 2026 idea it draws on.
- **Why now** — what changed that makes this a team-level standard.
- **What good looks like** — the standard holding in practice.
- **How to check** — an assessor's quick probe.
- **Failure modes** — how the box goes green while the standard stays hollow.
- **Evidence** — the repo file, config, dashboard, or PR trail that proves it.

---

## 1. Intent & Specification

### A spec / intent doc precedes non-trivial implementation and lives in the repo or tracker, not a chat thread
`S2` · `intent` `spec` · **Concept:** Factory Model / Intent Debt

**Why now.** The spec is the leverage when work fans out across agents; ambiguity multiplies. A spec stuck in a chat thread can't anchor review or survive the session.
**What good looks like.** Non-trivial work links to a spec that predates its implementation commits.
**How to check.** Sample recent features — does a spec exist, and is it dated before the code?
**Failure modes.** Specs reconstructed after the fact; intent living only in Slack.
**Evidence.** `docs/specs/`, linked tickets, or PR descriptions referencing a spec.

### A shared spec template captures goals, constraints, non-goals, edge cases, and a checkable definition of done
`S2` · `spec` `template` · **Concept:** Spec-Driven Development

**Why now.** Templates make consistent, evaluable specs the path of least resistance for both humans and agents.
**What good looks like.** A template exists and recent specs use it without blank required sections.
**How to check.** Open the template; open two recent specs — do they follow it?
**Failure modes.** A template that exists but is an empty shell; everyone freestyles.
**Evidence.** `templates/spec.md`, `.github/` issue/PR templates.

### Decision logs / ADRs are standard and captured at decision time — the *why* is a first-class artifact
`S3` · `intent` `decision-log` · **Concept:** Intent Debt

**Why now.** Capturing *why* at decision time is nearly free; reconstructing it later is a fortune, and agents fabricate plausible wrong reasons.
**What good looks like.** Consequential choices leave an ADR; the habit is routine, not heroic.
**How to check.** List ADRs from the last quarter — do they track real recent decisions?
**Failure modes.** ADRs that stopped a year ago; rationale only in people's heads.
**Evidence.** `docs/adr/` with recent entries; ADRs linked from PRs.

### `AGENTS.md` is the team's intent ledger (conventions, boundaries, "we don't do X because…"), not an autogenerated file
`S3` · `intent` `harness` · **Concept:** Intent Debt / Harness Engineering

**Why now.** Agents start cold every session and can't infer team meaning; an autogenerated file describes the code, not the intent.
**What good looks like.** `AGENTS.md` carries conventions and hard-won "don't, because…" notes.
**How to check.** Does it contain anything `/init` couldn't have generated?
**Failure modes.** A generated file nobody curates.
**Evidence.** `/AGENTS.md` git history showing human-authored, rationale-bearing edits.

### The definition of done is explicit and shared beyond "functionally correct" — the quality bar (perf / a11y / security) is named
`S3` · `spec` `quality` · **Concept:** Spec-Driven Development

**Why now.** Agents hit "it functions" and stop; unnamed qualities regress silently across the fleet.
**What good looks like.** A shared definition of done that names the non-negotiables.
**How to check.** Find the team's DoD — does it go past "works"?
**Failure modes.** A DoD that's just "tests pass."
**Evidence.** DoD in contributing guide / `AGENTS.md` / definition-of-done doc.

### The team treats intent debt as real: load-bearing rationale is externalized so agents don't guess it
`S4` · `intent` `compounding` · **Concept:** Intent Debt

**Why now.** Un-externalized intent used to cost once at onboarding; now you pay it every session times every agent.
**What good looks like.** The team consciously writes down the load-bearing "why," and notices when it's missing.
**How to check.** Ask why a non-obvious design exists — is the answer findable, or only "an agent suggested it"?
**Failure modes.** Guard clauses deleted because no one recorded why they were there.
**Evidence.** Decision logs + `AGENTS.md` + specs that capture rationale, used in review.

---

## 2. Context, Memory & Harness

### A root-level `AGENTS.md` is the canonical place agents learn the repo's conventions, the lines they must not cross, and how to build and test
`S2` · `harness` `context` · **Concept:** Harness Engineering

**Why now.** It lands in the prompt every turn — the highest-leverage configuration point in the repo.
**What good looks like.** A root `AGENTS.md` with build/test commands, key paths, boundaries, and review expectations, linked from the README.
**How to check.** Open it; confirm sections match the actual repo layout.
**Failure modes.** Stale references to removed scripts; long prose with no actionable rules.
**Evidence.** `/AGENTS.md`; README "for AI assistants" link.

### The README and docs are AI-consumable — key paths, commands, and architecture an agent can navigate without guessing
`S2` · `context` · **Concept:** Factory Model (onboarding parallel)

**Why now.** Agents work like new hires reading the docs and history; if a new engineer would be lost, so is the agent.
**What good looks like.** A fresh clone can run build/test from the README; key directories are explained.
**How to check.** Follow only the README on a clean checkout — does it work?
**Failure modes.** Broken commands; badges and install steps but no architecture.
**Evidence.** `/README.md` with Development and Project-structure sections.

### Architecture and domain knowledge live in machine-readable artifacts an agent can cite — decision records, specs, a glossary, and schema / API definitions
`S2` · `context` · **Concept:** Harness Engineering (memory/search)

**Why now.** Agents (and humans) cite structured docs; tacit-only knowledge can't be retrieved.
**What good looks like.** Current ADRs, an architecture overview, a glossary, and schema/API docs agents reference.
**How to check.** Spot-check glossary terms in code; confirm ADRs match current design.
**Failure modes.** Wiki-only docs agents can't reach; ADRs that contradict the code.
**Evidence.** `docs/architecture/`, `docs/adr/`, OpenAPI/schema files.

### The harness is a real, owned artifact — prompts, tools, hooks, and context policies are versioned and improved, not left to each dev
`S3` · `harness` · **Concept:** Harness Engineering

**Why now.** Behavior you experience is dominated by the harness, not the model; leaving it to each dev means inconsistent, un-improvable results.
**What good looks like.** Shared, version-controlled harness config with named owners.
**How to check.** Is there a repo-level home for prompts/tools/hooks, with review history?
**Failure modes.** Every dev's private setup; no one owns the scaffolding.
**Evidence.** `.claude/` or equivalent config in git; PRs improving the harness.

### Each recurring kind of work — new feature, fix, refactor, data migration — has a ready-made context bundle or rule set the agent loads
`S3` · `context` `harness` · **Concept:** Loop Engineering (skills)

**Why now.** Re-assembling context from scratch each task is the loop re-deriving your project from zero every time.
**What good looks like.** Reusable rules/skills per task type, discoverable and used.
**How to check.** Find the rules; confirm recent PRs used them.
**Failure modes.** One giant rule that tries to do everything; rules nobody invokes.
**Evidence.** `skills/`, `.cursor/rules`, or task-type rule files.

### Long-running work has a memory standard — state files, progress logs, hand-off briefs — so agents survive context resets
`S3` · `harness` `memory` · **Concept:** Self-Improving Loops

**Why now.** Models forget between runs; durable memory on disk is what makes multi-session work coherent.
**What good looks like.** A convention for state/progress files and structured hand-offs.
**How to check.** Could a long task resume from files after a full context reset?
**Failure modes.** Context trapped in one chat; no resumable state.
**Evidence.** `tasks.json` / progress logs / hand-off docs in active use.

### Team knowledge (past PRs, incidents, decisions) is indexed so people and agents can retrieve it
`S3` · `context` `knowledge` · **Concept:** Factory Model (git as knowledge graph)

**Why now.** Git history and incident records are becoming the knowledge graph agents navigate to understand "why."
**What good looks like.** Search/RAG or curated indexes over PRs, incidents, and decisions.
**How to check.** Try to retrieve the reasoning behind a past incident — how hard is it?
**Failure modes.** Knowledge scattered across tools with no retrieval path.
**Evidence.** A search index, curated docs, or RAG over team history.

---

## 3. Loops, Autonomy & Orchestration

### Every workflow is assigned an autonomy tier from suggest-only up to auto-merge, and the riskier the work the tighter the tier
`S2` · `autonomy` · **Concept:** Agentic Code Review (blast radius)

**Why now.** A single autonomy setting is wrong somewhere; risk should set the dial.
**What good looks like.** A documented map of workflow → autonomy level, with shared vocabulary.
**How to check.** Find the doc; confirm risky workflows run at lower autonomy.
**Failure modes.** Max autonomy on prod-DB work; a doc nobody follows.
**Evidence.** Autonomy section in `AGENTS.md` / workflow docs.

### The exact conditions that force an agent or loop to halt and hand back to a human are written down
`S3` · `autonomy` `loop` · **Concept:** Self-Improving Loops

**Why now.** Unattended loops need defined exits or they make mistakes unattended.
**What good looks like.** Written stop conditions and escalation triggers per workflow.
**How to check.** Can the team state when a loop must stop and ask?
**Failure modes.** Open-ended "keep going" with no escalation path.
**Evidence.** Escalation/stop-condition docs; hook configs enforcing them.

### The team uses loop primitives deliberately — scheduled automations, worktree isolation, sub-agents, connectors, a state file — not ad hoc scripts
`S4` · `loop` · **Concept:** Loop Engineering

**Why now.** The leverage moved from prompting to loop design; the five primitives plus memory are the durable shape.
**What good looks like.** Recurring work runs as designed loops using the standard primitives.
**How to check.** Point to a loop the team designed once and reuses.
**Failure modes.** A pile of bespoke bash nobody maintains.
**Evidence.** Automations/cron configs, worktree usage, sub-agent definitions, a state file.

### Maker/checker separation is standard for non-trivial work: generation and evaluation are different agents or stages
`S3` · `loop` `verification` · **Concept:** Harness Engineering (planner/generator/evaluator)

**Why now.** Agents skew positive grading their own work; separation makes "done" trustworthy.
**What good looks like.** A distinct verifier agent/stage with its own instructions, sometimes a different model.
**How to check.** On a recent task, was the checker different from the maker?
**Failure modes.** The author agent certifying itself.
**Evidence.** Sub-agent/reviewer definitions; `/goal`-style verified stop conditions.

### Autonomous and cloud agents run under explicit rules: who may start one, the blast radius it's allowed, and how its results return for review
`S3` · `autonomy` `governance` · **Concept:** Loop Engineering / Factory Model

**Why now.** A growing share of merged PRs originate from autonomous cloud agents; ungoverned, they're a blast-radius problem.
**What good looks like.** Clear rules on who launches them, their scope, and how results surface.
**How to check.** Ask who can launch a background agent against this repo and what it can reach.
**Failure modes.** Anyone running cloud agents with prod access, reporting nowhere.
**Evidence.** Governance doc; sandbox/permission configs for background agents.

### Parallel-execution patterns (worktrees, best-of-N) are documented and scaled to the team's *review* capacity, not the tool's spawn limit
`S3` · `orchestration-tax` `loop` · **Concept:** The Orchestration Tax

**Why now.** Worktrees remove collisions, but review bandwidth is the true ceiling; throughput equals review throughput.
**What good looks like.** Patterns documented, with fleet size bounded by reviewable output (backpressure).
**How to check.** Is there guidance that ties agent count to review capacity?
**Failure modes.** Encouraging "run 20 agents" with no review plan.
**Evidence.** Worktree/parallel docs; review-capacity guidance.

### Overnight / self-improving loops, where used, have guardrails: feature branches, read-only auto-approve, sandboxes, stop conditions, human PR at the end
`S4` · `loop` `safety` · **Concept:** Self-Improving Loops

**Why now.** Loops with commit and shell access are powerful and risky; guardrails are what make "ship while you sleep" safe.
**What good looks like.** Loops run on branches, auto-approve only read-only ops, sandboxed, capped, ending in a human PR.
**How to check.** Inspect one loop's config — are all five guardrails present?
**Failure modes.** Autonomous loops on `main` with `--dangerously-allow-all`.
**Evidence.** Loop scripts/config showing branch, permission, sandbox, and stop settings.

---

## 4. Verification & Review

### Review depth is tiered by blast radius, not by author — risk tiers and their required gates are written down
`S2` · `review` `blast-radius` · **Concept:** Agentic Code Review

**Why now.** Reviewing everything to one depth wastes scarce attention; match effort to the cost of being wrong.
**What good looks like.** Documented risk tiers (config vs. payments) with required gates per tier.
**How to check.** Find the tiering; confirm a high-risk PR cleared more gates than a low-risk one.
**Failure modes.** Same shallow review everywhere; tier by who wrote it.
**Evidence.** Review policy / CODEOWNERS / risk-label workflow.

### AI-generated code clears the same review bar as human code, with a human owning the merge on load-bearing paths
`S2` · `review` `accountability` · **Concept:** Human-on-the-loop

**Why now.** A model can't be paged; accountability stays with whoever merges.
**What good looks like.** Same bar regardless of author; a named human owns load-bearing merges.
**How to check.** Read AI-heavy PRs — same scrutiny as human ones?
**Failure modes.** Lower bar for "it's just AI output"; auto-merge on green.
**Evidence.** Branch protection requiring human approval on protected paths.

### The team runs *heterogeneous* AI reviewers on high-risk PRs — two built differently, not two copies of one
`S3` · `review` `heterogeneous` · **Concept:** Agentic Code Review (heterogeneity)

**Why now.** Reviewers built differently overlap remarkably little; heterogeneity surfaces bugs no single one finds.
**What good looks like.** High-risk PRs get two deliberately different reviewers; results measured on your own code.
**How to check.** Which reviewers run on high-risk PRs, and how different are they?
**Failure modes.** Two instances of one model agreeing in the same blind spots.
**Evidence.** CI config showing 2+ distinct review tools on protected paths.

### An intake bar is enforced: PRs arrive with stated intent, a readable / small diff, and evidence the tests ran — or they bounce
`S3` · `review` `intake` · **Concept:** Agentic Code Review (intake bar)

**Why now.** Without an intake bar, reviewers absorb the expensive intent-reconstruction; with one, it's pushed back to the submitter.
**What good looks like.** PRs missing intent/test-evidence are returned, not reviewed.
**How to check.** Do recent PRs carry purpose + test output? Are any sent back for lacking it?
**Failure modes.** 3,500-line diffs with no description getting full review anyway.
**Evidence.** PR template requiring intent + test output; bounce comments in history.

### Review explicitly checks the test diff for assertions weakened or rewritten to match changed behavior
`S3` · `review` `testing` · **Concept:** Agentic Code Review

**Why now.** Agents "fix" tests by rewriting assertions to match broken behavior — a green check that means nothing.
**What good looks like.** Test diffs are read first on behavior changes; weakened assertions are flagged.
**How to check.** On a recent PR that changed many tests, was each edit verified as correct?
**Failure modes.** Trusting "200 tests updated, all green."
**Evidence.** Review checklist line on test-diff scrutiny; review comments catching it.

### A fast-fail / triage step routes trivial agent PRs to a light path and flags high-maintenance ones before a human invests time
`S4` · `review` `metrics` · **Concept:** Agentic Code Review (circuit breaker)

**Why now.** Agents nail small changes (~28% merge fast) but "ghost" on subjective feedback; predicting high-effort PRs from cheap signals saves hours.
**What good looks like.** A triage step fast-tracks the trivial and flags the sprawling before deep review.
**How to check.** Is there any pre-review triage on agent PRs?
**Failure modes.** A human sinking an hour into a PR the agent will abandon.
**Evidence.** Triage automation / labels by patch size and file type.

### Agents are instructed to keep PRs small; oversized unreviewable diffs are sent back, not rubber-stamped
`S2` · `review` `quality` · **Concept:** Agentic Code Review

**Why now.** Agent PRs run ~51% larger; large diffs get rejected or rubber-stamped. The unit of review is the unit of comprehension.
**What good looks like.** Small-commit instructions are standard; big diffs are split.
**How to check.** Size distribution of recent agent PRs.
**Failure modes.** One mega-diff per feature.
**Evidence.** `AGENTS.md` small-PR rule; PR size metrics.

### The review checklist names AI-specific risks (hallucinated imports, shallow tests, duplication, untrusted input flowing into a prompt)
`S2` · `review` `quality` · **Concept:** Agentic Code Review

**Why now.** AI changes carry predictable, locatable weaknesses; a review can aim straight at them.
**What good looks like.** The checklist explicitly lists AI failure modes, including prompt-injection surfaces.
**How to check.** Read the review checklist — are AI-specific risks named?
**Failure modes.** A generic checklist that ignores how AI code fails.
**Evidence.** Review checklist / PR template enumerating AI risks.

---

## 5. Tests & Deterministic Gates

### Tests are part of the AI-assisted workflow from the start; coverage expectations apply equally to AI-written code
`S2` · `testing` · **Concept:** Factory Model

**Why now.** A test-first suite is the most effective lever for keeping autonomous output correct as the codebase grows.
**What good looks like.** AI PRs include tests in the same merge; coverage rules don't exempt AI code.
**How to check.** Sample five AI PRs — tests changed in the same PR?
**Failure modes.** "Tests later" tickets; coverage waived for AI changes.
**Evidence.** PRs with paired test changes; coverage policy applied uniformly.

### Red/green TDD is the norm for non-trivial logic — tests written and seen to fail before implementation
`S3` · `testing` `tdd` · **Concept:** Red/Green TDD

**Why now.** With a fleet optimizing for "tests pass," test-after means tests confirm what the code happens to do, not what it should.
**What good looks like.** Red-before-green is expected and visible on non-trivial work.
**How to check.** Can the team show a recent red→green sequence?
**Failure modes.** Tests authored to fit finished code.
**Evidence.** Commit history showing failing tests before implementation; TDD note in `AGENTS.md`.

### CI is the immovable wall: lint, types, tests, security and dependency scans are required and cannot be skipped to go green
`S2` · `gates` `ci` · **Concept:** Agentic Code Review (CI as the wall)

**Why now.** Deterministic gates are the one part of the pipeline a confident paragraph can't talk out of its verdict.
**What good looks like.** Required, non-bypassable checks on every PR.
**How to check.** Open CI config + branch protection — are checks required and enforced?
**Failure modes.** Optional checks teams ignore; no dependency audit on AI bumps.
**Evidence.** `.github/workflows/*`, branch protection rules.

### The pipeline detects agents quietly lowering the bar — removed tests, skipped lint, dropped coverage thresholds
`S3` · `gates` `ci` · **Concept:** Agentic Code Review

**Why now.** Agents weaken CI to pass — not maliciously, just gradient descent toward green.
**What good looks like.** Removed tests, skipped lint, or lowered thresholds are flagged automatically.
**How to check.** Would a PR that deletes tests or lowers coverage get caught?
**Failure modes.** Coverage floors that only ratchet down.
**Evidence.** Coverage-delta gate; checks for `.skip(`/`xit(`/threshold edits.

### Mutation testing or equivalent guards the suite on critical paths where coverage alone misleads
`S4` · `testing` `quality` · **Concept:** Agentic Code Review

**Why now.** Coverage says a line ran; mutation testing says the test would notice if it were wrong.
**What good looks like.** Critical modules carry stronger-than-coverage guarantees.
**How to check.** On a key module, is there any mutation/fault-injection check?
**Failure modes.** Coverage percentage treated as proof.
**Evidence.** Mutation-testing config/report on critical paths.

### Verify-after-generate is required by the workflow and enforced by the review checklist
`S2` · `testing` `quality` · **Concept:** Verification Bottleneck

**Why now.** Generation is solved; the discipline is proving the output works before it's trusted.
**What good looks like.** The workflow requires evidence of verification and review enforces it.
**How to check.** Does the review checklist demand verification evidence?
**Failure modes.** "It looks done" as the exit criterion.
**Evidence.** Workflow doc + review checklist requiring verification.

---

## 6. Safety, Security & Guardrails

### Ignore files keep secrets and sensitive paths out of agent context by default
`S2` · `security` · **Concept:** Harness Engineering (safety)

**Why now.** Sensitive paths must never enter agent context; ignore files are the cheap, structural defense.
**What good looks like.** Ignore files list secrets, keys, env files, and private data; agents can't attach them.
**How to check.** Open the ignore files; try to attach an ignored path — it should warn/block.
**Failure modes.** Ignoring `.env` but not `.env.local` or `secrets/`.
**Evidence.** `.gitignore`, `.cursorignore`/tool ignore configs.

### A secrets-management policy is explicit *and technically enforced* — not just "don't paste secrets"
`S2` · `security` `governance` · **Concept:** Harness Engineering

**Why now.** Policy without technical blocks is a hope, not a control.
**What good looks like.** A written policy plus enforcement (ignore files, pre-commit secret scan, hooks).
**How to check.** Is there a block that stops a secret reaching an agent, or only a rule?
**Failure modes.** "We don't paste secrets" with nothing enforcing it.
**Evidence.** Secret-scanning hook/CI; documented policy.

### Tool / MCP permissions are scoped (never "allow all" for prod-adjacent work); credentials come from env, not hard-coding
`S2` · `security` `permissions` · **Concept:** Harness Engineering

**Why now.** Default-allow on prod-adjacent work turns one bad step into an incident.
**What good looks like.** Scoped permissions per project; env-sourced credentials.
**How to check.** Inspect the shared config — any "allow all" or hard-coded creds?
**Failure modes.** Global allow-all; tokens committed in config.
**Evidence.** `.mcp.json`/permission config with scoped servers and env vars.

### No MCP server or third-party tool is adopted until it clears a provenance-and-risk check — publisher, signature, reachable scope, dependency exposure — and it's version-pinned
`S3` · `security` `mcp` · **Concept:** Harness Engineering

**Why now.** Tool descriptions are trusted text in the prompt; a malicious MCP can prompt-inject before anyone types.
**What good looks like.** A vetting step and pinned versions/sources for every server.
**How to check.** Can the team account for every server in the shared config and how it was vetted?
**Failure modes.** Unpinned servers added on vibes.
**Evidence.** Vetting checklist/ADR; pinned `.mcp.json`.

### Destructive actions are denied at the system level whatever the agent intends — no force-push, production migration, bulk delete, or secret writes
`S3` · `security` `guardrails` · **Concept:** Harness Engineering (hooks)

**Why now.** Instructions aren't enforcement; hooks separate "I told it not to" from "the system won't allow it."
**What good looks like.** Destructive operations are blocked by hooks/policy, not prose.
**How to check.** Try (in a safe context) a blocked op — is it actually prevented?
**Failure modes.** Relying on `AGENTS.md` lines to prevent disasters.
**Evidence.** Pre-commit/pre-push/tool hooks blocking dangerous commands.

### Agent-executed code handling untrusted input runs in sandboxes; indirect prompt-injection defenses are in place
`S3` · `security` `sandbox` `injection` · **Concept:** Agentic Code Review / Harness Engineering

**Why now.** Agent features piping user text into a model are a fresh injection surface; the risk is latent in the data, not the diff.
**What good looks like.** Sandboxed execution for untrusted input; documented injection defenses (allowlists, human approval for irreversible ops).
**How to check.** Red-team one malicious-issue scenario — what stops it?
**Failure modes.** Agents acting on raw web/issue content outside a sandbox.
**Evidence.** Sandbox/ephemeral-env config; injection-defense section in security docs.

### Documented "what AI must NOT do" boundaries exist (never auto-merge to main, never touch billing / prod config) and are enforced
`S3` · `governance` `guardrails` · **Concept:** Factory Model (guardrails)

**Why now.** Clear, enforced "never" boundaries are how you keep autonomy from reaching load-bearing systems.
**What good looks like.** A written, enforced list of forbidden agent actions.
**How to check.** Find the list; confirm a technical control backs each "never."
**Failure modes.** Boundaries documented but not enforced.
**Evidence.** Boundary doc + branch protection / CODEOWNERS / hooks enforcing it.

### Enterprise / privacy / data-residency constraints are documented, enforced, and AI usage is auditable where compliance requires
`S3` · `governance` `security` · **Concept:** Comprehension Debt (regulation horizon)

**Why now.** As AI code reaches regulated systems, "the AI wrote it and we didn't review it" won't survive a post-incident report.
**What good looks like.** Documented, enforced constraints and an audit trail where required.
**How to check.** Can the team produce an audit trail of AI usage for a regulated path?
**Failure modes.** Undocumented data flows; no audit capability.
**Evidence.** Compliance doc; audit logs of AI usage.

---

## 7. Comprehension & Judgment

### The team treats comprehension as a real risk — it doesn't assume "reviewed" means "understood"
`S3` · `comprehension` · **Concept:** Comprehension Debt

**Why now.** Comprehension debt is invisible to velocity dashboards and shows up at the worst moment.
**What good looks like.** The team distinguishes "tests passed" from "a human understands this," and acts on the gap.
**How to check.** Ask whether anyone could rebuild a recently shipped subsystem from first principles.
**Failure modes.** Assuming approved code is understood code.
**Evidence.** Comprehension/ownership norms in engineering docs; deliberate readthroughs.

### The team calls out and pushes back on known bad habits — shipping without a spec, accepting output unread, recycling prompts blindly, rubber-stamping under deadline
`S2` · `comprehension` `surrender` · **Concept:** Cognitive Surrender

**Why now.** Naming the failure modes is the first defense; surrender feels identical to offloading from the inside.
**What good looks like.** Explicitly discouraged anti-patterns the team can point to.
**How to check.** Can engineers name the anti-patterns the team rejects?
**Failure modes.** Tolerating vibe-merges when the deadline looms.
**Evidence.** Anti-pattern list in `AGENTS.md`/engineering handbook.

### For load-bearing systems, at least one human keeps a current mental model — ownership of "why it's built this way" is explicit
`S3` · `comprehension` `intent` · **Concept:** Comprehension Debt / Intent Debt

**Why now.** As volume rises, the human who truly understands the system becomes the scarce resource the whole thing depends on.
**What good looks like.** Named owners hold a current model of load-bearing systems.
**How to check.** For a critical system, who can explain it from first principles today?
**Failure modes.** Everyone deferring to the agent; no human owner.
**Evidence.** Ownership map; design docs maintained by named owners.

### AI literacy is differentiated by role (driver vs. reviewer expectations), and onboarding teaches the agentic workflow
`S3` · `knowledge` `people` · **Concept:** Factory Model

**Why now.** Strong engineers get more leverage from these tools, not less; expectations should reflect role and seniority.
**What good looks like.** Differentiated expectations and an onboarding ramp for the agentic workflow.
**How to check.** Is there a defined ramp and role-based expectation?
**Failure modes.** Juniors auto-merging agent output; no onboarding for the workflow.
**Evidence.** Onboarding guide; role-based competency notes.

### Friction is designed in where it matters — a required spec, a confirm before merge, a checklist before deploy — to interrupt heuristic acceptance
`S3` · `surrender` `guardrails` · **Concept:** Cognitive Surrender (scaffolded friction)

**Why now.** Deliberate friction is exactly what stands between offloading and surrender.
**What good looks like.** Required pauses at the high-stakes steps, by design.
**How to check.** Are there mandatory checkpoints before risky merges/deploys?
**Failure modes.** Frictionless one-click paths on load-bearing changes.
**Evidence.** Required-review/spec gates; deploy checklist.

### The team values and makes time for the engineer who can tell a safe refactor from one quietly shifting behavior users depend on
`S4` · `comprehension` `compounding` · **Concept:** Comprehension Debt

**Why now.** That judgment is the scarce, appreciating asset as AI volume climbs.
**What good looks like.** Deep-understanding work is recognized and resourced, not just throughput.
**How to check.** Does calibration/recognition reward understanding, or only merged PRs?
**Failure modes.** Rewarding velocity while comprehension hollows out.
**Evidence.** Calibration criteria; time budgeted for architecture/readthrough.

---

## 8. Reusable Capability & the Ratchet

### A versioned, team-maintained library of skills, commands, and rules exists and covers the common task types
`S3` · `ratchet` `skills` · **Concept:** Loop Engineering (skills)

**Why now.** Skills are intent written once where every agent reads it, so the team stops re-explaining the project.
**What good looks like.** A maintained library covering the frequent task types.
**How to check.** Does the library exist, and is it used in recent work?
**Failure modes.** A few stale skills nobody updates.
**Evidence.** `skills/` directory with git activity.

### The ratchet is institutional — recurring agent mistakes become permanent guards (rules, hooks, reviewer checks), not repeat incidents
`S4` · `ratchet` · **Concept:** Harness Engineering (the ratchet)

**Why now.** Mistakes are signals; the ratchet turns each into a permanent fix so the system compounds.
**What good looks like.** Repeat failures vanish because they're closed off structurally.
**How to check.** Trace a recent guard back to the failure that prompted it.
**Failure modes.** The same class of bug recurring across PRs.
**Evidence.** Rules/hooks with commit messages linking to the incident.

### Skills, rules, and hooks are treated as code — reviewed in PRs, tested, and retired when models make them redundant
`S4` · `ratchet` `skills` · **Concept:** Harness Engineering

**Why now.** A harness is a living system; redundant constraints become noise that dilutes attention.
**What good looks like.** Scaffolding is reviewed, tested, and pruned over time.
**How to check.** When did the team last retire a rule a better model made redundant?
**Failure modes.** Endless accretion; dead scaffolding nobody removes.
**Evidence.** PRs reviewing/removing skills; eval results gating skill changes.

### Lifecycle hooks automate the repeatable (format, test, secret-scan, notify) with "silent success / verbose failure" discipline
`S3` · `harness` `hooks` · **Concept:** Harness Engineering (hooks)

**Why now.** Silent success / verbose failure makes feedback almost free in the common case and actionable when it isn't.
**What good looks like.** Hooks run the routine and stay quiet unless something fails.
**How to check.** Inspect hook config — quiet on success, specific on failure?
**Failure modes.** Noisy hooks that get muted; failures that never reach the agent.
**Evidence.** Hook definitions (pre/post-tool, pre-commit, on-completion).

### Lessons from real agent sessions are fed back into `AGENTS.md`, rules, and skills — the memory loop is closed, not write-once
`S4` · `ratchet` `compounding` · **Concept:** Self-Improving Loops / Intent Debt

**Why now.** Each recorded learning makes the next improvement easier — the compounding flywheel.
**What good looks like.** Session learnings flow back into shared artifacts routinely.
**How to check.** Does `AGENTS.md`/rules history show updates born from real sessions?
**Failure modes.** Learnings stuck in individuals' memories of bad afternoons.
**Evidence.** Commit trail updating rules/skills from incidents and sessions.

### Skills are shared across repos / teams (e.g. packaged as plugins) so the org compounds rather than each team rebuilding
`S4` · `knowledge` `compounding` · **Concept:** Loop Engineering (plugins)

**Why now.** A plugin is how a skill ships across repos; sharing is what turns local wins into org leverage.
**What good looks like.** Common capability is packaged and installed once, not rebuilt per team.
**How to check.** Is there a shared plugin/marketplace or a common skills repo in use?
**Failure modes.** Every team reinventing the same skills.
**Evidence.** Shared plugin/marketplace; cross-repo skill usage.

---

## 9. Measurement, Cost & Compounding

### A named owner publishes a regular readout of how well the AI tooling performs — suggestion-acceptance, revert / rework, time-to-merge, cycle time
`S3` · `metrics` · **Concept:** Verification Bottleneck

**Why now.** Raw output overstates value (~4× code, ~12% more value); effectiveness KPIs tell the real story.
**What good looks like.** A small KPI set, tracked on a cadence, with owners who act on it.
**How to check.** Find the dashboard and the owner; confirm a recent decision it drove.
**Failure modes.** Metrics with no owner, cadence, or consequence.
**Evidence.** Dashboard URL + cadence doc naming an owner.

### DORA-style metrics carry an AI-adoption dimension so quality regressions stay visible behind velocity
`S3` · `metrics` `quality` · **Concept:** Comprehension Debt (measurement gap)

**Why now.** Velocity dashboards look immaculate while churn, defects, and zero-review merges climb underneath.
**What good looks like.** DORA metrics sliced by AI adoption so regressions surface.
**How to check.** Can you see change-failure/churn against AI adoption over time?
**Failure modes.** Velocity up, quality regressions invisible.
**Evidence.** Metrics with an AI-adoption dimension.

### Changes to prompts, rules, and skills run against an eval set, and the pass rate is trended like any other quality signal
`S4` · `evals` · **Concept:** Self-Improving Loops

**Why now.** Skills and prompts are code; without evals they regress silently when changed.
**What good looks like.** An eval suite gates skill/prompt changes; pass rate is tracked.
**How to check.** Does changing a key skill run evals?
**Failure modes.** Tweaking rules and hoping.
**Evidence.** Eval suite + pass-rate trend.

### Every agent run leaves a replayable trail — the tool calls made, the choices taken, the model version — for debugging and audit
`S3` · `observability` · **Concept:** Harness Engineering (observability)

**Why now.** Failures often live in a wrong tool call mid-run, invisible in the final diff.
**What good looks like.** Traces capture tool calls, decisions, and model versions, and are replayable.
**How to check.** Pull the trace for a recent agent incident — is it there and useful?
**Failure modes.** Only final code retained; no run history.
**Evidence.** Tracing/observability tooling with retained agent runs.

### Token / cost is visible per team or project, with budgets, quotas, or alerts and a documented response
`S2` · `cost` `governance` · **Concept:** Loop Engineering (cost caution)

**Why now.** Loop and multi-agent usage varies wildly; cost visibility keeps the practice sustainable.
**What good looks like.** Live per-team/project cost, with budgets/alerts and a response procedure.
**How to check.** Find the cost dashboard and the alert/response doc.
**Failure modes.** No visibility until the bill arrives.
**Evidence.** Cost dashboard + budget/alert config.

### AI-attributable incidents are counted and reviewed; post-incident reviews ask "was this AI-related?"
`S3` · `metrics` `quality` · **Concept:** Comprehension Debt

**Why now.** You can't manage what you don't measure; AI-attributable failures need their own line.
**What good looks like.** Post-incident reviews include an AI-related analysis; counts are tracked.
**How to check.** Do recent postmortems ask the AI question?
**Failure modes.** AI-related incidents lost in the general pile.
**Evidence.** Postmortem template with an AI-related field; incident tags.

### AI authorship / provenance is attributed in commits or PRs, and license / IP policy for generated code is documented
`S2` · `governance` · **Concept:** Factory Model (provenance)

**Why now.** Provenance and IP for generated code are increasingly compliance requirements.
**What good looks like.** Attribution is verifiable from git; a license/IP policy exists.
**How to check.** Can you tell which commits are AI-assisted, and find the IP policy?
**Failure modes.** Silent AI authorship; no provenance rules.
**Evidence.** Commit/PR attribution convention; documented IP policy.

### The team can show the factory compounding — fewer repeat mistakes, rising eval pass rates, stable quality as volume grows
`S4` · `compounding` `metrics` · **Concept:** Self-Improving Loops / Factory Model

**Why now.** Maturity is the factory getting *better*, not just faster — quality holding (or rising) as output scales.
**What good looks like.** Trends show fewer repeat failures, rising eval pass rates, and steady quality at higher volume.
**How to check.** Pull the trends — is quality stable or improving as volume grows?
**Failure modes.** Volume up, quality quietly down — speed mistaken for maturity.
**Evidence.** Trend lines: repeat-incident rate, eval pass rate, quality vs. volume.

---

*62 entries — the companion guide to the Team / Project checklist.*