tt-workflow-audit

Contents

• CRITICAL: the contract is non-negotiable
• How this differs from the other audit skills
• When to use / when not
• Workflow
  • Step 0 — Locate the project + scope (parent, inline)
  • Step 1 — Read project-invariant context once + partition (parent, inline)
  • Step 2 — Fan out read-only analysis
  • Step 3 — Aggregate into a risk register (parent, plain code/reasoning)
  • Step 4 — Present the register (parent)
  • Step 5 — Optional write-back (parent only, gated)
  • Resumability
• Anti-patterns
• Quality checklist
• Resources
  • references/
  • Related skills
• Key principles

Reference files (open one when a step points to it):

• references/workflow-tasktracker-contract.md: Workflow ↔ TaskTracker Contract

A tasktracker-native, project-wide parallel audit. It is the first concrete skill in the tt-workflow-* tier — the "parallel and tasktracker-correct" quadrant that the sequential tt-* skills don't cover.

The shape is a hybrid: the parent (this session) scouts and partitions inline, fans the analysis out — one Workflow run when that tool is available, otherwise batches of parallel Agent calls — then does all writes in the tail. The parallel agents only read and report.

CRITICAL: the contract is non-negotiable

Read references/workflow-tasktracker-contract.md before running. It is the shared contract for every tt-workflow-* skill, grounded in verified facts about the live system.

The one rule you cannot break:

The PARENT orchestrates (through a Workflow script, or directly with Agent calls).
Parallel agents are READ/ANALYZE-ONLY and return schema output.
The PARENT (this main-loop session) performs ALL tasktracker writes — serially.

Why (verified): the active task is a single process-global pointer, parallel agents — workflow agent() calls and Agent subagents alike — share one session id + one MCP process, and the shared stdio MCP cannot attribute a tool call to a specific agent. So no agent may call setActiveTask or any write-gated tool — it would clobber the shared pointer and bill time to the wrong task. Reads are fine (gate-exempt and reachable in background runs, probe-verified).

How this differs from the other audit skills

Use this when the project is in tasktracker AND you want findings to become tracked work. Use the others for pure-report or metrics-only runs.

When to use / when not

Use it when the job is large, embarrassingly parallel, read/analyze-heavy, with aggregable per-unit output: audit every file/component, find all architecture drift or duplicate tasks, a per-file tech-debt sweep, a coverage/security-surface scan.

Don't use it when the work is sequential or must branch on results mid-run (a fixed fan-out can't adapt mid-flight — use plain subagents one at a time), or when the project isn't in tasktracker (use /codebase-audit).

Workflow

Step 0 — Locate the project + scope (parent, inline)

1. tasktracker_listProjects({search})  (or use the argument hint) → project id.
2. tasktracker_getProject({projectId}) → understand the project.
3. Decide the AUDIT MODE (argument or ask):
   - architecture-drift   → inputs from scanArchitectureDrift / listArchitectureComponents
   - duplicate-backlog    → detectDuplicates / auditDuplicates over the task tree
   - file-risk            → per-file tech-debt / complexity / smell sweep
   - coverage-gaps        → per-module test-coverage analysis
   - security-surface     → per-entrypoint security review
   - (compose modes if the user wants a full sweep)

Step 1 — Read project-invariant context once + partition (parent, inline)

Read the things every agent would otherwise re-fetch (principles, architecture components, the task tree, the file list) once, in the parent, and pass them into the agents as data (contract R3). Then build the partition list — the unit of parallelism:

• file-risk → a list of files/dirs (glob the repo; group into balanced partitions).
• architecture-drift → the registered components.
• duplicate-backlog → the task tree (or sub-trees).
• coverage-gaps / security-surface → modules / entrypoints.

Scope the partitions inline, then fan out.

Step 2 — Fan out read-only analysis

Pick the engine from your tool list (contract, "Tool availability"):

• Workflow is in your tool list → one Workflow run (2a).
• It isn't → batches of parallel Agent calls (2b). Workflow is opt-in, so this is the common case; it is not a reason to stop.

Both engines give every partition the same read-only prompt and collect the same FINDING shape, so Step 3 onward doesn't change. The agent prompt MUST forbid setActiveTask and every write tool.

2a — With the Workflow tool

Give Workflow a script that parallel()s (or pipeline()s) one read-only agent per partition, each returning schema-checked findings. Skeleton:

export const meta = {
  name: 'tt-workflow-audit-run',
  description: 'Read-only parallel audit fan-out; parent does all tasktracker writes',
  phases: [{ title: 'Audit' }],
}

const FINDING = {
  type: 'object', additionalProperties: false,
  required: ['partition', 'findings'],
  properties: {
    partition: { type: 'string' },
    findings: {
      type: 'array',
      items: {
        type: 'object', additionalProperties: false,
        required: ['title', 'severity', 'location', 'detail'],
        properties: {
          title:    { type: 'string' },
          severity: { type: 'string', enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
          location: { type: 'string', description: 'file:line or component/task id' },
          detail:   { type: 'string' },
          suggestedFix: { type: 'string' },
        },
      },
    },
  },
}

phase('Audit')
// `args` carries {partitions, invariantContext} passed in by the parent.
const results = await parallel(
  args.partitions.map((p) => () =>
    agent(
      `Audit partition "${p.id}" of project ${args.projectName}. Mode: ${args.mode}.
Context (already read — do NOT re-fetch): ${JSON.stringify(args.invariantContext)}
Scope: ${JSON.stringify(p.scope)}
READ ONLY. Report findings against the schema. You MUST NOT call setActiveTask or ANY tasktracker write tool (no create/update/log/batch). Reads are fine.`,
      { label: `audit:${p.id}`, phase: 'Audit', schema: FINDING }
    )
  )
)
return { findings: results.filter(Boolean).flatMap((r) => r.findings) }

Pass args as real JSON ({partitions, invariantContext, projectName, mode}). For a write-heavy variant that edits code, add isolation: 'worktree' and have agents return integrationIntents (contract R6) — but a pure audit is read-only and needs no worktrees.

No Date.now() / Math.random() / new Date() in the script (contract R5). Vary agent labels by partition id, not RNG.

2b — Without the Workflow tool (parallel Agent calls)

The parent runs the same fan-out itself:

1. Checkpoint first. Write the checkpoint file (see Resumability) with every partition id, and tell the user its path.
2. Dispatch a batch of up to 8 partitions as one message holding one Agent call per partition, so the batch runs concurrently. Each call:
   • subagent_type: "Explore" — read-only by construction (no Write, Edit or Agent);
   • description: "audit <partition id>";
   • prompt: the per-partition prompt from the 2a script, filled in for this partition (same context, scope and write prohibition), plus: "Read the files in scope in full. Reply with ONLY a JSON object of this shape, no prose:" followed by FINDING as JSON.
3. Collect. Agent subagents run in the background: wait until every agent in the batch has sent its completion notification. Parse each reply and check it against FINDING (required keys, the severity enum). For a malformed reply, SendMessage that agent once asking for the JSON only; if it is still malformed, mark the partition failed. Add each valid result to the checkpoint as it lands.
4. Repeat with the next batch until every partition has a result or is marked failed. Re-dispatch failed partitions once; any still failing are uncovered and Step 4 says so (contract R8).

The concatenated findings are what the workflow would have returned.

Step 3 — Aggregate into a risk register (parent, plain code/reasoning)

Collect the fan-out's findings, dedupe (same file:line / same component) and rank by severity. This is ordinary parent-side work — not an agent, not a write.

Step 4 — Present the register (parent)

Show the user the ranked register: counts by severity, the top findings with location + suggestedFix. If coverage was bounded (sampled, top-N, partitions that failed), state what was dropped (contract R8) — never imply full coverage silently.

Step 5 — Optional write-back (parent only, gated)

If the user wants findings tracked:

1. Confirm with the user (this writes to PRODUCTION).
2. Ensure a "Bug Fix" phase exists (or create one — createTask/createPhaseFromTemplate are planning-exempt).
3. tasktracker_setActiveTask(<Bug Fix phase or coordination task>)   ← parent owns the pointer
4. tasktracker_batchCreateTasks(register.map(toFixTask))             ← planning-exempt, atomic
5. For findings worth an insight: tasktracker_logDefect(...)         ← gated; needs the active task set in (3)
6. tasktracker_clearActiveTask()

Dry-run/report mode is the default for any first run; only create tasks after the user sees the register and confirms. Never batchDelete* from an audit.

Resumability

• Workflow path: the run is journaled. If a run is interrupted (rate-limit, crash, network), resume it with Workflow({scriptPath, resumeFromRunId}) — completed partitions return cached results; only the unfinished ones re-run.
• Agent path: there is no journal and no resumeFromRunId. The checkpoint replaces it: a JSON file tt-workflow-audit-<projectId>-<mode>.json in the session scratchpad (or the system temp directory when there is none), holding the partition list and each finished partition's validated result. On a re-run for the same project and mode, or one given that path, read the checkpoint first and dispatch only the partitions without a result. It is a local file because the audit writes nothing to tasktracker before the user has seen the register (Step 5); a resume therefore needs the same machine, or the user handing over the file.

Either way, resuming beats re-running the whole scope — the main reason to use this skill for large audits.

Anti-patterns

• ❌ An agent calling setActiveTask or any write tool. Agents read and report; the parent writes.
• ❌ Each agent re-reading principles/architecture/the task tree. Read once in the parent, pass down.
• ❌ Date.now()/Math.random()/new Date() in the workflow script (breaks resume).
• ❌ Stopping, or auditing serially, because Workflow isn't in the tool list. Use the Agent fan-out (2b).
• ❌ On the Agent path, one agent per message (serial) or all partitions in one message (unbounded). Batch up to ~8.
• ❌ Editing a locked phase body with findings. Route to a sub-task (parent) or a Bug-Fix-phase task.
• ❌ Creating fix tasks in prod before the user has seen the register and confirmed.
• ❌ Silently capping coverage (top-N / sampling / failed partitions) without saying so.
• ❌ Running this as an Agent-dispatched subagent — Workflow is main-loop-only, and the parent must be the session that owns the writes; invoke this skill in the main session.

Quality checklist

• Project + audit mode resolved (Step 0).
• Project-invariant context read ONCE in the parent and passed into agents as data.
• Partition list built before the fan-out.
• Engine picked from the tool list: Workflow if listed, else batched Explore Agent calls with a checkpoint.
• Every agent prompt forbids setActiveTask + all write tools; agents returned schema findings only (validated by the parent on the Agent path).
• Workflow path: no Date.now()/RNG in the script; labels vary by partition id.
• Findings deduped + ranked into a risk register (parent-side).
• Bounded coverage (if any) disclosed, not silent.
• Write-back (if any) done by the parent with an active task set, after user confirmation; dry-run first.
• On interruption, resumed (resumeFromRunId, or the checkpoint) rather than re-run from scratch.

Resources

references/

• workflow-tasktracker-contract.md — the shared contract every tt-workflow-* skill obeys (tool availability and the Agent fallback, parent-owns-writes, read-only agents, locked body, no Date/RNG, worktree intents, prod safety, MCP reachability). Read it first.

Related skills

• /workflow-guide — routes read-only audits at scale here.
• /codebase-audit, /adversarial-reviewer --codebase, /code-quality-audit — non-tasktracker / report-only audit alternatives.
• /tt-create-plan, /tt-implement-plan — where the fix tasks this audit creates get planned and executed.

Key principles

1. Parent owns every tasktracker write. Agents read and report.
2. Scout inline, fan out, write in the tail. Hybrid orchestration.
3. Read project-invariant context once. Don't fan out N× identical reads.
4. Resumable. A journaled Workflow run, or the checkpoint on the Agent path; resume on interruption.
5. Disclose coverage. No silent truncation.
6. Write-back is gated. Production writes only after the user sees the register and confirms.