npm package: @lnittman/pi-steer
Description: Steering compiler for pi — turn-by-turn decision prompts, context-aware handoff synthesis, and pickup-ready prompt packaging
Author: Luke Nittmann
Latest version: 0.32.0

# @lnittman/pi-steer

High-trust steering compiler for [pi](https://github.com/mariozechner/pi-coding-agent).

`pi-steer` turns the next-step decision after an agent turn into a grounded steering pass:
- pointed multi-select questions instead of vague “what next?” prompts
- context-aware options grounded in files, diagnostics, session phase, trajectory, and prior decisions
- **user-programmable steering behavior** through settings and persistent prompt instructions
- handoff synthesis that packages a summary **plus the full interview responses** for stronger next-turn and pickup behavior
- receiver-grade handoff briefs without embedding fake transport commands like `agents session start ...`
- cold-start support (`Ctrl+I` / `/steer ask`) before any assistant turn

## Product framing

`pi-steer` is not just a questionnaire after each response.
It is a **steering compiler** and **user-programmable prompt layer** for the main pi agent.

Its job is to help the user encode:
- orchestration preferences
- validation style / release bar
- environment and tooling assumptions
- scope, taste, and constraint preferences

without forking code or teaching the main agent a new bespoke workflow every session.

Model routing and hidden route planning exist to support that outcome. They are not the core product.

## Programming pi-steer

The primary way to “program” `pi-steer` today is through its runtime control surfaces:

### 1. `/steer settings`

Use the settings UI to control:
- `interviewModel`
- `handoffModel`
- allowed model fleet
- thinking level
- trigger mode (`manual` / `auto`)
- `contextSourceMode` (`portable` / `balanced` / `all`)
- a visible per-source adapter checklist behind the `Context` row
- the resolved local-adapter bundle implied by that context mode

### 2. `/steer config instruction <text>`

Use a persistent instruction to tell `pi-steer` how you want it to behave.
This instruction is injected directly into the interview prompt and should be treated as durable prompt policy.

Examples:

```text
/steer config instruction Prefer interview questions that surface orchestration choices only when they materially change execution leverage. Bias toward validation gates, repo-local tooling assumptions, and strong handoff scaffolding.

/steer config instruction Assume my environment uses custom agent skills and local tooling, but keep the portable path valid when those adapters are unavailable.
```

### 3. `/steer config contextSources <comma-separated-source-keys>`

Advanced users can explicitly override the local adapter bundle behind the `Context` preset.
The same capability-level selection is now visible in `/steer settings`; the command surface remains useful for automation and direct edits.

Current source keys:
- `pi-local-skills`
- `agents-rules`
- `agents-skills`
- `agents-projects`
- `agents-roles`
- `session-topology`
- `system-prompt-summary`

This is the explicit escape hatch when the preset is too coarse.

See also:
- `docs/adapter-separation.md`

### 4. `/steer config agentRegistryRoot <path>`

The `agents-*` adapters resolve through a configurable agent-registry root instead of assuming `~/.agents` forever.
Use this when your machine keeps `rules.index.json`, `skills.index.json`, `projects.json`, and `roles.json` somewhere else.

`~/.pi` remains the stable local interface for Pi-local skills; this override only repoints the optional agent-registry adapters.

### 5. Interview selections and note overrides

The interview UI itself is also a programming surface:
- selected options act as explicit steering policy for the next turn
- freeform notes act as per-turn overrides
- both survive into handoff composition and pickup context

## Portable vs local context

`pi-steer` now has a portable context envelope and an explicit context-source policy.

`contextSourceMode` means:
- `portable` — do not depend on local adapter context; ideal for portable behavior and dogfooding the cross-machine contract
- `balanced` — use the portable core and add limited local enrichment when available
- `all` — allow richer local adapter context when available

Optional local adapters may draw from machine-local agent context, but the production-critical path should remain correct without Luke-specific `~/.agents` or `~/.pi` state.

## How it works

At a high level, `pi-steer` now:
1. builds a portable `SteerContextV1` envelope from turn/project/state context
2. optionally enriches that envelope depending on `contextSourceMode`
3. runs hidden route planning to sharpen focus, question budget, and guidance
4. generates interview questions that respect grounded evidence plus the persisted user instruction
5. composes the selected answers into next-turn and handoff context

Handoff output is intentionally transport-neutral: it should tell the receiving agent what to do, what to preserve, and what stays in scope, without pretending a generic shell command is the product.

This means the main extensibility story is: **improve the promptable control plane first**. Model choreography is secondary.

## Model policy

`pi-steer` is a policy layer, not the main driver model.
It still exposes separate interview and handoff slots, but those are supporting controls.

The current operator model policy and escalation heuristics live in `docs/model-combinations.md`.
Use that doc for model selection doctrine, not for the core product story.

## Install / update source

`@lnittman/pi-steer` is published on the public npm registry.

Install or update it directly:

```bash
npm install -g @lnittman/pi-steer@latest
```

No custom `@lnittman` scoped registry is required for this package.

Legacy packages `@lnittman/pi-interview` and `pi-quiz` have been superseded by `@lnittman/pi-steer`.

## Commands

Primary command surface:
- `/steer ask` — trigger manually
- `/steer settings` — edit model, thinking, trigger-mode, and context-source settings
- `/steer config instruction <text>` — persist a durable user preference
- `/steer config contextSourceMode portable|balanced|all` — set the context-source policy directly
- `/steer config contextSources <comma-separated-source-keys>` — override the local adapter bundle explicitly
- `/steer config agentRegistryRoot <path>` — repoint the optional `agents-*` adapters without changing the stable `~/.pi` interface
- `/steer status` — show config, usage, and latest runtime details
- `/steer audit` — inspect the current context packet
- `/steer trace` — toggle trace-rich context auditing
- `Ctrl+I` — manual steering shortcut

## Development

```bash
cd ~/Developer/packages/pi/pi-steer
pnpm install
pnpm build
pnpm test
pnpm typecheck
```

## Quality work

The current quality bar is defined in:
- `docs/quality-rubric.md`
- `docs/evals.md`
- `docs/roadmap.md`
- `docs/v1-architecture.md`

Key dimensions:
- pointedness
- context-awareness
- preservation fidelity
- phase fit
- taste / noise discipline
- user-programmed behavior actually shaping the interview output

## Evals

Commands:

```bash
pnpm telemetry:evals:list
pnpm telemetry:evals:quality
pnpm telemetry:evals:pairwise
pnpm telemetry:evals:workflow
pnpm telemetry:evals:portfolio
pnpm telemetry:evals:handoff
pnpm telemetry:evals:handoff:variants
pnpm telemetry:evals:preservation
pnpm telemetry:dataset:seed
```

In Luke's workspace, run them through CIC Doppler:

```bash
doppler run --project cic --config dev -- pnpm telemetry:evals:quality
doppler run --project cic --config dev -- pnpm telemetry:evals:workflow
doppler run --project cic --config dev -- pnpm telemetry:evals:handoff:variants
doppler run --project cic --config dev -- pnpm telemetry:evals:preservation
```

## License

MIT