# pi-workflow bundled workflows

These are the official bundled `/workflow` starters shipped with pi-workflow. A workflow defines structure and role prompts; the concrete task is supplied at runtime.

Run them from the project root by exact workflow name, for example:

```text
/workflow list
/workflow show deep-research
/workflow validate deep-research
/workflow profile deep-research
/workflow run deep-research "Research the current project architecture and verify the key claims. Use max depth."
```

For spec-less direct dynamic execution, use `/workflow dynamic "<task>"`; it does not select one of the bundled workflow specs below.

## Official bundled workflows

| Workflow | Required agents | Use when |
|---|---|---|
| `deep-research` | `researcher` | Use when you need a grounded answer or summary based on source material. |
| `deep-review` | `scout` | Use when you want code or design reviewed carefully from multiple angles. |
| `spec-review` | `scout` | Use when you want to check whether requirements, an API spec, or a contract are reflected in the implementation and tests. |
| `impact-review` | `scout` | Use before merging or releasing a change to check affected areas, risks, missing tests, and missing docs. |

All four bundled workflows declare semantic `profileRole` values for every model-backed stage, so `/workflow profile <name>` offers Codex, Codex High, Claude, Mixed, and Custom with an exact stage preview. The private selection is reused for the same workflow definition across projects and applies to subsequent interactive, headless, and tool launches; an explicit declared `--profile` still wins. Missing model/capability combinations and stale definitions block rather than silently substitute or clamp.

Separately, `deep-research` declares workflow-owned `low`, `medium`, and `high` execution profiles and defaults to `medium`. With no saved user profile, interactive launches offer those declared profiles plus Base and headless omission uses `medium`. `low` is an explicit faster/cheaper quality trade-off, `low` and `medium` use profile-only max-2 batching for compatible `verify-claims` items, and `high` spends more reasoning while retaining singleton verification. Pass `--profile <name>` to choose one explicitly. A saved user profile overlays model/thinking on the `medium` default and therefore preserves its batching. Declared names are workflow-defined rather than reserved; see `docs/usage.md` for both profile layers and fallback guarantees.

Every official bundled workflow ends with the same user-facing completion envelope: a compact `completionSummaryMarkdown` passed through without parent re-summarization, a safe project-relative link to the workflow-specific `final-report.md` (and declared evidence audit when available), explicit evidence/limitations, and a final **Related artifacts** appendix in the full report. The deterministic renderer keeps each workflow's own authority model rather than forcing research verdicts onto review/readiness outputs. `deep-research` retains byte-identical `executive.md` plus claim-level `audit.md`; `deep-review` retains byte-identical `review.md`; `spec-review` and `impact-review` write `source-ledger.json`. Missing, partial, contradictory, or incompletely represented canonical inputs fail or block the final renderer instead of producing a clean completion.

Deep-research synthesis stays anchored to the runtime task and writes parent-facing text in that task's language unless another language is requested. Side-by-side tasks also require a concise subject-versus-reference comparison snapshot, with unknown and roadmap-only states distinguished from verified current capability. Its report body preserves research scope/method, detailed findings, recommendations, action plan, evidence strength, gaps, sources, and audit totals. Deep-review uses finding dispositions and severity; each reviewer must account for every planned evidence path byte-for-byte as `read`, `ocr-extracted`, `metadata-only`, or `unreadable`. The deterministic reducer verifies `read` quotes against the planned file/range using a bounded descriptor read. OCR quotes require a current-user-owned, single-link, non-writable artifact under the non-symlinked `.pi/ocr-artifacts/` control-plane root plus an exact `<artifact>.binding.json` manifest that binds source path/digest and artifact path/digest. Missing, unverifiable, duplicate, or unusable required content forces `PARTIAL_REVIEW`, quarantines findings from that incomplete reviewer to `NEEDS_HUMAN`, makes the final render gate fail closed, and remains listed in the report. Singleton verifier evidence for every KEEP/WEAKEN/DROP disposition is likewise structured and checked against its exact repository file/range before partitioning. Spec-review uses conformance and requirement coverage; impact-review uses contract, regression-risk, and ship-readiness joins.

Spec-review's verifier `evidence`/`counterEvidence` arrays accept typed `{file,lineStart,lineEnd,quote,relevance?}` rows (up to 64 per array). KEEP/WEAKEN require real local evidence bytes, DROP requires real local counter-evidence bytes before removal, and positive requirement coverage also requires typed bytes. All typed citations must pass; legacy strings are display-only/unverified, even when they look like file:line, URL, or opaque web locators. No remote-byte attestation is implied. Ungrounded dispositions remain in `needsHuman`; the partition's `evidenceGate` records per-row results and file SHA-256 values. The renderer reconciles that ledger and rechecks current bytes, so missing gate data, changed bytes, missing/failed required source manifests or controls, and absent/inconsistent reports cannot yield `passed`.

Spec-review and the `support-partition` scaffold use equivalent bundle-local readers: current valid UTF-8 regular files under canonical cwd, at most 4 MiB, bounded descriptor reads, no symlinked descendants or escapes, and fail-closed observed mutation. Inclusive 1-based LF ranges retain CR, BOM, diff markers, and whitespace; a terminal LF creates an empty final line, and an out-of-bounds end is never clamped. Quotes must be exact substrings inside the range. This is current-byte verification, not semantic entailment, historical worker-read proof, or a same-user OS sandbox. See [Local review evidence](../docs/usage.md#local-review-evidence) for the complete reader and source-accounting boundaries.

Experimental or candidate workflows should live outside the bundled `workflows/` directory until their task fit is validated. Workflow-specific batched verification/devil-advocate path-ref variants are not shipped. The public runtime supports profile-only transparent max-2 batching for eligible `foreach` stages, while generic orchestration primitives such as `foreach`, `matrix`, `fanout`, and multi-query web-source calls remain available where documented.

Bundled workflows that verify source-backed claims can share the verification outcome ontology exported by the package: `verified`, `partially_supported`, `unsupported`, `conflicting`, and `verification_blocked`. Workflow helpers should keep dependency-free bundle-local shims in parity with that package export, because helper imports are bundled from the workflow spec directory. `verification_blocked` means verification could not complete because evidence, tool, source-access, or policy conditions blocked evaluation; it is never counted as verified. Deep-research uses this ontology. Workflows with different verdict models, such as finding disposition or ship readiness, should not be forced into it.

## Evidence integrity and limitations

- Research preserves planned-question coverage, source identities, gaps, and canonical claim ledgers. Use typed local file/range/quote evidence instead of ambiguous source labels. Recommendations cannot upgrade unsupported or blocked claims; positive recommendations derived from verified claims remain derived judgments. Both research specs require the synthesis header and all eight indexed lossless pages under `packet.synthesisInput`, including empty tails, exactly once at 24,000 serialized UTF-16 units per read. The fixed page bank caps aggregate page data at 192,000 units plus a separately bounded header; it accommodates realistic near-max ledgers, not every unbounded schema value. Oversized indivisible rows/metadata or bank exhaustion block explicitly while retaining the canonical ledger. The renderer rejects missing, duplicate, tampered, or incompletely reconstructed canonical data; larger/root reads are not substitutes.
- Review keeps independently actionable defects separate even when they share code lines or quotes. It preserves synthesis rationale, risks, and actions, and distinguishes reviewer/source quotes from unavailable verifier evidence. Its final report describes the reviewed snapshot, not a new current-tree byte attestation.
- Spec review grounds extracted requirements in declared local spec sources and checks the runtime candidate universe independently. A genuinely empty finding set can conform; forged zero counts or absent coverage cannot.
- Impact review conserves original scope, finding, and action rows and enforces their risk floor. The final support helper derives canonical observation IDs, source provenance, and control-value hashes directly from all twelve source controls; models do not recopy ledgers. Model-written owner or resolution references are not human approval. Conservation cannot prove that the models discovered every defect, and impact citations do not independently attest source bytes.
- Requested report-sidecar publication failures are surfaced rather than silently returning a clean completion with broken artifact links.

## Bundle layout

Bundled workflows use directory-local bundles:

```text
workflows/name/
  spec.json
  schemas/
    stage-control.schema.json
  helpers/
    support-helper.mjs
```

Bundle names resolve from the directory name (`/workflow run name ...`). Name priority is project-shared `<cwd>/workflows/`, then project-private `<cwd>/.pi/workflows/`, then user/global `~/.pi/agent/workflows/`, then this bundled package root. A higher-priority match shadows lower roots. Multiple matching forms at the winning priority fail closed as ambiguous.

`output.controlSchema` in a bundle is resolved relative to the workflow spec file, for example `./schemas/final-control.schema.json`.

## DAG authoring

Artifact-graph workflows use `from` for data edges, `after` for order-only edges, and `type: "dag"` containers for nested sibling-scoped graphs. A downstream stage consumes a container with `from: "analysis"`, which resolves to the container's `outputFrom` child. See `docs/usage.md` for the full DAG example, artifact bundle rules, and validation rules.

## Support helpers and web tools

Support nodes run bundle-local `.mjs` helper code inline instead of launching a subagent (deep-research uses them to compact normalize inputs and preserve audited verdict/sourceRef ledgers). Bundled workflows prefer the normalized web-source tools (`workflow_web_search`, `workflow_web_fetch_source`, `workflow_web_source_read`) over legacy web tools.

Legacy `fetch_content` workflow tasks use a run-scoped cache and a configurable inline text cap to reduce worker context pressure.

See `docs/usage.md` for the support helper API and path-containment rules ("Support helpers") and for web tool semantics, batching, cache layout, and the `fetch_content` security policy ("Run-scoped web-source cache" and "Web tools").