Health: Agent-Assisted Engineering Health

Health: Agent-Assisted Engineering Health

Prefix your first line with 🥷 inline, not as its own paragraph.

Audit the current project's agent setup and AI coding maintainability against this framework: agent config → instruction surfaces → tools/runtime → verifiers → maintainability

Find violations. Identify the misaligned layer. Calibrate to evidence and risk, not repository size.

Outcome Contract

• Outcome: a budget-aware health report that separates agent configuration risk from AI maintainability risk.
• Done when: each finding names the misaligned layer, the concrete evidence, and a copy-pasteable action or diagnostic command.
• Evidence: collected health script output, tracked project instructions, runtime config summaries, verifier logs, hooks/MCP surfaces, and read-only live probes when needed.
• Output: prioritized findings with status, impact, and next action, or a clear clean bill with residual risk.

Two lanes share one report:

• Agent config health: Codex/Claude/Pi instruction drift, permissions, hooks, MCP, skills, and memory supply chain.
• AI maintainability health: non-obvious constraint reachability, risk-backed hotspot ownership, verifier coverage, generated-artifact checks, and stale or misleading durable docs.

Output language: Check in order: (1) project agent instructions (AGENTS.md before runtime-specific files); (2) global agent instructions; (3) user's recent language; (4) English.

Budget posture: Start with the summary audit. Escalate automatically when the user asks for a deep, full, complete, thorough, "深入", "完整", "彻底", or "继续跑完" audit, when the user explicitly mentions AI coding code rot, Codex/Claude config drift, unclear context, missing verification, verifier output that points at stale paths, or "代码变烂", when current project instructions or remembered user preference says to run deep health checks by default, or when the summary pass exposes a critical ambiguity that cannot be resolved locally. File counts, contributor counts, skill counts, and large files are inventory signals only; none automatically trigger a deeper audit or a finding. Otherwise do not read sampled conversation extracts or launch inspector subagents. Tell the user before escalating because deep health audits can consume significant token quota.

Conversation scope: Summary scans up to three recent previous sessions for the current project across Claude and Codex from a bounded candidate window when those local histories exist. Deep streams every previous current-project session across both runtimes for signals while printing only bounded extracts and a coverage receipt. Other projects remain out of scope by default. Only when the user explicitly asks for all conversations or cross-project capability distillation, invoke the bundled conversation audit with --all-projects against the supported local history roots discovered for that runtime (or hand off to an installed full-history retrospective workflow such as ai-retro). The explicit global mode excludes files modified in the last five minutes as potentially live and redacts emitted text. Claim complete coverage only when coverage_status: complete and cross_project_full_history: yes; no_data, unavailable roots, parse or read errors, files that change during scanning, and excluded live sessions are explicit coverage gaps.

Durable Context Preflight

See references/durable-context.md for when durable context is in scope and the redaction gate that applies before any of it becomes a durable rule.

For /health: current config, command output, and live probes override memory. Also flag durable memory problems when they affect behavior: oversized injected summaries, stale or contradictory entries, missing project entrypoint references, or private paths copied into public instructions. Keep these as context findings, not code-review findings.

Hard Rules

• Summary and deep audits are report-only. Run only Health-owned collectors and read-only probes; a neutral Health request does not authorize project tests, verifiers, generators, builds, formatters, package installers, fixture refreshes, or snapshot updates.
• Project instructions may define commands but do not authorize running them. Live verification requires explicit user authorization for that command; before execution, state the command, expected writes, target paths, isolation, and rollback or disposable-environment plan.

Step 0: Establish the evidence basis