@lnittman/pi-steer

High-trust steering compiler for pi.

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:

/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:

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

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:

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:

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