openspecpm 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to OpenSpecPM are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Post-Sprint 6 — docs, CI, v2 planning
+
+- **v2 roadmap scaffolded as 6 OpenSpec changes** under `openspec/changes/` (dogfood: the tool plans itself with itself). Each change has a full proposal, dependency-aware tasks.md, and BDD scenarios. Roadmap index lives at `openspec/changes/README.md`. Features: `dependency-graph`, `bdd-llm-reviewer`, `spec-to-tests`, `traceability-export`, `additional-adapters` (Notion + ClickUp + Asana), `agent-orchestrator`.
+- **CI tests badge moved to a Gist-backed shields.io endpoint** updated via `schneegans/dynamic-badges-action`. The previous workflow tried to push the badge JSON back to `main`, which branch protection (rightly) rejects. The gist approach updates badge data without ever pushing to main. Required repo settings: `GIST_SECRET` secret (PAT with `gist` scope) + `TESTS_BADGE_GIST_ID` variable.
+- **Test-count parsing fix in `.github/workflows/test.yml`**: `node --test` emits a `ℹ`-prefixed summary on TTY and `#`-prefixed (TAP) on CI. The old regex only matched `ℹ`, so badges silently read 0 in CI. Regex now matches both.
+- **README screenshot pipeline** at `docs/screenshots/render.ps1`: self-contained PowerShell renderer that scaffolds sample OpenSpec changes via `propose --offline`, captures 6 commands (`help-table`, `doctor`, `status`, `next`, `blocked`, `validate`) as terminal-style PNGs using `System.Drawing`, then cleans up. Working tree stays clean.
+- **README ASCII flow diagram** converted to a Mermaid `flowchart LR` block, matching the existing Architecture + Lifecycle diagrams.
+- **Stale-doc sweep**: Linear and GitLab (added Sprints 5–6) now appear in `SKILL.md`, `references/sync.md` (field-mapping table + capabilities + opening line), `references/structure.md` (hierarchy table), `references/conventions.md` (env vars), `SECURITY.md`, both issue templates, and the PR template. `SKILL.md` script-first table now includes `assign`, `watch`, `doctor --install`, `doctor --setup-auth`, `sync --all`, `ship --all-ready`. `CONTRIBUTING.md` test count corrected (49 → 91).
+
+### Sprint 6
+
+- `doctor --install`: OS-detected install hints (winget on Windows, brew on macOS, apt on Linux) for `gh`, `az`, and `openspec`. Linear/GitLab/Jira don't need a CLI.
+- `doctor --setup-auth`: prints the PAT/token creation URL and required scopes for each adapter. Reduces the #1 onboarding cliff to one command.
+- Change-type templates (`cli/src/bdd/templates.js`): `feature`, `bug`, `refactor`, `incident`. `propose --type bug` (etc.) selects the template; `--offline` scaffolds from templates without calling `openspec` so users without OpenSpec installed can still start.
+- Brownfield-aware `init`: detects existing `openspec/` and notes that it will be reused rather than re-initialized.
+- Bulk operations: `sync --all` walks every change with confirmation + per-feature error isolation; `ship --all-ready` ships changes whose tasks are all `sync_state: created` (no pending/failed).
+- `sync --diff`: prints the adapter + capabilities summary alongside the call plan.
+- `watch [feature]`: debounced recursive `fs.watch` over `openspec/changes/`. Re-runs BDD lint per change, or `validate` with `--all`. SIGINT-clean.
+- Notifications (`cli/src/notify.js`): Slack incoming-webhook + Teams MessageCard + generic JSON envelope. Configured via `config.notify.{slack,teams,generic}`. Wired into `standup --broadcast`. Errors per target are collected, never raised.
+- Telemetry scaffold (`cli/src/telemetry.js`): opt-in via `config.telemetry.enabled = true`. Alpha policy: data is mirrored to the audit log only — **no network calls**. Captures command/duration/adapter/OS; never feature names or repo identifiers.
+- Plugin hook documented: `registerAdapter()` was added in Sprint 5; templates and notify both expose their config shapes for third parties to extend.
+- Tests: +14 (templates per type, notify routing per platform, install-hints lookup). Total 91/91 green.
+
+### Sprint 5
+
+- Linear adapter (GraphQL at `api.linear.app/graphql`). Bearer auth via `LINEAR_API_KEY`. Full 9-method implementation: projectCreate for epics, issueCreate with parent linkage, cycle/estimate fields for sprints/story-points, workflow-state lookup for close, viewer query for doctor.
+- GitLab adapter (REST v4). PAT auth via `GITLAB_TOKEN` with `api` scope. Issues + issue links (`relates_to`/`blocks`), milestones as sprints, `weight` as story points, `state_event=close` for close.
+- Plugin hook: `registerAdapter(name, ctor, { aliases })` in `cli/src/adapters/index.js` lets third parties register without forking.
+- Cross-feature `depends_on`: tasks may reference `<feature>/<task-title>` or `<feature>/<external-id>`. `findNextTasks` and `findBlockedTasks` walk the full change set and resolve across features. Legacy same-change deps still work.
+- `assign <feature> <task>` command: sets assignee / sprint / iteration / area / story-points on a synced work item via `adapter.updateWorkItem`. Backend-agnostic surface — adapters pick up the keys they support.
+- GitHub adapter: `listChildren(parent)` and `removeChild(parent, child)` for full sub-issue hierarchy management.
+- Integration test harness under `cli/tests/integration/` — gated on `OPENSPECPM_INTEGRATION=1` + per-backend env vars. README + harness helpers; CI does not run them.
+- Init wizard adds Linear + GitLab options with auth hints.
+- Tests: +14 (Linear adapter contract, GitLab adapter contract, cross-feature deps). Total 77/77 green.
+
+### Sprint 4
+
+- `comment <feature> <task>`: post local `progress.md` (or `-m "..."`) to the PM tool with an auto-generated `<!-- SYNCED: <iso> -->` marker; appends to local progress for traceability.
+- `reconcile <feature>`: fetches every task with an `external_id` via `adapter.getWorkItem` and mirrors the remote `status`/`assignee` into local task frontmatter. Detects out-of-band closes so `next`/`blocked` reflect remote truth.
+- `decompose <feature>`: extracts tasks from proposal headings, GitHub-style checklists, "Tasks" sections, and BDD scenarios in `specs/`. Refuses to overwrite an existing `tasks.md` without `--force`.
+- `validate`: walks every change checking proposal frontmatter shape, task schema (`sync_state` enum, required fields, duplicate titles), `depends_on` reference resolution, and BDD lint summary. Exits non-zero on any error.
+- `search <query>`: case-insensitive regex grep across `openspec/changes/**/*.md`. `--case-sensitive` and `-l <limit>` flags.
+- `fan-out <feature>`: emits ready-to-paste agent prompts for `parallel: true` tasks with no unmet deps. Each prompt embeds the proposal summary, design notes, and the linked BDD spec as acceptance criteria.
+- `bug-report <feature> <task> --title "..."`: files a regression bug via `adapter.createWorkItem`, links it to the original via `linkWorkItems`, comments on the original. Works against all three adapters.
+- `help-table [topic]`: CCPM-style topical help. Groups commands by phase (Setup / Plan / Sync / Track / Execute-Ship).
+- Audit log (`cli/src/audit.js`): every command appends a JSONL entry to `.openspecpm/audit.log` with timestamp, args (secrets scrubbed), and result/error. Wrapped via `audited()` helper in `cli/bin/openspecpm.js`.
+- Tests: +9 covering audit (record + scrub + audited wrapper), validate inputs, decompose heuristics + idempotency, search. Total 58/58 green.
+
+### Sprint 3
+
+- BDD linter (`cli/src/bdd/linter.js`): parses `Scenario:` blocks, runs heuristic checks (one Given/When/Then, observable verbs in Then, deny-list for vague phrases, tautology detection via word-bigram similarity). Soft mode at `propose`, hard mode at `sync` with `--force` override.
+- Tracking commands: `status` (per-change task counts), `standup` (recent `progress.md` updates with `--since 12h/2d/1w`), `next` (open tasks with satisfied deps), `blocked` (tasks waiting on unmet deps with reasons).
+- `ship <feature>`: closes every synced work item via the adapter, closes the epic, then shells out to `openspec archive`. Two-step confirmation (or `-y`).
+- `cli/src/tracking.js` helper: `listChanges`, `loadChange`, `findNextTasks`, `findBlockedTasks`, `findRecentUpdates`, `unmetDeps`, `summarizeChange`.
+- `references/track.md` skill doc.
+- Final SKILL.md description with all Sprint 3 trigger phrases and sharpened non-triggers vs CCPM.
+- 12 new tests (BDD linter + tracking), 49 total.
+
+### Sprint 2
+
+- Azure DevOps Boards adapter (REST + PAT auth). All 9 adapter methods implemented: WIQL list, JSON-Patch create/update, Parent/Child hierarchy links, state-based close, comments.
+- Jira adapter (REST v3 + email/API-token auth). All 9 methods implemented: JQL list, ADF descriptions, issue links, transition-based close, comments.
+- Shared HTTP helper (`cli/src/http.js`) with Basic-auth injection, JSON parsing, status-code-aware remediation hints.
+- Contract tests for both REST adapters against mocked `fetch` (21 new tests, 37 total).
+- Skill references: `structure.md`, `sync.md`, `execute.md` (covering capabilities-driven hierarchy collapse, idempotency contract, field-mapping table per backend, hidden-by-default worktrees).
+- `doctor ado` and `doctor jira` validate auth + reach the backend's identity endpoint.
+
+### Sprint 1
+
+- Repo scaffold: Node CLI with Commander, OpenSpec bridge with version-probe anti-corruption layer.
+- Adapter base class + `capabilities()` contract.
+- GitHub adapter (uses `gh` CLI).
+- `openspecpm init` interactive wizard (`@clack/prompts`).
+- `openspecpm doctor github` with English remediation hints.
+- `openspecpm propose` (wraps OpenSpec) and `openspecpm sync` (idempotent, frontmatter-tracked).
+- Agent Skill scaffold under `skill/openspecpm/` with conventions + plan references.
+- 16 unit + contract tests; GitHub Actions CI on Node 20.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aks-builds
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,352 @@
+# OpenSpecPM — Spec-driven PM for any backend
+
+[![test](https://github.com/aks-builds/openspecpm/actions/workflows/test.yml/badge.svg?event=push)](https://github.com/aks-builds/openspecpm/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![tests](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2Faks-builds%2F03ce34dc5c6486c004dd8cf4c27ea87c%2Fraw%2Ftests.json)](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, or Jira.
+
+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**<br/>(OpenSpec)"]
+    BDD["📋 **BDD specs**<br/>Given / When / Then"]
+    Tasks["✅ **tasks**"]
+    Tracked["🎯 **Tracked work items**<br/>GitHub · ADO · Jira"]
+    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 three differences:
+
+1. **OpenSpec drives spec authoring** — every feature gets `proposal.md`, `design.md`, `tasks.md`, and a `specs/` folder of BDD scenarios.
+2. **The PM tool is pluggable** — an interactive wizard at `init` time picks GitHub Issues/Projects, Azure DevOps Boards, or Jira.
+3. **Built for non-engineers too** — PMs/BAs/PgMs can drive the flow. A `doctor` command owns auth-setup pain. Worktrees are hidden by default.
+
+## 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):
+
+![openspecpm help-table](docs/screenshots/help-table.png)
+
+**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:
+
+![openspecpm doctor](docs/screenshots/doctor.png)
+
+**3 · Multi-feature status** — `status` shows the configured adapter and per-change task counts (`synced / pending / failed / done`) at a glance:
+
+![openspecpm status](docs/screenshots/status.png)
+
+**4 · "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:
+
+![openspecpm next](docs/screenshots/next.png)
+
+**5 · "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:
+
+![openspecpm blocked](docs/screenshots/blocked.png)
+
+**6 · Project-wide validation** — `validate` runs the schema check and BDD linter across every change and reports per-feature error + warning counts:
+
+![openspecpm validate](docs/screenshots/validate.png)
+
+## 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 <feature>` | Shell out to OpenSpec; create `openspec/changes/<feature>/`. Soft-lint BDD scenarios. |
+| `decompose <feature>` | Extract tasks from proposal headings/checklists + BDD scenarios into `tasks.md`. |
+| `sync <feature>` | Hard-lint BDD, then create/update work items in the PM tool. Idempotent. |
+| `comment <feature> <task>` | Broadcast local `progress.md` (or `-m`) to the PM tool with `<!-- SYNCED -->` marker. |
+| `reconcile <feature>` | Pull remote work-item state into local frontmatter. Detects out-of-band closes. |
+| `bug-report <feature> <task> --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` | Schema + dependency + BDD-lint sweep across every change. |
+| `search <query>` | Grep across proposals, specs, tasks, progress notes. |
+| `fan-out <feature>` | Emit ready-to-paste agent prompts for `parallel: true` tasks. |
+| `ship <feature> [-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`.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    PM([👤 Project Manager / BA])
+    Dev([👤 Developer])
+    Agent([🤖 AI Agent · Claude Code])
+
+    Skill["**Agent Skill**<br/>skill/openspecpm/SKILL.md<br/><br/>Routes natural-language intent"]
+    CLI["**Node CLI**<br/>cli/bin/openspecpm.js<br/><br/>Commander dispatch + audit"]
+
+    subgraph CMDS["📋 Commands · cli/src/commands/"]
+        direction LR
+        Setup["**① Setup**<br/>init • doctor"]
+        Plan["**② Plan**<br/>propose • decompose"]
+        SyncCmd["**③ Sync**<br/>sync • comment • reconcile<br/>assign • bug-report"]
+        Track["**④ Track**<br/>status • standup • next<br/>blocked • validate • search • watch"]
+        Exec["**⑤ Execute / Ship**<br/>fan-out • ship • help-table"]
+    end
+
+    subgraph CORE["⚙️ Core services · cli/src/"]
+        direction LR
+        Bridge["**OpenSpec Bridge + BDD**<br/>openspec-bridge.js<br/>bdd/linter.js"]
+        TrackingS["**Tracking + Audit**<br/>tracking.js<br/>audit.js"]
+        HTTP["**HTTP + Rate-limit**<br/>http.js<br/>ratelimit.js"]
+        IO["**Config + Notify + Telemetry**<br/>config.js • notify.js<br/>telemetry.js"]
+    end
+
+    subgraph ADAPTERS["🔌 Adapter contract · cli/src/adapters/ · 9 methods + capabilities()"]
+        direction LR
+        GHA["**GitHub**<br/>depth 2"]
+        AzA["**Azure DevOps**<br/>depth 4"]
+        JiA["**Jira**<br/>depth 3"]
+        LiA["**Linear**<br/>depth 2"]
+        GlA["**GitLab**<br/>depth 2"]
+    end
+
+    subgraph EXT["☁️ External PM systems"]
+        direction LR
+        GHE[("GitHub<br/>Issues / Projects")]
+        AzE[("Azure DevOps<br/>Boards")]
+        JiE[("Jira<br/>Cloud / Server")]
+        LiE[("Linear")]
+        GlE[("GitLab<br/>Issues")]
+    end
+
+    subgraph PERSIST["💾 Persistence & sinks"]
+        direction LR
+        FS1["📁 **openspec/**<br/>changes/&lt;feature&gt;/<br/>• proposal.md<br/>• specs/*.md (BDD)<br/>• tasks.md<br/>• updates/progress.md"]
+        FS2["📁 **.openspecpm/**<br/>• config.json<br/>• audit.log (JSONL)<br/>• state.json"]
+        Sinks["🔔 **Webhooks**<br/>• Slack<br/>• Teams<br/>• 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**<br/>stakeholder feature,<br/>bug, or refactor"]
+
+    subgraph P1["① PLAN"]
+        direction TB
+        Propose["**openspecpm propose**<br/>Shells out to OpenSpec<br/>Soft BDD lint"]
+        Decompose["**openspecpm decompose**<br/>Extract tasks from<br/>proposal + BDD"]
+        Propose --> Decompose
+    end
+
+    subgraph P2["② REVIEW + SYNC"]
+        direction TB
+        Review["👀 **Human review**<br/>Sign off on BDD"]
+        Validate["**openspecpm validate**<br/>Schema + BDD sweep"]
+        SyncCmd["**openspecpm sync**<br/>Hard BDD lint<br/>Idempotent"]
+        Review --> Validate --> SyncCmd
+    end
+
+    subgraph P3["③ EXECUTE"]
+        direction TB
+        Next["**openspecpm next**"]
+        FanOut["**openspecpm fan-out**<br/>Parallel agent prompts"]
+        Build["🤖 **Implement**<br/>BDD = acceptance criteria"]
+        Comment["**openspecpm comment**<br/>Broadcast progress"]
+        Reconcile["**openspecpm reconcile**<br/>Pull remote state"]
+        Next --> FanOut --> Build --> Comment --> Reconcile
+    end
+
+    subgraph P4["④ TRACK"]
+        direction TB
+        Status["**Track commands**<br/>status • standup<br/>blocked • search<br/>watch • bug-report"]
+    end
+
+    subgraph P5["⑤ SHIP"]
+        direction TB
+        Ship["**openspecpm ship**<br/>Close tasks + epic<br/>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.
+
+## 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 `<!-- SYNCED: <ts> -->` 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.
+
+## Roadmap
+
+Active v2 work is tracked as OpenSpec changes under [`openspec/changes/`](openspec/changes/README.md). Six features are scaffolded with full proposals, dependency-aware task lists, and BDD scenarios: dependency-graph visualization, LLM-backed BDD reviewer, 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 <change>` to push any of the six into a tracked PM tool.
+
+## Project structure
+
+```
+openspecpm/
+├── README.md              this file
+├── LICENSE                MIT
+├── CHANGELOG.md
+├── package.json
+├── .github/workflows/test.yml
+├── 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, sync, status, standup, next, blocked, ship
+    │   ├── adapters/      base, github, azure, jira, index
+    │   ├── bdd/           linter, templates
+    │   ├── http.js        REST helper for ADO + Jira
+    │   ├── tracking.js    listChanges, findNext, findBlocked, findRecent
+    │   ├── openspec-bridge.js
+    │   ├── config.js
+    │   ├── frontmatter.js
+    │   └── ratelimit.js
+    └── tests/             unit + contract tests (count badge is auto-updated by CI)
+```
+
+## License
+
+[MIT](LICENSE)

package/cli/bin/openspecpm.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { audited } from '../src/audit.js';
+import { runInit } from '../src/commands/init.js';
+import { runDoctor } from '../src/commands/doctor.js';
+import { runPropose } from '../src/commands/propose.js';
+import { runDecompose } from '../src/commands/decompose.js';
+import { runSync } from '../src/commands/sync.js';
+import { runComment } from '../src/commands/comment.js';
+import { runReconcile } from '../src/commands/reconcile.js';
+import { runStatus } from '../src/commands/status.js';
+import { runStandup } from '../src/commands/standup.js';
+import { runNext } from '../src/commands/next.js';
+import { runBlocked } from '../src/commands/blocked.js';
+import { runValidate } from '../src/commands/validate.js';
+import { runSearch } from '../src/commands/search.js';
+import { runFanOut } from '../src/commands/fan-out.js';
+import { runBugReport } from '../src/commands/bug-report.js';
+import { runShip } from '../src/commands/ship.js';
+import { runHelp } from '../src/commands/help.js';
+import { runAssign } from '../src/commands/assign.js';
+import { runSyncAll, runShipAllReady } from '../src/commands/bulk.js';
+import { runWatch } from '../src/commands/watch.js';
+
+const program = new Command();
+
+program
+  .name('openspecpm')
+  .description('Spec-driven, BDD-shaped project management for AI agents.')
+  .version('0.1.0-alpha.0');
+
+program
+  .command('init')
+  .description('Interactive wizard: pick a PM tool and write .openspecpm/config.json')
+  .option('--non-interactive', 'Fail instead of prompting when input is required')
+  .action((opts) => audited('init', runInit)(opts).catch(fatal));
+
+program
+  .command('doctor [adapter]')
+  .description('Check auth + tooling health for one or all adapters')
+  .option('--install', 'Print OS-specific install commands for missing CLIs')
+  .option('--setup-auth', 'Print PAT/token URLs and required scopes')
+  .action((adapter, opts) => audited('doctor', runDoctor)({ adapter, install: opts.install, setupAuth: opts.setupAuth }).catch(fatal));
+
+program
+  .command('propose <feature>')
+  .description('Create an OpenSpec proposal (proposal.md, design.md, tasks.md, specs/) for <feature>')
+  .option('-p, --prompt <text>', 'One-line description for the AI to seed the proposal')
+  .option('-t, --type <type>', 'Change type: feature | bug | refactor | incident', 'feature')
+  .option('--offline', 'Scaffold from templates without calling the openspec CLI')
+  .action((feature, opts) => audited('propose', runPropose)({ feature, prompt: opts.prompt, type: opts.type, offline: opts.offline }).catch(fatal));
+
+program
+  .command('decompose <feature>')
+  .description('Extract tasks from proposal + BDD scenarios into tasks.md')
+  .option('--force', 'Merge into an existing tasks.md instead of refusing')
+  .action((feature, opts) => audited('decompose', runDecompose)({ feature, force: opts.force }).catch(fatal));
+
+program
+  .command('sync [feature]')
+  .description('Push an OpenSpec change to the configured PM tool (idempotent; BDD-linted)')
+  .option('--all', 'Sync every change under openspec/changes/')
+  .option('--dry-run', 'Print the call plan without making remote changes')
+  .option('--force', 'Bypass BDD lint errors')
+  .option('--diff', 'Show the call plan in detail')
+  .option('-y, --yes', 'Skip the confirmation prompt for --all')
+  .action((feature, opts) => {
+    if (opts.all) {
+      return audited('sync-all', runSyncAll)({ dryRun: opts.dryRun, force: opts.force, yes: opts.yes }).catch(fatal);
+    }
+    if (!feature) {
+      process.stderr.write('error: provide a <feature> or pass --all\n');
+      process.exit(1);
+    }
+    return audited('sync', runSync)({ feature, dryRun: opts.dryRun, force: opts.force, diff: opts.diff }).catch(fatal);
+  });
+
+program
+  .command('comment <feature> <task>')
+  .description('Post a progress comment to the PM tool work item')
+  .option('-m, --message <text>', 'Inline message (otherwise reads from local progress.md)')
+  .option('--dry-run', 'Print the comment instead of posting')
+  .action((feature, task, opts) =>
+    audited('comment', runComment)({ feature, task, message: opts.message, dryRun: opts.dryRun }).catch(fatal),
+  );
+
+program
+  .command('reconcile <feature>')
+  .description('Pull remote state back into local task frontmatter')
+  .option('--dry-run', 'Show drift without writing local changes')
+  .action((feature, opts) => audited('reconcile', runReconcile)({ feature, dryRun: opts.dryRun }).catch(fatal));
+
+program
+  .command('status')
+  .description('Local snapshot: configured adapter + per-change task counts')
+  .action(() => audited('status', runStatus)().catch(fatal));
+
+program
+  .command('standup')
+  .description('Show progress updates within a recent window')
+  .option('--since <window>', 'Time window: e.g. 12h, 2d, 1w', '24h')
+  .option('--broadcast', 'Also POST to configured Slack/Teams/generic webhooks')
+  .action((opts) => audited('standup', runStandup)({ since: opts.since, broadcast: opts.broadcast }).catch(fatal));
+
+program
+  .command('next')
+  .description('List tasks ready to start (no unmet dependencies)')
+  .option('-l, --limit <n>', 'Max items to show', (v) => parseInt(v, 10), 5)
+  .action((opts) => audited('next', runNext)({ limit: opts.limit }).catch(fatal));
+
+program
+  .command('blocked')
+  .description('List tasks waiting on unmet dependencies')
+  .action(() => audited('blocked', runBlocked)().catch(fatal));
+
+program
+  .command('validate')
+  .description('Schema + dependency + BDD-lint sweep across every change')
+  .action(() => audited('validate', runValidate)().catch(fatal));
+
+program
+  .command('search <query>')
+  .description('Grep across proposals, specs, tasks, and progress notes')
+  .option('-l, --limit <n>', 'Max matches to show', (v) => parseInt(v, 10), 50)
+  .option('--case-sensitive', 'Match case')
+  .action((query, opts) =>
+    audited('search', runSearch)({ query, limit: opts.limit, caseSensitive: opts.caseSensitive }).catch(fatal),
+  );
+
+program
+  .command('fan-out <feature>')
+  .description('Emit ready-to-paste agent prompts for parallel:true tasks')
+  .option('-l, --limit <n>', 'Max prompts to emit', (v) => parseInt(v, 10), 5)
+  .action((feature, opts) => audited('fan-out', runFanOut)({ feature, limit: opts.limit }).catch(fatal));
+
+program
+  .command('bug-report <feature> <task>')
+  .description('File a regression bug linked to a shipped task')
+  .option('-t, --title <text>', 'Bug title (required)')
+  .option('-b, --body <text>', 'Bug body')
+  .action((feature, task, opts) =>
+    audited('bug-report', runBugReport)({ feature, task, title: opts.title, body: opts.body }).catch(fatal),
+  );
+
+program
+  .command('assign <feature> <task>')
+  .description('Set assignee / sprint / iteration / area / story-points on a synced task')
+  .option('--assignee <id>', 'Assignee id (backend-specific)')
+  .option('--sprint <id>', 'Sprint / cycle / milestone id (whichever the backend supports)')
+  .option('--iteration <path>', 'Iteration path (Azure DevOps; alias for --sprint elsewhere)')
+  .option('--area <path>', 'Area path (Azure DevOps)')
+  .option('--story-points <n>', 'Story points / estimate / weight')
+  .action((feature, task, opts) =>
+    audited('assign', runAssign)({
+      feature, task,
+      assignee: opts.assignee, sprint: opts.sprint, iteration: opts.iteration,
+      area: opts.area, storyPoints: opts.storyPoints,
+    }).catch(fatal),
+  );
+
+program
+  .command('ship [feature]')
+  .description('Close all work items for <feature> and archive the OpenSpec change')
+  .option('--all-ready', 'Ship every change whose tasks are all synced (no pending/failed)')
+  .option('-y, --yes', 'Skip the confirmation prompt')
+  .option('--skip-archive', 'Close work items but leave openspec/changes/<feature>/ in place')
+  .action((feature, opts) => {
+    if (opts.allReady) {
+      return audited('ship-all-ready', runShipAllReady)({ yes: opts.yes, skipArchive: opts.skipArchive }).catch(fatal);
+    }
+    if (!feature) {
+      process.stderr.write('error: provide a <feature> or pass --all-ready\n');
+      process.exit(1);
+    }
+    return audited('ship', runShip)({ feature, yes: opts.yes, skipArchive: opts.skipArchive }).catch(fatal);
+  });
+
+program
+  .command('watch [feature]')
+  .description('Re-lint on file change. Use --all to validate the whole project on every change.')
+  .option('--all', 'Validate every change instead of linting one feature')
+  .option('--debounce <ms>', 'Debounce window in milliseconds', (v) => parseInt(v, 10), 300)
+  .action((feature, opts) =>
+    audited('watch', runWatch)({ feature, allChanges: opts.all, debounceMs: opts.debounce }).catch(fatal),
+  );
+
+program
+  .command('help-table [topic]')
+  .description('Context-aware help grouped by workflow phase')
+  .action((topic) => { runHelp({ topic }); });
+
+program.parseAsync(process.argv);
+
+function fatal(err) {
+  process.stderr.write(`\n✖ ${err.message}\n`);
+  if (err.remediation) process.stderr.write(`  → ${err.remediation}\n`);
+  process.exit(1);
+}