---
name: project-deterministic-workflows
description: Use when planning, executing, inspecting, resuming, or auditing PRD Plugin workflows, or whenever bounded mechanics should be removed from LLM orchestration.
---

# Deterministic Workflows

Use the workflow engine as the authority for bounded mechanics. The model owns only genuine judgment and communication.

## Staleness

Apply the shared freshness policy in `.prd_plugin/method/staleness-rules.md` to every source and receipt used by a run.

## Start

1. Read `.prd_plugin/config.json` through `prd_config_get`/`prd_config_list`; do not infer workflow enablement.
2. Call `prd_service_audit`, `prd_substrate_catalog` (`audit`), and
   `prd_workflow_audit`. Fix findings before execution.
3. Call `prd_workflow_plan` with exact inputs. Check actions, mutation classes, judgment steps, runtime fallbacks, and postconditions.
4. Call `prd_workflow_run` with a stable idempotency key. Enabled coordinate
   mode automatically dispatches waiting judgment through
   `prd_substrate_runtime`; results still return only through
   `prd_workflow_resume`.

The CLI equivalent is:

```bash
python .prd_plugin/scripts/prd_workflows.py --repo-root . <command> --json
```

## Shipped Workflow Routing

| Workflow | Owning skill |
| --- | --- |
| `session.start` | `project-decision-policy` |
| `session.stop` | `project-session-close` |
| `request.intake`, `request.import` | `project-request-intake` |
| `planning.requirements` | `project-planning-lifecycle` |
| `engineering.debug` | `project-systematic-debugging` |
| `engineering.code-review` | `project-code-review` |
| `engineering.verify` | `project-verification-before-completion` |
| `evidence.record` | `project-evidence` |
| `project.closeout` | `project-session-close` |
| `project.maintenance` | `project-health` |
| `install.update-check` | `project-prd-plugin-setup` |
| `hub.release` | `project-git-workflow` |

Run the workflow for bounded mechanics, then apply the owning skill only to
judgment, interpretation, and communication. The skill must not replay actions
already completed by the workflow receipt.

## Outcome handling

- `completed`: every declared postcondition passed. Use receipts as evidence, but still apply the task's completion skill.
- `waiting_judgment`: automatic dispatch may have attached a runtime capsule.
  If it did not, use `prd_substrate_runtime` with `judgment` or `drain`. The
  request is source-bounded and hash-bound; validate only through
  `prd_workflow_resume`.
- `failed`: inspect the typed error; change inputs/code/state, then retry only when safe.
- `blocked`: resolve the named boundary. An `outcome_unknown` mutation must be reconciled; never replay it speculatively.
- `cancelled`: terminal and auditable.

## Judgment boundary

The external runtime may reason over the supplied sources and return the declared schema. It may not mutate files, canonical state, IDs, tracking, evidence, configuration, Git, or release state. The deterministic engine validates the request hash, executor/profile, schema, and source references before continuing.

If the configured executor is unavailable, follow `workflows.judgment.fallback`. Never silently call a different model or treat a draft as project truth.

## Safety and efficiency

- Workflow JSON selects code-owned actions; it never embeds shell or Python.
- Custom definitions are rejected unless explicitly enabled.
- Canonical mutations use the MCP state authority and remain disabled for parallel workers.
- `verification.execute` uses exact changes, Substrate impact neighbours, local
  test mapping, argv-only execution, and mandatory widening on uncertainty.
  `hub.release` owns the one release-boundary full run.
- Inspect with read-only UTCP `workflow` actions; mutate only through MCP/CLI workflow operations.

## CRAFTESB gate

Before accepting a new or changed workflow, verify it is correct, robust to interruption/replay, aligned with configured authority, faithful to the project method, tested at contract and integration levels, efficient in persisted output and verification scope, secure across the boundaries it crosses, and bounded — it automates the mechanics that were asked for and no more. A workflow that grows steps, actions, or persisted state beyond the task it was requested for fails the gate even if every step works.