openspecpm 0.1.0-alpha.0 → 1.0.0

package/cli/src/bdd/judge.js

@@ -0,0 +1,216 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DEFAULT_MODEL = 'claude-haiku-4-5';
+export const DEFAULT_MAX_FINDINGS_PER_SPEC = 8;
+const MAX_CONCURRENT = 5;
+
+const ALLOWED_RULES = new Set([
+  'bdd/llm-contradiction',
+  'bdd/llm-missing-coverage',
+  'bdd/llm-vague-then',
+]);
+
+const ALLOWED_SEVERITY = new Set(['error', 'warning']);
+
+const REPORT_TOOL = {
+  name: 'report_findings',
+  description:
+    'Report BDD scenario findings as a structured list. Each finding flags a specific defect that the heuristic linter cannot catch: cross-spec contradictions, missing coverage against success criteria, or vague Then predicates that pass regex checks but state no observable outcome.',
+  input_schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      findings: {
+        type: 'array',
+        items: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            severity: { type: 'string', enum: ['error', 'warning'] },
+            line: { type: 'integer', minimum: 1 },
+            scenario: { type: 'string' },
+            rule: {
+              type: 'string',
+              enum: ['bdd/llm-contradiction', 'bdd/llm-missing-coverage', 'bdd/llm-vague-then'],
+            },
+            message: { type: 'string' },
+          },
+          required: ['severity', 'scenario', 'rule', 'message'],
+        },
+      },
+    },
+    required: ['findings'],
+  },
+};
+
+const SYSTEM_PROMPT = `You are a BDD scenario reviewer. You augment a heuristic linter by catching defects it cannot see: cross-spec contradictions, missing coverage of declared success criteria, and Then predicates that state no observable outcome. You are reviewing one spec file at a time, with the full feature proposal as context.
+
+Rules:
+- Use the report_findings tool exactly once.
+- Only emit findings for the three rules: bdd/llm-contradiction, bdd/llm-missing-coverage, bdd/llm-vague-then.
+- Each finding must name the specific scenario by title and include the line number where the issue appears.
+- bdd/llm-contradiction: a scenario contradicts another scenario in the same file or another spec referenced in the proposal.
+- bdd/llm-missing-coverage: the proposal's success criteria contain a requirement with no scenario covering it.
+- bdd/llm-vague-then: a Then predicate uses an observable verb but its outcome is not actually checkable (e.g. "Then the user receives confirmation" with no detail on what confirmation).
+- Severity error for contradictions and uncovered hard requirements; severity warning for vague Thens and uncovered nice-to-haves.
+- Empty findings array is the correct output when the spec is clean.
+- Never invent rule names. Never include findings outside the three rules above.`;
+
+export async function judgeChange(featureDir, opts = {}) {
+  const {
+    client,
+    model = DEFAULT_MODEL,
+    proposal = '',
+    maxFindingsPerSpec = DEFAULT_MAX_FINDINGS_PER_SPEC,
+    onUsage,
+  } = opts;
+
+  if (!client) throw new Error('judge: client is required');
+
+  const specsDir = join(featureDir, 'specs');
+  if (!existsSync(specsDir)) return [];
+
+  const files = (await readdir(specsDir)).filter((f) => f.endsWith('.md'));
+  if (!files.length) return [];
+
+  const tasks = files.map((f) => () =>
+    judgeSpec(join(specsDir, f), { client, model, proposal, maxFindingsPerSpec, onUsage }),
+  );
+
+  const results = await runBounded(tasks, MAX_CONCURRENT);
+  return results.flat();
+}
+
+async function judgeSpec(file, { client, model, proposal, maxFindingsPerSpec, onUsage }) {
+  let specSource;
+  try {
+    specSource = await readFile(file, 'utf8');
+  } catch (err) {
+    return [{
+      severity: 'warning',
+      file,
+      line: 1,
+      scenario: '(read failed)',
+      rule: 'bdd/llm-parse-error',
+      message: `Could not read spec file: ${err.message}`,
+    }];
+  }
+
+  const userPrompt = `Review the following BDD spec file. Use report_findings to report up to ${maxFindingsPerSpec} findings.
+
+<spec file="${file}">
+${specSource}
+</spec>`;
+
+  let response;
+  try {
+    response = await client.messages.create({
+      model,
+      max_tokens: 4096,
+      tools: [REPORT_TOOL],
+      tool_choice: { type: 'tool', name: 'report_findings' },
+      system: [
+        {
+          type: 'text',
+          text: SYSTEM_PROMPT,
+        },
+        {
+          type: 'text',
+          text: `Feature proposal (shared context across every spec in this feature):\n\n${proposal || '(no proposal.md available)'}`,
+          cache_control: { type: 'ephemeral' },
+        },
+      ],
+      messages: [{ role: 'user', content: userPrompt }],
+    });
+  } catch (err) {
+    return [{
+      severity: 'warning',
+      file,
+      line: 1,
+      scenario: '(judge failed)',
+      rule: 'bdd/llm-parse-error',
+      message: `LLM judge call failed: ${err.message}`,
+    }];
+  }
+
+  if (onUsage && response?.usage) {
+    try {
+      onUsage({
+        file,
+        model,
+        input_tokens: response.usage.input_tokens ?? 0,
+        output_tokens: response.usage.output_tokens ?? 0,
+        cache_creation_input_tokens: response.usage.cache_creation_input_tokens ?? 0,
+        cache_read_input_tokens: response.usage.cache_read_input_tokens ?? 0,
+      });
+    } catch { /* never break the judge on telemetry */ }
+  }
+
+  return extractFindings(response, file);
+}
+
+function extractFindings(response, file) {
+  const toolUse = (response?.content ?? []).find(
+    (b) => b.type === 'tool_use' && b.name === 'report_findings',
+  );
+  if (!toolUse) {
+    return [{
+      severity: 'warning',
+      file,
+      line: 1,
+      scenario: '(no findings reported)',
+      rule: 'bdd/llm-parse-error',
+      message: 'LLM did not call report_findings tool.',
+    }];
+  }
+  const raw = toolUse.input?.findings;
+  if (!Array.isArray(raw)) {
+    return [{
+      severity: 'warning',
+      file,
+      line: 1,
+      scenario: '(malformed response)',
+      rule: 'bdd/llm-parse-error',
+      message: 'report_findings input was not a findings array.',
+    }];
+  }
+  const out = [];
+  for (const f of raw) {
+    if (!f || typeof f !== 'object') continue;
+    if (!ALLOWED_RULES.has(f.rule)) continue;
+    if (!ALLOWED_SEVERITY.has(f.severity)) continue;
+    if (typeof f.scenario !== 'string' || !f.scenario) continue;
+    if (typeof f.message !== 'string' || !f.message) continue;
+    out.push({
+      severity: f.severity,
+      file,
+      line: Number.isInteger(f.line) && f.line > 0 ? f.line : undefined,
+      scenario: f.scenario,
+      rule: f.rule,
+      message: f.message,
+    });
+  }
+  return out;
+}
+
+async function runBounded(tasks, limit) {
+  const results = new Array(tasks.length);
+  let i = 0;
+  const workers = new Array(Math.min(limit, tasks.length)).fill(0).map(async () => {
+    while (true) {
+      const idx = i++;
+      if (idx >= tasks.length) return;
+      results[idx] = await tasks[idx]();
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+export function defaultClient() {
+  return import('@anthropic-ai/sdk').then(({ default: Anthropic }) => {
+    return new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+  });
+}

package/cli/src/commands/doctor.js

@@ -33,6 +33,17 @@ export async function runDoctor({ adapter, install = false, setupAuth = false }
     if (install) suggestAdapterInstall(name);
     if (setupAuth) suggestAuth(name);
   }
+
+  process.stdout.write('\n[judge]\n');
+  if (process.env.ANTHROPIC_API_KEY) {
+    line(true, 'ANTHROPIC_API_KEY is set (LLM BDD judge available)');
+  } else {
+    line(
+      false,
+      'ANTHROPIC_API_KEY not set',
+      'Create a key at https://console.anthropic.com/settings/keys, then set ANTHROPIC_API_KEY in your shell. Required for `openspecpm propose --llm` and `sync --llm`.',
+    );
+  }
 }
 
 function line(ok, msg, remediation) {

package/cli/src/commands/propose.js

@@ -1,11 +1,14 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { propose, changeExists, changeDir, OpenSpecError } from '../openspec-bridge.js';
 import { lintChange, summarize, formatFindings } from '../bdd/linter.js';
+import { judgeChange, defaultClient, DEFAULT_MODEL } from '../bdd/judge.js';
 import { CHANGE_TYPES, proposalTemplate, specsTemplate, STARTER_TASKS } from '../bdd/templates.js';
+import { readConfig } from '../config.js';
+import { record } from '../audit.js';
 
-export async function runPropose({ feature, prompt, type = 'feature', offline = false } = {}) {
+export async function runPropose({ feature, prompt, type = 'feature', offline = false, llm = false } = {}) {
   if (!feature) throw new Error('feature name is required');
   if (!CHANGE_TYPES.includes(type)) {
     const err = new Error(`Unknown change type "${type}".`);
@@ -15,14 +18,14 @@ export async function runPropose({ feature, prompt, type = 'feature', offline =
 
   if (changeExists(feature)) {
     process.stdout.write(`Change "${feature}" already exists at ${changeDir(feature)}. Skipping propose.\n`);
-    await softLint(changeDir(feature));
+    await softLint(changeDir(feature), { llm, feature });
     return changeDir(feature);
   }
 
   if (offline) {
     const dir = await scaffoldOffline(feature, type);
     process.stdout.write(`\nProposal scaffolded offline at ${dir} (type=${type}).\n`);
-    await softLint(dir);
+    await softLint(dir, { llm, feature });
     process.stdout.write(`Next: refine the templates, then run \`openspecpm sync ${feature}\`.\n`);
     return dir;
   }
@@ -31,7 +34,7 @@ export async function runPropose({ feature, prompt, type = 'feature', offline =
   try {
     const dir = await propose(feature, seed);
     process.stdout.write(`\nProposal created at ${dir}.\n`);
-    await softLint(dir);
+    await softLint(dir, { llm, feature });
     process.stdout.write(`Next: review proposal.md + specs/, then run \`openspecpm sync ${feature}\`.\n`);
     return dir;
   } catch (err) {
@@ -57,11 +60,43 @@ async function scaffoldOffline(feature, type) {
   return dir;
 }
 
-async function softLint(dir) { // eslint-disable-line
+async function softLint(dir, { llm = false, feature } = {}) { // eslint-disable-line
   const findings = await lintChange(dir);
+  const judgeEnabled = await isJudgeEnabled(llm);
+  if (judgeEnabled) {
+    const extra = await runJudgeSoft(dir, feature);
+    findings.push(...extra);
+  }
   const sum = summarize(findings);
   if (!sum.total) return;
   process.stdout.write(`\nBDD lint (soft): ${sum.errors} errors, ${sum.warnings} warnings\n`);
   process.stdout.write(formatFindings(findings));
   process.stdout.write('These will block `sync` unless you pass --force. Refine scenarios before pushing.\n');
 }
+
+async function isJudgeEnabled(llm) {
+  if (llm) return true;
+  const cfg = await readConfig();
+  return Boolean(cfg?.judge?.enabled);
+}
+
+async function runJudgeSoft(dir, feature) {
+  try {
+    const cfg = await readConfig();
+    const model = cfg?.judge?.model ?? DEFAULT_MODEL;
+    const proposalPath = join(dir, 'proposal.md');
+    const proposal = existsSync(proposalPath) ? await readFile(proposalPath, 'utf8') : '';
+    const client = await defaultClient();
+    return await judgeChange(dir, {
+      client,
+      model,
+      proposal,
+      onUsage: (u) => {
+        record({ command: 'judge', args: { feature }, meta: u }).catch(() => {});
+      },
+    });
+  } catch (err) {
+    process.stdout.write(`  (LLM judge skipped: ${err.message})\n`);
+    return [];
+  }
+}

package/cli/src/commands/sync.js

@@ -5,9 +5,11 @@ import { readConfig } from '../config.js';
 import { loadAdapter } from '../adapters/index.js';
 import { changeDir, changeExists } from '../openspec-bridge.js';
 import { lintChange, summarize, formatFindings } from '../bdd/linter.js';
+import { judgeChange, defaultClient, DEFAULT_MODEL } from '../bdd/judge.js';
 import * as fm from '../frontmatter.js';
+import { record } from '../audit.js';
 
-export async function runSync({ feature, dryRun = false, force = false, diff = false } = {}) {
+export async function runSync({ feature, dryRun = false, force = false, diff = false, llm = false } = {}) {
   if (!feature) throw new Error('feature name is required');
   const config = await readConfig();
   if (!config) {
@@ -23,6 +25,30 @@ export async function runSync({ feature, dryRun = false, force = false, diff = f
 
   const dir = changeDir(feature);
   const findings = await lintChange(dir);
+  if (llm || config?.judge?.enabled) {
+    try {
+      const model = config?.judge?.model ?? DEFAULT_MODEL;
+      const proposalPath = join(dir, 'proposal.md');
+      const proposalForJudge = existsSync(proposalPath) ? await readFile(proposalPath, 'utf8') : '';
+      const client = await defaultClient();
+      const judgeFindings = await judgeChange(dir, {
+        client,
+        model,
+        proposal: proposalForJudge,
+        onUsage: (u) => {
+          record({ command: 'judge', args: { feature }, meta: u }).catch(() => {});
+        },
+      });
+      findings.push(...judgeFindings);
+    } catch (err) {
+      if (!force) {
+        const e = new Error(`LLM judge failed: ${err.message}`);
+        e.remediation = 'Run `openspecpm doctor` to check ANTHROPIC_API_KEY, or pass --force to skip the LLM judge.';
+        throw e;
+      }
+      process.stdout.write(`  (LLM judge skipped under --force: ${err.message})\n`);
+    }
+  }
   const sum = summarize(findings);
   if (sum.errors > 0 && !force) {
     process.stderr.write(`BDD lint: ${sum.errors} errors, ${sum.warnings} warnings\n`);

package/cli/src/commands/validate.js

@@ -1,13 +1,21 @@
 import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { listChanges } from '../tracking.js';
 import { lintChange, summarize } from '../bdd/linter.js';
+import { judgeChange, defaultClient, DEFAULT_MODEL } from '../bdd/judge.js';
+import { readConfig } from '../config.js';
+import { record } from '../audit.js';
 
 const REQUIRED_PROPOSAL = ['name'];
 const TASK_STATES = ['pending', 'created', 'failed'];
 
-export async function runValidate() {
+export async function runValidate({ llm = false } = {}) {
   const changes = await listChanges();
+  const config = await readConfig();
+  const judgeEnabled = llm || Boolean(config?.judge?.enabled);
+  const model = config?.judge?.model ?? DEFAULT_MODEL;
+  const client = judgeEnabled ? await defaultClient().catch(() => null) : null;
   out(`openspecpm validate — ${changes.length} change(s)\n`);
   let totalIssues = 0;
 
@@ -52,6 +60,29 @@ export async function runValidate() {
 
     // BDD lint
     const findings = await lintChange(change.dir);
+    if (judgeEnabled && client) {
+      try {
+        const proposalPath = join(change.dir, 'proposal.md');
+        const proposal = existsSync(proposalPath) ? await readFile(proposalPath, 'utf8') : '';
+        const judgeFindings = await judgeChange(change.dir, {
+          client,
+          model,
+          proposal,
+          onUsage: (u) => {
+            record({ command: 'judge', args: { feature: change.name }, meta: u }).catch(() => {});
+          },
+        });
+        findings.push(...judgeFindings);
+      } catch (err) {
+        findings.push({
+          severity: 'warning',
+          file: change.dir,
+          scenario: '(judge failed)',
+          rule: 'bdd/llm-parse-error',
+          message: `LLM judge failed: ${err.message}`,
+        });
+      }
+    }
     const { errors, warnings } = summarize(findings);
 
     const total = issues.length + errors;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspecpm",
-  "version": "0.1.0-alpha.0",
+  "version": "1.0.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": {
@@ -52,6 +52,7 @@
     "url": "https://github.com/aks-builds/openspecpm/issues"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.65.0",
     "@clack/prompts": "^1.4.0",
     "commander": "^14.0.3",
     "execa": "^9.4.0",

package/skill/openspecpm/SKILL.md

@@ -1,74 +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.
+---
+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> [--llm]` |
+| Decompose proposal → tasks | `npx openspecpm decompose <feature>` |
+| Push to PM tool | `npx openspecpm sync <feature> [--llm]` |
+| 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 [--llm]` |
+| 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.