openspec-pi: Spec-Driven Development, Built Into Your Agent

Spec-driven development (SDD) is a compelling answer to a recurring problem with AI coding agents: they often don't know what they're building or why. Without an explicit source of truth, an agent drifts, churns, and produces changes that miss the point. OpenSpec fixes this on the process side — it puts the "what and why" into a versioned openspec/ folder in the repo. But OpenSpec is only useful if the agent actually reads it, stays aligned with it, and re-checks it mid-task. That's exactly what openspec-pi automates.

openspec-pi is a pi package that makes spec-driven development the default instead of an afterthought. In a single install it bundles the official OpenSpec skills and prompts, a native openspec tool, and — the headline feature — automatically injects openspec context into the system prompt so every session starts with the project's specs already in context. No hand-written "please read the specs first" instructions required.

Why Auto-Context Matters

Anyone who has run a coding agent on a real codebase has seen the failure mode: the agent makes a change that contradicts an existing design decision, ignores a constraint, or re-implements something that was already specified. The traditional remedies are fragile — paste the spec into the chat, maintain a CLAUDE.md-style file that drifts, or write a long preamble the model may or may not internalize.

openspec-pi removes the overhead by hooking into pi's before_agent_start event. At session start it walks the working directory looking for an OpenSpec root (the openspec/config.yaml marker). When it finds one, it runs openspec context and appends the output to the system prompt — giving the model the active changes, targets, and working context as first-class input for every turn. The result is cached per root, so there's no per-turn CLI overhead.

A Native Tool, Not a Prompt Hack

Auto-injection covers the start of a session, but a good agent should be able to check its own state mid-task. The native openspec tool handles that: the agent can call status, doctor, context, list, show, and validate — with --change and --spec arguments where relevant. No slash commands, no shell subprocess-escape hacks.

That closes the tightest SDD loop: implement a task → validate the result against the spec → re-read the spec — without the model fumbling around a subprocess. There's also an interactive /ospec command in the TUI for running the CLI directly.

What's in the Package

openspec-pi is a proper pi-package — an npm tarball with a pi manifest that declares its resources:

• extensions/openspec.ts — the auto-context hook, the openspec tool, and the /ospec command
• skills/openspec-* (6) — official OpenSpec agent skills: propose, apply-change, explore, update-change, sync-specs, archive-change
• prompts/opsx-*.md (6) — official OpenSpec slash commands (/opsx-propose, /opsx-apply, …)

The skills and prompts are exactly what openspec init --tools pi generates into .pi/ — but now they're versioned, reusable and installable globally from one package instead of copied into every repo. Registered OpenSpec stores are handled too: if you're not in a local root but inside a registered store, the extension detects it via openspec store list and pulls the right context.

Installation

# one command
pi install npm:openspec-pi

# or from GitHub
pi install git:github.com/tobias-weiss-ai-xr/pi-openspec

# the only prerequisite — the OpenSpec CLI:
npm install -g @fission-ai/openspec

Restart pi, open any repo with an openspec/ root, and spec context flows in automatically.

Why Specs Should Live Where the Code Does

The whole package rests on OpenSpec's core idea: the spec belongs in the repository. An openspec/ folder is the source of truth for what and why. openspec-pi doesn't replace that — it makes sure the agent actually reads it, without being prompted.

The Payoff

The real value isn't the tool, the command, or even the injection — it's the habit of alignment. When specs load automatically and the agent can self-check against them mid-task, the loop that used to be "specs in a folder nobody remembers to read" becomes "specs the agent lives by." For teams adopting spec-driven development, openspec-pi is the bridge between the spec on disk and the agent in the session.

No more gambling that "the model probably understands what we're trying to build." If you have a spec, the agent knows it.