--- updated: "2026-10-06T17:57:00Z" source_commit: "94268a7fa802" update_event: "review_refresh" context: "changes=XL task=T-148" description: "Teach ordinary and detailed workflow authoring with shared Pi contracts" --- # Workflow examples These workflows ship with locus-pi and are ready to run after [installation](../../docs/getting-started.md). Open `/workflows list`, select the Package tab, and inspect a workflow before running it. ```text /workflows info live-smoke /workflows run live-smoke ``` The live smoke check starts real child agents. For authoring, begin with [task/draft and task/plan](task/README.md). For a modular read-only review, see [post-code-review](post-code-review/README.md). Read the [stage-loop source](stage-loop/stage-loop.workflow.mjs) before running it: that workflow implements a task stage and commits accepted changes. ## Package catalog `examples/workflows/` is the shipped registry. Each folder owns one namespace: a `.workflow.mjs` root runs as ``, and each direct `.workflow.mjs` entry runs as `/`. The registry ships four curated Package workflow namespaces with thirteen runnable names. | Workflow | Namespace | Purpose | | ----------------------------- | ------------------ | ------------------------------------------------------------------------------------------ | | `live-smoke` | `live-smoke` | Checks that the Pi host can spawn full-tool workflow agents and collect their reports. | | `post-code-review` | `post-code-review` | Run modular code-shape review lanes that write caller-assigned reports. | | `post-code-review/boundaries` | `post-code-review` | Audit ownership and architecture boundaries, then publish review-boundaries.md. | | `post-code-review/contracts` | `post-code-review` | Audit API and internal contracts for one post-code review scope. | | `post-code-review/necessity` | `post-code-review` | Challenge behavioral and code-shape fixes for necessity, ownership, and complexity. | | `post-code-review/scope` | `post-code-review` | Resolve a review target into an exact evidence boundary and write review-scope.md. | | `post-code-review/simplicity` | `post-code-review` | Audit a frozen review scope for delete-first contraction and publish simplicity findings. | | `post-code-review/style` | `post-code-review` | Audit comments and project-specific code style for one post-code review scope. | | `post-code-review/synthesis` | `post-code-review` | Verify review evidence and publish the final code-shape decision. | | `stage-loop` | `stage-loop` | Implements one task stage, gates it, fixes it up to three times, then commits. | | `task/draft` | `task` | Turn a raw request into an editable workflow brief with explicit orchestration choices. | | `task/plan-light` | `task` | Turn an accepted workflow brief into a checked workflow.mjs through bounded source slices. | | `task/plan` | `task` | Turn an accepted workflow brief into a checked workflow.mjs: write once, review, revise. | `task` is a group-only namespace and is not runnable by itself. Its three runnable entries are `task/draft`, `task/plan`, and `task/plan-light`. The post-code-review parent coordinates its seven children; use the parent for a complete review. ## Choose an example Run these commands inside Pi in the project the agents should inspect or change. Use `/workflows result last` to read the final result and `/workflows status` to find the run and its workspace. Model-using examples require your Pi model access. | Example and input | Run in Pi | Expected result and technique | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [live-smoke source](live-smoke/live-smoke.workflow.mjs): an optional topic; no input defaults to `runtime smoke test`. | `/workflows run live-smoke -- check this installation` | Two child agents list the project directory sequentially; the result contains their exact notes. Demonstrates [agent](../../docs/workflows/dsl.md#agent), [phase](../../docs/workflows/dsl.md#phase), and [log](../../docs/workflows/dsl.md#log). | | [task/draft](task/draft.workflow.mjs): describe the workflow and assign its exact draft.md path in the input. | `/workflows run task/draft -- Review a proposed change; draft.md: /project/reports/draft.md` | Produces editable `draft.md`. Agents write the assigned file through ordinary tools; a reader verifies it before the whole draft handoff returns. | | [task/plan](task/plan.workflow.mjs): pass exact authoring paths plus the complete accepted draft, or its assigned file path. | `/workflows run task/plan -- ` | Writes the same caller-assigned `workflow.mjs`, or preserves source and diagnostics as non-success when a gate fails. Demonstrates one author call with a bounded review-and-revise loop, [agent choices](../../docs/workflows/dsl.md#agent-options), and exact-file checker/reviewer handoffs. See the [task guide](task/README.md) for the two-stage handoff. | | [task/plan-light](task/plan-light.workflow.mjs): the same accepted draft, for a lighter author model. | `/workflows run task/plan-light -- ` | Produces the same checked `workflow.mjs` through designed, individually checked source slices; slower, with a gate after every step. See the [task guide](task/README.md). | | [post-code-review](post-code-review/README.md): name a function, file, commit, commit range, diff, or locally available PR range. Assign exact report paths in the input and the `smol` model role through `/model-roles`. | `/workflows run post-code-review -- Review the current diff. Reports: review-scope.md: /project/reports/review-scope.md; review-boundaries.md: /project/reports/review-boundaries.md; review-simplicity.md: /project/reports/review-simplicity.md; review-contracts.md: /project/reports/review-contracts.md; review-style.md: /project/reports/review-style.md; review-necessity.md: /project/reports/review-necessity.md; post-code-review.md: /project/reports/post-code-review.md` | Writes `post-code-review.md` with independently verified findings. Demonstrates [saved children](../../docs/workflows/dsl.md#invokeworkflow), [parallel](../../docs/workflows/dsl.md#parallel), and the same exact report destinations in every child input. | | [stage-loop source](stage-loop/stage-loop.workflow.mjs): task file plus exact handoff, round-report and stage.md destinations, scope, base commit and checks. | `/workflows run stage-loop -- ` | Implements changes, reviews and checks them in parallel, then commits accepted stage changes. Verifies the resulting commit and assigned handoff through an exact choice before returning `stage.md` with the complete commit report; refusal or failed verification returns a blocked result with evidence. Demonstrates [parallel](../../docs/workflows/dsl.md#parallel), [agent choices](../../docs/workflows/dsl.md#agent-options), and [artifact publication](../../docs/workflows/dsl.md#publishartifact). | The [typed-review example](../../docs/workflows/dsl.md#typed-workflow-input) shows schema-proven object/array input and its exact tool/command forms. Save those reviewed bytes as `typed-review.workflow.mjs` in your project workflow directory, then run `/workflows run typed-review --input-json {"task":"Review","ids":["A","B"]}`. Replace `/project/reports/` in the post-code-review command with your intended absolute report directory before launch. Keep all seven file assignments in the whole input. `stage-loop` edits the project and requests a Git commit. Read the task file and source before launching it; use a project and branch where those changes are intended. ### Post-code review children The seven children below are individually inspectable Package entries. Run the parent command above for the complete review: it passes the same semantic review input to each child, binds the children to its namespace, and supplies one shared workspace. Direct standalone launches create separate workspaces and do not supply the required preceding reports. Each child uses an [agent](../../docs/workflows/dsl.md#agent) that writes its exact caller-assigned file through ordinary tools. Every reader receives the same whole input and reopens that path. | Child source | Parent-managed input and prerequisites | File produced | | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | [scope](post-code-review/scope.workflow.mjs) | The review request and project evidence; establishes the exact scope first. | `review-scope.md` | | [boundaries](post-code-review/boundaries.workflow.mjs) | Review request and `review-scope.md`; inspects ownership independently. | `review-boundaries.md` | | [simplicity](post-code-review/simplicity.workflow.mjs) | Review request and `review-scope.md`; inspects opportunities to simplify independently. | `review-simplicity.md` | | [contracts](post-code-review/contracts.workflow.mjs) | Review request and `review-scope.md`; inspects API and consumer contracts independently. | `review-contracts.md` | | [style](post-code-review/style.workflow.mjs) | Review request, `review-scope.md`, and an optional exact caller-owned criteria-file path (omitted/empty means no extra criteria). | `review-style.md` | | [necessity](post-code-review/necessity.workflow.mjs) | Review request, scope, and all four lane reports after their parallel barrier. | `review-necessity.md` | | [synthesis](post-code-review/synthesis.workflow.mjs) | Review request and all six preceding reports; verifies admitted findings against source. | `post-code-review.md` | ## Copy and adapt a workflow Project sources resolve before User sources, which resolve before Package sources. `/workflows list` shows the active catalog directory, and source inspection shows the selected entry path. From Package source inspection, choose `Copy to Project` or `Copy to User`. Copying preserves the complete namespace, including children and adjacent README, prompt, diagram, and resource files. A group-only namespace remains group-only after copying. Project and User sources offer the opposite destination. Copying never merges or overwrites. An existing destination folder or flat root produces a conflict notice and leaves both locations unchanged. Reopen `/workflows list` after a successful copy to see the new editable source take precedence. See [Running workflows](../../docs/workflows/running.md) for launch, workspace, result, and resume commands. ## Distribution boundary Git tracks public repository contents; `package.json#files` controls the npm package. The package-boundary test proves that packed workflow names equal the entries discovered from this directory. Adding or removing a workflow changes the public package surface and requires matching documentation and tests. All shipped entries use the `standard` authoring profile. It describes the source-shape checks used during authoring, not a model choice or runtime mode. ## Authoring boundary Standard authoring is one continuous Design → review → Build sequence. A raw request first writes and reviews `.locus-pi/workflows//.design.md`, then creates exactly the root and direct children declared by that design. Explicit design-only wording may pause after design. `Build design: ` and `Build approved design: ` remain Build-only compatibility forms. To ask an agent for your own workflow, follow [Create a workflow](../../docs/workflows/create.md). The detailed source-shape contract lives in [source contract](../../docs/workflows/source-shape.md#machine-enforced-standard-source-shape). The [complete DSL reference](../../docs/workflows/dsl.md) describes the available operations. ## Patterns to adapt Start with an [ordinary or detailed authoring lesson](../../docs/workflows/create.md#choose-an-authoring-route), then use the [authoring approach index](../../skills/locus-pi-workflow-create/references/agentic-approaches.md#choose-an-approach) to select a graph from task needs. The same guide explains feedback, planning and composition. The [small starter guide](../../extensions/workflows/references/examples/starters/README.md) shows how to simplify and adapt six complete modules. The teaching modules under `extensions/workflows/references/examples/` ship with the package but are separate from the saved Package registry. Read and adapt them, or run a reviewed module by explicit path; their filenames do not register runnable Package names. | Teaching source | What it demonstrates | | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Project tour](../../extensions/workflows/references/examples/starters/project-tour.workflow.mjs) | The complete first lesson: two known readers before one explanation. | | [Caller audit](../../extensions/workflows/references/examples/starters/caller-audit.workflow.mjs) | Independent per-source inspect/verify pipeline, then complete-account synthesis and coverage review. | | [Evaluator-Optimizer](../../extensions/workflows/references/examples/starters/evaluator-optimizer.workflow.mjs) | Known work with reviewer-owned findings and choice, bounded correction/recheck, and honest incomplete exits. | | [Plan/replan](../../extensions/workflows/references/examples/starters/plan-replan.workflow.mjs) | Revise a named sequential plan from observed results; preserve remaining work when the teaching allowance ends. | | [Reflection](../../extensions/workflows/references/examples/starters/reflection.workflow.mjs) | Draft, critique and revise a low-risk explanation; the revision has no independent acceptance claim. | | [Parallel investigation + Reflection](../../extensions/workflows/references/examples/starters/parallel-reflection.workflow.mjs) | Combine independent investigation, synthesis and editorial feedback; omit nodes when their responsibility is unnecessary. | | [Fixed graph](../../extensions/workflows/references/examples/fixed.workflow.mjs) | One declared worker and one primary result. | | [Refinement](../../extensions/workflows/references/examples/refinement.workflow.mjs) | Bounded work and independent review, with explicit completion, failure, and no-progress exits. | | [Decomposition](../../extensions/workflows/references/examples/decomposition.workflow.mjs) | Run caller-supplied work units as bounded parallel workers and combine ordered results. | | [Adaptive design](../../extensions/workflows/references/examples/adaptive-design.workflow.mjs) | Refine a specification and preserve review decisions before a separate implementation request. | | [Adaptive slices](../../extensions/workflows/references/examples/adaptive-slices.workflow.mjs) | Revise the remaining work after each accepted implementation slice, then verify the complete result. | | [Human continuation](../../extensions/workflows/references/examples/human-continuation.workflow.mjs) | Join two runs through an operator handoff and host-verified artifacts. This is a reviewed compatibility example, outside the standard opaque-text profile. | ### Councils and judge panels A council gives advisors different jobs, preserves their independent evidence and disagreements, and asks a synthesizer to write one document. A fresh verifier checks that document against the advisor texts. Publish the terminal document only after acceptance so rejection leaves no final artifact; acceptance publishes the exact verified synthesis. The repository-only reference at `extensions/workflows/references/consilium/consilium.workflow.mjs` demonstrates this sequence. It runs by path from a checkout and is excluded from npm. A judge panel instead combines declared decisions under an explicit majority or unanimity rule. Decide whether partial panels are acceptable; otherwise a failed judge fails the group. Vote aggregation is not [Fusion](../../docs/workflows/fusion.md): Fusion preserves proposals and reasoning for a synthesizer to resolve. Use [runtime-validated choices](../../docs/workflows/agent-results.md#standard-exact-choice--agent-choice-) for control flow rather than scanning model prose. ### Bounded loops and replay Loops need a measured completion condition and a hard round cap, with a result that names which exit was taken. Use the runtime clock [`now()`](../../docs/workflows/dsl.md#now) for replayable deadline checks; runtime [`random()`](../../docs/workflows/dsl.md#random) likewise records choices for replay. These are runtime capabilities: their availability does not expand the [standard source profile](../../docs/workflows/source-shape.md). Follow its supported bounded-loop form when generating standard source, and consult [replay](../../docs/workflows/replay.md) before relying on resumed control flow.