pi-openspec/README.md

@trentuna/pi-openspec

OpenSpec workflow tools for pi agent sessions. Wraps the OpenSpec CLI as 13 native pi tools, making spec-driven development a first-class operation in any agent session.

This is the first protocol-level pi package built for the pi ecosystem — OpenSpec as infrastructure, not a team-internal tool.

---

What it does

OpenSpec brings discipline to AI-assisted software development: write the spec before writing the code, track changes explicitly, archive what's done. This package makes those operations available directly in pi sessions — no manual CLI, no skill-file hunting.

---

Install

External (npm — preferred for external users)

pi install npm:@trentuna/pi-openspec

Requires npm auth — see npm publish status.

Internal (Trentuna VM — git install)

pi install git:http://localhost:3001/trentuna/pi-openspec.git

Trentuna members (bootstrap)

Included automatically when you run commons/bin/bootstrap.sh. No manual install needed.

---

Requirements

• openspec CLI — npm install -g openspec (v1.2.0+)
• pi — any recent version
• Node.js 18+

---

Tools

All 13 tools are available immediately after install.

Tool	Description
openspec_init	Initialize OpenSpec in a project (creates openspec/ dir, config, skill files)
openspec_update	Regenerate skill/instruction files after config changes or schema switch
openspec_list	List active changes (work in progress) or stable spec domains
openspec_show	Show the full content of a change or spec
openspec_new_change	Create a new change directory with scaffolded artifacts
openspec_status	Artifact dependency graph — what's done, what's ready, what's blocked
openspec_instructions	Enriched instructions for creating a specific artifact (or implementing tasks)
openspec_validate	Validate change or spec for structural correctness
openspec_archive	Archive a completed change (merges delta specs → main, preserves history)
openspec_spec_list	List all spec domains (the stable source of truth)
openspec_spec_show	Display a specific spec by ID
openspec_schema_list	List available workflow schemas
openspec_schema_fork	Fork a schema for customization

---

Quick Start

5 steps to ship a specified, implemented, archived change:

# 1. Initialize in your project (once)
openspec_init(path=".", tools="pi")

# 2. Create a change
openspec_new_change(name="add-user-auth", description="Add JWT authentication")

# 3. Check what to write next
openspec_status(changeName="add-user-auth")

# 4. Get instructions for each artifact, then write it
openspec_instructions(changeName="add-user-auth", artifact="proposal")
# → write proposal.md, then specs, design, tasks

# 5. Implement and archive
openspec_instructions(changeName="add-user-auth", artifact="apply")
# → implement tasks, then:
openspec_validate(name="add-user-auth")
openspec_archive(changeName="add-user-auth")

---

Workflow Skill

Load the workflow skill for step-by-step guidance on all operations:

Load the openspec skill

The skill covers the full workflow: init → new_change → status → instructions → implement → validate → archive. It includes common patterns, gotchas, and tool reference.

Skill location: skills/openspec/SKILL.md

---

How It Works

OpenSpec organizes work into:

• Specs (openspec/specs/) — the source of truth. Describe how the system currently works.
• Changes (openspec/changes/) — proposed modifications. Each change is a folder containing a proposal, delta specs, design, and task list.

When a change is complete, openspec_archive merges its delta specs into the main specs and moves the folder to changes/archive/YYYY-MM-DD-<name>/. History preserved, source of truth updated.

The default spec-driven schema builds artifacts in dependency order:

proposal → specs → design → tasks → implement → archive

openspec_status shows the dependency graph at any point. openspec_instructions gives you enriched context before writing each artifact.

---

Package Structure

pi-openspec/
  package.json          # pi manifest + npm metadata
  extensions/
    openspec.ts         # 13-tool extension (wraps openspec CLI)
  skills/
    openspec/
      SKILL.md          # workflow guidance for agent sessions
  README.md
  LICENSE               # MIT

---

npm Publish Status

Not yet published. The package installs cleanly via git from Forgejo (Trentuna internal). npm publish requires:

1. npm login on the publishing machine
2. @trentuna npm org created at npmjs.com
3. npm publish --access public from this repo

This is a Ludo action. Track at trentuna/a-team#107.

---

Contributing

This package is part of the Trentuna tooling stack. After it's stable and battle-tested, it will be submitted to the pi-mono package gallery as the first protocol-level pi package in the ecosystem.

Issues and PRs welcome at trentuna/pi-openspec.

---

License

MIT — Trentuna, 2026.

OpenSpec CLI by Fission AI. pi by badlogic.