pi-openspec 1.0.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-openspec",
+  "version": "1.0.0",
+  "description": "OpenSpec integration for pi — /openspec commands, auto-naming, and spec-driven workflow skill.",
+  "keywords": [
+    "openspec",
+    "pi",
+    "pi-package",
+    "spec-driven",
+    "workflow"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pankajudhas81/pi-openspec.git"
+  },
+  "files": [
+    "src",
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "@earendil-works/pi-tui": "latest",
+    "@types/node": "^25.5.0",
+    "oxfmt": "0.41.0",
+    "oxlint": "1.56.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"no tests yet\"",
+    "lint": "oxlint && oxfmt --check .",
+    "lint:fix": "oxlint --fix . && oxfmt --write .",
+    "format": "oxfmt --write ."
+  }
+}

package/skills/openspec-workflow/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: openspec-workflow
+description: >-
+    Spec-driven development with OpenSpec. Use when the user wants to start a
+    new feature/change, write a proposal, create specs, design a solution,
+    break work into tasks, or follow the OpenSpec artifact pipeline. Triggers
+    on mentions of "openspec", "spec-driven", "proposal", "change proposal",
+    "write a spec", "design doc", or when working inside openspec/changes/.
+---
+
+# OpenSpec — Spec-Driven Development Workflow
+
+OpenSpec enforces a disciplined pipeline for changes:
+**proposal → specs → design → tasks**. Each artifact unlocks the next.
+Artifacts are blocked until their dependencies are complete.
+
+## The Pipeline
+
+```
+proposal.md          WHY this change is needed
+    ↓
+specs/*.md           WHAT the system must do (requirements)
+    ↓
+design.md            HOW the system will do it (architecture)
+    ↓
+tasks.md             WORK breakdown (implementable steps)
+```
+
+## Directory Structure
+
+Changes live in `openspec/changes/<name>/` where `<name>` follows the
+format `NNNNN-YYYY-MM-DD-slug` (auto-generated by `/openspec new`):
+
+```
+openspec/
+├── changes/
+│   └── 00001-2026-06-04-add-auth/
+│       ├── .openspec.yaml      # schema + metadata (auto-created)
+│       ├── proposal.md         # artifact 1: why
+│       ├── specs/              # artifact 2: what
+│       │   ├── user-auth/
+│       │   │   └── spec.md
+│       │   └── session-mgmt/
+│       │       └── spec.md
+│       ├── design.md           # artifact 3: how
+│       └── tasks.md            # artifact 4: work
+├── specs/                      # main specs (accumulated from archived changes)
+└── config.yaml                 # project-level openspec config
+```
+
+## Commands
+
+| Command                          | What it does                                |
+| -------------------------------- | ------------------------------------------- |
+| `/openspec new <name>`           | Create a new change (auto-numbered + dated) |
+| `/openspec status [id]`          | Show artifact completion status             |
+| `/openspec next [id] [artifact]` | Get enriched instructions for next artifact |
+| `/openspec validate [id]`        | Validate a change or all changes            |
+| `/openspec archive <id>`         | Archive a completed change into main specs  |
+| `/openspec list`                 | List active changes                         |
+| `/openspec list --specs`         | List accumulated specs                      |
+| `/openspec init`                 | Initialize OpenSpec in a project            |
+| `/openspec schemas`              | List available workflow schemas             |
+
+**Identifiers:** Use the number (`3`), full name
+(`00003-2026-06-04-add-auth`), or slug (`add-auth`).
+
+## Workflow — Step by Step
+
+### 1. Start a change
+
+```
+/openspec new add-auth
+```
+
+Creates `openspec/changes/00001-2026-06-04-add-auth/` with
+`.openspec.yaml`. The first artifact (proposal) is now **ready**.
+
+### 2. Write each artifact
+
+Always use `/openspec next` to get enriched instructions before writing
+an artifact. The instructions include the template, output path,
+description, and what the artifact unlocks:
+
+```
+/openspec next 1 proposal
+```
+
+Then write the artifact file at the path indicated. When done, the
+extension auto-detects the edit and shows updated status.
+
+### 3. Follow the dependency chain
+
+- **proposal** → unlocks **specs** and **design**
+- **specs** → unlocks **design** (if not already unlocked)
+- **design** + **specs** → unlocks **tasks**
+
+Check status anytime with `/openspec status`.
+
+### 4. Validate and archive
+
+When all artifacts are complete:
+
+```
+/openspec validate 1        # check the change is valid
+/openspec archive 1         # archive + merge into main specs
+```
+
+## Rules for the Agent
+
+1. **Always get instructions first.** Before writing any artifact, run
+   `/openspec next` to get the enriched template and instructions from
+   the OpenSpec CLI. Do not guess the format.
+
+2. **Write artifacts in order.** Do not skip ahead. If `design` is
+   blocked, write `proposal` or `specs` first.
+
+3. **One artifact at a time.** Write, save, then check status before
+   moving to the next artifact.
+
+4. **Validate before archiving.** Always run `/openspec validate`
+   before `/openspec archive`.
+
+5. **Use the change number as shorthand.** `/openspec status 1` is
+   cleaner than typing the full directory name.
+
+6. **Proposal is about WHY, not HOW.** Keep implementation details out
+   of the proposal — they belong in design.md.
+
+7. **Specs are requirements, not implementation.** Use GIVEN/WHEN/THEN
+   scenarios. Specs say what the system SHALL do, not how it does it.
+
+8. **Design references specs.** The design document should trace back
+   to specific requirements from the specs.
+
+9. **Tasks must be implementable.** Each task should be a concrete,
+   completable unit of work. Include file paths and specific changes
+   where possible.
+
+## Artifact Status Icons
+
+| Icon | Meaning                                  |
+| ---- | ---------------------------------------- |
+| ✅ ● | Done — artifact file exists              |
+| 🔵 ○ | Ready — dependencies met, can be written |
+| ⏳ ◌ | Blocked — waiting on dependencies        |
+
+## Integration with pi-openspec-status
+
+If `pi-openspec-status` is installed, a persistent TUI widget shows
+the active change status above the editor. Press `Ctrl+Alt+O` for
+a detailed overlay. The widget auto-refreshes after each agent turn.