Pipeline Router

Pipeline Router

Routing is a commitment: select one Workflow from the desired Artifact and evidence method, record that choice, and expose the next human Decision.

Inputs

• GOAL.md, or the current user request when the Workspace is new.
• Existing PIPELINE.lock.md, UNITS.csv, STATUS.md, and DECISIONS.md when present.
• docs/PIPELINE_TAXONOMY.md and candidate Pipeline front matter during selection.

Outputs

• PIPELINE.lock.md for a newly bound Goal.
• The initial C0 checkpoint block in DECISIONS.md.
• queries.md when the selected retrieval Workflow starts at C0.
• A synchronized current Pipeline/checkpoint projection in STATUS.md.

Steps

1. Establish the requested Artifact

Read the Goal and identify:

• the reader-facing deliverable;
• the evidence method it requires;
• the requested format or delivery profile;
• the decisions that materially change Workflow selection.

When a routing discriminator is missing, write the smallest grouped question set to DECISIONS.md and stop at that Decision.

Completion criterion: every fact that can change the Workflow choice is known or explicitly bounded in DECISIONS.md.

2. Select one Workflow

Load docs/PIPELINE_TAXONOMY.md, then inspect only the candidate Pipeline contracts. Choose from target Artifact and evidence method rather than keyword matching alone. Treat delivery profiles and course-report use cases as overlays inside their existing Workflow family.

Completion criterion: exactly one executable Pipeline is selected and its target Artifacts match the Goal.

3. Materialize the commitment

Write PIPELINE.lock.md with:

pipeline: <pipeline path>
units_template: <template path from Pipeline front matter>
locked_at: <YYYY-MM-DD>

Initialize UNITS.csv from that template when the Workspace is new. Preserve a valid existing lock; a route change is an explicit operator Decision followed by reinitialization or migration, never a silent rewrite.

Completion criterion: the lock, Unit template, and Workspace projection refer to the same Pipeline.

4. Expose the C0 checkpoint

Materialize the C0 kickoff block and approval checkbox in DECISIONS.md. Seed queries.md from the Goal when retrieval is part of the selected Workflow. Later checkpoints use checkpoint-brief. Historical Workspaces whose saved Unit still invokes pipeline-router after C0 are delegated to checkpoint-brief with a deprecation warning; the router never approves them.

The deterministic helper may be used after selection:

uv run python .codex/skills/pipeline-router/scripts/run.py \
  --workspace workspaces/<name> \
  --checkpoint C0

Completion criterion: DECISIONS.md contains the C0 checkpoint and one clear approval or answer surface; retrieval Workflows have a non-empty C0 query seed.

5. Verify the route

Check that the locked Pipeline exists, its Unit template exists, and the active checkpoint is represented in both STATUS.md and DECISIONS.md.

Completion criterion: the Pipeline Runner can continue from Workspace files without making another routing inference.

Context Pointers

• Read docs/PIPELINE_TAXONOMY.md only while selecting or deliberately changing a Workflow.
• After selection, the locked pipelines/*.pipeline.md is the execution contract and the taxonomy leaves context.
• Use assets/pipeline-selection-form.md only when missing routing facts require a human answer.
• Run the helper with --help when C0 materialization needs debugging; the helper records the initial route projection but does not choose one.