idd-pipeline

name	idd-pipeline
description	Intent-Driven Development pipeline orchestrator. Accepts a vague natural language request and runs the full 5-step IDD pipeline: intent-extraction → architecture-synthesis → code-synthesis → icr-analysis → token-economics. Use when: generate app, build feature, patient risk calculator, IDD demo, run pipeline.

Skill: IDD Pipeline Orchestrator

Entry Point

This skill accepts a vague natural language request as input. Do NOT require a pre-structured intent document.

The same prompt used in Phase A becomes the input here. The pipeline transforms it — that transformation is the demo.

When a request arrives:

1. Do NOT generate code immediately.
2. Run Step 1 (Intent Extraction) to produce a structured intent from the vague input.
3. Show the extracted intent and pause for confirmation (Cortex Code / Claude Code) or proceed inline (Codex).
4. Continue through Steps 2–5 after confirmation.

---

Intent Detection

Detect the operator's intent and route to the matching resource before proceeding.

Intent	Triggers	Load
RUN DEMO	"patient risk", "run demo", "phase a", "phase b", "show app", "demo"	DIY.md
GENERATED BOUNDARY	"what can I commit", "generated boundary", "reset", "clean"	docs/reference/generated-boundary.md
GENERATE	any other request → proceed with pipeline steps below	—

---

Engine Detection

Set IDD_ENGINE before starting the session:

Engine	Command
Cortex Code	export IDD_ENGINE=cortex
Claude Code	export IDD_ENGINE=claude
Codex	export IDD_ENGINE=codex
Opencode	export IDD_ENGINE=opencode

Default if unset: cortex

---

Pipeline Sequence

Execute these steps in order. Each step feeds the next.

Step	Skill file	Output
1 — Intent Extraction	skills/idd-pipeline/intent-extraction/SKILL.md	Structured intent object in session
2 — Architecture Synthesis	skills/idd-pipeline/architecture-synthesis/SKILL.md	generated/architecture/
3 — Code Synthesis	skills/idd-pipeline/code-synthesis/SKILL.md	generated/code/
4 — ICR Analysis	skills/idd-pipeline/icr-analysis/SKILL.md	generated/reports/
5 — Token Economics	skills/idd-pipeline/token-economics/SKILL.md	generated/reports/

Do not skip steps. Do not reorder steps.

Demo Sequencing

For the patient-risk-calculator demo, follow this exact sequence:

Step	Action	Evidence
1	task api — start ICR lab API	Server up at localhost:8080
2	Call POST /simulate with -d @demo-workflows/phase-a-request.json	Phase A token amplification, 0/4 requirements
3	Load 3 IDD context files into session	Pipeline ready
4	Send vague prompt → live IDD synthesis (Steps 1–5)	Phase B: 4/4 requirements
5	ICR analysis (Step 4) calls API + measured Phase B → full report	Complete metrics, always populated

Phase A is NOT a live agent run. Call the simulation API instead — it is deterministic and always returns the same metrics for the same input.

Measurement Guardrails

When the task is the patient-risk-calculator demo, treat Phase A and Phase B as two separate measurements:

• Phase A baseline = call POST http://localhost:8080/simulate (see Demo Sequencing above). Do NOT send the vague prompt to the agent for Phase A measurement.
• Phase B optimized prompt = canonical foundation + this skill + the extracted intent only. Do not include generated code, architecture, reports, or prior outputs in the optimized prompt token count.
• Measure Phase A before any Phase B artifacts can overwrite the baseline run.
• If a token count, completion log, or output artifact is missing, mark it as unavailable or not retained; do not estimate or backfill it from other files.
• Do not compute savings, amplification, or ICR from mixed artifacts. Use only the matched Phase A/Phase B pair for the same intent and engine.
• If the same generated file would hide the baseline evidence, persist the baseline under a separate filename before writing Phase B outputs.

---

Adapter Selection

Before Step 3 (Code Synthesis), load the adapter for $IDD_ENGINE:

skills/idd-pipeline/adapters/$IDD_ENGINE/adapter.md

$IDD_ENGINE	Adapter
cortex	skills/idd-pipeline/adapters/cortex/adapter.md
claude	skills/idd-pipeline/adapters/claude/adapter.md
codex	skills/idd-pipeline/adapters/codex/adapter.md
opencode	skills/idd-pipeline/adapters/opencode/adapter.md

---

Constraints

• Step 1 (Intent Extraction) always runs before any generation step.
• Step 2 (Architecture Synthesis) always runs before Step 3 (Code Synthesis).
• Step 4 (ICR Analysis) requires both the vague prompt output and the optimized output.
• Step 5 (Token Economics) requires ICR data from Step 4.
• Do not generate code during Steps 1, 4, or 5.
• Do not write to skills/, prompts/, schemas/, or docs/.
• All generated artifacts go to generated/.
• Do not run, launch, preview, or smoke-test the generated app unless the operator explicitly asks for execution. Demo completion means printing the report, not running the generated application.

---

Demo Report

REQUIRED. Non-negotiable. This is the core deliverable of the IDD reference architecture.

After Step 5, render the full report below on-screen AND persist it to generated/reports/demo-report-<engine>.md. Both are required.

Do NOT:

• Skip the report or defer it
• Summarize it in a few lines
• Replace it with a "see the file" note
• Stop before the Final Recommendation section

The report — especially the Final Recommendation — is what makes the Phase A / Phase B contrast visible and actionable. Without it, the demo has no conclusion. Skipping it defeats the entire purpose of the reference architecture.

Do not run, launch, or preview the generated application unless the operator explicitly asks for it after the report is rendered.

---

Intent

Clarification Heavy (Phase A)

Build me a patient risk calculator.

Intent Optimized (Phase B — extracted by Step 1)

## Patient Risk Score Calculator

Streamlit app computing a readmission risk score from patient inputs.

### Requirements

1. Input form: age, prior admissions count, department (select), primary diagnosis code
2. Compute risk score: (prior_admissions × 0.4) + (age_factor × 0.3) + (diagnosis_factor × 0.3)
3. Color-coded badge: HIGH (score ≥ 0.7), MEDIUM (0.4–0.69), LOW (< 0.4)
4. Formula breakdown below the badge — each factor labeled with its weight

### Constraints

- Language: Python
- Framework: Streamlit
- Output: generated/code/

---

Clarification Heavy — What Would Have Happened

Render this from trace["Clarification Heavy"][*].prompt_text in generated/reports/phase-a-simulation.json:

Round	Message
1	Build me a patient risk calculator.
2	Something for tracking how sick patients are.
3	I guess like a score, based on their age and history.
4	Probably a web app, maybe Streamlit?
5	It should show if risk is high, medium, or low.
6	The formula? I'm not sure — you can decide.

6 rounds × growing context = token amplification. No code produced.

---

Requirements Coverage

Read requirements_coverage from generated/reports/phase-a-simulation.json. Include a column for every mode in the response.

Requirement	Clarification Heavy	Assumption Led	Intent Optimized
Input form (age, admissions, dept, diagnosis)	✗	✓	✓
Weighted risk formula (×0.4 / ×0.3 / ×0.3)	✗	✓	✓
Color-coded badge (HIGH / MEDIUM / LOW)	✗	✓	✓
Per-factor formula breakdown below badge	✗	✓	✓
Operations achieved	0 / 4	4 / 4	4 / 4

Fill ✓ / ⚠ / ✗ from actual requirements_coverage values in the simulation JSON.

---

Metrics

Pull all values from generated/reports/phase-a-simulation.json (token_metrics) and from the ICR measurement (generated/reports/icr-measurement-cortex.json). Include all modes returned in the simulation response.

Metric	Clarification Heavy	Assumption Led	Intent Optimized (sim)	Phase B — [engine] (actual)
Input tokens	input_tokens	input_tokens	input_tokens	measured
Completion tokens	output_tokens	output_tokens	output_tokens	measured
Total tokens	total_tokens	total_tokens	total_tokens	measured
Interaction rounds	interaction_rounds	interaction_rounds	interaction_rounds	1
ICR (normalized)	icr	icr	icr	—
Raw ICR	raw_icr	raw_icr	raw_icr	computed
Token amplification	token_amplification×	token_amplification×	token_amplification×	computed
Assumptions	0	total_assumptions total · wrong_assumptions wrong	0	0
Est. cost	estimated_cost	estimated_cost	estimated_cost	computed
Quality score (1–5)	1	5	5	5
Ops achieved	0 / 4	4 / 4	4 / 4	4 / 4

Pricing: input $0.01/1K · output $0.03/1K · icr-lab

---

Savings Hypothesis (1,000 runs / month)

Pull from savings_hypothesis in generated/reports/phase-a-simulation.json. Show all three comparisons.

Comparison	Savings / run	Monthly (1K runs)	Annual	Context
Clarification Heavy → Intent Optimized	computed	monthly_projection_1k_runs	×12	Simulation best case — token_savings_pct% token savings
Clarification Heavy → Assumption Led	computed	computed	×12	Strong model still wastes rounds on wrong-assumption correction
Clarification Heavy → Phase B [engine] (actual)	computed	computed	×12	Actual IDD run — 1 round, 0 assumptions, deterministic

Pricing basis (reference only): input $0.01 / 1K tokens · output $0.03 / 1K tokens. This is a hypothesis — actual costs vary by provider, region, model version, and contract. The ratio (not the absolute number) is what matters.

Methodology: ICR & Token Economics · ICR Lab

---

Narrative

[Engine writes a short paragraph (3–5 sentences) using blog vocabulary: token amplification, interaction rounds, operations achieved, Intent Compression Ratio, Clarification Heavy mode vs Intent Optimized mode.]

---

Recommended Engine

[Engine from Step 5] — [one-sentence justification from token-economics analysis]

---

Final Recommendation

REQUIRED. Do NOT skip this section. It is the conclusion of the demo.

Three approaches were tested against the same task. One conclusion:

Approach	Correct output?	Reproducible?	Token-efficient?	Zero-ambiguity output?
Clarification Heavy	✗ (0/4 reqs)	✗	✗ (worst_amplification×)	✗ (deflects — asks instead of builds)
Assumption Led (assumption_accuracy)	✓	✗ (model-dependent)	✗ (token_amplification×)	✗ (silent guesses, wrong_assumptions wrong)
IDD Pipeline — Intent Optimized	✓	✓	✓ (1.0× baseline)	✓

Use the IDD pipeline for any task where requirement completeness, token efficiency, and reproducibility are non-negotiable.

Why Clarification Heavy fails: It is not assumption-free — it is assumption-deferring. The missing context does not disappear; it gets offloaded to the user as clarification rounds. Every token spent asking is a token not spent building, and the user ends up supplying all the resolution that structured intent would have carried from the start. Even after multiple rounds there is no guarantee all requirements are met — the engine has no way to know what it does not know.

Why Assumption Led is insufficient for production: It reaches the correct answer at assumption_accuracy accuracy — which means it silently produces wrong assumptions on every other run. For this task (1 assumption) that is one correction cycle. For higher-complexity tasks with 2–3 assumptions, a strong model at 0.85 accuracy will make multiple wrong guesses, each adding rounds and cost. The result is correct when you are lucky, not because the system is reliable.

Why Intent Optimized wins: Structured intent resolved all requirements before a single token of generation was spent. No clarification rounds. No wrong guesses. No correction overhead. The same result is reproducible on any engine, on any run, regardless of model version or assumption accuracy — because the requirements were explicit, not inferred.

The IDD advantage scales with task complexity. This demo used a 4-requirement task. For 8, 12, or 20 requirements, the gap between Assumption Led (compounding wrong guesses) and Intent Optimized (zero assumptions) grows with every additional requirement.

[Engine adds one sentence grounding this in the actual numbers from this run.]

---

→ Intent Compression Ratio → ICR & Token Economics → ICR Lab

---

Loading This Skill

Load in this order (3 files):

1. skills/idd-pipeline/idd-foundation.md   ← role primer
2. skills/idd-pipeline/SKILL.md            ← this file
3. skills/idd-pipeline/adapters/$IDD_ENGINE/adapter.md

Engine	How to load
Cortex Code	@-mention each file above in order
Claude Code	@-mention each file above in order
Codex	Include contents of all three in the system prompt

Use task demo-context ENGINE=<engine> to print all three files in load order.