# locus-pi workflow skills

The npm package is the canonical source for four workflow skills.
Pi discovers them directly from `package.json#pi.skills`. External agents use managed
symlinks; they do not receive copied skill text that can drift from the package.

| Skill                               | Owns                                                                                  | Native Pi/API route                                                     | External agent route                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `locus-pi-workflow-create`          | Ordinary authoring lesson; reviewed design, checked source and authorized run handoff | Follow the packaged skill directly                                      | Follow the managed packaged skill directly                           |
| `locus-pi-workflow-create-detailed` | Explicitly selected detailed lesson under the same authoring contracts                | Invoke the detailed entry                                               | Follow the managed packaged skill directly                           |
| `locus-pi-workflow-run`             | One existing reviewed workflow run, receipts, evidence, resume                        | Call the structured `workflow` tool; the skill is only routing guidance | Delegate session ownership to `external-locus-pi`                    |
| `external-locus-pi`                 | External interactive Pi session and manual attachment                                 | Not needed when already inside Pi                                       | Start Pi in a retained terminal; keep the UI available after the run |

## Install for Codex and Claude Code

Choose the ordinary or detailed lesson using the [public selection guide](../docs/workflows/create.md#choose-an-authoring-route).
Both are actual packaged entries; the run and external-session skills keep their existing responsibilities.

Run these commands inside Pi after installing the locus-pi package:

```text
/workflows skills status --host all --scope user
/workflows skills sync --host codex --scope user
/workflows skills sync --host claude --scope user
```

`--host all` manages both hosts. `--scope project` writes under the current
project instead of the user home. Codex entries live in `.agents/skills`;
Claude Code entries live in `.claude/skills`.

`sync` creates or refreshes only locus-pi-managed symlinks. It removes managed
links under the retired names, including `locus-pi-workflow-implement-task`. A real directory or foreign symlink is a
conflict and is never overwritten. Ownership comes only from the adjacent
`.locus-pi-workflow-skills.v1.json` provenance file, never from a suggestive
symlink target. `remove` has the same ownership check. The command snapshots
managed links and provenance before mutation and rolls the whole selected host
set back after an unexpected filesystem error.

## Find the installed workflow documentation

Both authoring entries require the [co-located DSL/API reference](locus-pi-workflow-create/references/dsl.md)
before source is written. It contains every runtime method, signature, example and source-mode constraint.
`docs/workflows/dsl.md` is canonical; `npm run build:catalogs` generates this version-matched projection
and `check:generated` rejects drift. Both this copy and the canonical document ship in the npm package.
Codex and Claude Code reach the same files through their managed skill links, in either user or project scope.

Pi initially advertises each skill's name, description and `SKILL.md` location. For a matching ordinary
request, the agent reads that entry; an explicit `/skill:locus-pi-workflow-create` or
`/skill:locus-pi-workflow-create-detailed` invocation inserts the selected `SKILL.md` body into the request.
Neither discovery nor explicit invocation recursively loads linked files. The authoring instructions
then require the agent to read the linked co-located DSL and selected references before writing source.
Child agents receive the context their workflow prompts supply; references are not silently injected.

The [workflow manual](../docs/workflows/index.md) ships in the same npm package.
Pi discovers these skills through `package.json#pi.skills`. Codex and Claude Code may
expose a managed directory symlink as the skill's location. Resolve the physical
`SKILL.md` **before** following any package-relative link; then resolve
`../../docs/workflows/index.md` from its parent directory. Do not use the caller's
working directory or assume a global npm prefix. A copied skill folder without
its package is not the supported installation; use the managed sync above.

Given the actual skill location reported by the host:

```bash
realpath '<skill-location>/SKILL.md'
```

The portable Python equivalent also prints the manual's absolute entry path:

```bash
python3 - '<skill-location>/SKILL.md' <<'PYDOC'
from pathlib import Path
import sys
skill = Path(sys.argv[1]).resolve(strict=True)
manual = (skill.parent / "../../docs/workflows/index.md").resolve(strict=True)
print(manual)
PYDOC
```

This follows Pi's own packaging pattern: it [ships a docs directory](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/package.json)
and its [system prompt supplies the absolute docs path](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/src/core/system-prompt.ts).
That path identifies Pi's documentation; the physical skill identifies the Locus
package and its version-matched manual.

## Model selection

For an external Pi invocation, select the main Pi model and reasoning level on
the command line:

```bash
pi --approve \
  --model '<provider/model>' --thinking high \
  '/workflows run <name> -- <semantic input>'
```

Child model routing is separate. Configure roles through `/model-roles` or
`~/.pi/agent/model-roles/config.json`. An unassigned role inherits the main Pi
model.
`--approve` is broad project trust, not workflow-only approval.

For an inspectable session launched from Codex or Claude Code, use
[`external-locus-pi`](external-locus-pi/SKILL.md). It returns a command to attach
to the same interactive Pi terminal. JSON print mode is an explicit alternative
for non-interactive output, not the default external session.