openspecpm 0.1.0-alpha.0

package/cli/src/tracking.js

@@ -0,0 +1,197 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { OPENSPEC_CHANGES_DIR } from './openspec-bridge.js';
+import * as fm from './frontmatter.js';
+
+/**
+ * @typedef {Object} TaskItem
+ * @property {string} title
+ * @property {'pending'|'created'|'failed'} sync_state
+ * @property {string} [external_id]
+ * @property {string} [external_url]
+ * @property {string[]} [depends_on]
+ * @property {boolean} [done]
+ *
+ * @typedef {Object} ChangeView
+ * @property {string} name
+ * @property {string} dir
+ * @property {Object} proposal     // frontmatter from proposal.md
+ * @property {TaskItem[]} items
+ * @property {Date} mtime          // most recent mtime across change files
+ */
+
+export async function listChanges(cwd = process.cwd()) {
+  const dir = join(cwd, OPENSPEC_CHANGES_DIR);
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const names = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  const out = [];
+  for (const name of names) out.push(await loadChange(name, cwd));
+  return out;
+}
+
+export async function loadChange(name, cwd = process.cwd()) {
+  const dir = join(cwd, OPENSPEC_CHANGES_DIR, name);
+  let proposal = {};
+  const proposalPath = join(dir, 'proposal.md');
+  if (existsSync(proposalPath)) {
+    const raw = await readFile(proposalPath, 'utf8');
+    proposal = fm.parse(raw).data ?? {};
+  }
+  let items = [];
+  const tasksPath = join(dir, 'tasks.md');
+  if (existsSync(tasksPath)) {
+    const raw = await readFile(tasksPath, 'utf8');
+    const { data, body } = fm.parse(raw);
+    items = data.items ?? parseChecklist(body);
+  }
+  const mtime = await mostRecentMtime(dir);
+  return { name, dir, proposal, items, mtime };
+}
+
+/**
+ * Resolve a dep token against a change. Tokens may be:
+ *   "task title"                — same-change reference by title
+ *   "<external-id>"             — same-change reference by remote id
+ *   "<feature>/<task title>"    — cross-change reference by title
+ *   "<feature>/<external-id>"   — cross-change reference by remote id
+ */
+function resolveDep(dep, change, allChanges) {
+  const cross = String(dep).match(/^([^/]+)\/(.+)$/);
+  if (cross) {
+    const [, featureName, rest] = cross;
+    const target = allChanges.find((c) => c.name === featureName);
+    if (!target) return { found: false };
+    const ref = target.items.find((t) => t.title === rest) ?? target.items.find((t) => String(t.external_id) === String(rest));
+    return ref ? { found: true, ref } : { found: false };
+  }
+  const ref = change.items.find((t) => t.title === dep) ?? change.items.find((t) => String(t.external_id) === String(dep));
+  return ref ? { found: true, ref } : { found: false };
+}
+
+export function unmetDeps(task, allTasks, options = {}) {
+  // Backwards compat: when called with a flat task list, treat as same-change.
+  // When called with options.change + options.allChanges, support cross-feature deps.
+  const deps = task.depends_on ?? [];
+  if (!deps.length) return [];
+
+  const unmet = [];
+  if (options.change && options.allChanges) {
+    for (const dep of deps) {
+      const r = resolveDep(dep, options.change, options.allChanges);
+      if (!r.found) { unmet.push({ dep, reason: 'not-found' }); continue; }
+      const ref = r.ref;
+      if (ref.done || (ref.sync_state === 'created' && ref.closed)) continue;
+      unmet.push({ dep, reason: ref.sync_state === 'failed' ? 'dep-failed' : 'dep-open' });
+    }
+    return unmet;
+  }
+
+  // Legacy path
+  const byTitle = new Map(allTasks.map((t) => [t.title, t]));
+  const byId = new Map(allTasks.filter((t) => t.external_id).map((t) => [String(t.external_id), t]));
+  for (const dep of deps) {
+    const cross = String(dep).match(/^([^/]+)\/(.+)$/);
+    if (cross) {
+      // Cross-feature dep with legacy callsite — we can't resolve, mark not-found.
+      unmet.push({ dep, reason: 'cross-feature-unresolved' });
+      continue;
+    }
+    const ref = byTitle.get(dep) ?? byId.get(String(dep));
+    if (!ref) { unmet.push({ dep, reason: 'not-found' }); continue; }
+    if (ref.done || (ref.sync_state === 'created' && ref.closed)) continue;
+    if (!ref.done) unmet.push({ dep, reason: ref.sync_state === 'failed' ? 'dep-failed' : 'dep-open' });
+  }
+  return unmet;
+}
+
+export function findNextTasks(changes) {
+  const candidates = [];
+  for (const change of changes) {
+    for (const task of change.items) {
+      if (task.done) continue;
+      if (task.sync_state === 'created' && task.closed) continue;
+      const unmet = unmetDeps(task, change.items, { change, allChanges: changes });
+      if (unmet.length === 0) candidates.push({ change: change.name, task });
+    }
+  }
+  return candidates;
+}
+
+export function findBlockedTasks(changes) {
+  const blocked = [];
+  for (const change of changes) {
+    for (const task of change.items) {
+      if (task.done) continue;
+      const unmet = unmetDeps(task, change.items, { change, allChanges: changes });
+      if (unmet.length > 0) blocked.push({ change: change.name, task, unmet });
+    }
+  }
+  return blocked;
+}
+
+export async function findRecentUpdates(changes, sinceMs = 24 * 60 * 60 * 1000) {
+  const cutoff = Date.now() - sinceMs;
+  const recent = [];
+  for (const change of changes) {
+    const updatesDir = join(change.dir, 'updates');
+    if (!existsSync(updatesDir)) continue;
+    const tasks = await readdir(updatesDir, { withFileTypes: true });
+    for (const t of tasks) {
+      if (!t.isDirectory()) continue;
+      const progressPath = join(updatesDir, t.name, 'progress.md');
+      if (!existsSync(progressPath)) continue;
+      const s = await stat(progressPath);
+      if (s.mtimeMs >= cutoff) {
+        recent.push({ change: change.name, task: t.name, path: progressPath, mtime: s.mtime });
+      }
+    }
+  }
+  recent.sort((a, b) => b.mtime - a.mtime);
+  return recent;
+}
+
+export function summarizeChange(change) {
+  const total = change.items.length;
+  const counts = { pending: 0, created: 0, failed: 0, done: 0 };
+  for (const t of change.items) {
+    if (t.done) counts.done++;
+    else counts[t.sync_state ?? 'pending']++;
+  }
+  return { total, counts };
+}
+
+function parseChecklist(body) {
+  const items = [];
+  for (const line of (body ?? '').split(/\r?\n/)) {
+    const m = line.match(/^\s*-\s*\[( |x|X)\]\s+(.+?)\s*$/);
+    if (m) items.push({ title: m[2], done: m[1].toLowerCase() === 'x', sync_state: 'pending' });
+  }
+  return items;
+}
+
+async function mostRecentMtime(dir) {
+  let latest = 0;
+  async function walk(d) {
+    let entries;
+    try {
+      entries = await readdir(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) {
+        await walk(p);
+      } else {
+        try {
+          const s = await stat(p);
+          if (s.mtimeMs > latest) latest = s.mtimeMs;
+        } catch { /* ignore */ }
+      }
+    }
+  }
+  await walk(dir);
+  return latest ? new Date(latest) : new Date(0);
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "openspecpm",
+  "version": "0.1.0-alpha.0",
+  "description": "Spec-driven, BDD-shaped project management for AI agents — OpenSpec proposals synced to GitHub, Azure DevOps, Jira, Linear, or GitLab.",
+  "type": "module",
+  "bin": {
+    "openspecpm": "cli/bin/openspecpm.js"
+  },
+  "files": [
+    "cli/bin",
+    "cli/src",
+    "skill",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start": "node cli/bin/openspecpm.js",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "openspec",
+    "ccpm",
+    "agent-skill",
+    "claude-code",
+    "anthropic",
+    "ai-agents",
+    "project-management",
+    "bdd",
+    "spec-driven",
+    "cli",
+    "nodejs",
+    "github",
+    "github-issues",
+    "azure-devops",
+    "jira",
+    "linear",
+    "gitlab"
+  ],
+  "license": "MIT",
+  "author": "aks-builds <its.aks@outlook.com>",
+  "homepage": "https://github.com/aks-builds/openspecpm#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aks-builds/openspecpm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aks-builds/openspecpm/issues"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0",
+    "commander": "^14.0.3",
+    "execa": "^9.4.0",
+    "yaml": "^2.6.0"
+  }
+}

package/skill/openspecpm/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: openspecpm
+description: "OpenSpecPM — spec-driven, BDD-shaped project management for any PM backend: OpenSpec proposal → BDD specs (Given/When/Then) → tasks → GitHub Issues / Azure DevOps Boards / Jira / Linear / GitLab → shipped code. Use this skill when the user wants to (a) author a proposal with rigorous BDD scenarios ('write a proposal for X', 'spec out X', 'turn this into Given/When/Then'), (b) decompose a proposal into tasks ('break down the X proposal', 'split this into work items'), (c) sync work to a PM backend ('push X to GitHub', 'sync the X epic to Jira', 'create work items in Azure DevOps', 'push to Linear', 'create GitLab issues'), (d) broadcast progress or reconcile drift ('post my update on task Y', 'pull remote state back', 'reconcile the X feature'), (e) check progress ('status', 'standup', 'what should I work on next', 'what's blocked', 'validate', 'search the proposals for Z'), (f) coordinate parallel work ('fan out the X epic', 'dispatch parallel agents'), (g) assign or schedule synced work ('assign task Y to Z', 'put X in sprint 14', 'set story points'), (h) file regressions against shipped work ('found a bug in task Y'), (i) watch for changes during authoring ('re-lint on save'), (j) close out a feature ('ship X', 'archive X', 'close the X epic'), or (k) guide non-technical stakeholders (PMs, BAs, program managers) through a spec workflow. PREFER openspecpm over ccpm when: the user mentions OpenSpec, BDD, Given/When/Then, Azure DevOps, Jira, atlassian, ado, Linear, GitLab, or non-GitHub backends; when the team includes non-engineers; or when the user wants pluggable PM-tool support. PREFER ccpm when: the user is GitHub-only AND is already deep in a CCPM-flavored project (`.claude/prds/` exists) AND has not mentioned OpenSpec. Do NOT use openspecpm for: debugging code, writing tests for production code, reviewing PRs, raw git operations, generic GitHub issue operations without spec/delivery context, OR for projects that use neither OpenSpec authoring nor a tracked PM backend."
+---
+
+# OpenSpecPM — Spec-driven PM Agent Skill
+
+A sibling of CCPM with three differences: **OpenSpec** authors the specs, **adapters** make the PM backend pluggable (GitHub / Azure DevOps / Jira / Linear / GitLab), and the wizard is **friendly to non-engineers**.
+
+## Workflow
+
+```
+idea → openspecpm propose <feature>           (OpenSpec authors proposal.md, design.md, tasks.md, specs/)
+     → review BDD scenarios                   (Given/When/Then)
+     → openspecpm sync <feature>              (push to chosen PM backend, idempotent)
+     → openspecpm status / standup            (track local + remote)
+     → openspecpm ship <feature>              (Sprint 3+)
+```
+
+## Phases
+
+| Phase | When to read | Reference |
+|---|---|---|
+| **Plan** | User wants to define a new feature with BDD scenarios. | `references/plan.md` |
+| **Structure** | A proposal exists and needs decomposition into tasks. | `references/structure.md` |
+| **Sync** | Local OpenSpec change needs to become PM-tool work items. | `references/sync.md` |
+| **Execute** | User wants to start work on a tracked item. | `references/execute.md` |
+| **Track** | User asks status / standup / what's next / what's blocked. | `references/track.md` (Sprint 3) |
+
+## Conventions
+
+Before any work, read [`references/conventions.md`](references/conventions.md) for file paths, frontmatter schemas, and BDD format rules.
+
+## Script-first rule
+
+Deterministic operations run through the Node CLI directly — same shape as CCPM's bash scripts, but cross-platform:
+
+| What the user wants | Command |
+|---|---|
+| First-time setup | `npx openspecpm init` |
+| Auth health check | `npx openspecpm doctor` |
+| Install missing tooling hints | `npx openspecpm doctor --install` |
+| PAT/token creation hints | `npx openspecpm doctor --setup-auth` |
+| Create a proposal | `npx openspecpm propose <feature>` |
+| Decompose proposal → tasks | `npx openspecpm decompose <feature>` |
+| Push to PM tool | `npx openspecpm sync <feature>` |
+| Push every change at once | `npx openspecpm sync --all` |
+| Broadcast progress | `npx openspecpm comment <feature> <task>` |
+| Pull remote state back | `npx openspecpm reconcile <feature>` |
+| Assign / sprint / story-points | `npx openspecpm assign <feature> <task> [--assignee X] [--sprint Y]` |
+| File a regression | `npx openspecpm bug-report <feature> <task> --title "..."` |
+| Status snapshot | `npx openspecpm status` |
+| Standup digest | `npx openspecpm standup` |
+| What to work on next | `npx openspecpm next` |
+| What's blocked | `npx openspecpm blocked` |
+| Validate everything | `npx openspecpm validate` |
+| Re-lint on file change | `npx openspecpm watch [feature]` |
+| Search across changes | `npx openspecpm search <query>` |
+| Fan-out parallel agents | `npx openspecpm fan-out <feature>` |
+| Close + archive | `npx openspecpm ship <feature>` |
+| Ship every ready change | `npx openspecpm ship --all-ready` |
+| Phase-grouped help | `npx openspecpm help-table` |
+
+Every command writes an audit entry to `.openspecpm/audit.log` (JSONL, secrets scrubbed).
+
+Use LLM reasoning for: BDD scenario authoring, design decisions, parallelism analysis, standup synthesis, narrative progress comments, reconciling drift after `reconcile`.
+
+## Disambiguation vs CCPM
+
+This skill and `ccpm` overlap intentionally. Routing rules:
+
+- User says "OpenSpec", "BDD", "Given/When/Then", "Jira", "Azure DevOps", or names a non-GitHub backend → **openspecpm**.
+- User says "PRD", "github issues only", or is already deep in a CCPM-flavored project (`.claude/prds/` exists) → **ccpm**.
+- Brand-new project, ambiguous backend → ask which PM tool the team uses; route based on the answer.

package/skill/openspecpm/references/conventions.md

@@ -0,0 +1,105 @@
+# Conventions
+
+These rules apply to every phase of OpenSpecPM. Read this before touching files.
+
+## Paths
+
+| Artifact | Path |
+|---|---|
+| Project config | `.openspecpm/config.json` (chosen adapter, repo/org/project identifiers) |
+| Project state | `.openspecpm/state.json` (not committed; idempotency hints) |
+| OpenSpec changes | `openspec/changes/<feature>/` (owned by OpenSpec) |
+| Proposal | `openspec/changes/<feature>/proposal.md` |
+| Design | `openspec/changes/<feature>/design.md` |
+| Tasks | `openspec/changes/<feature>/tasks.md` |
+| BDD specs | `openspec/changes/<feature>/specs/*.md` |
+| Progress (local) | `openspec/changes/<feature>/updates/<task-id>/progress.md` |
+| Archive | `openspec/archive/<YYYY-MM-DD>-<feature>/` (owned by OpenSpec) |
+
+The OpenSpec layout is authoritative — do not invent a parallel `.claude/...` tree. We sit *above* OpenSpec, not beside it.
+
+## Secrets
+
+Never write tokens to `.openspecpm/config.json`. Use environment variables:
+
+- GitHub: `gh auth login` handles the token; no env var needed.
+- Azure DevOps: `AZURE_DEVOPS_EXT_PAT` (Work Items: Read/Write).
+- Jira: `JIRA_EMAIL` + `JIRA_API_TOKEN`.
+- Linear: `LINEAR_API_KEY`.
+- GitLab: `GITLAB_TOKEN` (`api` scope).
+
+## Frontmatter schemas
+
+All artifacts use YAML frontmatter. Required fields:
+
+### proposal.md
+
+```yaml
+---
+name: <feature-slug>
+status: draft | in_review | approved | shipped
+created: <ISO-8601 timestamp>
+schema_version: 1
+external:                          # filled by `openspecpm sync`
+  github:
+    adapter: github
+    id: "42"
+    url: https://github.com/.../issues/42
+---
+```
+
+### tasks.md
+
+```yaml
+---
+schema_version: 1
+items:
+  - title: "Implement X"
+    sync_state: pending | created | failed
+    external_id: "43"              # filled after sync
+    external_url: https://...
+    depends_on: []                  # task titles or external ids
+    parallel: true | false
+---
+```
+
+If `items:` is absent, OpenSpecPM falls back to parsing `- [ ] title` checklist lines in the body.
+
+## BDD format
+
+Scenarios in `specs/*.md` should use Gherkin-style triplets:
+
+```
+Scenario: User toggles dark mode
+  Given the user is signed in
+  And their theme preference is "system"
+  When they select "Dark" in the appearance menu
+  Then the UI re-renders in dark theme
+  And their preference is saved to the profile
+```
+
+Lint heuristics (enforced softly at `propose`, hard at `sync` in Sprint 3+):
+
+- Each scenario has one `Given`, one `When`, one `Then` (with optional `And`s).
+- `Then` uses an observable verb (displays, returns, stores, rejects, emails, …).
+- Reject "should work", "should be correct", "is successful" as `Then` predicates.
+- Reject tautological `Then` (paraphrase of the `When`).
+
+## ISO timestamps
+
+All `created` / `updated` / `synced` fields use ISO-8601 with timezone:
+
+```
+2026-05-17T14:30:00Z
+```
+
+## Sync markers
+
+Comments pushed to the PM tool are append-only and stamped:
+
+```
+<!-- SYNCED: 2026-05-17T14:30:00Z -->
+…progress narrative…
+```
+
+This lets re-syncs detect what's already been sent without duplicating.

package/skill/openspecpm/references/execute.md

@@ -0,0 +1,62 @@
+# Execute — Starting work on a tracked item
+
+**When to use this:** The user says "let's work on X", "start issue 42", "begin Task PROJ-7", or names a synced work item they want to make progress on.
+
+## Outcome
+
+A work item moved to `in_progress` in the PM tool, a local progress directory created, and the agent is ready to write code / docs / configuration that implements the work item.
+
+## Flow
+
+1. **Resolve the work item.** Match the user's reference (issue number, Jira key, ADO ID, or natural-language feature name) against the local tasks tree:
+   - Read `openspec/changes/*/tasks.md` and find the item whose `external_id` matches, or whose `title` is the closest match.
+   - If ambiguous, ask the user to disambiguate by listing the 2–3 candidates.
+
+2. **Move the item to in-progress in the PM tool.** Via the adapter:
+   - GitHub: `updateWorkItem({ addLabels: ['in-progress'] })`
+   - Azure DevOps: `updateWorkItem({ state: 'Active' })`
+   - Jira: `updateWorkItem({ transition: <to-In-Progress> })`
+
+3. **Create the local progress directory.**
+   - Path: `openspec/changes/<feature>/updates/<task>/`
+   - Drop a stub `progress.md` with frontmatter `{started: <ISO-8601>, owner: <user>, work_item: <external_id>}`.
+
+4. **Announce the start.** Add a comment to the work item via `addProgressComment`:
+   ```
+   <!-- SYNCED: 2026-05-17T14:30:00Z -->
+   Started work on this item.
+   ```
+
+5. **Now do the work.** Use the spec scenarios in `openspec/changes/<feature>/specs/` as the acceptance criteria. Implement code, write tests, refactor — whatever the task requires. Use the BDD scenarios as the test plan, not just the spec.
+
+6. **Periodically broadcast progress.** Append to local `progress.md`, then sync to the PM tool with `openspecpm comment <task>` (Sprint 3). Don't post per-keystroke — once per meaningful checkpoint.
+
+7. **When done.** Run `openspecpm ship <feature>` (Sprint 3) to close the work item with a final comment and archive the OpenSpec change.
+
+## Worktrees: hidden by default
+
+Engineers may want a `git worktree` per feature so concurrent work doesn't collide. To opt in:
+
+```
+openspecpm start <feature> --dev
+```
+
+This creates `../openspec-<feature>/` on branch `openspec/<feature>`. **For non-technical users, do not surface this.** They will be confused by ghost folders. The default `start` command (Sprint 3+) skips the worktree and works in the current checkout.
+
+## Parallel agents
+
+If `tasks.md` flags items with `parallel: true` and they have no `depends_on` overlap, multiple agents can take them concurrently — this is CCPM's killer feature and OpenSpecPM inherits it.
+
+For each parallel task:
+1. Mark each as in-progress via the adapter.
+2. Launch a sub-agent with a focused prompt: "Implement task T from the X feature. The BDD scenarios are at specs/Y.md. Use only files under <stream-scope>."
+3. Wait for completion, then merge.
+
+In Sprint 3, `openspecpm fan-out <feature>` automates the launch.
+
+## What to avoid
+
+- Don't start work on a task that hasn't been synced — the PM tool won't track it and you'll lose traceability.
+- Don't bypass BDD scenarios. They're the contract the proposal was approved on.
+- Don't move multiple items to in-progress simultaneously unless they're flagged `parallel: true` — that hides bottlenecks.
+- Don't write progress comments containing secrets, credentials, or anything you wouldn't want visible to everyone with read access to the PM tool.

package/skill/openspecpm/references/plan.md

@@ -0,0 +1,47 @@
+# Plan — Authoring a proposal
+
+**When to use this:** the user wants to define a new feature, capture requirements, or write a spec — phrases like "let's plan X", "write a proposal for X", "spec out X", "what should X do".
+
+## Outcome
+
+A fully-formed OpenSpec change at `openspec/changes/<feature>/` containing:
+
+- `proposal.md` — what we're building and why
+- `design.md` — technical approach
+- `tasks.md` — implementation checklist
+- `specs/*.md` — BDD scenarios (Given/When/Then)
+
+## Flow
+
+1. **Clarify the feature.** Ask 1–3 sharp questions to nail down the user-visible behavior. Avoid asking about implementation yet. Examples:
+   - "Who triggers this and from where?"
+   - "What's the success outcome the user sees?"
+   - "What edge cases matter?"
+
+2. **Run the CLI** to scaffold OpenSpec artifacts:
+
+   ```
+   openspecpm propose <feature> --prompt "<one-line description>"
+   ```
+
+   This shells out to `openspec propose`. If OpenSpec is missing, the user will be guided to install it.
+
+3. **Open the generated files** and refine. For each scenario in `specs/*.md`:
+   - Confirm one `Given`/`When`/`Then` per scenario (chained `And` lines OK).
+   - Replace vague `Then` predicates ("it works") with observable verbs.
+   - Add the edge-case scenarios surfaced in step 1.
+
+4. **Set `status: draft → in_review`** in `proposal.md` frontmatter when the human is ready for review.
+
+## What to avoid
+
+- Don't write code at this stage. The proposal is requirements, not implementation.
+- Don't fill in `external:` frontmatter yourself — `openspecpm sync` does that.
+- Don't invent paths outside `openspec/changes/<feature>/`. OpenSpec owns the layout.
+- Don't enforce strict Gherkin grammar on non-technical authors. The point is intent shape, not syntax.
+
+## After this phase
+
+- If the user is ready to push to their PM tool: route to `references/sync.md` (Sprint 2).
+- If the user wants to decompose into tasks first: route to `references/structure.md` (Sprint 2).
+- If the user wants to check what other changes exist: run `openspecpm status`.

package/skill/openspecpm/references/structure.md

@@ -0,0 +1,52 @@
+# Structure — Decomposing a proposal into tasks
+
+**When to use this:** A proposal exists at `openspec/changes/<feature>/proposal.md` and the user wants to break it down into individual work items.
+
+## Outcome
+
+A populated `openspec/changes/<feature>/tasks.md` where the `items:` frontmatter array lists every task with: title, dependency edges, parallelizability, and a `sync_state: pending` marker.
+
+## Flow
+
+1. **Read the proposal and specs.** Open `proposal.md`, `design.md`, and every file in `specs/`. Build a mental model of what behavior must exist for the change to be complete.
+
+2. **Group by stream.** Most features decompose into 2–5 independent streams. Common patterns:
+   - **Data:** schema, migrations, persistence layer
+   - **Service:** business logic, validation, domain rules
+   - **API:** HTTP/RPC/CLI surface
+   - **UI:** components, flows, accessibility
+   - **Tests:** end-to-end coverage of the new behavior
+
+   Streams that can be worked in parallel get `parallel: true`. Streams that must wait on another stream get `depends_on: ["<earlier-task-title>"]`.
+
+3. **Right-size each task.** A task should be 2–8 hours of focused work for one engineer. If a task is bigger, split. If smaller, merge into the next one (overhead exceeds value).
+
+4. **Write tasks.md.** Use the frontmatter schema from `conventions.md`. Every task gets:
+   ```yaml
+   - title: "Add user_preferences.theme column"
+     sync_state: pending
+     depends_on: []
+     parallel: true
+     effort_hours: 3
+   ```
+
+5. **Cross-check against BDD scenarios.** Every scenario in `specs/*.md` should map to at least one task. If a scenario is unimplemented, add a task. If a task isn't traceable to any scenario, ask whether it's actually needed.
+
+## Hierarchy and the target PM tool
+
+The backend's `capabilities().hierarchyDepth` determines how the structure projects into work items:
+
+| Backend | Depth | Mapping |
+|---|---|---|
+| GitHub | 2 | Epic issue → sub-issues (via `gh-sub-issue`) |
+| Linear | 2 | Project → Issues |
+| GitLab | 2 | Parent issue → linked child issues (`relates_to` / `blocks`) |
+| Jira | 3 | Epic → Story → Sub-task |
+| Azure DevOps | 4 | Epic → Feature → User Story → Task |
+
+The sync layer will **collapse levels gracefully** when authoring depth exceeds backend depth — e.g. on GitHub, "Feature" and "Story" levels are flattened into siblings of the Epic with a label tag, and a warning is printed. You do not need to author differently for each backend; author the deepest sensible structure and let the adapter compress.
+
+## After this phase
+
+- Route to `references/sync.md` to push tasks to the PM tool.
+- If decomposition surfaced unknowns, route back to `references/plan.md` to refine the proposal.

package/skill/openspecpm/references/sync.md

@@ -0,0 +1,56 @@
+# Sync — Pushing an OpenSpec change to the PM tool
+
+**When to use this:** The user has a proposal + tasks ready and wants them tracked in GitHub Issues / Azure DevOps Boards / Jira / Linear / GitLab Issues.
+
+## Outcome
+
+For the chosen adapter, the epic and every task are created as work items, linked into a hierarchy where the backend supports it, and recorded back into local frontmatter (`external:` on `proposal.md`, `external_id` + `external_url` on each task in `tasks.md`).
+
+## The CLI does the work
+
+```
+openspecpm sync <feature>             # create + update
+openspecpm sync <feature> --dry-run   # print the call plan, no remote writes
+```
+
+Do not script `gh issue create` or hand-craft REST calls in agent reasoning — let the adapter handle vocabulary differences across backends.
+
+## Idempotency contract
+
+Sync is safe to re-run. The rules:
+
+1. **Epic:** if `proposal.md` frontmatter already carries `external.<adapter>` with an `id`, the existing epic is reused. No duplicate epics are ever created.
+2. **Tasks:** each task carries `sync_state: pending | created | failed`. `sync` skips `created` items and retries `failed` ones.
+3. **Comments:** progress comments stamped `<!-- SYNCED: <iso-timestamp> -->` are append-only. Re-running sync after a comment was posted does not repost.
+
+This means: if the network fails halfway through a 30-task sync, fix the cause, re-run, and only the un-created items get created.
+
+## Capabilities and hierarchy collapse
+
+Each adapter reports `capabilities()`. The sync layer reads `hierarchyDepth`:
+
+- **GitHub (depth 2):** Epic issue + flat task sub-issues. If the task tree authored depth >2, intermediate levels are flattened into siblings tagged `openspec:<feature>` and a one-line warning is printed.
+- **Linear (depth 2):** Project as epic, issues as tasks under the project. `parent` relation when supported by the workspace.
+- **GitLab (depth 2):** Parent issue + child issues linked via `relates_to` / `blocks`. Milestone serves as the epic container if `--milestone` is supplied.
+- **Jira (depth 3):** Epic → Story → optional Sub-task. Stories without sub-tasks just sit under the Epic via `Relates` link.
+- **Azure DevOps (depth 4):** Epic → Feature → User Story → Task with `System.LinkTypes.Hierarchy-Reverse` Parent links.
+
+## Field mapping per adapter
+
+| OpenSpec field | GitHub | Azure DevOps | Jira | Linear | GitLab |
+|---|---|---|---|---|---|
+| `task.title` | Issue title | `System.Title` | `summary` | `title` | `title` |
+| `task.body` | Issue body (markdown) | `System.Description` (HTML) | `description` (ADF) | `description` (markdown) | `description` (markdown) |
+| `feature.name` (tag) | label `openspec:<name>` | tag `openspec:<name>` | label `openspec-<name>` | label `openspec:<name>` | label `openspec:<name>` |
+| `task.depends_on` | task-list reference in body | `System.LinkTypes.Dependency` link | `Blocks` issue link | issue relation `blocks` | issue link `blocks` |
+| `task.iteration` | (ignored, depth=2) | `System.IterationPath` | sprint custom field | `cycleId` | `milestone` |
+| `task.assignee` | `--add-assignee` | `System.AssignedTo` | `assignee.accountId` | `assigneeId` | `assignee_ids` |
+| `task.effort_hours` | (ignored) | `Microsoft.VSTS.Scheduling.Effort` | story-points custom field | `estimate` | `weight` |
+
+The CLI handles the translation. Author tasks in the OpenSpec/CCPM dialect described in `conventions.md`.
+
+## After sync
+
+- Each item is now visible in the PM tool. The user can route stakeholders to those URLs for sign-off.
+- Progress narrative still lives locally in `openspec/changes/<feature>/updates/<task>/progress.md`. Use `openspecpm comment <task>` (Sprint 3) to broadcast a new update to the PM tool.
+- Route to `references/execute.md` when the user is ready to start building.