https://github.com/aks-builds/openspecpm
Spec-driven, BDD-shaped project management for AI agents. OpenSpec proposals → BDD specs → tracked work in GitHub / Azure DevOps / Jira / Linear / GitLab.
https://github.com/aks-builds/openspecpm
agent-skills azure-devops bdd-framework claude-code github-issues gitlab jira linear nodejs openspec project-management spec-driven-development
Last synced: 10 days ago
JSON representation
Spec-driven, BDD-shaped project management for AI agents. OpenSpec proposals → BDD specs → tracked work in GitHub / Azure DevOps / Jira / Linear / GitLab.
- Host: GitHub
- URL: https://github.com/aks-builds/openspecpm
- Owner: aks-builds
- License: mit
- Created: 2026-05-17T05:51:19.000Z (17 days ago)
- Default Branch: main
- Last Pushed: 2026-05-18T09:04:00.000Z (16 days ago)
- Last Synced: 2026-05-19T20:13:52.645Z (15 days ago)
- Topics: agent-skills, azure-devops, bdd-framework, claude-code, github-issues, gitlab, jira, linear, nodejs, openspec, project-management, spec-driven-development
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/openspecpm
- Size: 971 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# OpenSpecPM — Spec-driven PM for any backend
[](https://github.com/aks-builds/openspecpm/actions/workflows/test.yml)
[](https://opensource.org/licenses/MIT)
[](cli/tests)
> Spec-driven, BDD-shaped project management for AI agents — author once in [OpenSpec](https://github.com/Fission-AI/OpenSpec), sync to GitHub Issues, Azure DevOps Boards, Jira, Linear, or GitLab.
OpenSpecPM turns natural-language intent ("plan X", "sync the X epic", "what's blocked", "ship X") into a disciplined flow:
```mermaid
flowchart LR
Idea["💡 **Idea**"]
Proposal["📝 **proposal.md**
(OpenSpec)"]
BDD["📋 **BDD specs**
Given / When / Then"]
Tasks["✅ **tasks**"]
Tracked["🎯 **Tracked work items**
GitHub · ADO · Jira · Linear · GitLab"]
Shipped["🚀 **Shipped code**"]
Idea --> Proposal --> BDD --> Tasks --> Tracked --> Shipped
classDef ideaC fill:#FFF9C4,stroke:#F9A825,color:#000
classDef artifactC fill:#D5E8D4,stroke:#82B366,color:#000
classDef extC fill:#DAE8FC,stroke:#6C8EBF,color:#000
classDef doneC fill:#C8E6C9,stroke:#2E7D32,color:#000
class Idea ideaC
class Proposal,BDD,Tasks artifactC
class Tracked extC
class Shipped doneC
```
It is a sibling of [CCPM](https://github.com/automazeio/ccpm), with five differences:
1. **OpenSpec drives spec authoring + BDD scenarios become enforceable.** Every feature gets `proposal.md`, `design.md`, `tasks.md`, and a `specs/` folder of Given/When/Then scenarios. A heuristic linter blocks vague Thens at `sync` time. An optional [LLM judge](#architecture-highlights) (Claude Haiku 4.5, opt-in via `--llm`) catches cross-spec contradictions and missing-coverage gaps the regex linter can't see.
2. **Five pluggable PM backends** — an interactive wizard at `init` time picks GitHub Issues/Projects, Azure DevOps Boards, Jira, Linear, or GitLab. New backends register without forking via `registerAdapter()`.
3. **Built for non-engineers too** — PMs/BAs/PgMs can drive the flow. A `doctor` command owns auth-setup pain (with `--install` and `--setup-auth` flags for OS-specific install hints and PAT-creation URLs). Worktrees are hidden by default.
4. **Audit-logged by default.** Every command appends a JSONL entry (secrets scrubbed) to `.openspecpm/audit.log`. Useful for regulated industries that need a paper trail; useful for the rest of us when something looks weird.
5. **Cross-feature task graphs.** `depends_on:` can reach across changes (`/` or `/`), so `next` and `blocked` reflect the whole project rather than one feature in isolation.
## Architecture
```mermaid
flowchart TD
PM([👤 Project Manager / BA])
Dev([👤 Developer])
Agent([🤖 AI Agent · Claude Code])
Skill["**Agent Skill**
skill/openspecpm/SKILL.md
Routes natural-language intent"]
CLI["**Node CLI**
cli/bin/openspecpm.js
Commander dispatch + audit"]
subgraph CMDS["📋 Commands · cli/src/commands/"]
direction LR
Setup["**① Setup**
init • doctor"]
Plan["**② Plan**
propose • decompose"]
SyncCmd["**③ Sync**
sync • comment • reconcile
assign • bug-report"]
Track["**④ Track**
status • standup • next
blocked • validate • search • watch"]
Exec["**⑤ Execute / Ship**
fan-out • ship • help-table"]
end
subgraph CORE["⚙️ Core services · cli/src/"]
direction LR
Bridge["**OpenSpec Bridge + BDD**
openspec-bridge.js
bdd/linter.js"]
TrackingS["**Tracking + Audit**
tracking.js
audit.js"]
HTTP["**HTTP + Rate-limit**
http.js
ratelimit.js"]
IO["**Config + Notify + Telemetry**
config.js • notify.js
telemetry.js"]
end
subgraph ADAPTERS["🔌 Adapter contract · cli/src/adapters/ · 9 methods + capabilities()"]
direction LR
GHA["**GitHub**
depth 2"]
AzA["**Azure DevOps**
depth 4"]
JiA["**Jira**
depth 3"]
LiA["**Linear**
depth 2"]
GlA["**GitLab**
depth 2"]
end
subgraph EXT["☁️ External PM systems"]
direction LR
GHE[("GitHub
Issues / Projects")]
AzE[("Azure DevOps
Boards")]
JiE[("Jira
Cloud / Server")]
LiE[("Linear")]
GlE[("GitLab
Issues")]
end
subgraph PERSIST["💾 Persistence & sinks"]
direction LR
FS1["📁 **openspec/**
changes/<feature>/
• proposal.md
• specs/*.md (BDD)
• tasks.md
• updates/progress.md"]
FS2["📁 **.openspecpm/**
• config.json
• audit.log (JSONL)
• state.json"]
Sinks["🔔 **Webhooks**
• Slack
• Teams
• Generic JSON"]
end
PM --> Skill
Dev --> CLI
Agent --> Skill
Skill -- invokes --> CLI
CLI --> CMDS
CMDS --> CORE
CORE --> ADAPTERS
GHA --> GHE
AzA --> AzE
JiA --> JiE
LiA --> LiE
GlA --> GlE
Bridge -. writes .-> FS1
TrackingS -. writes .-> FS1
IO -. writes .-> FS2
IO -. broadcast .-> Sinks
classDef user fill:#DAE8FC,stroke:#6C8EBF,color:#000
classDef agent fill:#FFE0B2,stroke:#D97757,color:#000
classDef entry fill:#C5E1A5,stroke:#558B2F,color:#000
classDef skill fill:#FFE0B2,stroke:#D97757,color:#000
classDef github fill:#222,stroke:#000,color:#fff
classDef azure fill:#0078D7,stroke:#005A9E,color:#fff
classDef jira fill:#0052CC,stroke:#003580,color:#fff
classDef linear fill:#5E6AD2,stroke:#3F47A0,color:#fff
classDef gitlab fill:#FC6D26,stroke:#C44A19,color:#fff
classDef ext fill:#fff,stroke:#333,stroke-width:3px,color:#000
classDef fs fill:#fff,stroke:#444,stroke-width:2px,color:#000
class PM,Dev user
class Agent agent
class CLI entry
class Skill skill
class GHA github
class AzA azure
class JiA jira
class LiA linear
class GlA gitlab
class GHE,AzE,JiE,LiE,GlE ext
class FS1,FS2,Sinks fs
```
## Lifecycle
```mermaid
flowchart LR
Idea["💡 **Idea**
stakeholder feature,
bug, or refactor"]
subgraph P1["① PLAN"]
direction TB
Propose["**openspecpm propose**
Shells out to OpenSpec
Soft BDD lint"]
Decompose["**openspecpm decompose**
Extract tasks from
proposal + BDD"]
Propose --> Decompose
end
subgraph P2["② REVIEW + SYNC"]
direction TB
Review["👀 **Human review**
Sign off on BDD"]
Validate["**openspecpm validate**
Schema + BDD sweep"]
SyncCmd["**openspecpm sync**
Hard BDD lint
Idempotent"]
Review --> Validate --> SyncCmd
end
subgraph P3["③ EXECUTE"]
direction TB
Next["**openspecpm next**"]
FanOut["**openspecpm fan-out**
Parallel agent prompts"]
Build["🤖 **Implement**
BDD = acceptance criteria"]
Comment["**openspecpm comment**
Broadcast progress"]
Reconcile["**openspecpm reconcile**
Pull remote state"]
Next --> FanOut --> Build --> Comment --> Reconcile
end
subgraph P4["④ TRACK"]
direction TB
Status["**Track commands**
status • standup
blocked • search
watch • bug-report"]
end
subgraph P5["⑤ SHIP"]
direction TB
Ship["**openspecpm ship**
Close tasks + epic
Archive change"]
Shipped["🚀 **Shipped**"]
Ship --> Shipped
end
Idea --> P1
P1 --> P2
P2 --> P3
P3 --> P4
P4 --> P5
Shipped -. next feature .-> Idea
classDef ideaC fill:#FFF9C4,stroke:#F9A825,color:#000
classDef cmdC fill:#D5E8D4,stroke:#82B366,color:#000
classDef humanC fill:#FFF9C4,stroke:#F9A825,color:#000
classDef agentC fill:#FFE0B2,stroke:#D97757,color:#000
classDef shipC fill:#FFCDD2,stroke:#D32F2F,color:#000
classDef doneC fill:#C8E6C9,stroke:#2E7D32,color:#000
class Idea ideaC
class Propose,Decompose,Validate,SyncCmd,Next,FanOut,Comment,Reconcile,Status cmdC
class Review humanC
class Build agentC
class Ship shipC
class Shipped doneC
```
> Cross-cutting on every command: audit log (`.openspecpm/audit.log`, secrets scrubbed) · token-bucket rate-limiting per adapter · OpenSpec version probe · optional opt-in telemetry · optional Slack / Teams / generic-webhook broadcasts on `standup --broadcast`.
## Install
```bash
# Standalone CLI (any harness)
npx openspecpm@latest init
# Claude Code Agent Skill
# Copy skill/openspecpm/ into your Claude Code skills directory.
# SKILL.md handles routing — just talk to Claude.
```
OpenSpecPM shells out to [OpenSpec](https://github.com/Fission-AI/OpenSpec); install it first:
```bash
npm install -g @fission-ai/openspec
```
## In action
> A walkthrough of OpenSpecPM running against two sample features (`dark-mode`, `auth-rate-limit`). Source images live in [`docs/screenshots/`](docs/screenshots/); regenerate with `pwsh docs/screenshots/render.ps1` after CLI output changes — the renderer sets up its own sample data and cleans up after itself.
**1 · Phase-grouped command reference** — `help-table` shows every command grouped by workflow phase (Setup → Plan → Sync → Track → Execute/Ship):
**2 · Health check across every adapter** — `doctor` diagnoses auth + tooling for all five backends (GitHub, Azure DevOps, Jira, Linear, GitLab) with an English remediation hint on every failure. The `[judge]` section reports `ANTHROPIC_API_KEY` for the optional LLM BDD judge:
**3 · Author a proposal** — `propose --offline` scaffolds `proposal.md`, `tasks.md`, and `specs/main.md` from templates without calling the OpenSpec CLI. Soft BDD lint runs immediately so placeholder Then-clauses are flagged before you keep editing:
**4 · Optional LLM BDD judge** — pass `--llm` (or set `judge.enabled: true` in `.openspecpm/config.json`) to augment the heuristic linter with Claude Haiku 4.5. The judge catches what regex can't: cross-spec contradictions (`bdd/llm-contradiction`), success criteria with no scenario (`bdd/llm-missing-coverage`), and Then-clauses that pass the verb check but state no observable outcome (`bdd/llm-vague-then`). Findings merge into the same lint stream and respect `--force` the same way. Prompt-cached on the proposal so re-runs across multiple specs stay cheap. *Sample output below — real findings vary per scenario set; the judge can't be regenerated by `render.ps1` because it requires a live `ANTHROPIC_API_KEY`:*
**5 · Decompose into tasks** — `decompose` walks proposal headings, GitHub-style checklists, a `Tasks` section, and BDD scenarios under `specs/` and writes a structured `tasks.md` with `sync_state` frontmatter:
**6 · Multi-feature status** — `status` shows the configured adapter and per-change task counts (`synced / pending / failed / done`) at a glance:
**7 · "What can I work on right now?"** — `next` lists tasks with no unmet dependencies, marking parallel-safe ones so multiple agents can pick them up:
**8 · "What's waiting on what?"** — `blocked` lists every task held up by a dependency and names the blocker, so the path to unblocking is one read away:
**9 · Parallel-agent dispatch** — `fan-out` emits ready-to-paste prompts for `parallel: true` tasks with no unmet deps. Each prompt embeds the proposal summary, design notes, and BDD spec as acceptance criteria so subagents can work in isolation:
**10 · Cross-file search** — `search` is a case-insensitive grep across every proposal, spec, tasks file, and progress note. Useful for tracing back from a keyword to the change that owns it:
**11 · Project-wide validation** — `validate` runs the schema check and BDD linter across every change and reports per-feature error + warning counts:
## Quick start
```bash
# 1. One-time setup. The wizard asks which PM tool your team uses.
npx openspecpm init
# 2. Verify auth before doing anything remote.
npx openspecpm doctor
# 3. Author a proposal. OpenSpec generates proposal.md, design.md, tasks.md,
# and BDD scenarios in specs/. Soft BDD-lint runs after authoring.
npx openspecpm propose dark-mode --prompt "Per-user dark theme with persistence."
# 4. Review the generated files. Refine BDD scenarios until lint is clean.
# 5. Sync to the PM tool. Hard BDD lint runs first; pass --force to override.
npx openspecpm sync dark-mode
# 6. Pick up where you left off.
npx openspecpm next # tasks ready to start
npx openspecpm blocked # tasks waiting on dependencies
npx openspecpm standup # progress updates in the last 24h
# 7. When the feature is verified, close + archive.
npx openspecpm ship dark-mode
```
## Command reference
| Command | What it does |
|---|---|
| `init` | Interactive wizard. Picks the PM tool. Writes `.openspecpm/config.json`. |
| `doctor [adapter]` | Auth/tooling health check. English remediation hints on every failure. |
| `propose [--llm]` | Shell out to OpenSpec; create `openspec/changes//`. Soft-lint BDD scenarios; `--llm` adds the LLM judge. |
| `decompose ` | Extract tasks from proposal headings/checklists + BDD scenarios into `tasks.md`. |
| `sync [--llm]` | Hard-lint BDD, then create/update work items in the PM tool. Idempotent; `--llm` adds the LLM judge as a hard gate. |
| `comment ` | Broadcast local `progress.md` (or `-m`) to the PM tool with `` marker. |
| `reconcile ` | Pull remote work-item state into local frontmatter. Detects out-of-band closes. |
| `bug-report --title "…"` | File a linked regression against a shipped task. |
| `status` | Per-change task counts: pending / created / failed / done. |
| `standup [--since 24h]` | Recent `progress.md` updates, newest first. |
| `next [-l 5]` | Tasks with no unmet dependencies. |
| `blocked` | Tasks waiting on unmet dependencies (with reasons). |
| `validate [--llm]` | Schema + dependency + BDD-lint sweep across every change; `--llm` adds the LLM judge per change. |
| `search ` | Grep across proposals, specs, tasks, progress notes. |
| `fan-out ` | Emit ready-to-paste agent prompts for `parallel: true` tasks. |
| `ship [-y]` | Close all task work items + close the epic + archive the OpenSpec change. |
| `help-table [topic]` | Context-aware command reference grouped by workflow phase. |
Every command appends a JSONL entry (secrets scrubbed) to `.openspecpm/audit.log`.
## Workflow phases
OpenSpecPM is organized into five phases, each with a reference doc under [`skill/openspecpm/references/`](skill/openspecpm/references/):
1. **Plan** ([`plan.md`](skill/openspecpm/references/plan.md)) — Capture requirements through an OpenSpec proposal + BDD scenarios.
2. **Structure** ([`structure.md`](skill/openspecpm/references/structure.md)) — Decompose into tasks with explicit dependencies and parallelism hints.
3. **Sync** ([`sync.md`](skill/openspecpm/references/sync.md)) — Push to the PM tool. Capabilities-driven hierarchy collapse for flatter backends.
4. **Execute** ([`execute.md`](skill/openspecpm/references/execute.md)) — Start work on a tracked item. Optional worktrees, parallel-agent dispatch.
5. **Track** ([`track.md`](skill/openspecpm/references/track.md)) — Status, standup, next, blocked, ship.
## Architecture highlights
- **Adapter contract.** Every backend implements the same 9-method interface plus `capabilities()` reporting hierarchy depth (GitHub=2, Linear=2, GitLab=2, Jira=3, ADO=4). The sync layer collapses levels gracefully.
- **OpenSpec anti-corruption layer.** Version-pinned probe on every CLI invocation. One constant absorbs upstream path moves.
- **Idempotent sync.** Each task carries `sync_state` + `external_id` in frontmatter. Re-running `sync` skips created items and retries failures. Comments use `` markers to prevent duplication.
- **Token-bucket rate-limiting.** Per-adapter presets tuned for each backend's published limits.
- **BDD linter.** Heuristic checks: one Given/When/Then per scenario, observable verbs in Then, deny-list for vague phrases ("should work"), tautology detection via word-bigram similarity.
- **Optional LLM judge.** `--llm` (or `judge.enabled: true` in `.openspecpm/config.json`) augments the heuristic linter with Claude Haiku 4.5 to catch cross-spec contradictions, missing success-criteria coverage, and vague Then predicates the regex linter misses. Uses prompt caching on the proposal so re-runs across multiple specs stay cheap. Requires `ANTHROPIC_API_KEY` — `openspecpm doctor` reports its presence.
## Roadmap
Active v2 work is tracked as OpenSpec changes under [`openspec/changes/`](openspec/changes/README.md). The first scaffolded feature — **`bdd-llm-reviewer`** — shipped in v1.0.0. Five remain: dependency-graph visualization, spec → test scaffolding, compliance traceability export, three new adapters (Notion / ClickUp / Asana), and a real agent orchestrator that graduates `fan-out` from prompt-emitter to dispatcher.
OpenSpecPM dogfoods itself: anyone can `openspecpm next` to see what's ready to start, or `openspecpm sync ` to push any of the five into a tracked PM tool.
## Project structure
```
openspecpm/
├── README.md this file
├── LICENSE MIT
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── package.json
├── .github/
│ ├── workflows/ test.yml · auto-approve.yml · release.yml · publish.yml
│ ├── ISSUE_TEMPLATE/
│ └── PULL_REQUEST_TEMPLATE.md
├── docs/screenshots/ README captures + render.ps1 renderer
├── openspec/changes/ v2 roadmap (each subdir is a tracked change)
├── skill/openspecpm/ Claude Code Agent Skill
│ ├── SKILL.md
│ └── references/ conventions · plan · structure · sync · execute · track
└── cli/
├── bin/openspecpm.js Commander entrypoint
├── src/
│ ├── commands/ init · doctor · propose · decompose · sync · comment · reconcile ·
│ │ status · standup · next · blocked · validate · search · fan-out ·
│ │ bug-report · ship · assign · watch · help · bulk
│ ├── adapters/ base · github · azure · jira · linear · gitlab · index
│ ├── bdd/ linter · judge · templates
│ ├── audit.js JSONL audit log + secret scrubber
│ ├── http.js REST helper for ADO / Jira / Linear / GitLab
│ ├── tracking.js listChanges · findNext · findBlocked · findRecent
│ ├── notify.js Slack / Teams / generic-webhook envelopes
│ ├── telemetry.js opt-in, audit-log-only at alpha
│ ├── install-hints.js
│ ├── openspec-bridge.js
│ ├── config.js
│ ├── frontmatter.js
│ └── ratelimit.js
└── tests/ unit + contract tests (count badge is auto-updated by CI)
```
## License
[MIT](LICENSE)