pi-openspec/README.md

# @trentuna/pi-openspec

**OpenSpec workflow tools for pi agent sessions.** Wraps the [OpenSpec CLI](https://github.com/Fission-AI/OpenSpec) 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)

```bash
pi install npm:@trentuna/pi-openspec
```

*Requires npm auth — see [npm publish status](#npm-publish-status).*

### Internal (Trentuna VM — git install)

```bash
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:**

```bash
# 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](http://localhost:3001/trentuna/a-team/issues/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](https://github.com/Fission-AI/OpenSpec). pi by [badlogic](https://github.com/badlogicgames/pi-mono).