Harness Audit

Harness Audit

Audit a codebase against a baseline 8-artifact framework for how well-equipped it is for autonomous AI agents to do end-to-end implementation work. When asked for Symphony readiness, add the unattended ticket-execution overlay: workflow contract, disposable workspace bootstrap, validation/evidence, ticket lifecycle, observability, safety, and smoke-ticket eval. Optionally apply surgical fixes for the highest-leverage gaps.

Framework provenance: Ryan Lopopolo's "Harness Engineering" talk (OpenAI, AI Engineer London 2025). Core thesis: code is cheap; scarce resources are human time, attention, and model context window. Codebases that surface the right context to agents at the right time produce more shippable work per human hour.

Distinct from neighboring skills

• Repo architecture — structural design and repo organization. Use that for "how should this repo be laid out?"
• Adversarial review — hunts real bugs in working or near-complete implementations. Use that for "is this code correct?"
• Cold-start doc improvement — narrowly improves AGENTS.md / CLAUDE.md. This skill covers that plus seven more artifacts.
• This skill — asks: is this repo set up so agents can ship without a human babysitting every step?

Mode selection

Default mode is audit and is read-only.

Natural-language mapping:

• "harness audit", "agent-ready repo", "harness readiness", "make this repo agent-friendly" → audit
• "audit and fix", "fix harness gaps" → audit+fix
• "Symphony readiness", "prepare this repo for Symphony", "ticket-level agent automation", "unattended ticket execution" → symphony-readiness
• "fix Symphony readiness", "prepare and fix for Symphony" → audit+fix:symphony
• "focus on tests/pre-commit/rules/etc." → focus:<artifact-name>

Tie-breaker: default to baseline modes unless the user explicitly says Symphony, ticket-level orchestration, unattended execution, scheduler, tracker workflow, or workflow contract.

Accepted focus names: cold-start-brief, rules-dir, api-doc-policy, lint-messages, pre-commit, test-suite, pr-review, repo-skills, gc-cadence, workflow-contract, workspace-bootstrap, validate-loop, app-validation, evidence-protocol, ticket-lifecycle, observability, safety-policy, smoke-ticket-eval.

Numeric aliases:

When the user asks for readiness but also asks you to change files, prefer the matching audit+fix mode.

Baseline: the 8-artifact stack

For each artifact, score ✅ Present / ⚠️ Partial / ❌ Missing with concrete path evidence and a one-line gap.

1. Cold-start brief — root AGENTS.md / CLAUDE.md / operator docs. Tells an agent what this is, how to build, how to test, where rules live, and gotchas. Lean, not marketing. 2. Rules directory — per-domain coding standards in rules/, .cursor/rules/, docs/rules/, docs/solutions/, etc. Imperative rules with reasoning. For repos with exported APIs, this includes an API documentation policy or ADR. 3. Lint config with rich error messages — ESLint / Biome / SwiftLint / ruff / clippy with custom rules whose messages explain why and how to fix. 4. Pre-commit hooks — Husky / lefthook / pre-commit / native git hooks running formatters, type checks, or targeted tests before push/commit. 5. Test suite agents can drive — one-liner to run tests (npm test, ./scripts/test.sh, cargo test, etc.). Fast enough and deterministic enough for agents. 6. PR review automation — CodeRabbit, AI reviewer workflows, persona reviewers, or at minimum CI that gates PRs. 7. Repo-scoped skills/prompts — .agents/skills/, .pi/skills/, .claude/skills/, .codex/, .pi/prompts/, or package-scoped resources. Prefer 5-10 deep resources over many shallow ones. 8. Garbage-collection cadence — documented recurring loop that converts agent/PR feedback into permanent rules, lints, docs, or skills.

Cross-cutting API documentation check

When a repo exposes package, library, service, or app APIs that agents edit across package boundaries, inspect API documentation as a first-class harness surface:

• policy: docs/api-documentation-policy.md, rules/api-documentation.md, or equivalent
• decision record: docs/adr/*api*documentation*, docs/decisions/*api*documentation*, or equivalent
• tooling: TypeDoc, DocC, Sphinx/pdoc, rustdoc, godoc, or stack-native equivalent
• report/backlog: generated missing-docs report or coverage output that separates existing debt from new regressions
• commands: one-liners such as docs:api, docs:api:check, docs:api:report, or a documented equivalent

Treat a missing API documentation policy as a high-leverage rules/GC gap for repos with meaningful exported surfaces. Do not require full coverage before policy exists; prefer a baseline report plus a strict command that can be enabled once debt is paid down.

Symphony readiness overlay

Use this overlay when the user mentions Symphony, ticket-level orchestration, unattended agents, or preparing repos for an agent scheduler.

Score the overlay separately using references/symphony-readiness.md:

1. `WORKFLOW.md` contract — repo-local orchestrator contract with tracker states, live tracker preflight, workspace hooks, agent settings, and ticket lifecycle prompt. 2. Disposable workspace bootstrap — fresh clone/workspace can install dependencies, prepare services, and clean up without hidden local state. 3. One-command validate loop — stable command for the meaningful quality gate. 4. Agent-visible app validation — app/browser/log/test path an agent can drive and inspect. 5. Evidence protocol — documented proof format for reproduction, validation, screenshots/videos/logs, and PR/ticket handoff. 6. Ticket/PR lifecycle skill — repo-scoped workflow for workpad, branch, PR, review comments, human review, rework, and landing. 7. Agent-readable observability — token-efficient CLI/API access to local logs, CI failures, browser console, metrics, or traces. 8. Safety/secrets/workspace policy — env-backed secrets, destructive-command policy, workspace isolation, sandbox/approval posture. 9. Smoke-ticket eval — runnable or documented tiny ticket proving unattended bootstrap → change → validate → evidence → handoff.

Verdict definitions are canonical in references/symphony-readiness.md.

Workflow

Phase 1 — Capture inputs

Inputs may be supplied in natural language with or without an explicit mode label.

• Target repo path: default to the current working directory when omitted.
• Mode: audit default, audit+fix, symphony-readiness, audit+fix:symphony, or focus:<artifact-name>.
• Stack hint: auto-detect unless supplied.

Do not edit files in audit mode. For audit+fix, inspect uncommitted changes first and avoid overwriting user work.

Phase 2 — Detect stack

Read whichever exist:

• package.json plus lockfiles (bun.lockb, pnpm-lock.yaml, yarn.lock, package-lock.json) → TypeScript / Node.
• Package.swift, *.xcodeproj, *.xcworkspace → Swift.
• pyproject.toml, requirements.txt, setup.py, poetry.lock, uv.lock, Pipfile → Python.
• Cargo.toml → Rust.
• go.mod → Go.

If multiple stack markers exist, audit every major stack that has runtime/build impact. For example, a TypeScript frontend plus Python backend should use both stack references and call out cross-stack bootstrap/validation gaps.

Read the matching reference from references/stack-<stack>.md. If there is no dedicated stack reference, use references/audit-prompt.md plus generic judgment. For symphony-readiness or audit+fix:symphony, also read references/symphony-readiness.md, references/evidence-protocol.md, and references/smoke-ticket-eval.md.

Phase 3 — Run the audit

Use references/audit-prompt.md as the checklist. Execute the audit directly with available Pi tools (read, bash, rg/find through shell as needed). Keep evidence path-specific.

Return:

• 8 baseline artifact scorecards with evidence.
• Summary scorecard (X/8 ✅, Y/8 ⚠️, Z/8 ❌).
• Top 3 highest-leverage gaps with effort estimate and what each unlocks.
• Notable strengths.
• Stack-specific observations.

For Symphony modes, additionally return:

• 9-item Symphony readiness overlay scorecard.
• Symphony readiness verdict: Ready, Close, or Not ready.
• Minimum blockers before unattended orchestration, including missing live tracker preflight when Linear/Symphony is in scope.
• One recommended smoke-ticket eval shape for this repo.

Keep the baseline report under about 1500 words. For Symphony modes, keep the combined report under about 2200 words unless the user asks for depth. Do not pad.

Phase 4 — Mode-specific follow-up

• `audit`: stop after the report. Do not edit.
• `audit+fix`: fix the top 3 baseline gaps, or fewer if the safe scope is smaller.
• `symphony-readiness`: audit baseline plus Symphony overlay. Do not edit.
• `audit+fix:symphony`: fix the smallest set of blockers that moves the repo toward unattended ticket execution. Prefer workflow contract, disposable bootstrap, validation/evidence, and smoke eval over cosmetic docs.
• `focus:<artifact>`: read-only by default; skip the full audit and audit only that artifact. For focused edits, use the normal audit+fix mode and state the artifact scope in natural language, e.g. audit+fix, focus pre-commit.

Use references/fix-patterns.md for fix templates. For Symphony workflow seeding, use references/workflow-template.md. For proof requirements, use references/evidence-protocol.md and references/smoke-ticket-eval.md.

Fix rules:

• Make surgical changes only; no unrelated refactors.
• Verify functionally and show output.
• Do not commit or push unless the user explicitly requested commits.
• Do not post to external systems unless explicitly requested.
• Avoid emojis in committed source/config/docs unless the repo already uses them. Status emojis in audit chat reports are allowed.
• Use kebab-case filenames unless the repo convention differs.
• Run fixes sequentially when they touch overlapping files.

Phase 5 — Report after fixes

Show:

• Updated scorecard (X/8 → Y/8 ✅).
• File paths changed.
• Verification evidence.
• Remaining gaps ranked by leverage and effort.

Stack references

Symphony readiness uses cross-stack references: references/symphony-readiness.md, references/evidence-protocol.md, and references/smoke-ticket-eval.md.

Fix templates

Use references/fix-patterns.md.

Focus/fix-template map:

Output format

# Harness Audit — {repo name}

## 1. Cold-start brief
**Status:** ✅ / ⚠️ / ❌
**Evidence:** {file paths or "not found"}
**Gap:** {1-2 lines}

[... artifacts 2-8, same format ...]

## Summary scorecard
X/8 ✅, Y/8 ⚠️, Z/8 ❌

## Top 3 highest-leverage gaps
1. **{name}** — what to add, est. effort, what unlocks
2. ...
3. ...

## Symphony readiness overlay
Include only for `symphony-readiness` and `audit+fix:symphony`.

### 1. WORKFLOW.md contract
**Status:** ✅ / ⚠️ / ❌
**Evidence:** {file paths or "not found"}
**Gap:** {1-2 lines}

[... overlay items 2-9, same format ...]

## Symphony readiness verdict
Ready / Close / Not ready

## Minimum blockers before unattended orchestration
1. ...
2. ...
3. ...

## Recommended smoke-ticket eval shape
- Fixture: ...
- Expected change: ...
- Validation command: ...
- Evidence required: ...
- Cleanup: ...

## Notable strengths
- ...

## Stack-specific observations
- ...

Audit Checklist / Delegation Prompt

Use this directly as the audit checklist. Paths in this file are relative to the skill root (skills/harness-audit/), not to the references/ directory. When delegating to a separate exploration agent, first replace every {{...}} placeholder with concrete repo values; do not send unresolved placeholders to another agent.

Placeholder sources:

• {{STACK}}, {{PACKAGE_MANAGER}}, {{REPO_PATH}}, and {{REPO_CONTEXT}} come from stack detection and initial repo inspection.
• {{LINT_CONFIG_PATHS}}, {{TEST_RUNNER}}, and {{STACK_SPECIFIC_BONUS_SIGNALS}} come from the matching stack reference.
• {{LINT_CMD}} for fix templates must be derived from package scripts, Makefile targets, or the matching stack reference; if no lint command exists, report that as the gap instead of inventing one.

---

You are auditing a {{STACK}} repo for "harness engineering" readiness — meaning: how well-equipped is this codebase for autonomous AI agents (Pi, Claude Code, Codex) to do end-to-end work without a human babysitting them?

Repo: {{REPO_PATH}} Stack: {{STACK}} ({{PACKAGE_MANAGER}}) Context: {{REPO_CONTEXT}} (one-liner — what this repo is and lifecycle stage)

The 8-Artifact Harness Stack — score each one

For EACH artifact below, return:

• Status: ✅ Present / ⚠️ Partial / ❌ Missing
• Evidence: specific file paths or "not found"
• Gap: what's missing or weak (1-2 lines)

1. Cold-start brief (AGENTS.md or CLAUDE.md at root)

Look for AGENTS.md, CLAUDE.md, README.md at root. Read the first ~150 lines of whatever exists. Assess: does it tell an agent what this is, how to run it, where rules live, how to test, gotchas? Or is it a marketing README?

Critical failures to flag:

• Missing entirely
• Says "no build/test commands yet" or similar — but project actually has them (stale)
• All marketing prose, no operator-grade content
• Bloated (>500 lines) — agent context burn

2. Rules directory

Per-domain coding standards: naming, logging, error handling, DB conventions, auth, security. Look in:

• rules/, .cursor/rules/, docs/rules/, .claude/rules/
• docs/solutions/, docs/patterns/, docs/guidelines/
• CONTRIBUTING.md, UBIQUITOUS_LANGUAGE.md
• docs/api-documentation-policy.md, rules/api-documentation.md, docs/adr/, docs/decisions/

Are they imperative ("do X, not Y") or descriptive prose? Imperative is far stronger for agents. Flag stale rules (e.g., rules for a stack the project doesn't use anymore).

For repos with exported package/library/service APIs, also check whether API documentation expectations are explicit. A repo can have good style rules but still be weak for agents if it has no policy for which exports need TSDoc/JSDoc/docstrings, no ADR explaining the standard, and no missing-docs report to distinguish baseline debt from new regressions.

3. Lint config with rich error messages

Find the linter config for this stack ({{LINT_CONFIG_PATHS}}). Sample 3-5 custom rules — do their error messages explain why and how to fix, or are they terse defaults? Stock messages are descriptions; rich messages are remediation prompts.

4. Pre-commit hooks

Look for .husky/, lefthook.yml, .git/hooks/pre-commit, pre-commit-config.yaml, package.json#lint-staged, or Cargo.toml#[hooks]. What runs on commit? Formatter? Type check? Tests on changed files?

5. Test suite agents can drive

• Test runner present? ({{TEST_RUNNER}})
• One-liner script? (npm test, ./scripts/test.sh, cargo test, etc.) — agents should NOT need to compose toolchain incantations
• Test file count vs source file count (rough ratio)
• Are tests integration or unit-heavy?
• E2E setup if applicable (playwright, cypress, XCUITest, etc.)

6. PR review agents (persona reviewers)

• .github/workflows/ — any AI review workflows? CodeRabbit config (.coderabbit.yaml)?
• Any GitHub Actions that spawn Pi/Claude/Codex/etc on PRs?
• Branch protection rules (try gh api repos/{{OWNER}}/{{REPO}}/branches/main/protection 2>&1)
• Even basic CI matters here — no CI = no automated quality gate

7. Repo-scoped skills and prompts (.agents/skills/, .pi/skills/, .claude/skills/, .codex/, .pi/prompts/)

Skills checked into the repo (not home dir). What's there? Are they stable wrappers over churning infra (deploy, test, seed), or thin shells? Are they symlinks to fragile sibling paths (audit risk: breaks on fresh clone)?

Concentration check: 5-10 deep skills > 50 shallow ones. Flag sprawl.

8. Garbage collection cadence

This is hard to detect from code alone. Look for: weekly review docs, CHANGELOG.md with structured entries, docs/ folder with retros/postmortems, .github/ISSUE_TEMPLATE/ for "agent slop" or similar, docs/decisions/ ADRs. Note any signal that PR feedback gets converted into rules/lints over time.

For API-heavy repos, look for doc debt becoming permanent evidence rather than invisible reviewer feedback: generated API documentation reports, coverage summaries, or a strict command that can fail once the baseline backlog is closed.

Symphony readiness overlay

When the requested mode is symphony-readiness or audit+fix:symphony, also use references/symphony-readiness.md and score the repo on:

1. WORKFLOW.md contract 2. Disposable workspace bootstrap 3. One-command validate loop 4. Agent-visible app validation 5. Evidence protocol 6. Ticket/PR lifecycle skill 7. Agent-readable observability 8. Safety, secrets, and workspace policy 9. Smoke-ticket eval

This overlay answers whether an unattended ticket-level orchestrator can safely run agents in this repo. Do not treat good docs/tests as sufficient if there is no disposable bootstrap, evidence path, tracker preflight, or smoke-ticket proof. For Linear workflows, verify the repo documents a live preflight command that checks the API key, project slug, and configured state names; without that, real Symphony readiness cannot be ✅.

Bonus signals to capture

{{STACK_SPECIFIC_BONUS_SIGNALS}} — read the matching references/stack-{{STACK}}.md for stack-specific things to look for here.

Also universal:

• Project structure (monorepo? package count?)
• CI setup — what runs on push/PR?
• Pi package/resource metadata (package.json#pi, .pi/settings.json, .pi/skills, .pi/prompts)
• Any .claude/settings.json with hooks configured?
• .mcp.json — what MCP servers are wired?
• API documentation policy/ADR/report — especially for exported package APIs and cross-package contracts

API documentation policy check

When the repo exposes meaningful exported APIs, inspect this as a focused sub-check even if the user did not request it explicitly.

Look for:

• policy docs: docs/api-documentation-policy.md, rules/api-documentation.md, CONTRIBUTING.md sections, or equivalent
• decision records: docs/adr/*api*documentation*, docs/decisions/*api*documentation*, or equivalent
• tooling/config: typedoc.json, eslint-plugin-jsdoc, pydocstyle, Sphinx/pdoc, rustdoc config, DocC, or stack-native equivalent
• scripts: docs:api, docs:api:check, docs:api:report, docs:api:strict, or documented equivalents
• baseline report: docs/api-documentation-report.md, coverage output, or a generated backlog of undocumented exports

Report these states separately:

• Policy missing — no clear standard for what requires API docs.
• Tooling missing — policy exists but no command can check or report coverage.
• Backlog exists — tooling found missing docs; this is acceptable only if the backlog is visible and not falsely wired as a required green gate.
• Strict gate ready — policy, tooling, and coverage are sufficient to fail new regressions.

Output format

Use markdown headers per artifact. Keep evidence concrete (file paths, line numbers). End with:

Summary scorecard (X/8 ✅, Y/8 ⚠️, Z/8 ❌)

Top 3 highest-leverage gaps

For each: what to add, est. effort (hours), and what unlocks once it's there. Order by leverage × low effort.

Notable strengths

What's already well-set-up that should be preserved.

Stack-specific observations

Toolchain caveats agents need to know (Swift project file conflicts, Bun gotchas, Python venv conventions, etc.).

For Symphony modes, also include:

Symphony readiness overlay

9-item scorecard with evidence and gaps.

Symphony readiness verdict

Ready / Close / Not ready.

Minimum blockers before unattended orchestration

The smallest set of fixes needed before a scheduler can run agents unattended.

Keep baseline reports under ~1500 words. Keep Symphony reports under ~2200 words unless depth is requested. Be ruthless — gaps not present, but no padding.

Evidence Protocol

Use this reference when a repo needs human-reviewable proof for unattended agent work.

Evidence goals

Evidence should answer three questions quickly:

1. What behavior was reproduced or inspected before the change? 2. What changed? 3. What proves the acceptance criteria now pass?

Raw logs are not enough. Agents should compress proof into a short workpad/PR section and attach durable artifacts only when they add signal.

Required evidence by change type

Workpad / PR evidence section

Agents should maintain a compact section like:

## Evidence

### Reproduction / baseline
- `command`: outcome summary
- artifact: `path-or-url`

### Validation
- `command`: pass/fail summary
- `command`: pass/fail summary

### UI/runtime proof
- screenshot/video/log query: `path-or-url`
- console/log errors checked: yes/no

### Known limits
- ...

Artifact storage

Prefer durable, reviewable locations:

• PR comment attachments
• issue/workpad attachments
• tmp/evidence/ ignored by git for local-only proof
• CI artifact uploads

Do not commit bulky generated evidence unless the repo already has that convention.

Agent instructions to add to repo skills

• Capture evidence immediately after validation while context is fresh.
• Quote only the useful tail/summary of long output.
• Include exact commands, not paraphrases.
• Include failing evidence when blocked.
• Never claim UI behavior was validated without browser/app evidence.
• Never claim CI is green without checking the current commit's checks.

Fix Pattern Templates

Templates for audit+fix mode. Each template fills in {{...}} placeholders from the audit report and target repo context.

Universal preamble — apply before every fix:

Repo: `{{REPO_PATH}}` ({{STACK}}, package manager: {{PKG_MGR}})

Constraints from the repo operator docs:
- Surgical fixes only — no refactors of unrelated code
- Functional verification required — run the change and show output
- **Do not commit, push, open PRs, post comments, or call external systems unless explicitly requested.**
- No emojis in committed files unless repo already uses them
- kebab-case for new filenames

Read AGENTS.md / CLAUDE.md and CONTRIBUTING.md first. If commits were explicitly requested, match the repo's commit message conventions (check `git log --oneline -20`).

---

add-cold-start-brief

Use when: artifact #1 is ❌ Missing or ⚠️ Partial (stale).

Write a fresh AGENTS.md (or fix the existing one) at the repo root. Target: 100-200 lines. NOT a marketing README.

Required sections:
1. **What this is** (1 paragraph) — name, purpose, runtime/stack, lifecycle stage
2. **How to run locally** — exact commands, not prose. Include any env vars to set.
3. **How to test** — the one-liner. If the repo doesn't have one, ALSO add `scripts/test.sh` (see `wrap-test-runner` template).
4. **Where rules live** — pointers to `rules/`, `docs/solutions/`, `CONTRIBUTING.md`, etc.
5. **Gotchas** — concrete past failures. 5-10 bullets max. Each bullet = one rule with reasoning.
6. **Source-of-truth hierarchy** — when docs disagree, which wins.

Anti-patterns to avoid:
- Hardcoded counts ("the project has 14 packages") — these go stale silently
- Directory listings ("the src/ folder contains...") — same problem
- Marketing prose ("a beautifully designed app that...")
- Generic advice ("write tests, follow SOLID") — agents don't need this

If the repo has a stale section saying "no commands yet" but commands DO exist, fix that first.

After writing, ask: "is this lean enough to be useful at cold-start?" If >250 lines, cut.

Verify: read it back end-to-end, then ignore surrounding conversation context and try to run the documented test command using only the brief. If you can't, the brief failed.

---

extract-rules-dir

Use when: artifact #2 is ⚠️ Partial (rules scattered across many files).

Find all coding-standards content currently scattered across the repo. Likely sources:
- AGENTS.md / CLAUDE.md "Conventions" section
- CONTRIBUTING.md "Code style" section
- Random .md files in docs/
- Cursor `.mdc` files
- README sections

Consolidate into a `rules/` directory at repo root, ONE file per domain:
- `rules/naming-conventions.md`
- `rules/error-handling.md`
- `rules/logging.md`
- `rules/{domain-specific}.md` (e.g., `rules/db-conventions.md` for backend, `rules/swiftui-style.md` for iOS)

Each file:
- Imperative voice ("do X, not Y" — never "we tend to prefer X")
- Reasoning included ("because Z happened in production")
- Code examples for both the wrong and right form

After extracting, leave a 1-line pointer in the original location:
> See `rules/naming-conventions.md` for naming standards.

Preserve surrounding rationale when it is specific and useful. Move only the enforceable rule content; do not erase narrative context that explains why the rule exists unless that rationale moves into the new rule file.

Update AGENTS.md to point to `rules/` in the "Where rules live" section.

Do NOT duplicate rules across files — pick one home, point everywhere else.

---

add-api-doc-policy

Use when: focus:api-doc-policy is requested, or the audit finds a repo with meaningful exported APIs but no API documentation policy, ADR, tooling, or baseline report.

Add the smallest policy/tooling surface that lets agents understand and improve public API documentation without forcing a giant one-shot docstring cleanup.

Universal requirements:
- Add a policy doc such as `docs/api-documentation-policy.md` or `rules/api-documentation.md`.
- Add an ADR or decision note such as `docs/adr/0001-api-documentation-policy.md` when the repo already uses ADRs or decision docs.
- Define what requires docs: exported package APIs, app/server entrypoints consumed by other packages, public types, config schemas, runner/tracker/workspace contracts, and error-prone lifecycle hooks.
- Define what does not require docs: private helpers, obvious local constants, test-only fixtures, and symbols explicitly marked internal.
- Explain the allowed internal marker for the stack, such as `@internal` for TSDoc/JSDoc.
- Add a generated baseline report when a tool can produce one cheaply.
- Do not wire a strict coverage gate into CI until the baseline backlog is low enough to keep CI actionable.

For TypeScript/Bun repos:
1. Add TypeDoc if it is not already present.
2. Add `typedoc.json` using real package/app entrypoints.
3. Add scripts shaped like:
   - `docs:api`
   - `docs:api:check`
   - `docs:api:report`
   - `docs:api:strict`
4. If TypeDoc alone does not give a useful missing-docs backlog, add a small AST-based report script that scans exported top-level declarations and detects leading `/** ... */` comments.
5. Add generated docs output such as `docs/api/` to `.gitignore`.
6. Commit the baseline report, not the generated HTML/API site, unless the repo already tracks generated docs.

For other stacks, adapt to the native documentation checker:
- Python: Sphinx, pdoc, pydocstyle, interrogate, or docstring coverage tooling.
- Swift: DocC plus SwiftLint documentation rules when useful.
- Rust: rustdoc, `cargo doc`, and `#![deny(missing_docs)]` only after baseline debt is handled.
- Go: godoc plus `golint`/staticcheck-style comments where the repo already uses those checks.

Verification:
- Run the report command and ensure it writes the expected baseline report.
- Run the non-strict docs check.
- Run the repo's typecheck/test/verify command if package config changed.
- Run the strict docs command and treat failure as expected only when the report has known missing docs. State the exact missing count instead of claiming the repo is compliant.

---

add-rich-lint-messages

Use when: artifact #3 is ⚠️ Partial.

Identify the top 10 most-fired lint rules in this repo. Sources:
- Run `{{LINT_CMD}}` and count violations by rule
- Look in PR review history (gh pr list + comments) for repeat patterns
- Check `docs/solutions/` for documented rule violations

For each, rewrite the error message with:
- WHY this rule exists (the consequence in this codebase)
- HOW to fix (specific suggestion, not generic advice)
- WHERE to read more (pointer to rules/ or docs/)

Example transformation:
- BEFORE (stock): `'X' is not allowed`
- AFTER: `Use Y instead — X bypasses our auth middleware (see rules/auth.md). Replace with: Y(...)`

Tools by stack:
- Biome / ESLint: custom rule messages or `noRestrictedSyntax` with `message`
- SwiftLint: `custom_rules` with `message:` field
- ruff: harder — most messages are stock; use `select` + per-file overrides instead
- clippy: same — limited custom message support

Verify: run the linter against a known-bad file, capture output, confirm the new message is clear and actionable.

---

setup-pre-commit

Use when: artifact #4 is ❌ Missing.

Set up a pre-commit gate appropriate for this stack. Read `references/stack-{{STACK}}.md` from the harness-audit skill for the specific tooling pattern.

Universal requirements:
- Format/lint runs on staged files only (not the whole repo — too slow)
- Type check or compile check runs (project-wide is OK if <10s)
- If type check >10s, demote to pre-push
- Hook FAILS the commit on real violations (not just warnings)
- Auto-fixable issues (formatting) get applied + restaged automatically

Verification steps (REQUIRED):
1. Prefer a scratch worktree or temporary branch so verification does not mutate the user's active index.
2. Stage a file with an intentional lint violation. Run the hook command directly (`pre-commit run`, `npx lint-staged`, `.git/hooks/pre-commit`, etc.). Show that it blocks or fixes.
3. Stage a file with a type error. Run the hook command directly. Show that it blocks.
4. Revert the test changes and restore the original branch/index.
5. Show the actual hook output for both cases.

Only run a real `git commit` when the user explicitly requested commit-based verification.

Don't claim done until you've shown evidence.

For Node/TS: `bun add -D husky lint-staged`, `bunx husky init`, configure lint-staged in package.json.
For Swift: tracked `scripts/git-hooks/pre-commit` plus `make install-hooks`/installer that symlinks into `.git/hooks/`; do not rely on committing `.git/hooks/` directly.
For Python: `pre-commit install` after writing `.pre-commit-config.yaml`.
For Rust: tracked `scripts/git-hooks/pre-commit` plus `make install-hooks`/installer running `cargo fmt --check` and `cargo clippy`; do not rely on committing `.git/hooks/` directly.
For Go: tracked hook installer or pre-commit framework running `gofmt`, `go vet`, and `golangci-lint` when present.

If commits were explicitly requested, use commit message: `chore: add pre-commit hook running {tools}`. Match repo conventions.

---

wrap-test-runner

Use when: artifact #5 is ⚠️ Partial (tests exist but no one-liner).

Write `scripts/test.sh` (or equivalent for the stack — Makefile target, package.json script) that:
- Takes optional argument for subset selection (e.g., `./scripts/test.sh ios` vs `./scripts/test.sh watch`)
- Uses `set -euo pipefail` (bash) or strict mode equivalent
- Prints what it's running before running it
- Falls back gracefully if optional pretty-printers (xcbeautify, jq, etc.) aren't installed
- Exits non-zero on failure

For Swift specifically (most common gap):
- Use `OS=latest` not pinned simulator versions — pinned breaks on Xcode mismatch
- Wrap with xcbeautify if available, raw xcodebuild if not
- One subcommand per scheme

Update AGENTS.md "How to test" section to point at the new script.

Verify: actually run the script end-to-end. Show passing test count.

If commits were explicitly requested, use commit message: `chore: add scripts/test.sh wrapping {tool} test runner`.

---

add-pr-review

Use when: artifact #6 is ❌ Missing.

Add automated PR review. Two paths — pick based on repo:

**Path A: CodeRabbit (recommended for free for public, paid for private)**
- Create `.coderabbit.yaml` at repo root
- Configure language, instructions, file filters
- Add a "reviews" section pointing CodeRabbit at the repo's rules dir
- No GitHub Actions changes needed — CodeRabbit's GitHub App handles it

Example minimal config:

language: en-US reviews: profile: chill instructions:

• path: "*/"

instructions: "Follow rules in rules/ and docs/solutions/critical-patterns.md" path_filters:

• "!/dist/"
• "!/node_modules/"

**Path B: Custom Pi/Claude/Codex GitHub Action**
- Create `.github/workflows/ai-review.yml`
- On `pull_request`, spawn Pi, Claude, or Codex with persona prompt
- Posts comment via `gh pr comment` only when explicitly approved and credentials are available

Path A is simpler if CodeRabbit is acceptable. Path B is better if Ossie wants persona-specific reviewers (reliability persona, security persona, etc.) or to avoid CodeRabbit cost.

Default: Path A unless audit found Ossie already runs CodeRabbit elsewhere and is dissatisfied.

Verify: validate config syntax and file placement locally. Treat CodeRabbit GitHub App installation as a hard gate: verify it is installed for the repo/org, or print a clear `App not installed — config is dormant` warning and leave PR review automation as partial. Only open a draft PR with an intentional issue when the user explicitly authorizes external GitHub-side verification; otherwise document the exact manual verification command/steps.

---

seed-repo-skills

Use when: artifact #7 is ❌ Missing or ⚠️ Partial.

Create 3-5 starter repo skills covering the most agent-touched workflows. Prefer `.agents/skills/` for cross-harness Agent Skills, `.pi/skills/` for Pi-only projects, and `.claude/skills/` for Claude-only projects. Per stack:

**TypeScript:**
- `run-tests` (wraps the test runner with common subset patterns)
- `seed-db` (if applicable — wraps the DB seed script)
- `regen-types` (if using prisma/drizzle/sqlacodegen)
- `deploy-preview` (if applicable)

**Swift:**
- `add-swift-file` (wraps `scripts/add-swift-file.rb` if XcodeGen not used)
- `check-design` (audits view code against project design rules)
- `release-build` (archive + export with signing)

**Python:**
- `run-migration` (alembic / django wrapper)
- `seed-test-data` (fixture loader)

Each skill:
- 1 SKILL.md, 30-60 lines
- `allowed-tools` frontmatter scoped to what the skill actually needs
- Imperative steps, not prose
- Bound to specific commands the project actually has

DO NOT seed skills the project doesn't need. 5-10 deeply-maintained > 50 shallow. Sprawl burns model attention.

If commits were explicitly requested, use commit message: `chore: seed repo skills with {N} starter skills for {workflows}`.

---

setup-gc-cadence

Use when: artifact #8 is ❌ Missing.

Set up a "garbage collection day" ritual converting agent/PR feedback into permanent rules. Two pieces:

1. **Schedule** — If a scheduling tool is available and the user explicitly wants automation, ask for or use the repo's documented cadence. If unspecified, document a manual weekly cadence instead of hardcoding a time. The routine should:
   - Pulls the week's PR review comments
   - Pulls any "agent slop" issues / labels
   - Drafts proposed rule additions or lint changes
   - Opens a draft PR only when credentials and approval are available

   If no scheduler is available, document the manual Friday ritual instead.

2. **Documentation** — Add a `docs/garbage-collection.md` (or section in AGENTS.md) describing:
   - What it does
   - When it runs
   - How to handle the auto-PR

Optional but recommended: add a `.github/ISSUE_TEMPLATE/agent-slop.yaml` with a label `agent-slop` so noisy agent failures can be tagged for the GC pass.

Verify: for automated cadence, trigger a manual run and confirm it produces output. For manual cadence, verify the docs point to the exact commands or checklist.

---

add-workflow-contract

Use when: Symphony overlay #1 is ❌ Missing or ⚠️ Partial.

Seed or improve a repo-local `WORKFLOW.md` using `references/workflow-template.md`.

Rules:
- Use obvious placeholders for tracker slug, repo URL, and credentials.
- Do not paste real tokens or personal local paths.
- Match the repo's real validation/bootstrap commands when they exist.
- If commands do not exist yet, point to the scripts this fix also creates or mark the placeholder clearly.
- Include state semantics for Todo, In Progress, Human Review, Rework, Merging, and terminal states, adjusted to the repo's tracker workflow.
- Include explicit handoff criteria and evidence requirements.

Verify: parse the YAML front matter manually or with an available YAML parser; confirm no secrets are present; confirm referenced scripts exist or are marked TODO placeholders.

---

add-disposable-bootstrap

Use when: Symphony overlay #2 is ❌ Missing or ⚠️ Partial.

Add a minimal disposable bootstrap path such as `scripts/bootstrap.sh` and, when useful, `scripts/verify-ready.sh`.

Requirements:
- strict shell mode (`set -euo pipefail`)
- install dependencies using the repo's package manager
- document required env vars through `.env.example` or AGENTS.md
- avoid machine-specific absolute paths
- avoid destructive cleanup outside the current repo/workspace
- be safe to run in a freshly cloned workspace

Verify in a temporary directory when cheap. If full install is too expensive, run syntax checks and the cheapest dry-run available, then state exactly what was not executed.

---

add-evidence-protocol

Use when: Symphony overlay #5 is ❌ Missing or ⚠️ Partial.

Add `docs/agent-evidence.md` or an equivalent section using `references/evidence-protocol.md`.

Then wire it into AGENTS.md / repo skills / WORKFLOW.md so agents actually read it.

Must define:
- evidence by change type
- required reproduction signal
- validation command transcript expectations
- screenshot/video/log expectations for UI/runtime work
- where evidence should be attached or stored
- what not to claim without proof

Verify: ensure the cold-start brief or workflow points to the evidence doc.

---

add-validate-loop

Use when: Symphony overlay #3 is ❌ Missing or ⚠️ Partial.

Add one stable validation command that represents the meaningful pre-handoff quality gate.

Prefer the repo's existing convention:
- `make verify`
- `./scripts/verify.sh`
- `pnpm verify` / `npm run verify`
- `uv run ...`
- `cargo test --workspace && cargo clippy ...`
- `go test ./... && go vet ./...`

The command should run, as applicable:
- lint/format check
- typecheck/compile
- unit/integration tests that are safe locally
- app smoke check when cheap and deterministic

If `wrap-test-runner` already created `scripts/test.sh` or an equivalent test wrapper, extend or call that wrapper from the validate loop instead of creating a parallel, inconsistent test script.

If full validation is slow, expose tiers such as `verify-fast` and `verify-full`, and document which one Symphony agents must run before handoff.

Wire the command into AGENTS.md, WORKFLOW.md, and the ticket lifecycle skill.

Verify: run the fastest real validation tier. If full validation is intentionally skipped due to cost, state the exact skipped command and why.

---

add-app-validation

Use when: Symphony overlay #4 is ❌ Missing or ⚠️ Partial.

Add the smallest agent-visible app validation path for the repo.

Prefer existing tools and scripts. Do not install a full browser/observability stack unless the repo already uses it.

For web apps, add or document:
- one app launch command (`scripts/launch-app.sh`, `make dev`, `pnpm dev`, etc.)
- one browser validation path (Playwright, Cypress, agent-browser, Chrome DevTools, or existing E2E runner)
- screenshot/video capture command if available
- browser console/server log capture instructions
- shutdown/cleanup command
- deterministic seed/test user instructions when needed

For service/CLI repos, adapt this to a smoke request/CLI invocation plus log capture.

Wire the path into AGENTS.md, the ticket lifecycle skill, or WORKFLOW.md so agents actually use it for UI/runtime changes.

Verify: run the launch command when cheap and show a healthy empty-state/log output. If browser automation is not configured, document the gap explicitly instead of claiming app validation is ready.

---

add-ticket-lifecycle-skill

Use when: Symphony overlay #6 is ❌ Missing or ⚠️ Partial.

Create a repo-scoped skill/prompt for ticket execution, preferably in the repo's existing skill system. Use `.agents/skills/ticket-lifecycle/SKILL.md` for cross-harness repos when no convention exists.

Include:
- read ticket and acceptance criteria
- maintain one persistent workpad/comment
- branch/worktree policy
- plan/reproduce/implement/validate/handoff loop
- PR creation/update policy
- review comment sweep
- rework policy
- landing policy
- blocker policy

Keep it 60-120 lines. Link out to evidence, testing, and landing docs instead of embedding everything.

Verify: read the skill end-to-end and ensure every linked file exists.

---

add-observability-access

Use when: Symphony overlay #7 is ❌ Missing or ⚠️ Partial.

Document or add the smallest agent-readable observability path.

Prefer:
- `scripts/logs.sh` for local service logs
- `scripts/ci-failure-summary.sh` for CI logs
- browser console capture instructions for UI apps
- metrics/traces query commands if the repo already has them

Do not invent a full observability stack during a harness fix. Add the thinnest stable wrapper around existing signals.

Verify: run the wrapper against existing logs or show a clear empty-state output.

---

add-safety-policy

Use when: Symphony overlay #8 is ❌ Missing or ⚠️ Partial.

Add a short `docs/agent-safety.md` or AGENTS.md section covering:
- secrets via env vars only
- required `.env.example` entries
- workspace-only editing expectation
- destructive command policy
- external posting/publishing policy
- sandbox/approval posture
- cleanup boundaries

Verify: run the repo's secret scanner if present, preferably `gitleaks detect --staged` or `gitleaks detect --no-git --source <changed-path>`. If no scanner is present, document that as a remaining safety gap; then grep added files for common token names (`API_KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PRIVATE_KEY`) and confirm no values were introduced. Do not mark the secret-scan gate as complete unless an actual scanner or CI gate exists.

---

add-smoke-ticket-eval

Use when: Symphony overlay #9 is ❌ Missing.

Add a local smoke-ticket fixture and runner based on `references/smoke-ticket-eval.md`.

Prefer:
- `docs/agent-evals/smoke-ticket.md`
- `scripts/agent-smoke-eval.sh`

The first version may be a dry-run verifier that checks the fixture, expected marker file, validation command, and evidence section shape. Do not require real tracker credentials unless the user explicitly wants live integration. If the eval is a placeholder, make it fail by default in CI or exclude it from CI with an explicit TODO; do not let a stub silently pass.

Verify: prefer the dry-run path and show pass/fail output. A live smoke-ticket eval may spawn agents, create worktrees, call external trackers, and burn tokens; run it only with explicit user approval. If it is intentionally a template, make that explicit and ensure it exits non-zero until configured.

---

Execution order

When running audit+fix mode and multiple gaps need fixing:

Parallel-safe (different files):

• wrap-test-runner + add-pr-review (touches scripts/ and .github/)
• setup-pre-commit + add-cold-start-brief (touches .husky/ and AGENTS.md)

Sequential required (overlapping files):

• setup-pre-commit BEFORE add-rich-lint-messages (the second needs the first's lint config in place)
• wrap-test-runner / add-validate-loop BEFORE add-cold-start-brief (the brief points at validation scripts)
• extract-rules-dir BEFORE add-rich-lint-messages (lint messages point at rules)
• extract-rules-dir BEFORE add-api-doc-policy when the API policy belongs under the rules directory
• add-api-doc-policy BEFORE setup-gc-cadence when the GC routine should track documentation debt
• wrap-test-runner / add-validate-loop / add-disposable-bootstrap BEFORE add-workflow-contract (workflow hooks should reference real commands)
• add-evidence-protocol BEFORE add-ticket-lifecycle-skill (ticket skill should link to evidence rules)
• add-app-validation BEFORE add-ticket-lifecycle-skill when ticket skill references UI/runtime proof
• add-ticket-lifecycle-skill BEFORE add-workflow-contract when the workflow prompt references repo skills
• add-smoke-ticket-eval AFTER validation/bootstrap scripts exist

When in doubt, sequential. Wrong parallelization causes conflicts; wrong sequencing only costs time.

Smoke-Ticket Eval

A smoke-ticket eval proves the repo is ready for ticket-level unattended orchestration.

This can be implemented against a real tracker or as a local dry-run fixture. Prefer local first; it is cheaper and safer.

Minimal fixture

Create a tiny issue fixture such as docs/agent-evals/smoke-ticket.md:

# SMOKE-001: Update smoke-test marker

## Goal
Make the smallest safe change that proves the agent can edit, validate, and hand off.

## Acceptance criteria
- Change the configured marker text from `before` to `after` in the documented fixture file.
- Run the repo validation command.
- Record evidence in the workpad/PR section.
- Do not touch unrelated files.

## Validation
- Run `./scripts/verify.sh` or the repo's equivalent validation command.

Eval harness expectations

A runnable eval should:

1. create a disposable workspace or git worktree 2. render the repo's workflow prompt with the fixture issue 3. launch the selected agent runner or dry-run substitute 4. require the expected file change 5. require validation evidence 6. verify no unrelated tracked files changed 7. clean up workspace state unless debugging is requested

Pass/fail criteria

Pass only when:

• expected change exists
• validation command was run and recorded
• evidence section exists
• no unrelated files changed
• run completes without human prompt/input

Fail when:

• the agent asks the human what to do despite clear fixture instructions
• it cannot bootstrap the workspace
• it edits outside the workspace
• it skips validation
• it claims evidence without artifact/command proof

Practical script shape

A repo can expose this as:

./scripts/agent-smoke-eval.sh

or:

make agent-smoke-eval

The script may use a cheap stub agent first. The important part is that the repo has an executable definition of what "ready for unattended ticket work" means.

Go Stack

Covers: Go modules, CLIs, services, workers, monorepos with multiple Go modules.

Tooling matrix

Config paths to check

• go.mod, go.sum
• go.work, go.work.sum
• .golangci.yml, .golangci.yaml, .golangci.toml, .golangci.json
• Makefile, Taskfile.yml, justfile
• .github/workflows/*

Pre-commit pattern

Prefer tracked hook scripts plus an installer, or the pre-commit framework. Do not rely on writing only to .git/hooks/; that directory is not version-controlled.

Example tracked hook:

scripts/git-hooks/pre-commit:

#!/usr/bin/env bash
set -euo pipefail

STAGED_GO=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.go$' || true)
if [ -z "$STAGED_GO" ]; then
  exit 0
fi

# Format staged Go files and restage them.
echo "$STAGED_GO" | xargs gofmt -w
echo "$STAGED_GO" | xargs git add

go vet ./...
if command -v golangci-lint >/dev/null 2>&1; then
  golangci-lint run ./...
fi

Makefile:

install-hooks:
	mkdir -p .git/hooks
	ln -sf ../../scripts/git-hooks/pre-commit .git/hooks/pre-commit

Test wrapper

go test ./... is the baseline one-liner. For agent use, expose a stable command:

verify:
	go test ./...
	go vet ./...
	golangci-lint run ./...

For slow integration tests, use build tags:

go test ./...                  # fast/unit
go test -tags=integration ./... # integration

CI pattern (GitHub Actions)

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true
      - run: go test ./...
      - run: go vet ./...
      - uses: golangci/golangci-lint-action@v6

Go-specific gotchas to flag

• Context propagation — services should pass context.Context; flag long-running calls without timeout/deadline.
• Ignored errors — errcheck or golangci-lint should catch these.
• Global mutable state — parallel tests and agent edits often expose races; recommend go test -race ./... for critical packages.
• Integration tests hitting real services — require env-gated tests and .env.example docs.
• Generated code drift — check go generate ./... or documented generation commands.
• Multiple modules — go test ./... from one module will not cover sibling modules unless go.work or a wrapper exists.

Repo skills worth seeding

• run-go-tests — wraps fast/unit/integration/race variants
• regen-go-code — wraps go generate ./... and protobuf/sqlc generation
• inspect-ci-failure — summarizes failing Go test output from CI

Bonus signals (for the audit prompt)

• Go version (go directive in go.mod)
• Single module vs go.work workspace
• Race test coverage for concurrent code
• Presence of generated code (// Code generated, sqlc, protobuf, mockgen)
• Service framework hints (gin, chi, echo, connect-go, grpc)

Python Stack

Covers: Python 3.10+, FastAPI / Django / Flask, ML projects, data engineering, CLI tools.

Tooling matrix

Lint config paths to check

• pyproject.toml → [tool.ruff] section is the modern standard
• ruff.toml, .ruff.toml
• setup.cfg → [flake8] (legacy)
• pyproject.toml → [tool.black], [tool.isort], [tool.mypy]
• .flake8, .pylintrc

Pre-commit pattern (using pre-commit framework)

.pre-commit-config.yaml:

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.9
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.11.2
    hooks:
      - id: mypy
        additional_dependencies: [types-requests]  # add your stubs

Install: pip install pre-commit && pre-commit install

Test wrapper

Usually no wrapper needed — pytest is the one-liner. Gaps to look for:

# pyproject.toml
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra -q --strict-markers"

If the project has slow integration tests, group them with markers:

@pytest.mark.integration
def test_db_round_trip():
    ...

And expose make test / make test-fast / make test-integration so agents can run the right subset.

CI pattern (GitHub Actions)

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.11', '3.12']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pip install -e '.[dev]'
      - run: ruff check .
      - run: ruff format --check .
      - run: mypy .
      - run: pytest

For uv-based projects, replace pip install with uv sync --all-extras.

Python-specific gotchas to flag

• Virtualenv assumptions — agent runs python -m pytest outside venv, gets wrong interpreter. Document the activation in AGENTS.md.
• `requirements.txt` vs `pyproject.toml` drift — both present, only one is authoritative. Flag as a gap.
• No type hints — Python is gradually typed. A codebase with zero type hints leaves agents without static contracts. Recommend adding mypy even if loosely configured.
• `__init__.py` vs implicit namespace packages — modern Python prefers no __init__.py, but mixing is a footgun. Pick one convention.
• `pytest` discovery — if test files don't match test_*.py pattern, pytest won't find them. Audit the discovery config.
• Mocked DB tests — Lopopolo's "agents shouldn't mock the DB if migrations exist" applies hard here. Flag if integration tests use sqlite-in-memory but prod is Postgres.
• `os.environ.get` without defaults — silent None propagation. Recommend pydantic-settings or explicit fail-fast on missing env.

Repo skills worth seeding

• run-migration — wraps alembic / django manage.py for the project
• seed-test-data — fixture loader
• regen-types — for projects using sqlacodegen, datamodel-code-generator, etc.

Bonus signals (for the audit prompt)

• Python version pinned? (python_requires, pyproject.toml#tool.poetry.dependencies.python)
• Package manager (uv / poetry / pip + requirements.txt)
• ASGI vs WSGI framework
• Async-heavy or sync-heavy
• ML stack hints (torch, jax, tensorflow, transformers)
• Data eng hints (dagster, prefect, airflow, dbt)
• Makefile with conventional targets (test, lint, fmt, typecheck)

Rust Stack

Covers: Rust 1.70+, Cargo workspaces, embedded Rust, web (axum/actix), Tauri.

Tooling matrix

Config paths to check

• Cargo.toml (workspace root) → [workspace], [lints], [profile.*]
• rustfmt.toml, .rustfmt.toml
• clippy.toml, .clippy.toml
• .cargo/config.toml for build flags

Pre-commit pattern

Do not rely on committing .git/hooks/ directly; it is not version-controlled. Put the hook in scripts/git-hooks/pre-commit and add make install-hooks or an equivalent installer that symlinks/copies it into .git/hooks/pre-commit.

scripts/git-hooks/pre-commit:

#!/usr/bin/env bash
set -euo pipefail

# Format check (fails if not formatted)
cargo fmt --all -- --check

# Lint staged
cargo clippy --workspace --all-targets -- -D warnings

# Tests scoped to changed crates would be ideal but cargo doesn't do incremental test selection well.
# For small projects: cargo test --workspace
# For large: skip tests in pre-commit, rely on pre-push or CI

Example installer:

install-hooks:
	mkdir -p .git/hooks
	chmod +x scripts/git-hooks/pre-commit
	@if [ -e .git/hooks/pre-commit ] && [ ! -L .git/hooks/pre-commit ]; then \
		echo ".git/hooks/pre-commit exists and is not a symlink; refusing to overwrite"; \
		exit 1; \
	fi
	ln -sf ../../scripts/git-hooks/pre-commit .git/hooks/pre-commit

For larger workspaces (>30s cargo build), use cargo nextest run and only test the workspace member containing staged files.

Test wrapper

cargo test is the one-liner. Variants:

cargo test --workspace --all-features  # everything
cargo test -p my-crate                  # one crate
cargo nextest run --workspace           # 2-3× faster, parallel

If the project has integration tests in tests/ directories that take long (DB, network), gate them behind a feature:

[features]
integration = []

And expose:

cargo test                       # unit only
cargo test --features integration  # everything

CI pattern (GitHub Actions)

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      - uses: Swatinem/rust-cache@v2
      - run: cargo fmt --all -- --check
      - run: cargo clippy --workspace --all-targets -- -D warnings
      - run: cargo test --workspace

Swatinem/rust-cache is essential — without it, every PR rebuilds from scratch.

Lints worth encoding in Cargo.toml

[workspace.lints.rust]
unsafe_code = "deny"
unused_imports = "warn"

[workspace.lints.clippy]
pedantic = { level = "warn", priority = -1 }
nursery = { level = "warn", priority = -1 }
unwrap_used = "warn"
expect_used = "warn"

The [workspace.lints] section (Rust 1.74+) propagates to all workspace members — single source of truth.

Rust-specific gotchas to flag

• Long compile times burn agent attention — every iteration that waits 30s+ for cargo build is harness debt. Recommend sccache, mold linker, cargo nextest.
• `unwrap()` proliferation — clippy can catch this, but only if the lint is enabled. Flag projects with lots of .unwrap() in non-test code.
• `unsafe` blocks without `// SAFETY:` comments — house rule worth encoding via clippy undocumented_unsafe_blocks.
• Macro-heavy code — agents struggle with derive-macros and proc-macros if the expanded output isn't documented. Recommend cargo expand skill for inspection.
• Workspaces with diverging dependency versions — cargo tree -d finds duplicates. Worth flagging.
• Tokio runtime mismatches — multi-runtime panics. Document which runtime the project uses.

Repo skills worth seeding

• run-bench — wraps cargo bench with the right baseline comparison
• expand-macro — wraps cargo expand for the active file
• update-deps — wraps cargo update + cargo outdated

Bonus signals (for the audit prompt)

• Workspace members count
• Edition (edition = "2021", "2024")
• MSRV (rust-version)
• Embedded? (no_std, target triple)
• Tauri / Bevy / Embassy / Axum / Actix detection
• Custom build scripts (build.rs)
• [profile.release] tuning (LTO, codegen-units, opt-level)

Swift / iOS Stack

Covers: iOS apps (UIKit + SwiftUI), watchOS, macOS apps, Swift packages. Server-side Swift (Vapor) follows similar patterns.

Tooling matrix

Lint config paths to check

• .swiftlint.yml, .swiftlint.yaml
• .swift-format (JSON config for apple/swift-format)
• swiftformat config in .swiftformat

Test runner one-liner

This is THE most common gap in Swift projects. xcodebuild test requires scheme name, destination string, derived data path — agents shouldn't compose this from memory.

scripts/test.sh:

#!/usr/bin/env bash
set -euo pipefail

PROJECT="MyApp.xcodeproj"
SCHEME="MyApp"
WATCH_SCHEME="MyAppWatch"  # if applicable

run_xcb() {
  if command -v xcbeautify >/dev/null 2>&1; then
    xcodebuild "$@" | xcbeautify
  else
    xcodebuild "$@"
  fi
}

case "${1:-all}" in
  ios)
    run_xcb test \
      -project "$PROJECT" -scheme "$SCHEME" \
      -destination 'platform=iOS Simulator,OS=latest,name=iPhone 15 Pro' \
      -derivedDataPath .build/DerivedData
    ;;
  watch)
    run_xcb test \
      -project "$PROJECT" -scheme "$WATCH_SCHEME" \
      -destination 'platform=watchOS Simulator,OS=latest,name=Apple Watch Series 9 (45mm)' \
      -derivedDataPath .build/DerivedData
    ;;
  all|*)
    "$0" ios
    "$0" watch  # if applicable
    ;;
esac

Critical: use OS=latest not pinned versions. Pinning to "iPhone 17 Pro" specifically breaks on machines with older Xcode where that simulator name doesn't exist.

Pre-commit pattern

Do not rely on committing .git/hooks/ directly; it is not version-controlled. Put the hook in scripts/git-hooks/pre-commit and add make install-hooks or an equivalent installer that symlinks/copies it into .git/hooks/pre-commit.

scripts/git-hooks/pre-commit:

#!/usr/bin/env bash
set -euo pipefail

# Lint staged Swift files
if command -v swiftlint >/dev/null 2>&1; then
  STAGED=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.swift$' || true)
  if [ -n "$STAGED" ]; then
    echo "$STAGED" | xargs swiftlint lint --strict --use-script-input-files
  fi
fi

# Optional: light build check (slower, demote to pre-push if >10s)
# xcodebuild build -project MyApp.xcodeproj -scheme MyApp -quiet

Example installer:

install-hooks:
	mkdir -p .git/hooks
	chmod +x scripts/git-hooks/pre-commit
	@if [ -e .git/hooks/pre-commit ] && [ ! -L .git/hooks/pre-commit ]; then \
		echo ".git/hooks/pre-commit exists and is not a symlink; refusing to overwrite"; \
		exit 1; \
	fi
	ln -sf ../../scripts/git-hooks/pre-commit .git/hooks/pre-commit

Run make install-hooks after cloning.

CI pattern (GitHub Actions, macOS)

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: macos-14  # M1 runners
    steps:
      - uses: actions/checkout@v4
      - run: xcodebuild -version  # log Xcode version
      - run: ./scripts/test.sh ios
      - run: ./scripts/test.sh watch  # if applicable

If the project uses SwiftUI iOS 26+ APIs (Liquid Glass, etc.), pin Xcode 26+:

- uses: maxim-lobanov/setup-xcode@v1
  with:
    xcode-version: '26.0'

Swift-specific gotchas to flag

• AGENTS.md says "no build commands yet" but project DOES build — the most common Swift harness failure. The original brief was scaffolded before Xcode project existed and never updated.
• `.xcodeproj/project.pbxproj` is a binary coordination surface — two parallel agent worktrees calling project-mutation scripts simultaneously will corrupt it. If the project uses agent worktrees, document a "one agent owns project file mutations at a time" rule.
• Swift files created but not registered — agents create .swift files but they're not in any target. Solve with scripts/add-swift-file.rb (xcodeproj gem) or use folder references / file system synchronized groups (Xcode 16+).
• Strict concurrency surfacing — SWIFT_STRICT_CONCURRENCY = complete in xcconfig is the right call but means agents must compile under it. Document this in rules.
• HealthKit / device-only APIs cannot be tested in CI — flag these for human verification on physical device. Agents should not claim "tests pass" for HealthKit changes without a device run.
• Simulator name drift — Xcode 15/16/17 ship different simulator catalogs. Always use OS=latest.

Repo skills worth seeding

For Swift projects, common high-value repo skill entries (.agents/skills/, .pi/skills/, or .claude/skills/ depending on the harness):

• add-swift-file — wraps scripts/add-swift-file.rb, takes file path + target list
• check-design — audits view code against the project's design rules
• xcodebuildmcp (if using MCP) — wired in .mcp.json for native build/test from agents
• release-build — wraps archive + export, handles signing

Bonus signals (for the audit prompt)

• Workspace vs project (.xcworkspace vs .xcodeproj)
• SwiftPM dependencies (Package.swift) vs Cocoapods (Podfile) vs Carthage
• XcodeGen / Tuist usage
• config/ directory with xcconfig files (good sign — externalized build settings)
• Strict concurrency setting in xcconfig (SWIFT_STRICT_CONCURRENCY)
• iOS deployment target
• Multi-target structure (iOS + watchOS + macOS)

TypeScript / Node Stack

Covers: Node, Deno, Bun. Most patterns assume Node + npm/pnpm/yarn or Bun.

Tooling matrix

Lint config paths to check

• biome.json, biome.jsonc (Biome 1.x), biome.json with $schema: "https://biomejs.dev/schemas/2.x.x/schema.json" (Biome 2.x)
• eslint.config.js, eslint.config.mjs, eslint.config.ts (flat config)
• .eslintrc, .eslintrc.js, .eslintrc.json (legacy)
• .prettierrc*
• oxlint.json (oxlint, Rust-based, very fast)

Test runner detection

• vitest.config.*, vite.config.* with vitest plugin → Vitest
• jest.config.* or jest key in package.json → Jest
• bun test referenced in package.json scripts → Bun native
• node --test → Node native runner

API documentation policy checks

For TypeScript repos with exported package APIs, check for:

• typedoc.json or typedoc config in package.json
• package.json scripts such as docs:api, docs:api:check, docs:api:report, or docs:api:strict
• docs/api-documentation-policy.md or rules/api-documentation.md
• docs/adr/*api*documentation* or docs/decisions/*api*documentation*
• a generated missing-docs report, usually docs/api-documentation-report.md
• optional lint support through eslint-plugin-jsdoc or a custom rule when the repo already uses ESLint

Recommended shape for Bun/TypeScript packages:

{
  "scripts": {
    "docs:api": "typedoc --options typedoc.json",
    "docs:api:check": "typedoc --options typedoc.json --emit none",
    "docs:api:report": "bun scripts/api-docs-report.ts --write docs/api-documentation-report.md",
    "docs:api:strict": "bun scripts/api-docs-report.ts --fail-on-missing && typedoc --options typedoc.json --emit none --treatValidationWarningsAsErrors"
  }
}

Do not wire docs:api:strict into CI while the baseline report still has known debt. The useful first step is making the debt explicit and giving agents a contract for documenting new or changed exports.

Pre-commit pattern (bun + Biome)

# Install
bun add -D husky lint-staged
bunx husky init

package.json:

{
  "scripts": {
    "prepare": "husky",
    "typecheck": "tsc --noEmit"
  },
  "lint-staged": {
    "*.{ts,tsx,js,jsx,json}": ["bunx @biomejs/biome check --write --no-errors-on-unmatched"]
  }
}

.husky/pre-commit:

#!/usr/bin/env sh
bunx lint-staged
bun run typecheck

If typecheck >10s on a fresh checkout, demote to pre-push instead. Pre-commit needs to stay snappy.

Test wrapper

For most TS projects, npm test / bun test is already the one-liner. The gap is usually that the script in package.json only runs a subset:

"scripts": {
  "test": "vitest run packages/data packages/briefing"  // ← covers 2 of 7 packages
}

When auditing, check whether npm test actually exercises ALL packages. If not, that's a gap.

For monorepos: turbo test, pnpm -r test, bun --filter '*' test are the right shape.

CI pattern (GitHub Actions)

Minimal CI that's enough to gate PRs:

name: CI
on: [push, pull_request]
jobs:
  lint-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2  # or actions/setup-node@v4
      - run: bun install --frozen-lockfile
      - run: bun run lint
      - run: bun run typecheck
      - run: bun test

Common gotchas to flag

• Biome `--write .` from monorepo root — destructive in some configs (cf. Finance-Guru-v2 gotcha #8). Always scope to staged files in pre-commit.
• `any` proliferation — TS strict not actually strict if any is everywhere. Check tsconfig.json#strict AND grep for any density.
• No `noUncheckedIndexedAccess` — for data-heavy apps (financial, ML), this is a meaningful safety gap even with strict: true.
• Lockfile committed but ignored in CI — bun install without --frozen-lockfile lets versions drift between dev and CI.
• Workspaces with no shared tsconfig — each package has divergent compiler options, agent edits one config and breaks another.
• Doc coverage warning treated as mystery failure — if CodeRabbit or CI flags missing JSDoc/TSDoc, check whether the repo has a policy, ADR, and generated backlog before asking agents to blindly edit every export.

Custom rule patterns worth encoding

When auditing custom Biome / ESLint rules, recommend these patterns specifically:

• noRestrictedImports — block direct imports that bypass an architectural boundary (e.g., node:fs from browser code, direct DB client from UI layer)
• noRestrictedSyntax — block direct constructor calls that should go through a factory
• noConsole (override console.warn allowed) — force agents to use the project logger

Bonus signals (for the audit prompt)

• Monorepo or single-package? (pnpm-workspace.yaml, turbo.json, nx.json, bun workspaces)
• TS strictness (strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes)
• Package count
• Path aliases / module resolution custom config
• Tauri / Electron / Next.js / specific framework hints
• API documentation contract (typedoc.json, docs:api* scripts, docs/api-documentation-policy.md, ADR/report)

Symphony Readiness Overlay

Use this overlay when the user asks for Symphony readiness, ticket-level agent automation, unattended agent execution, or preparing a repo for an orchestrator like Symphony.

Baseline harness readiness asks: can agents understand and edit this repo?

Symphony readiness asks: can an unattended agent pick up a ticket, work in isolation, validate the change, produce reviewable evidence, and hand off through the tracker/PR workflow without babysitting?

Score each item ✅ Present / ⚠️ Partial / ❌ Missing with concrete path evidence and one-line gap.

1. WORKFLOW.md contract

Look for a repo-local WORKFLOW.md or equivalent orchestrator contract.

Must include:

• tracker config placeholders, not hardcoded personal secrets
• real tracker preflight command/instructions that verify the project/key/states exist before unattended runs
• active, review, rework, merge, and terminal state semantics
• workspace bootstrap hooks or pointers
• agent command / sandbox / approval posture
• prompt body with ticket lifecycle rules
• handoff definition: what counts as ready for human review

Strong signal: workflow is versioned with the repo and written as a durable operating contract, not a one-off launch command.

2. Disposable workspace bootstrap

Verify a fresh workspace can be prepared without hidden local state.

Look for:

• clone/setup command
• dependency install command
• environment template (.env.example, mise.toml, .tool-versions, devcontainer.json)
• database/service bootstrap command when applicable
• cleanup command

Audit question: from an empty directory, can an agent create the same working environment Symphony will create per ticket?

3. One-command validate loop

Look for one stable command that runs the meaningful quality gate:

• tests
• typecheck/compile
• lint/format check
• app smoke check where applicable

Good names: make all, make verify, ./scripts/verify.sh, pnpm verify, uv run pytest, cargo test.

Flag commands that only work after undocumented setup, require interactive input, or run only a narrow subset while claiming full validation.

Check this even when baseline artifact #5 passes. Baseline tests can exist while the unattended validate loop is still incomplete or too narrow for Symphony.

4. Agent-visible app validation

For UI/service repos, check whether an agent can launch and inspect the app.

Look for:

• scripts/launch-app.*, make dev, docker compose up, or equivalent
• Playwright/Cypress/agent-browser/Chrome DevTools instructions
• deterministic test user/seed data
• console/server log capture
• screenshot/video capture
• shutdown/cleanup instructions

If the repo has user-facing behavior but no agent-visible app path, score this low even if unit tests exist.

5. Evidence protocol

Check for instructions that tell the agent what proof to produce.

Evidence may include:

• reproduction signal before changes
• test command and output summary
• screenshot/video for UI changes
• logs/metrics/traces for runtime changes
• PR comment or issue workpad update
• CI/check URL after push

Strong signal: evidence is compressed for humans. Raw logs alone are weak.

6. Ticket/PR lifecycle skill

Look for a repo-scoped skill/prompt that covers:

• read ticket and acceptance criteria
• verify the tracker project exists and configured state names match the real tracker workflow before launch
• maintain one persistent workpad/comment
• create branch/worktree
• open/update PR
• gather and resolve review comments
• push back or defer out-of-scope feedback
• move to human review
• handle rework by starting clean when needed
• land/merge only through approved flow

This can live under .codex/skills/, .agents/skills/, .pi/skills/, .claude/skills/, or docs/agent-workflows/.

7. Agent-readable observability

Check whether agents can query the signals needed to debug without human screenshots.

Look for:

• local app logs with clear paths
• structured logs
• summarized CI failure extraction
• metrics/traces query instructions
• browser console capture
• production log access docs, with safe scoping

Raw vendor dashboards with no CLI/API path are partial at best.

8. Safety, secrets, and workspace policy

Check that unattended execution has explicit boundaries:

• secrets loaded via env vars or secret manager, never pasted into docs
• .env.example names required vars without values
• destructive commands documented and guarded
• workspace path isolation expected
• generated artifacts ignored or scoped
• external posting/publishing requires configured credentials and clear policy
• sandbox/approval posture documented

9. Smoke-ticket eval

Best readiness proof: a tiny issue can be completed end-to-end by the workflow.

Look for a documented or runnable eval that: 1. creates or simulates a small ticket 2. launches the orchestrated agent flow in a disposable workspace 3. requires a branch/PR or local patch 4. requires validation evidence 5. verifies the handoff state/comment/PR body 6. cleans up disposable state

If no external tracker is available, a local fixture issue file is acceptable for a dry-run eval. If Linear is the tracker, a live preflight like bun run symphony validate WORKFLOW.md --live-tracker must pass before scoring this as runnable against the real tracker.

Output addendum

After the 8 baseline harness artifacts, add:

## Symphony readiness overlay

### 1. WORKFLOW.md contract
**Status:** ✅ / ⚠️ / ❌
**Evidence:** ...
**Gap:** ...

[... items 2-9 ...]

## Symphony readiness verdict
Ready / Close / Not ready

## Minimum blockers before unattended orchestration
1. ...
2. ...
3. ...

Verdict guide:

• Ready: no ❌ items, and a smoke-ticket eval is runnable end-to-end against a fixture. Placeholder docs or non-functional templates do not qualify.
• Close: no launch-blocking ❌ items in workflow contract, disposable bootstrap, validate loop, evidence protocol, ticket lifecycle, or safety policy; and app validation/observability/smoke eval gaps are documented as remaining work. Also use Close when all items are ✅/⚠️ but the smoke-ticket eval is not yet runnable.
• Not ready: no disposable bootstrap, no workflow contract, no validation/evidence path, unsafe secrets/workspace policy, or any other gap that would make unattended execution fail before meaningful work starts.

Minimal WORKFLOW.md Template

Use this as a starting point when audit+fix:symphony needs to seed a repo-local Symphony contract. Keep placeholders obvious. Do not add real secrets.

---
tracker:
  kind: "REPLACE_WITH_TRACKER_KIND" # examples: linear, github, jira, custom
  project_slug: "REPLACE_WITH_PROJECT_SLUG"
  api_key: $LINEAR_API_KEY
  active_states:
    - Todo
    - In Progress
    - Rework
    - Merging
  terminal_states:
    - Done
    - Closed
    - Cancelled
    - Canceled
    - Duplicate
polling:
  interval_ms: 30000
workspace:
  root: "REPLACE_WITH_WORKSPACE_ROOT"
hooks:
  after_create: |
    git clone REPLACE_WITH_REPO_URL .
    ./scripts/bootstrap.sh
  before_run: |
    ./scripts/verify-ready.sh
agent:
  max_concurrent_agents: 2
  max_turns: 20
  max_retry_backoff_ms: 300000
agent_runner:
  kind: "REPLACE_WITH_AGENT_RUNNER_KIND" # examples: codex, claude, pi, custom
  command: "REPLACE_WITH_AGENT_APP_SERVER_COMMAND"
  sandbox: "REPLACE_WITH_SANDBOX_OR_APPROVAL_POLICY"
---

You are working on ticket `{{ issue.identifier }}`.

Title: {{ issue.title }}
State: {{ issue.state }}
URL: {{ issue.url }}
Labels: {{ issue.labels }}

Description:
{% if issue.description %}
{{ issue.description }}
{% else %}
No description provided.
{% endif %}

## Operating contract

- Work only inside the provided workspace.
- Start by reading repo-local agent instructions (`AGENTS.md`, repo skills, and rules docs).
- Maintain one persistent workpad/comment for plan, acceptance criteria, validation, evidence, and blockers.
- Before edits, capture a reproduction signal or state why reproduction is not applicable.
- Keep scope tied to the ticket acceptance criteria.
- File follow-up work separately instead of expanding scope.
- Run the repo's required validation before handoff.
- Produce compressed evidence a human can review quickly.
- Stop only for true blockers: missing auth, missing required secrets, or impossible acceptance criteria.

## State flow

- `Todo`: move to `In Progress`, create/update workpad, then execute.
- `In Progress`: continue from current workpad and workspace state.
- `Rework`: re-read feedback, start from a clean branch/workspace when policy requires it, then execute.
- `Human Review`: do not code unless feedback moves the ticket back to `Rework`.
- `Merging`: follow the repo landing skill; do not bypass required merge policy.
- Terminal states: do nothing.

## Required preflight

Before unattended execution, run the tracker preflight and fix every error:

bun run symphony validate WORKFLOW.md --live-tracker

This must verify the tracker API key, project slug, active states, terminal states, and lifecycle states against the real tracker workflow. Do not start polling if preflight fails.

## Required handoff

Before moving to human review, ensure:

- plan/checklist is current and complete
- acceptance criteria are checked off
- validation command(s) and results are recorded
- UI/runtime evidence is attached when behavior is user-facing
- PR is opened or updated, if this repo uses PRs
- review comments and CI failures are resolved or explicitly pushed back with rationale

Template rules

• Keep this file repo-local and versioned.
• Prefer placeholders over environment-specific values.
• The after_create hook must be safe in an empty workspace.
• Do not hardcode personal API tokens, local absolute repo paths, or private machine names.
• Customize tracker.kind and state names to the actual tracker workflow.
• Include a live tracker preflight command for the actual orchestrator; for Symphony + Linear use bun run symphony validate WORKFLOW.md --live-tracker.
• If targeting OpenAI's Elixir reference implementation, use tracker.kind: linear and adapt agent_runner to its current codex front-matter schema. This generic template is intentionally runner-adapter-neutral.