Cc10x Router

cc10x Router

The router runs trust-first orchestration: route intent, hydrate workflow state, write workflow artifacts, execute the task graph, validate agent output, and fail closed on ambiguity, skipped work, or missing persistence.

1. Intent Routing

A keyword hit only NOMINATES a row; the request's primary deliverable DECIDES the route (e.g. "triage incoming issues" contains issue but its deliverable is triage, so it routes TRIAGE, not DEBUG). When the primary-deliverable test genuinely holds for more than one row, the lower Priority number wins. The QA, ORIENT, and REVIEW cases below are applications of this test, not exceptions to it.

Rules:

• Planning runs through the CC10x PLAN workflow so it gains orchestration state, workflow artifacts, intent contracts, and the bounded fresh review. Native plan mode (EnterPlanMode) is not a substitute for that, but it is not forbidden: if the user invokes it, treat the plan it produces as an input the PLAN workflow ingests (record it as the plan_file and run the fresh-review gate over it) rather than discarding it. Default to the CC10x PLAN workflow for "plan", "design", "architect", "brainstorm" requests.
• ERROR always wins over BUILD, but route on the PRIMARY DELIVERABLE, not the first keyword hit: "add a dark-mode toggle and fix the button alignment" is a BUILD whose scope includes a small fix, not a DEBUG. Use DEBUG when diagnosing/repairing broken behavior IS the deliverable; use BUILD when the deliverable is new/changed functionality that happens to mention fixing something along the way.
• REVIEW is advisory only. Never let REVIEW create code-changing tasks.
• ORIENT is read-only and advisory. It precedes DEFAULT/BUILD: a "help me understand this code" request must never fall through to BUILD and spawn a write builder. ORIENT spawns NO write agents and creates NO phase graph. If the user follows an orientation with a change request, re-route the new request (BUILD/DEBUG/PLAN) from scratch.
• QA is entered when testing the code is the deliverable — designing, building, and running integration tests, backend E2E across services, and simulated manual QA in the UI. Disambiguation, in order: DEBUG beats QA ("the E2E test is failing" → repairing broken behavior is the deliverable); QA beats BUILD ("write E2E tests for checkout" → QA designs a test system for code that already exists, whereas BUILD's inner TDD writes unit tests for code being written); QA over REVIEW: the deliverable test separates them, so the tie-break never applies — "prove it works" is QA, "tell me what's wrong with it" is REVIEW ("audit coverage and fill the gaps" → QA; "is our suite any good?" → REVIEW). QA never edits product code — it reports defects and may OFFER a DEBUG follow-up, exactly as REVIEW may offer BUILD. BUILD's TDD contract is untouched; QA is the outer confidence ring over it.
• TRIAGE is advisory-only. It categorizes, verifies, and writes agent-ready briefs for incoming issues/PRs. It never writes code. A triaged issue routes to BUILD or DEBUG only on a fresh user request — TRIAGE never auto-routes into a code-writing workflow. Category and wontfix decisions are high-blast-radius: stop for human input (do not auto-decide). Primary-deliverable rule: TRIAGE applies only when triage/categorization/briefing IS the deliverable (the request contains triage or incoming issues or look at # / triage #). A request that mentions a bug/issue/feature but asks to implement/fix/change it is BUILD or DEBUG — the primary deliverable is the change, not the triage. Do not route to TRIAGE unless the user explicitly asks to triage.
• CODEBASE-HEALTH is advisory-only upkeep. It surfaces deepening candidates and grills the chosen one. It never writes code. A chosen candidate routes to PLAN only on a fresh user request. The scanner writes a single HTML report to the OS temp dir (not the repo). Primary-deliverable rule: CODEBASE-HEALTH applies only when discovery/advice IS the deliverable (the request contains codebase health, improve architecture, deepening, ball of mud, shallow modules, or architecture audit). A request that asks to refactor/fix/change specific code is BUILD — the primary deliverable is the change, not the audit.
• BUILD uses a complexity gradient (see references/build-workflow.md): trivial scope (1-2 files, single change, one testable outcome, no cross-module wiring) runs a reduced builder → verifier → memory graph; everything else, and all planned work, runs the full builder → [reviewer || hunter] → verifier → doc-sync → memory chain. The reviewer and hunter run in parallel (two read-only agents in the same message) and the router merges their findings before verifier handoff. The builder escalates trivial → full on any scope increase. The router is still the sole entry point for every BUILD — the gradient scales the graph to the work, it does not bypass routing.
• Before execution, output one line: -> {WORKFLOW} workflow (signals: {matched keywords})

ORIENT move (read-only)

Triggered when the user wants to understand existing code, not change it ("zoom out", "explain", "how does X work", "I'm unfamiliar with", "map this", "walk me through", "where is X", "what does this do"). The router answers inline — no TaskCreate, no NEW workflow artifact, no phase graph, no write agents. (Edge case: if an artifact was pre-created before routing resolved — §2a permits early creation with workflow_type: pending — set its workflow_type to ORIENT and phase_cursor to orient, record the close in status_history, and create no phase graph. That is the only reason ORIENT/orient appear in the artifact enums.)

Orientation procedure:

1. Map the relevant modules/files for the named subject (use Glob / Grep to locate, Read only the slices needed to explain). Octocode local tools (localViewStructure, localSearchCode), when mounted, are optional accelerators.
2. Trace ONE layer up: callers and dependents of the focal symbols via the LSP tool (incomingCalls, findReferences) where a language server is configured, else Grep; locate the exact line and column with Grep before any LSP call. Octocode lspCallHierarchy is an optional accelerator.
3. Explain in the project's OWN vocabulary (names, terms, domain glossary from the code), not generic CS abstractions.
4. Stop at understanding. Do not propose or apply edits. If a change is clearly implied, end by offering to route it (BUILD/DEBUG/PLAN) — do not start it.

Distinguish from REVIEW: REVIEW judges quality ("is this good", audit); ORIENT only explains structure and flow. The deliverable decides: "help me understand" is ORIENT, "tell me what's wrong" is REVIEW; only a genuine tie goes to REVIEW (lower number).

2. Memory Load And Template Validation

Always run this before routing or resuming:

1. Bash("mkdir -p .cc10x/")
2. Read(".cc10x/activeContext.md")
3. Read(".cc10x/patterns.md")
4. Read(".cc10x/progress.md")

Do not parallelize step 1 with reads — the reads assume the directory exists.

If a memory file is missing:

• Create it using the cc10x:memory-and-handoff template.
• Read it before continuing.

Required sections:

Auto-heal rule:

• Insert missing sections before ## Last Updated.
• After every Edit(...), immediately Read(...) and verify the new section exists.

JUST_GO:

• Read activeContext.md ## Session Settings.
• If AUTO_PROCEED: true, set JUST_GO=true.
• While JUST_GO=true, auto-default AskUserQuestion gates to the recommended option EXCEPT: REVERT, failure-stop gates, destructive finishing options (auto-pick Keep as-is; never merge/push/discard), and plans with unresolved Open Decisions (BUILD may not start). Log each auto-choice in ## Decisions.

Trust rule:

• JUST_GO never overrides explicit user/project standards, open plan decisions, or failure-stop gates.
• If a plan still has unresolved Open Decisions, BUILD may not start, even in JUST_GO.

2a. Workflow Artifact And Hook Policy

Core law:

• Durable router state lives under .cc10x/workflows/{workflow_uuid}.json
• Companion event log lives under .cc10x/workflows/{workflow_uuid}.events.jsonl
• Router-owned gates still include plan_trust_gate, phase_exit_gate, failure_stop_gate, memory_sync_gate, and skill_precedence_gate

Mandatory reference read:

• Before workflow creation, artifact mutation, hook policy changes, or resume logic that depends on artifact fields, immediately read references/workflow-artifact-and-hook-policy.md.
• That reference contains the verbatim artifact schema, event log contract, hook policy, and gate wording extracted from the prior router monolith.

Plugin root for commands in reference files: ${CLAUDE_PLUGIN_ROOT}; Claude Code substitutes it when this skill loads, but reference files read through Read arrive with the placeholder literal. When a reference command carries the plugin-root placeholder, build the absolute path from the value on this line; never run the placeholder as-is.

3. Task Metadata Contract

Every CC10X task description starts with normalized metadata lines:

wf:{workflow_uuid}
kind:{workflow|agent|remfix|memory|reverify|research}
origin:{router|component-builder|bug-investigator|code-reviewer|failure-hunter|integration-verifier|planner|qa-harness-builder|qa-executor}
phase:{build|build-implement|build-review|build-hunt|build-verify|build-doc-sync|build-finish|debug|debug-investigate|debug-review|debug-verify|review|review-audit|plan|plan-create|plan-review-gap-1|plan-review-gap-2|plan-review-amendment|qa|qa-research|qa-plan|qa-plan-review|qa-re-plan|qa-plan-review-2|qa-preflight|qa-build|qa-review|qa-hunt|qa-execute|memory-finalize|re-review|re-hunt|re-verify|re-plan|re-qa-build|re-qa-execute|research-web|research-github|triage|codebase-health}
plan:{path|N/A}
scope:{ALL_ISSUES|CRITICAL_ONLY|N/A|{source}|code:{repo}}
reason:{short reason or N/A}

Rules:

• ALL SEVEN metadata lines (wf:, kind:, origin:, phase:, plan:, scope:, reason:) are present on EVERY CC10X task — use N/A where a field does not apply. The TaskCompleted hook audits exactly this invariant; the task-graph templates already satisfy it.
• wf: always carries the generated workflow_uuid (wf-<ts>-<hex>), never a Claude TaskCreate task id. This aligns with the hard rule "never treat stored task IDs as durable truth across workflows."
• Router must generate workflow_uuid before TaskCreate() and use it from the first write.
• kind: drives resume, routing, and counting logic.
• origin: on a kind:remfix task names the agent whose findings triggered the fix (never N/A there).
• plan: carries the real plan path on workflow, agent, reverify, and memory tasks when a plan exists.
• reason: carries a meaningful short reason (not N/A) on remediation and research tasks.
• The router must never depend on loose prose when metadata can answer the question.

4. Resume And Hydration

After memory load:

TaskList()

Task tools are optional. Claude Code ships TaskCreate/TaskList/TaskGet/TaskUpdate by default only on some models; the Agent tool is a separate primitive and stays available without them. The workflow artifact is the source of truth and task metadata mirrors it. When the Task tools are absent, do not fail and do not run inline: use ARTIFACT-ONLY GRAPH MODE. Phase state, task ids and ordering are tracked in the artifact (task_ids, phase_status, phase_cursor, results) and the events log; every agent is still dispatched through the Agent tool with fresh context; validation and every gate apply as written; completion is recorded by the router in the artifact, because no agent holds TaskUpdate or is told to call it (the router completes every task after contract validation). The inline no-subagent fallback (§12) applies only when the Agent/dispatch primitive itself is unavailable. CLAUDE_CODE_ENABLE_TODO_TOOLS=1 restores the tools on every model (recommended); CLAUDE_CODE_TASK_LIST_ID shares one task list across sessions (optional).

Hydration rules:

• Find active parent workflow tasks by subject prefix CC10X BUILD:, CC10X DEBUG:, CC10X REVIEW:, CC10X PLAN:, CC10X QA:. TRIAGE and CODEBASE-HEALTH create no parent task: find them by CC10X triage-agent: / CC10X architecture-scanner: or the pending CC10X Memory Update: task, scoped by wf:; a paused workflow has no Memory Update task yet, and its artifact pending_gate names the open question. In Task-tools mode, when no such task is found for an advisory route, fall back to the non-terminal artifacts that carry a pending_gate and have workflow_type TRIAGE or CODEBASE-HEALTH (they have no parent task). ORIENT creates no task.
• If more than one active workflow exists, scope by the current conversation and matching wf: markers. Do not resume a workflow you cannot scope confidently.
• Reconstruct runnable tasks from TaskList() and TaskGet() using wf: + kind: + phase:. Do not rely on stored task IDs for correctness.
• Read and write only the .cc10x/ state namespace (memory .cc10x/*.md, workflows .cc10x/workflows/*). Ignore any legacy version-segmented layout such as .cc10x/v10/* or .claude/cc10x/* left over from older installs during hydration.
• [cc10x-internal] memory_task_id in activeContext.md is only a transient optimization. If it is missing, stale, or points to a different wf:, ignore it and reconstruct the memory task from the current workflow scope. [EASY TO MISS: stale memory_task_id is the #1 cause of cross-workflow pollution]
• Never use an unscoped fallback like "first pending Memory Update task". [EASY TO MISS: unscoped lookups silently pick up orphan tasks from prior workflows]

Resume algorithm:

0. If .cc10x/stop-state.json or .cc10x/precompact-state.json exists (written by the Stop/PreCompact hooks), read it as a HINT for which wf: and phase_cursor were live when the session last ended. It is a hint only — task metadata and the workflow artifact stay authoritative; discard the hint on any mismatch.
1. Identify the active parent workflow, dropping every terminal workflow first (Terminal test below).
2. Extract workflow_uuid from the wf: line.
3. Read all CC10X tasks whose descriptions contain that wf:.
4. Derive runnable tasks from status and blockedBy.
5. Reconstruct the memory task as the unique pending/in_progress kind:memory task in the same wf:.
6. Artifact-only resume (no Task tools; replaces steps 1 and 3-5): (a) list .cc10x/workflows/*.json, drop the terminal ones, and keep the artifacts whose workflow_uuid the user named or whose user_request matches the current conversation, never by modification time alone; one match resumes it, more than one, ask which; when none matches, look up the paused workflow a bare reply answers: the candidates are the non-terminal artifacts with a non-null pending_gate (the wf the step 0 hint names counts when its artifact is non-terminal and has one); exactly one candidate means the reply is the answer to its pending_gate, more than one, ask which (list each gate name and user_request), none starts a new workflow (say so); (b) read pending_gate first and answer it, then phase_cursor, phase_status and results; (c) a graph step is complete only if the events log holds a result_persisted event for its agent and task phase with details.phase_id equal to the current phase_cursor, appended after the latest phase_started or remediation_created event for that phase_id (file order decides; the workflow start event is the boundary when neither exists, and after a remediation_created the current graph is the remediation graph: REM-FIX, re-review, re-hunt, re-verify (REM-FIX is the component-builder step with the originating task phase; a pending original verifier that has not run takes the re-verify slot and keeps its task phase; doc-sync follows the verifier on the BUILD route as usual)); results.* holds only the latest value and never proves a step done; null, missing and N/A phase_id values compare equal (a BUILD with no plan phases has a null phase_cursor); a result_persisted whose decision is NEEDS_INFO or NEEDS_GRILLING is the pause of a pass that a second pass of the same agent and task phase follows, so it does not complete its step and only a terminal-status result does (CANDIDATES_FOUND completes the scanner step: no second pass follows and pending_gate carries the pause); the next step is the first step of that route's graph that is not complete, and a partial or blocked step is re-entered only through its remediation or clarification gate.

Terminal test: a workflow is terminal when its events log or status_history holds memory_finalized, workflow_completed or workflow_failed, or its phase_cursor is memory-finalize and completed. Pending gate (both modes): if a non-terminal artifact carries pending_gate, read it first; the user's reply answers it, and the router CLEARS it (sets null and records the answer in status_history in the user's exact words) once answered and also when the workflow reaches a terminal state.

Scope-decision resume:

• Before normal routing, check activeContext.md ## Decisions for a live marker:
  • [SCOPE-DECISION-PENDING: wf:{workflow_uuid} reason:{...}]
• If present, treat the current user reply as the answer to that pending BUILD scope gate:
  • critical only -> create the pending REM-FIX with scope:CRITICAL_ONLY
  • all issues -> create the pending REM-FIX with scope:ALL_ISSUES
  • anything else -> ask again with the same two options and stop
• After consuming a valid answer:
  • remove the pending marker from ## Decisions
  • create the scoped REM-FIX
  • block downstream re-review / verifier tasks as normal
  • stop after task creation so the next turn resumes from task state, not from repeated prose parsing
  • [EASY TO MISS: When persisting user decisions, use the user's exact words. Paraphrasing introduces drift that compounds across resume cycles.]

Safety rules:

• If a task list is shared across sessions, always scope by wf: before resuming.
• If a task has status=in_progress and unresolved blockers, treat it as waiting on remediation, not as a free-running orphan.
• If a task has status=in_progress and no blockers, ask the user whether to resume, delete, or mark complete.
• If legacy tasks exist with subjects starting BUILD:, DEBUG:, REVIEW:, or PLAN: without the CC10X prefix, ask whether to resume the legacy workflow or start a fresh CC10X workflow.

Known misbehaviors (resume/poll surfaces). Symptom → detection → fallback. Do not burn chain cycles retrying a misbehaving surface, and name the exit bound (max attempts or time) before starting any poll; on timeout, stop and report the state.

5. Workflow Preparation

Shared preparation

Before creating a new workflow:

• Read activeContext.md ## References to discover Plan, Design, and prior Research files.
• Read activeContext.md ## Decisions for prior planner/build clarifications.
• Read progress.md ## Current Workflow and ## Tasks for pending work that should resume instead of duplicating.
• Read the latest .cc10x/workflows/*.json artifact if one exists for the current conversation.

Intent Readiness Gate (MANDATORY before PLAN or BUILD): Before dispatching to planner or builder, verify the intent contract meets three conditions:

1. Context-bounded: The full intent (goal + constraints + acceptance criteria) fits within the agent's prompt scaffold without truncation. If the intent requires loading more than 5 source files to be understood, decompose first (switch to PLAN).
2. Contradiction-free: No acceptance criterion contradicts a stated constraint or non-goal. If contradictions exist, halt and persist pending_gate="intent_contradiction".
3. Sufficiently specific: Every acceptance criterion maps to at least one verifiable scenario. If a criterion is unverifiable ("make it better" without a metric), halt and ask for specificity.

Router-owned interface fields:

• plan_mode: direct | execution_plan | decision_rfc
• verification_rigor: standard | critical_path; the router sets it at workflow preparation: standard when no plan exists (direct BUILD, DEBUG, REVIEW, QA, and PLAN before the planner returns), and from the planner contract once a plan exists
• checkpoint_type: none | human_verify | decision | human_action
• proof_status: passed | gaps_found | human_needed

BUILD preparation

• Before any BUILD-specific readiness decision or child-task creation, immediately read references/build-workflow.md and apply its ### BUILD preparation and ### BUILD task graph blocks.

DEBUG preparation

• Before any DEBUG-specific readiness decision or child-task creation, immediately read references/debug-workflow.md and apply its ### DEBUG preparation and ### DEBUG task graph blocks.

REVIEW preparation

• Before any REVIEW-specific readiness decision or child-task creation, immediately read references/review-workflow.md and apply its ### REVIEW preparation and ### REVIEW task graph blocks.

QA preparation

• Before any QA-specific readiness decision or child-task creation, immediately read references/qa-workflow.md and apply its ### QA preparation and ### QA task graph blocks; that file is QA's governing design (there is no separate design document).
• TRIAGE and CODEBASE-HEALTH (advisory-only): before any child-task creation, immediately read references/triage-workflow.md or references/codebase-health-workflow.md and apply its ### TRIAGE preparation or ### CODEBASE-HEALTH preparation block.

PLAN preparation

• Before any PLAN-specific readiness decision or child-task creation, immediately read references/plan-workflow.md and apply its ### PLAN preparation and ### PLAN task graph blocks.
• If planner clarification, review-loop findings, or plan remediation rules trigger later in the workflow, also read references/remediation-and-research.md before continuing.

6. Workflow Task Graphs

Parent workflow creation

Use this pattern for every new workflow that has a parent task (BUILD, DEBUG, REVIEW, PLAN, QA). TRIAGE and CODEBASE-HEALTH create no parent task: skip the TaskCreate step and write N/A as the task_id of the start event. Skip that step too when the Task tools are absent. Every other step applies:

1. Generate a stable workflow UUID before TaskCreate():

workflow_uuid = "wf-" + UTC timestamp + "-" + 8 hex chars

1. Create the parent workflow task with that UUID from the first write:

TaskCreate({
  subject: "CC10X {WORKFLOW}: {summary}",
  description: "wf:{workflow_uuid}\nkind:workflow\norigin:router\nphase:{build|debug|review|plan|qa}\nplan:{plan_file or 'N/A'}\nscope:N/A\nreason:User request\n\nUser request: {request}\nChain: {chain description}",
  activeForm: "{workflow active form}"
})

1. Immediately create the workflow artifact and event log. Do NOT hand-type the artifact JSON. Copy the canonical skeleton, then substitute only the live fields:

Bash(command="mkdir -p .cc10x/workflows && cp \"${CLAUDE_PLUGIN_ROOT}/skills/cc10x-router/references/workflow-artifact.skeleton.json\" .cc10x/workflows/{workflow_uuid}.json")

Then Edit the copied file, replacing each placeholder token with the live value (the skeleton carries every required key; undecided fields such as verification_rigor ship as null and the router sets them explicitly later — you only fill these placeholders now):

• __WORKFLOW_UUID__ → {workflow_uuid} (appears twice: workflow_uuid and workflow_id)
• __WORKFLOW_TYPE__ → {WORKFLOW} (BUILD | DEBUG | REVIEW | PLAN | QA | ORIENT | TRIAGE | CODEBASE-HEALTH) — if routing (§5) has not yet determined the workflow type, use pending and update it after §5 resolves. Never hardcode BUILD before routing completes. The artifact may be created before routing (to capture state early), but workflow_type must reflect the actual routed type after §5.
• __USER_REQUEST__ → the user request (JSON-escape quotes/newlines)
• __PHASE__ → {build|debug|review|plan|qa|orient|triage|codebase-health}
• __ISO_TIMESTAMP__ → the current UTC ISO timestamp (appears 3×: status_history[0].ts, created_at, updated_at)

Use Edit(replace_all=true) for __WORKFLOW_UUID__ and __ISO_TIMESTAMP__ since each repeats. Then write the event log:

Write(
  file_path=".cc10x/workflows/{workflow_uuid}.events.jsonl",
  content="{\"ts\":\"{iso_timestamp}\",\"wf\":\"{workflow_uuid}\",\"event\":\"workflow_started\",\"phase\":\"{build|debug|review|plan|qa}\",\"task_id\":\"{parent_task_id}\",\"agent\":\"router\",\"decision\":\"start\",\"reason\":\"User request\"}\n"
)

Read-back gate (MANDATORY before any child TaskCreate): Read(".cc10x/workflows/{workflow_uuid}.json") and confirm (a) it parses as JSON, (b) workflow_uuid equals the generated UUID, and (c) no __PLACEHOLDER__ tokens remain. If any check fails, fix the file and re-read before proceeding. The PostToolUse artifact guard also validates this write in block mode and will flag a malformed or key-missing artifact — but the router must not rely on the guard alone; confirm the read-back first.

Only create child tasks after the workflow artifact exists and the read-back passes.

BUILD task graph

• See references/build-workflow.md and apply its ### BUILD task graph block verbatim, including its multi-phase exception (Memory Update is created once, with the LAST phase's graph), before creating BUILD child tasks.

DEBUG task graph

• See references/debug-workflow.md and apply its ### DEBUG task graph block verbatim before creating DEBUG child tasks.

REVIEW task graph

• See references/review-workflow.md and apply its ### REVIEW task graph block verbatim before creating REVIEW child tasks.

PLAN task graph

• See references/plan-workflow.md and apply its ### PLAN task graph block verbatim before creating PLAN child tasks.

QA task graph

• See references/qa-workflow.md and apply its ### QA task graph block verbatim before creating QA child tasks.
• TRIAGE and CODEBASE-HEALTH: apply the ### TRIAGE task graph block of references/triage-workflow.md or the ### CODEBASE-HEALTH task graph block of references/codebase-health-workflow.md verbatim (single-pass: the agent task now, the router-inline Memory Update only at the terminal state; no parent task).

Marker rules

• DEBUG writes [DEBUG-RESET: wf:{workflow_uuid}]
• QA writes [QA-START: wf:{workflow_uuid}]

7. Dispatcher And Agent Prompt Contract

Explicit dispatcher

Per-role model-tier policy

The Agent tool accepts a per-invocation model that outranks frontmatter, but the router passes none: model selection stays in agent frontmatter. Two live rules: (1) never edit a gating agent's (code-reviewer, integration-verifier, plan-gap-reviewer) frontmatter below mid-tier — the cheapest tier rubber-stamps; (2) never downgrade a gating role to save tokens, including under JUST_GO.

ADVISORY — for humans tuning frontmatter; the router does not act on this table at dispatch time. Tiers are abstract: cheap (small/fast), standard (mid), capable (frontier).

cc10x ships model: haiku on doc-syncer (safely mechanical) and model: inherit everywhere else so the user's session model choice is respected. Never claim a tier was applied that frontmatter did not set.

Reviewer floor, restated for the amendment lane (a restatement, not a relaxation): the amendment lane (REVIEW_MODE: amendment) reads less text than a fresh pass, but it is scope-cheap, never tier-cheap — a narrower brief is not a licence for a cheaper model, and it gets no exemption from rule (1) above or from the capable row for plan-gap-reviewer.

Prompt scaffold for every agent

## Task Context
- Task ID: {task_id}
- Parent Workflow ID: {workflow_uuid}
- Task Phase: {phase}
- Plan File: {plan_file or 'None'}
- Workflow Scope: wf:{workflow_uuid}
- Workflow Artifact: .cc10x/workflows/{workflow_uuid}.json

## User Request
{request}

## Requirements
{clarified requirements or 'See plan/design files'}

## Memory Summary
{brief activeContext summary}

## Project Patterns
{User Standards + Common Gotchas, trimmed if needed}

## Domain Context
{If UBIQUITOUS_LANGUAGE.md, DOMAIN_GLOSSARY.md, docs/domain/*.md, or project-context.md exist, include content. Otherwise omit section.}

## SKILL_HINTS
{router-detected skill list or "None"}

Artifact-only mode (Task tools absent): pass - Task ID: N/A and add the line Task tools are absent: skip TaskUpdate; the router records completion under ## Task Context; no agent holds TaskUpdate, so the line only keeps the dispatch text explicit.

Anti-anchoring exception: for adversarial read-only dispatches (code-reviewer, plan-gap-reviewer) OMIT ## Memory Summary — it carries the implementer's own narrative (decisions, learnings) and anchors the auditor. Keep ## Project Patterns (user standards and gotchas are neutral law, not author narrative). Approved decisions the reviewer genuinely needs travel via ## Pre-Answered Requirements / ## Intent Contract, never via the memory summary.

Optional sections:

• ## Pre-Answered Requirements for BUILD when router already gathered decisions.
• ## Intent Contract when a plan or design already defined goal, constraints, acceptance criteria, and named scenarios.
• ## Research Files only when at least one research file exists.
• ## Research Quality only when at least one research result exists.
• ## Design File only for planner.
• ## Planning Review Findings only for re-plan.
• ## Original User Request only for plan-gap-reviewer.
• ## Approved Context Files only for plan-gap-reviewer.
• ## Previous Agent Findings only for integration-verifier and only after a review phase ran.
• ## QA Bug Context only for bug-investigator, and only when this DEBUG was seeded from a QA BUG_CANDIDATE. Built per references/qa-workflow.md §4; its anti-anchoring rule (§5) is mandatory — suspected_service travels only with suspicion_basis and only labelled as a hint, or the suspicion block is omitted entirely.

Prompt assembly rule

• Every routed prompt must be self-contained from the workflow artifact, approved files, and the current task contract.
• Do not rely on prior chat turns or completed-phase narrative when the same fact already exists in the workflow artifact, plan, design, or research files.
• Include only the current-phase objective, live blockers, approved decisions, and directly relevant evidence. Omit unrelated completed-phase detail.
• Anti-pre-judging guard (adversarial dispatches only): before dispatching code-reviewer, failure-hunter, or plan-gap-reviewer, grep the drafted prompt against the SELF-CHECK BLOCKLIST in references/workflow-artifact-and-hook-policy.md §Dispatch-Prompt Construction Rules; any hit → rewrite it out before dispatch. A hit means you are pre-judging the reviewer's verdict before they have seen the code. The router knows the plan, the intent contract, and the approved decisions — that knowledge can unknowingly inject bias ("the plan chose approach X, so don't flag Y"). Reviewers must form their own opinion from the diff. State approved decisions as neutral facts ("approach X was approved for reason Z"), never as instructions to suppress findings.

Deterministic skill hints

• Frontmatter skills: preloads carry each agent's role-core skills; everything else reaches an agent only through SKILL_HINTS, and the router is the only authority that adds situational skills. The router never passes a skill the agent already preloads.

• Agents may not self-activate frontend or architecture.

• Include cc10x:frontend only when the request, changed files, plan, or design targets UI/frontend work. The skill has two modes: authoring (build UI with patterns) and critique (score built UI). Router selects mode via dispatch context.

• Include cc10x:architecture only for multi-component, API, schema, auth, or integration-heavy work.

• Include cc10x:research only when planner or investigator receives ## Research Files.

• cc10x:exploration is not a SKILL_HINTS entry: no dispatched agent loads it. The router runs it inline (see Inline exploration handoff) only on an explicit de-risk/spike intent ("spike", "try out", "what should this look like", "prototype", "throwaway") or in PLAN — never as the default for a real build. The skill has two modes: design (brainstorm a design) and spike (throwaway prototype). Absorbing a spike's answer is a fresh gated BUILD, not promotion.

• Include cc10x:codebase-hygiene only when (a) the code-reviewer is asked for a reuse/consolidation audit or the request targets semantic duplication, OR (b) the request targets retrofitting/deepening shallow modules in EXISTING code (not greenfield architecture, which stays cc10x:architecture). The skill has two modes: duplicate detection and module deepening.

• Include cc10x:qa-strategy only on QA-route dispatches whose agent loads skills (qa-researcher, qa-plan, qa-re-plan, qa-preflight, qa-harness-builder, qa-executor). qa-plan-review and qa-plan-review-2 dispatch plan-gap-reviewer, which loads no skills and has no Skill tool — a SKILL_HINTS entry cannot reach it, so there the coverage lens is a scaffold Read of skills/qa-strategy/SKILL.md, named in the dispatch itself (§7). It is the test-system design discipline — tier selection, scenario matrices, environment topology, flake sources. Do NOT inject it into BUILD's component-builder: BUILD's inner TDD is governed by cc10x:building, and mixing the two blurs "write a failing test for the code I am writing" with "design a test system for code that exists."

• Include cc10x:mcp-cli only when a researcher needs a one-off MCP capability that is not already mounted.

• Include cc10x:code-review only when a human/external reviewer's feedback (pasted PR comments, review notes, "can you change X") must be acted on — it governs verify-before-agreeing in the MAIN session, not the internal reviewer→router→fix loop.

• Include cc10x:memory-and-handoff only when work is being handed to a coworker, a different tool, or a fresh non-cc10x session.

• Include project/domain skills only from patterns.md ## Project SKILL_HINTS.

• Skill precedence is strict:

  1. explicit user prompt
  2. project CLAUDE.md / repo standards / user standards
  3. approved plan and design docs
  4. domain-specific external skills
  5. internal CC10X skills
  6. model heuristics

Previous Agent Findings handoff

When invoking integration-verifier, build and pass the ## Previous Agent Findings section per the Verifier findings handoff law in §12 — read results.reviewer and results.hunter from the workflow artifact and use the exact template defined there (single source). DEBUG skips the hunter.

Task metrics and timing telemetry

• Timing telemetry is measurement only. It must never bypass gates, phase exit, or remediation rules.
• After TaskGet() / TaskList(), if Claude Code exposes task duration metrics, persist them into:
  • telemetry.workflow_wall_clock_seconds
  • telemetry.agent_wall_clock_seconds.{agent}
• If task metrics are unavailable, keep task_metrics_available="unknown" and continue. Missing telemetry is never a reason to advance or block a workflow.
• When integration-verifier reports a ### Timing & Workload section, persist:
  • telemetry.verifier.phase_exit_proof_runs
  • telemetry.verifier.extended_audit_runs
  • telemetry.verifier.workload_seconds
• Use telemetry to explain latency. Do not use it to auto-reduce verification scope.

8. Post-Agent Validation

Read-only contracts

One rule, the same one references/workflow-artifact-and-hook-policy.md §contracts states: the STATUS in the fenced YAML Router Contract block decides. The line-1 envelope CONTRACT {"s":"...","b":...,"cr":...} and the line-2 heading are fast-path signals, and the fallback verdict signal only when the YAML block is absent; if they disagree with the YAML, the YAML decides.

Fallback headings on line 2: ## Review: Approve|Changes Requested, ## Verification: PASS|FAIL, ## Planning Review: Pass|Findings, ## QA Research: PASS|FAIL, ## QA Harness: PASS|FAIL|BLOCKED, ## QA Execution: PASS|FAIL|BLOCKED.

Finding the YAML block: take the fenced yaml block that follows the ### Router Contract (MACHINE-READABLE) heading when that heading exists (qa-researcher has it); otherwise take the first fenced yaml block after the envelope and heading (code-reviewer, failure-hunter, integration-verifier, plan-gap-reviewer, triage-agent and architecture-scanner carry no such heading). plan-gap-reviewer emits PLANNING_REVIEW_STATUS: PASS|FINDINGS as its status field, not STATUS.

Verdict extraction:

1. Read the YAML block and take the verdict from its STATUS (PLANNING_REVIEW_STATUS for plan-gap-reviewer).
2. If the YAML block is absent, the envelope on line 1, else the heading in the first 5 lines, only names the verdict to re-check.
3. Extract CRITICAL_ISSUES from ### Critical Issues.
4. If the YAML block is absent or any required contract field is missing, whatever the envelope and heading say, run inline verification rather than approving; for TRIAGE and CODEBASE-HEALTH there is nothing to verify inline, so the router sets failure_stop_gate instead (see their workflow references; no Memory Update).
5. Detect SELF_REMEDIATED from task state:
   • If the task remains in_progress and blockedBy is non-empty after the agent stops, treat it as self-remediated. This is blockedBy based, so it cannot fire in artifact-only mode; there the structured remediation fields decide.
6. For integration-verifier, parse scenario accounting:
   • SCENARIOS_TOTAL
   • SCENARIOS_PASSED
   • SCENARIOS_FAILED
   • Fail validation if those counts do not reconcile with the evidence array.
   • Fail validation if any scenario omits explicit Expected or Actual evidence.

Read-only structured intent fields:

• REMEDIATION_NEEDED: true|false
• REMEDIATION_REASON: ...
• REMEDIATION_SCOPE_REQUESTED: N/A|CRITICAL_ONLY|ALL_ISSUES
• REVERT_RECOMMENDED: true|false
• PLANNING_REVIEW_STATUS: PASS|FINDINGS
• BLOCKING_FINDINGS_COUNT: [number]
• REPLAN_NEEDED: true|false
• REPLAN_REASON: ...

Compatibility rule:

• Accept legacy self-healed blocked task behavior during migration.
• Prefer the new structured remediation fields over task-state inference when both exist.

Write-agent YAML contracts

For write agents, parse the fenced YAML block that follows the ### Router Contract (MACHINE-READABLE) heading.

Before post-agent validation, read references/workflow-artifact-and-hook-policy.md §contracts for the per-agent required-field table and the contract-override pass conditions.

If the YAML block is missing or malformed:

• Treat the task as invalid output.
• Do not continue the workflow based on prose alone.
• Re-run inline verification and fail safe.