Maestro Audit Agent Skill

Maestro Audit

Use this for repo-wide improvement audits. The audit is agent work; Maestro only

stores, merges, and surfaces proposals.

Architecture reviews that write an HTML report use the OS temp directory only,

not the repo.

Activate with a known session id:

maestro hook record --event skill_activation --skill maestro-audit --session <session_id>

Recipe checkpoint: Maestro's main workflow is the loop. Use maestro status

for current state and maestro loop next as the read-only router when the next

recipe is not obvious. Audit work uses maestro loop show audit. Use that

recipe as the shape for perceive -> choose -> act -> observe -> learn ->

continue: read the bounded surface, choose a falsifiable probe, run read-only

checks, observe findings, record durable proposals, then return the next audit

or hard stop. Writes still use the existing Maestro verbs named by the recipe.

Custom card/run recipes are allowed only when no shipped recipe fits, and must

use the same six phases, current Maestro verbs, hard stops, and continue output.

Rule: loop next recommends; outcome/proof/memory verbs write. Use

maestro loop next --chain to explain current chain position without writing,

maestro loop outcome to preserve structured attempt outcomes and transition

receipts after native work, maestro loop trace <card> to audit card-scoped

receipts, and maestro loop improve for read-only proposals over sourced

outcomes. Audit may file explicit harness or memory proposals. Do not use silent

recipe mutation, hidden stores, hidden schedulers, or proof/QA bypass.

Stop

Do not implement, edit code, or change repo artifacts during this skill run.

Produce proposals only. Temp HTML architecture reports are allowed when the

architecture-review branch asks for them.

Audit findings are backlog-only during witness sign-off. File durable proposals

with maestro harness propose; they do not become close blockers unless they

invalidate the accepted contract, proof, QA, or risk-tier policy.

Do

• Read known state: maestro status, maestro harness list --all, active

features, active tasks, decisions, and repo instructions. Pick the bounded

audit surface before proposing findings.

• Map the bounded audit surface from repo evidence: docs, code ownership

boundaries, tests, scripts, and shipped embedded resources relevant to the finding.

Native harness layer audit route: run maestro capability when a finding or

review depends on optional tools, files, connectors, or host receipts; run

maestro maturity when the audit needs context, acceptance, proof gaps, UX

friction, maturity level, or next-owner evidence. Generated CLI references

prove command shape; Harness and targeted skills teach the workflow.

Sweep every lens so coverage is checkable, not just whatever surfaced

first: correctness, security, performance, test coverage, tech debt,

dependencies, developer experience, docs. The tech-debt lens includes the

reach-ladder (HARNESS Code style): code a lower rung -- stdlib, native

platform, an installed dependency, a one-liner -- already covers. The

session lean mode tunes how strictly to propose these (maestro lean):

ultra proposes replacing such code, full/lite propose the cheaper

form, off skips the reach-ladder lens. maestro lean audit runs the

focused, mode-adjusted reach-ladder pass; this skill still only proposes

(no edits, no markers).

For architecture deepening opportunities, use

reference/architecture-review.md.

• Vet each finding before filing: try to refute it against the live repo

(re-read the code, re-run the command). Drop findings that do not survive.

• Cross-check findings against Maestro state so you do not propose work already

accepted, dismissed, measured, or covered by active tasks.

• Re-propose every finding still seen with maestro harness propose

(signatures: reference/cli.md). Use one stable

--topic per finding so the verb merges repeats, and end the --evidence

text with a leverage estimate:

impact/effort/confidence: <H|M|L>/<H|M|L>/<H|M|L>.

Completion criterion: every surviving finding has a maestro harness propose

record with stable topic, concrete evidence, and leverage estimate; every

finding that failed refutation or Maestro-state cross-check is dropped.

Evidence

Each proposal needs concrete evidence: file paths, line numbers, command output,

or exact artifact names, plus the closing impact/effort/confidence estimate

(H, M, or L each) so the backlog ranks without re-deriving it. Do not

file style opinions without a repo-specific impact and a way to verify the

improvement.

Hand-off

Pipeline: [maestro-audit] -> maestro harness apply -> maestro-card

Architecture pipeline: `[maestro-audit: architecture report] -> maestro-design

(deepening-candidate + grilling + domain-model) -> maestro-card`

Next: proposals filed -> inspect with maestro harness list; accepted proposals

spawn normal tasks through maestro harness apply <id>.