init: @trentuna/pi-openspec — 13-tool OpenSpec extension for pi
- extensions/openspec.ts — 13 tools wrapping openspec CLI - skills/openspec/SKILL.md — full workflow guidance for agents - package.json — pi manifest with pi-package keyword, @trentuna scope - README.md — comprehensive: install, all 13 tools, quick-start, workflow - LICENSE — MIT - .gitignore Adapted from a-team/extensions/openspec.ts (Hannibal, session 135). Standalone package so any trentuna member can: pi install git:http://localhost:3001/trentuna/pi-openspec.git
This commit is contained in:
commit
9e1f99a28f
GPG key ID:
159D6AD58C8E55E9
6 changed files with 808 additions and 0 deletions
166
README.md
Normal file
166
README.md
Normal file
|
|
@ -0,0 +1,166 @@
|
|||
# @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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue