tier-workflow

name

tier-workflow

description

Use when the orchestrator needs to resolve any mode-sensitive decision for the current TPM task — which reviewer dispatch pattern to invoke, how to aggregate verdicts, whether to run merge-resolver and QA, what to name Step 6b cleanup sessions. Encapsulates ALL fast / standard / prod tier policy so the orchestrator stays lean and `skills/dispatch-session/` stays mechanism-only. Required for the orchestrator agent at every tier-variant branch point.

Tier Workflow

Your job: given the mode: field recorded in .tpm/STATE.md (fast, standard, or prod), tell the orchestrator exactly which behavior to apply at each mode-sensitive decision point. This skill is pure policy and cross-references — it never duplicates the shell snippets that live in skills/dispatch-session/SKILL.md. The orchestrator consults tier-workflow to decide WHICH dispatch block to invoke; dispatch-session provides the HOW.

The three tiers exist to let the user trade rigor for speed:

• fast — low-risk / exploratory work. One reviewer, no merge-resolver, no QA. Conflicts escalate to the user.
• standard — today's flow. Adversarial trio, merge-resolver on conflict, QA at end of feature.
• prod — standard plus two new agents: Principal Engineer (BLOCKING philosophy auditor) and End-User Simulator (ADVISORY end-to-end exerciser).

Unresolvable mode field

If .tpm/STATE.md's frontmatter mode: field is missing, empty, mis-cased (e.g. Fast, PROD), or anything other than exactly fast, standard, or prod, the orchestrator halts and asks the user to resolve it — it does NOT silently default to standard, infer from context, or invent a new tier name. Resolution happens by the user re-running /tpm-start with an explicit --mode=... (fresh task) or by hand-editing STATE.md to a valid lower-case value (resume). Only the three tier names defined here are valid.

Tier summary

Tier	Reviewers	Merge-resolver	QA	Extra agents	Blocking layers
fast	1 reviewer (adversarial-reviewer.md)	skip	skip	—	1
standard	trio (blind / edge / acceptance)	dispatch	run	—	3
prod	trio + Principal Engineer (blocking) + End-User Simulator (advisory)	dispatch	run	principal-engineer, end-user-simulator	4

The "Blocking layers" column counts only layers whose verdict can flip the overall result to REJECTED or CHANGES_REQUESTED. End-User Simulator is intentionally absent from the prod count because its findings are advisory — see ## Verdict aggregation.

Per-tier reviewer dispatch

For each tier, the orchestrator invokes one or more reviewer dispatch blocks documented in skills/dispatch-session/SKILL.md. This skill says WHICH block; dispatch-session owns the aoe add / aoe send / per-session Monitor mechanics.

fast

Dispatch a single reviewer session using the all-in-one agents/adversarial-reviewer.md persona (per D-02). The orchestrator invokes the single-reviewer block from skills/dispatch-session/SKILL.md (under its ## Tier-specific dispatches group). The reviewer writes .tpm/REVIEW.md directly — no per-layer files, no combined-verdict aggregation step. One worktree, one session, one verdict.

standard

Dispatch the adversarial trio in parallel (blind / edge / acceptance) using the existing ## Dispatching the Three Reviewers block from skills/dispatch-session/SKILL.md. Each layer writes its own .tpm/REVIEW-<layer>.md. The orchestrator waits for all three Agent tool calls to return, aggregates per ## Verdict aggregation below, and writes the combined .tpm/REVIEW.md.

prod

Dispatch the standard trio (## Dispatching the Three Reviewers block in skills/dispatch-session/SKILL.md) plus:

• Principal Engineer — invoke the Principal Engineer dispatch block from skills/dispatch-session/SKILL.md. Writes .tpm/REVIEW-principal.md. BLOCKING.
• End-User Simulator — invoke the End-User Simulator dispatch block from skills/dispatch-session/SKILL.md. Writes .tpm/END-USER-REPORT.md. ADVISORY.

All five reviewers share the implementer's worktree and are dispatched in parallel as Agent subagents; the orchestrator waits for all five tool calls to return before aggregating.

No-philosophy fallback

The Principal Engineer relies on skills/philosophy-discovery/SKILL.md to locate philosophy sources (./CLAUDE.md and ./.claude/skills/**/SKILL.md) from the worktree. Per D-05, the fallback applies only when the bundle is fully empty — neither ./CLAUDE.md nor any ./.claude/skills/**/SKILL.md exists. In that single case the Principal Engineer's verdict is APPROVED with a "no philosophy to audit against" note in the body and does NOT block. A partial bundle (e.g. CLAUDE.md present but no .claude/skills/, or vice versa) is still a non-empty bundle and yields a normal Principal Engineer verdict audited against whatever sources were found — APPROVED / CHANGES_REQUESTED / REJECTED as usual. The orchestrator therefore treats the prod-tier Principal Engineer layer as effectively a no-op ONLY when there is nothing at all to audit against; any source at all re-enables blocking behavior.

Verdict aggregation

Per D-04. The orchestrator aggregates only BLOCKING layers; advisory findings are appended verbatim but never change the verdict.

Who writes .tpm/REVIEW.md: in fast tier, the single reviewer writes .tpm/REVIEW.md directly — there are no per-layer files and no aggregation step. In standard and prod, the orchestrator aggregates the per-layer .tpm/REVIEW-*.md files into a combined .tpm/REVIEW.md after all reviewer sessions have completed.

• fast — the single reviewer's verdict from .tpm/REVIEW.md IS the overall verdict. No aggregation step.
• standard — aggregate the three layer verdicts from .tpm/REVIEW-blind.md, .tpm/REVIEW-edge.md, .tpm/REVIEW-acceptance.md:
  • any REJECTED → overall REJECTED
  • else any CHANGES_REQUESTED → overall CHANGES_REQUESTED
  • else APPROVED
• prod — aggregate four BLOCKING layers: blind, edge, acceptance, principal (.tpm/REVIEW-principal.md). Same precedence rule (any REJECTED → REJECTED; else any CHANGES_REQUESTED → CHANGES_REQUESTED; else APPROVED). End-User Simulator findings from .tpm/END-USER-REPORT.md are recorded separately as advisory under a ## End-User Simulator Findings (advisory) section in the combined .tpm/REVIEW.md and re-surfaced verbatim in the PR body at Step 10. They never flip the verdict — they do not block merge.

Merge gate

Triggered when git merge --no-ff feature/${TASK_SLUG}-${TASK_ID} reports a conflict during integration.

• fast — do NOT dispatch a merge-resolver (per D-03). Escalate directly to the user: report the conflicting files, the incoming task summary, and pause until the user resolves manually or instructs how to proceed. This matches fast tier's "low-overhead, exploratory" intent.
• standard — dispatch a merge-resolver session using the existing ## Dispatching a Merge Resolver block in skills/dispatch-session/SKILL.md. Wait for its session.idle and consume .tpm/MERGE-${TASK_ID}.md.
• prod — same as standard: dispatch the merge-resolver block from skills/dispatch-session/SKILL.md. Prod adds review rigor, not merge rigor — the merge-resolution path is identical.

QA gate

Triggered after the final task in the wave plan has merged cleanly to the integration branch.

• fast — skip. No QA-REPORT.md is produced. The user validation step (Step 9) still runs.
• standard — dispatch the QA validator using the existing ## Dispatching a QA Validator block in skills/dispatch-session/SKILL.md. QA writes .tpm/QA-REPORT.md.
• prod — same as standard: dispatch the QA validator block from skills/dispatch-session/SKILL.md. End-User Simulator does NOT replace QA — they exercise different surfaces (per-task new-feature/happy-path vs whole-feature integration).

Step 6b session cleanup naming

Reviewers are Agent subagents — they produce no AoE sessions. Their .tpm/REVIEW-*.md files on disk are the only residue and stay as audit trail. The only AoE session to clean up per task is the implementer (impl-${TASK_ID} → renamed to task-${TASK_ID} anchor). Merge-resolver and QA sessions (when dispatched) follow the existing orchestrator cleanup pattern and are not tier-specific.

Planner tier-specific behavior

The planner agent (agents/planner.md) adapts its planning process based on the tier. The tier is detected from the orchestrator's initial message or from .tpm/STATE.md's mode: field.

fast

• Brainstorming: skipped. The planner designs directly from codebase research.
• User confirmation: skipped. No interactive questions before decomposition.
• PLAN.md output: no ## Brainstorm Summary section. Architecture decisions are stated directly.
• Rationale: fast tier is for low-risk/exploratory work where speed matters more than exhaustive exploration.

standard

• Brainstorming: the planner invokes skills/brainstorming/SKILL.md after codebase research at Step 2 (as part of Step 3). Produces alternatives, tradeoffs, constraints, and a recommended approach.
• User confirmation: the planner presents up to 5 numbered questions covering non-obvious choices (Step 4). Questions are structured (yes/no/preference), not open-ended. The planner waits for answers before decomposing.
• PLAN.md output: includes a ## Brainstorm Summary section between Overview and Architecture Decisions.
• Rationale: standard tier balances thoroughness with reasonable overhead.

prod

• Brainstorming: same as standard. The brainstorming skill is invoked identically.
• User confirmation: same as standard. The planner presents structured questions and waits.
• PLAN.md output: same as standard; includes ## Brainstorm Summary.
• Rationale: prod tier adds rigor at the review/QA stages, not at the planning stage. The brainstorming process is already thorough enough for both standard and prod.

Review cycle limits

Every implementation pass (including revisions after review findings) must be followed by a review. A revision is itself a new implementation that can introduce new issues, so it gets the same review treatment as the original.

The maximum number of implement → review cycles per task depends on the tier:

Tier	Max cycles	Behavior at limit
fast	1	Implement once, review once. If not APPROVED, escalate to user immediately.
standard	3	Up to 3 implement/review rounds. If still not APPROVED after 3 cycles, escalate.
prod	10	Up to 10 implement/review rounds. Prod tolerates more iteration for high-stakes work.

The orchestrator tracks cycle count per task in STATE.md (e.g. review_cycle: 2). When the limit is reached without APPROVED, the orchestrator escalates to the user with the full review history.

Cycle counting: the initial implementation + its first review = cycle 1. A revision triggered by CHANGES_REQUESTED + its review = cycle 2, and so on. REJECTED at any cycle is an immediate escalation regardless of the remaining cycle budget.

Anti-patterns

• Duplicating dispatch shell snippets instead of referencing skills/dispatch-session/. This skill is policy-only. If you ever find yourself writing an aoe add or aoe send line here, stop — that snippet belongs in skills/dispatch-session/SKILL.md and you should be cross-referencing the block by section name instead.
• Letting the orchestrator inline tier logic instead of calling this skill. Every mode-sensitive decision in agents/orchestrator.md should defer here ("consult skills/tier-workflow/SKILL.md using the mode: field in .tpm/STATE.md"). If the orchestrator starts enumerating reviewer files, blocking-layer counts, or per-tier session names inline, the tier matrix has been duplicated — collapse it back to a one-line pointer.
• Treating End-User Simulator findings as blocking. They are advisory by design (D-04). They surface in REVIEW.md and the PR body but never change the aggregated verdict.
• Aggregating REVIEW.md in fast tier — there are no per-layer files to aggregate. The fast reviewer writes .tpm/REVIEW.md directly. Any aggregation step is a symptom of reusing the standard/prod code path unconditionally; branch on mode: before the aggregation call.
• Inventing a fourth tier or a per-decision override. The three tiers are the contract. If a task needs different behavior, change the tier on the next /tpm-start, not mid-flight.