tdmcp-quality-audit

Use this skill for broad repository quality campaigns. It coordinates existing tdmcp specialists instead of replacing them: tdmcp-test-coverage handles focused coverage waves, and td-feature-qa handles tool/CLI/docs/bridge boundary QA.

Execution mode: hybrid fan-out/fan-in

This environment runs coordinated sub-agents rather than TeamCreate. Spawn the independent auditors in parallel, then fan their reports into one lead-owned plan. Implementation happens in small waves after QA verifies the findings.

Agent roster

Agent	Focus	Output
tdmcp-quality-audit-lead	scope, orchestration, shared edits, wave plan	_workspace/quality-audit/00_scope.md, 05_plan.md
tdmcp-command-auditor	scripts, Makefile, CI, CLI command health	_workspace/quality-audit/01_commands.md
tdmcp-security-auditor	trust boundaries, raw Python, env redaction, package safety	_workspace/quality-audit/02_security.md
tdmcp-ux-flow-auditor	first-run, docs-to-command parity, CLI help/errors	_workspace/quality-audit/03_usability.md
tdmcp-refactor-test-auditor	coverage gaps, weak tests, complexity, refactor seams	_workspace/quality-audit/04_refactor_tests.md
tdmcp-quality-qa	verifies evidence and first patch wave	_workspace/quality-audit/06_qa.md

Phase 0 - Context check

1. Read AGENTS.md, CLAUDE.md, package.json, Makefile, .github/workflows/*.yml, vitest.config.ts, and existing _workspace/quality-audit/ reports.
2. Decide run mode:
   • no quality workspace: fresh audit;
   • existing reports + user asks to continue/fix/re-run: partial re-run;
   • new broad request: archive prior reports under _workspace/quality-audit/archive/<timestamp>/ before a fresh audit.
3. Check git status. Do not revert unrelated user changes.

Phase 1 - Scope and command policy

Create _workspace/quality-audit/00_scope.md with:

• requested scope;
• current branch and dirty-state summary;
• commands that are safe one-shot;
• commands requiring timeout;
• commands requiring TouchDesigner, hardware, network, or credentials;
• commands that are publish/destructive and must not run without explicit user approval.

Command policy:

• Select the command runner before executing gates:
  • if command -v rtk >/dev/null 2>&1 succeeds, use rtk for shell commands and follow local repo instructions such as rtk proxy zsh -lc for pipelines or shell control flow;
  • if rtk is unavailable, record that fallback in 00_scope.md and run the same commands through the normal shell/Codex exec path without failing the audit solely because the wrapper is missing.
• Safe baseline: npm run typecheck, npm run build, ./node_modules/.bin/biome check ., npm test, npm run validate:recipes, npm run test:bridge, npm run docs:build, make complexity, npm run deps:check, npm run coverage:harness.
• Classify before running: dev, start, docs:dev, docs:preview, smoke:live, docs:clips, import:bottobot, prepublishOnly, npm publish, tag/push/version commands, and any server command.
• Long-running commands need timeout, readiness probe, and cleanup.
• TouchDesigner and hardware commands are UNVERIFIED when the bridge/device is unavailable; they are not failures by themselves.

Phase 2 - Parallel audit

Spawn the four auditors in parallel:

1. tdmcp-command-auditor
2. tdmcp-security-auditor
3. tdmcp-ux-flow-auditor
4. tdmcp-refactor-test-auditor

Each report must use PASS / FAIL / UNVERIFIED buckets and include file:line or command evidence. Avoid generic recommendations that cannot become a patch or a test.

Phase 3 - Synthesis

The lead reads all reports and writes _workspace/quality-audit/05_plan.md:

• deduped findings;
• severity and confidence;
• first safe patch wave;
• deferred items requiring TD, hardware, network, or user credentials;
• suggested tests and exact commands;
• owner for each item.

Patch waves should be small:

• Wave A: regression tests for concrete security/CLI/tool behavior.
• Wave B: behavior-preserving refactors guarded by tests.
• Wave C: command/CI/docs harness improvements.
• Wave D: live TouchDesigner/hardware verification.

Phase 4 - QA before edits

Run tdmcp-quality-qa against the reports. It must reject:

• claims without evidence;
• command passes with no command output;
• weakened test thresholds;
• broad rewrites without failing tests or measurable risk;
• unverified live checks reported as passing.

Phase 5 - Implement a wave

Only after QA, implement the smallest useful wave. For coverage-heavy work, invoke tdmcp-test-coverage and keep writers on disjoint test files. For boundary quality issues, invoke td-feature-qa. After edits, run narrow tests first, then the relevant gates from Phase 1.

Phase 6 - Final report

Update _workspace/quality-audit/06_qa.md with final command results and report:

• what was fixed;
• what was tested;
• what remains FAIL;
• what remains UNVERIFIED and why;
• next wave recommendation.

Error handling

• Retry deterministic local command failures once after checking dependencies.
• If dependencies are missing, run npm ci only when appropriate for the checkout and record that it was required.
• If generated files change from docs/build commands, inspect the diff before keeping it.
• Do not run publish, tag, push, credential, destructive, or hardware-control commands without explicit approval.

Test scenarios

Normal flow: user asks for a complete quality audit. The lead creates 00_scope.md, four auditors run in parallel, QA verifies evidence, Wave A adds two CLI/config security regression tests, and gates pass. The final report keeps TouchDesigner live smoke as UNVERIFIED if the bridge is offline.

Error flow: docs:build regenerates docs/reference/tools.md and fails because a tool schema is broken. The command auditor records FAIL, the lead routes the boundary to td-feature-qa, a focused test locks the schema behavior, docs build is re-run, and the final report names the fixed file and command.