vigilio
9e1f99a28f
- 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
159 lines
6.6 KiB
Markdown
159 lines
6.6 KiB
Markdown
---
|
|
name: openspec
|
|
description: Spec-driven development workflow using OpenSpec. Use when initializing OpenSpec in a project, creating change proposals, writing specs, generating designs and task lists, implementing changes, or archiving completed work. Provides step-by-step workflow guidance for all 13 openspec tools.
|
|
---
|
|
|
|
# OpenSpec Workflow Skill
|
|
|
|
OpenSpec organizes software work into **specs** (source of truth) and **changes** (proposed modifications). The workflow guides you from intent to implementation to archive.
|
|
|
|
## When to load this skill
|
|
|
|
Load when you are:
|
|
- Setting up OpenSpec in a new or existing project
|
|
- Creating a change proposal for a new feature or fix
|
|
- Writing specs, designs, or task lists for an active change
|
|
- Implementing tasks from a change
|
|
- Validating or archiving completed work
|
|
|
|
## Core Concepts
|
|
|
|
**Specs** (`openspec/specs/`) — the source of truth. Describe how the system currently behaves. Organized by domain (e.g., `specs/auth/`, `specs/payments/`).
|
|
|
|
**Changes** (`openspec/changes/`) — proposed modifications. Each change is a folder with proposal, delta specs, design, and task list. Changes merge into specs on archive.
|
|
|
|
**Artifacts** — the documents inside a change. The default `spec-driven` schema builds them in dependency order:
|
|
```
|
|
proposal → specs (delta) → design → tasks → implement → archive
|
|
```
|
|
|
|
**Key insight:** `openspec_instructions` is your north star. Call it before writing each artifact — it returns enriched context, rules, template structure, and output path. Do NOT skip this step.
|
|
|
|
## The Standard Workflow
|
|
|
|
### 0. Initialize (once per project)
|
|
|
|
```
|
|
openspec_init(path=".", tools="pi")
|
|
```
|
|
|
|
Creates `openspec/` directory, `config.yaml`, and pi-compatible skill files. Run once. Safe to skip if `openspec/` already exists.
|
|
|
|
### 1. Orient
|
|
|
|
```
|
|
openspec_list() # see active changes in progress
|
|
openspec_spec_list() # see stable spec domains
|
|
openspec_show(name="change-name") # read an existing change in full
|
|
```
|
|
|
|
Run at session start to understand what's in flight before creating anything new.
|
|
|
|
### 2. Create a Change
|
|
|
|
```
|
|
openspec_new_change(name="add-user-auth", description="Add JWT auth to API")
|
|
```
|
|
|
|
Creates `openspec/changes/add-user-auth/` with scaffolded artifact files. Name in kebab-case. Be specific — avoid generic names like `update` or `wip`.
|
|
|
|
Then immediately:
|
|
```
|
|
openspec_status(changeName="add-user-auth")
|
|
```
|
|
|
|
This shows the dependency graph: which artifacts exist, which are ready to write, which are blocked.
|
|
|
|
### 3. Write Each Artifact (in dependency order)
|
|
|
|
For each artifact the status shows as "ready":
|
|
|
|
```
|
|
openspec_instructions(changeName="add-user-auth", artifact="proposal")
|
|
```
|
|
|
|
Read the returned `context`, `rules`, and `template` carefully. The `outputPath` tells you exactly where to write. The `dependencies` list tells you what to read first.
|
|
|
|
**IMPORTANT:** `context` and `rules` guide what YOU write — do NOT copy them into the artifact file. Use `template` as the structure.
|
|
|
|
Write the artifact using the Write tool. Then call `openspec_status` again to see what unlocks next.
|
|
|
|
Repeat for: `specs`, `design`, `tasks`.
|
|
|
|
### 4. Implement Tasks
|
|
|
|
```
|
|
openspec_instructions(changeName="add-user-auth", artifact="apply")
|
|
```
|
|
|
|
Returns the task list and implementation approach. Work through tasks, checking them off in `tasks.md` as you go. Commit per completed task (not per file edit).
|
|
|
|
### 5. Validate
|
|
|
|
```
|
|
openspec_validate(name="add-user-auth")
|
|
```
|
|
|
|
Checks structural correctness of all artifacts. Fix any CRITICAL issues before archiving. WARNINGS are advisory.
|
|
|
|
### 6. Archive
|
|
|
|
```
|
|
openspec_archive(changeName="add-user-auth")
|
|
```
|
|
|
|
Merges delta specs into `openspec/specs/`. Moves the change folder to `openspec/changes/archive/YYYY-MM-DD-add-user-auth/`. The change is done.
|
|
|
|
## Schema Operations
|
|
|
|
```
|
|
openspec_schema_list() # see available workflow schemas
|
|
openspec_schema_fork(source="spec-driven", name="rapid") # fork for customization
|
|
```
|
|
|
|
Use `rapid` or other custom schemas when the full `spec-driven` workflow is more than the task needs (e.g., a small bugfix that doesn't warrant a full spec + design).
|
|
|
|
## Reading Existing Specs
|
|
|
|
```
|
|
openspec_spec_list() # list spec domains
|
|
openspec_spec_show(specId="auth") # read a spec in full
|
|
```
|
|
|
|
Always read relevant specs before creating a change — understand what's already specified and which domain your change touches.
|
|
|
|
## Common Patterns
|
|
|
|
**Starting fresh on an existing codebase:**
|
|
1. `openspec_init` → `openspec_spec_list` (probably empty) → `openspec_new_change` for your first feature → write artifacts → implement
|
|
|
|
**Resuming work in progress:**
|
|
1. `openspec_list` → `openspec_show` (read the change) → `openspec_status` (see what's ready) → `openspec_instructions` for next artifact → continue
|
|
|
|
**Quick change (small fix):**
|
|
1. `openspec_new_change(schema="rapid")` if you have a rapid schema, else use `spec-driven` and skip non-critical artifacts → `openspec_instructions(artifact="apply")` → implement → `openspec_archive`
|
|
|
|
## Gotchas
|
|
|
|
- **Don't skip `openspec_instructions`** before writing an artifact. The context and rules it returns are essential — they encode project-specific constraints that the template alone doesn't carry.
|
|
- **Commit per task, not per file.** The session commit protocol applies — each logical unit of work is one commit.
|
|
- **`openspec_update` after config changes.** If you modify `openspec/config.yaml` or switch schemas, run `openspec_update` to regenerate skill files.
|
|
- **Delta specs are not full specs.** A delta spec shows what's ADDED/MODIFIED/REMOVED relative to existing specs. Don't rewrite the entire domain — only the changes.
|
|
|
|
## Tool Reference
|
|
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| `openspec_init` | Initialize OpenSpec in a project |
|
|
| `openspec_update` | Regenerate skill/instruction files after config changes |
|
|
| `openspec_list` | List active changes (WIP) or stable specs |
|
|
| `openspec_show` | Show a change or spec in full |
|
|
| `openspec_new_change` | Create a new change directory with scaffolded artifacts |
|
|
| `openspec_status` | Artifact dependency graph and completion state |
|
|
| `openspec_instructions` | Enriched instructions for creating a specific artifact |
|
|
| `openspec_validate` | Validate change/spec structural correctness |
|
|
| `openspec_archive` | Archive completed change (merges delta specs into main) |
|
|
| `openspec_spec_list` | List spec domains (stable source of truth) |
|
|
| `openspec_spec_show` | View a specific spec by ID |
|
|
| `openspec_schema_list` | List available workflow schemas |
|
|
| `openspec_schema_fork` | Fork a schema for customization |
|