openplanr 1.25.3 → 2.0.0

package/lib/host-packages/claude/openplanr/skills/spec/references/specification-contract.md

@@ -0,0 +1,32 @@
+# Specification contract
+
+For spec-driven repositories, write
+`.planr/specs/SPEC-NNN-{slug}/SPEC-NNN-{slug}.md` with Protocol `1.7.0`
+frontmatter: `id`, `title`, `slug`, `schemaVersion`, `status`, `priority`,
+`created`, `updated`, `ui_files`, and `tech_dependencies`. Preserve supported
+optional fields used by the repository.
+
+Use these body sections, in this order, when the repository has no stronger
+template:
+
+1. `## Context & Goal`
+2. `## Audience`
+3. `## Outcome & Measurement`
+4. `## Functional Requirements`
+5. `## Business Rules`
+6. `## Constraints`
+7. `## Evidence Expectations`
+8. `## Failure Modes`
+9. `## Rollback`
+10. `## Scope Boundaries`, with `### In Scope` and `### Out of Scope`
+11. `## Acceptance Criteria`, with stable `AC-NNN` identifiers
+12. `## Declared Risk Specialists`
+13. `## Notes for Decomposition`
+
+Keep evidence and rollback as useful planning context, not approval gates or
+receipt requirements. A risk-specialist section may be empty when no specialist
+lens applies.
+
+For a repository intentionally using default mode, write
+`input/specs/spec-{slug}.md` and preserve its active schema. Do not create a
+parallel `.planr` spec solely to normalize the project.

package/lib/host-packages/claude/openplanr/skills/status/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: status
+description: Inspect project delivery or one feature's pipeline status without changing state. Use when the user asks what is done, pending, blocked, or next.
+license: MIT
+---
+
+# Planr Status
+
+Inspect delivery state read-only in the active session. Read the repository's
+planning artifacts, task statuses, dependency graph, current branch, and relevant
+runtime markers directly. Use the optional deterministic `planr status --json`
+utility when available, but do not require it or a semantic subprocess.
+
+Add GitHub or Linear lookups only when the user requests live remote state. Keep
+local results useful when credentials or connectors are unavailable. Report
+counts, ready and blocked work, dependency problems, and the most useful next
+action. Do not repair artifacts, start Plan or Ship, or change lifecycle state.
+
+When the OpenPlanr dashboard is running (`planr-dashboard`), the same delivery
+state is browsable there: `#/overview` for the whole project, `#/detail/<id>`
+for one feature. This is navigation only.

package/lib/host-packages/claude/openplanr/skills/status/openplanr.skill.json

@@ -0,0 +1,26 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-status",
+  "skillVersion": "1.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    }
+  ]
+}

package/lib/host-packages/claude/openplanr/skills/sync/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: sync
+description: Audit OpenPlanr planning artifacts for graph and protocol drift. Use when statuses, references, schemas, or generated planning views may be inconsistent.
+license: MIT
+---
+
+# Planr Sync
+
+Reconcile local planning artifacts and, when requested, GitHub or Linear state.
+Reason about conflicts in this active session; deterministic mapping and transport
+may use a host connector or the packaged [sync helper](scripts/sync.mjs). The optional
+OpenPlanr CLI is never required by the skill.
+
+Resolution order:
+
+1. use a host-native GitHub or Linear connector when available;
+2. otherwise use the packaged deterministic helper;
+3. optionally use the equivalent `planr github`, `planr linear`, or `planr sync`
+   terminal utility when the user has installed it.
+
+Audit is read-only by default. Apply local changes only when the request asks for
+reconciliation, and push remote changes only when the request asks for external
+synchronization. If credentials are unavailable, complete local reconciliation
+and report only the external step that could not run.
+
+Return aligned, locally repairable, conflict, and unavailable counts; changed
+paths or remote identifiers; and the single most useful next action.
+
+When the OpenPlanr dashboard is running, the reconciled graph is browsable at
+`#/overview` and recent changes at `#/activity`. This is navigation only.

package/lib/host-packages/claude/openplanr/skills/sync/openplanr.skill.json

@@ -0,0 +1,37 @@
+{
+  "kind": "openplanr-skill-package",
+  "schemaVersion": "1.0.0",
+  "protocolVersion": "1.8.0",
+  "skillId": "planr-sync",
+  "skillVersion": "1.0.0",
+  "entrypoint": "SKILL.md",
+  "hosts": [
+    "claude-code",
+    "codex",
+    "chatgpt",
+    "cursor"
+  ],
+  "execution": "host-agent",
+  "resources": [
+    {
+      "path": "scripts/sync.mjs",
+      "kind": "script",
+      "hosts": [
+        "claude-code",
+        "codex",
+        "chatgpt",
+        "cursor"
+      ],
+      "executable": true
+    },
+    {
+      "path": "agents/openai.yaml",
+      "kind": "agent-metadata",
+      "hosts": [
+        "codex",
+        "chatgpt"
+      ],
+      "executable": false
+    }
+  ]
+}

package/lib/host-packages/claude/openplanr/skills/sync/scripts/sync.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { access, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const LINEAR_ENDPOINT = 'https://api.linear.app/graphql';
+const LINEAR_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const LINEAR_IDENTIFIER = /^[A-Z][A-Z0-9]+-\d+$/u;
+
+export class IntegrationError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = 'IntegrationError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function isLikelyLinearIssueId(value) {
+  return typeof value === 'string'
+    && (LINEAR_UUID.test(value.trim()) || LINEAR_IDENTIFIER.test(value.trim()));
+}
+
+export function reconcileStatus({ base, local, remote }, strategy) {
+  if (local === remote) {
+    return { final: local, side: 'unchanged', conflictDecisions: 0, isTrueConflict: false };
+  }
+  if (base !== undefined && base === local) {
+    return { final: remote, side: 'remote', conflictDecisions: 0, isTrueConflict: false };
+  }
+  if (base !== undefined && base === remote) {
+    return { final: local, side: 'local', conflictDecisions: 0, isTrueConflict: false };
+  }
+  const remoteWins = strategy === 'remote';
+  return {
+    final: remoteWins ? remote : local,
+    side: remoteWins ? 'remote' : 'local',
+    conflictDecisions: 1,
+    isTrueConflict: true,
+  };
+}
+
+async function run(command, args, cwd) {
+  try {
+    return await execFileAsync(command, args, { cwd, encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 });
+  } catch (error) {
+    throw new IntegrationError('E_INTEGRATION_COMMAND', `${command} ${args.join(' ')} failed.`, {
+      command,
+      args,
+      stderr: typeof error?.stderr === 'string' ? error.stderr.trim() : undefined,
+    });
+  }
+}
+
+export async function inspectGitHub({ cwd = process.cwd() } = {}) {
+  const { stdout } = await run('gh', ['repo', 'view', '--json', 'nameWithOwner,url'], cwd);
+  return { provider: 'github', repository: JSON.parse(stdout) };
+}
+
+export async function executeGitHubOperations(operations, { cwd = process.cwd(), apply = false } = {}) {
+  if (!Array.isArray(operations)) throw new IntegrationError('E_SYNC_INPUT', 'GitHub operations must be an array.');
+  if (!apply) return { provider: 'github', applied: false, operations };
+  const results = [];
+  for (const operation of operations) {
+    if (operation.action === 'create') {
+      const args = ['issue', 'create', '--title', String(operation.title ?? '')];
+      if (operation.body !== undefined) args.push('--body', String(operation.body));
+      for (const label of operation.labels ?? []) args.push('--label', label);
+      const { stdout } = await run('gh', args, cwd);
+      results.push({ action: 'create', url: stdout.trim() });
+      continue;
+    }
+    if (operation.action === 'update' && operation.id) {
+      const args = ['issue', 'edit', String(operation.id)];
+      if (operation.title !== undefined) args.push('--title', operation.title);
+      if (operation.body !== undefined) args.push('--body', operation.body);
+      for (const label of operation.labels ?? []) args.push('--add-label', label);
+      await run('gh', args, cwd);
+      results.push({ action: 'update', id: String(operation.id) });
+      continue;
+    }
+    throw new IntegrationError('E_SYNC_OPERATION', 'Unsupported GitHub synchronization operation.', { operation });
+  }
+  return { provider: 'github', applied: true, results };
+}
+
+async function linearRequest(query, variables, token, fetchImpl = fetch) {
+  if (!token) throw new IntegrationError('E_LINEAR_CREDENTIAL', 'Linear credentials are unavailable.');
+  let response;
+  let payload;
+  try {
+    response = await fetchImpl(LINEAR_ENDPOINT, {
+      method: 'POST',
+      headers: { authorization: token, 'content-type': 'application/json' },
+      body: JSON.stringify({ query, variables }),
+    });
+    payload = await response.json();
+  } catch (error) {
+    throw new IntegrationError('E_LINEAR_API', 'Linear synchronization transport failed.', {
+      cause: String(error?.message ?? error),
+    });
+  }
+  if (!response.ok || !payload || typeof payload !== 'object' || payload.errors?.length) {
+    throw new IntegrationError('E_LINEAR_API', 'Linear rejected the synchronization request.', {
+      status: response.status,
+      errors: payload?.errors,
+    });
+  }
+  return payload.data;
+}
+
+function requireLinearMutationResult(data, field) {
+  const result = data?.[field];
+  const issue = result?.issue;
+  if (
+    result?.success !== true
+    || !issue
+    || typeof issue.id !== 'string'
+    || typeof issue.identifier !== 'string'
+    || typeof issue.url !== 'string'
+  ) {
+    throw new IntegrationError('E_LINEAR_API', `Linear ${field} did not confirm a successful issue mutation.`, {
+      field,
+      success: result?.success ?? null,
+    });
+  }
+  return issue;
+}
+
+export async function inspectLinear({ token = process.env.PLANR_LINEAR_TOKEN } = {}) {
+  const data = await linearRequest('query OpenPlanrViewer { viewer { id name email } }', {}, token);
+  return { provider: 'linear', viewer: data.viewer };
+}
+
+export async function executeLinearOperations(
+  operations,
+  { token = process.env.PLANR_LINEAR_TOKEN, apply = false } = {},
+) {
+  if (!Array.isArray(operations)) throw new IntegrationError('E_SYNC_INPUT', 'Linear operations must be an array.');
+  if (!apply) return { provider: 'linear', applied: false, operations };
+  const results = [];
+  for (const operation of operations) {
+    if (operation.action === 'create' && operation.teamId) {
+      const data = await linearRequest(
+        'mutation OpenPlanrCreate($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier url } } }',
+        { input: { teamId: operation.teamId, title: operation.title, description: operation.body } },
+        token,
+      );
+      results.push({ action: 'create', ...requireLinearMutationResult(data, 'issueCreate') });
+      continue;
+    }
+    if (operation.action === 'update' && isLikelyLinearIssueId(operation.id)) {
+      const data = await linearRequest(
+        'mutation OpenPlanrUpdate($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { id identifier url } } }',
+        { id: operation.id, input: { title: operation.title, description: operation.body, stateId: operation.state } },
+        token,
+      );
+      results.push({ action: 'update', ...requireLinearMutationResult(data, 'issueUpdate') });
+      continue;
+    }
+    throw new IntegrationError('E_SYNC_OPERATION', 'Unsupported Linear synchronization operation.', { operation });
+  }
+  return { provider: 'linear', applied: true, results };
+}
+
+async function readJsonInput(value, stdin) {
+  if (value) return JSON.parse(await readFile(resolve(value), 'utf8'));
+  let bytes = '';
+  for await (const chunk of stdin) bytes += chunk;
+  return JSON.parse(bytes || '[]');
+}
+
+async function inspectLocal(cwd) {
+  const candidates = ['.planr/config.json', '.openplanr/config.json'];
+  const roots = [];
+  for (const candidate of candidates) {
+    try {
+      await access(resolve(cwd, candidate));
+      roots.push(candidate.split('/')[0]);
+    } catch {
+      // A project can use either supported planning root.
+    }
+  }
+  return { provider: 'local', roots, configured: roots.length > 0 };
+}
+
+function parseArgs(argv) {
+  const [provider = 'local', action = 'inspect', ...rest] = argv;
+  const apply = rest.includes('--apply');
+  const inputIndex = rest.indexOf('--input');
+  return { provider, action, apply, input: inputIndex >= 0 ? rest[inputIndex + 1] : undefined };
+}
+
+export async function runPortableSync(
+  argv = process.argv.slice(2),
+  { cwd = process.cwd(), env = process.env, stdin = process.stdin, stdout = process.stdout } = {},
+) {
+  const args = parseArgs(argv);
+  let result;
+  if (args.provider === 'local' && args.action === 'inspect') result = await inspectLocal(cwd);
+  else if (args.provider === 'github' && args.action === 'inspect') result = await inspectGitHub({ cwd });
+  else if (args.provider === 'github' && args.action === 'sync') {
+    result = await executeGitHubOperations(await readJsonInput(args.input, stdin), { cwd, apply: args.apply });
+  } else if (args.provider === 'linear' && args.action === 'inspect') {
+    result = await inspectLinear({ token: env.PLANR_LINEAR_TOKEN });
+  } else if (args.provider === 'linear' && args.action === 'sync') {
+    result = await executeLinearOperations(await readJsonInput(args.input, stdin), {
+      token: env.PLANR_LINEAR_TOKEN,
+      apply: args.apply,
+    });
+  } else {
+    throw new IntegrationError(
+      'E_SYNC_USAGE',
+      'Usage: sync.mjs <local|github|linear> <inspect|sync> [--input path] [--apply]',
+    );
+  }
+  stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return result;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  runPortableSync().catch((error) => {
+    process.stderr.write(`${error.code ?? 'E_SYNC'}: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}