@planu/cli 5.7.5 → 5.7.7

package/CHANGELOG.md

@@ -1,3 +1,91 @@
+## [5.7.7] - 2026-09-02
+
+### Bug Fixes
+- fix(hooks): route src/config template assets through reference classification in selector
+- fix(tools): drop phantom multi_teammate_review from review-panel hook and scan hook templates
+- fix(tools): delete dead deprecated-tool stubs dropped by the purged registry
+- fix(tools): extend schema constraint audit to nested items and combinators
+- fix(tools): declare regex and max constraints in tool input schema descriptions
+- fix(storage): spec store returns absent for deleted canonical spec so validate fails closed with spec_not_found
+- fix(spec-grounding): surface structured diagnostics for dropped grounding records
+- fix(spec-format): accept plus bullet markers in checkbox and plain-list criterion parsers
+
+
+## [5.7.6] - 2026-09-01
+
+### Features
+- feat(skills): refresh first-party workflow skills on re-init with content-bound markers
+
+### Bug Fixes
+- fix(pre-push): replace process substitution with POSIX-portable loops in select-tests
+- fix(pre-push): fully fragment cli-spawn literal to stop test self-match
+- fix(pre-push): route unmapped tests/ helpers and src JSON to referencing suites
+- fix(types): break spec-format circular import with shared ModelTierUsed primitive
+- fix(skills): validate legacy marker hash, always emit skill-sync counts, tighten tests
+- fix(reconcile-spec): correct mirror propagation gaps found in review
+- fix(reconcile-spec): propagate section rewrites to frontmatter and contract mirrors
+- fix(validation): check payloads before writing provenance sidecars
+- fix(validation): skip provenance sidecars for absent evidence artifacts and refuse sentinel rebinds
+- fix(hooks): pass mirror test paths to vitest without the bare separator
+- fix(evidence-gates): repair legacy traceability matrices missing evidence fields
+- fix(spec-quality): bound trailing H3 subsection at the next H2 heading
+- fix(spec-format): close 3 review blockers in SPEC-1435 filler retirement
+- fix(spec-format): retire constant filler from renderer and gate the retired vocabulary
+- fix(list-specs): describe zero filtered matches instead of the global empty state
+- fix(list-specs): align in-progress counts between humanSummary and byStatus
+- fix(package-handoff): satisfy reliability gate in stage deadline catch
+- fix(package-handoff): close 6 review blockers in durable executor
+- fix(package-handoff): make handoff durable, timeout-safe and observable
+- fix(tools): purge remaining phantom tool references from SPEC-1721 emitters
+- fix: correct coverage-exclude parser and dedupe pathExists
+- fix(validate): classify non-ENOENT stale-prefix probe failures as degradation
+- fix(validate): self-heal stale worktree specPath and classify VALIDATION_STALE_SPEC_PATH
+- fix(update-status): realign store on done-freeze drift without rewriting frozen spec files
+- fix(pre-push): location-first classification, copy-record parsing, and truncated-stream fail-closed
+- fix(pre-push): NUL-safe test selection with bounded scripts lane and fail-closed classification
+- fix(git-ops): real-repo handler tests and routed test spawners after implementation review
+- fix(git-ops): expose structured branch results instead of parsing rendered markdown
+- fix(release): drop detached develop-to-main auto-merge for instructions-only mirror sync
+- fix(update-status): batch accepts per-spec model-routing evidence for guarded statuses
+- fix(validate): report restart timestamps and shape hints for missing evidence artifacts
+- fix(review-gates): enforce implementation-review independence fail-closed via reviewer sessionId (SPEC-1576)
+- fix(session-safeguard): honour session opt-out, refuse no-upstream branches, and run the pre-push gate
+- fix(self-healing): bound shell executions with timeouts and lockfile package-manager detection
+- fix(transports): refuse unauthenticated non-loopback HTTP and make api-key compare timing-safe
+- fix(engines): lower Node engines floor to verified LTS >=22.13.0
+- fix(release): abort clears the ledger when HEAD is already at the release base
+- fix(release): refuse abort when untracked work occupies a restore path and harden abort tests
+- fix(release): abort preserves uncommitted work or refuses on bump-owned overlap for SPEC-1398
+- fix(session,enricher): per-project checkpoint trackers and preview-only review enrichment for SPEC-1409
+- fix(startup): harden keybindings call-site assertion and strip narrative test comments (SPEC-1402 review)
+- fix(startup): make MCP startup read-only for user-owned state (SPEC-1402)
+- fix(spec-format): admit plus-bullet marker in single-line criterion regex
+- fix(challenge-spec): drop bare load token from scale capability signal
+- fix(ambiguity-scorer): preserve token boundaries and word count in literal-span masking
+- fix(ambiguity-scorer): exempt quoted and backticked literal spans from vague-unit matching
+- fix(spec-format): address SPEC-1439 review blockers
+- fix(spec-format): stop persisting frontmatter scenarios scavenged from prose
+- fix(spec-grounding): tighten YAML fallback signaling and per-section scoping
+- fix(spec-grounding): parse grounding frontmatter with YAML parser and legacy regex fallback
+- fix(spec-format): anchor inline TEST markers to their own scenario in bdd frontmatter
+- fix(evidence-index): resolve line-citation suffixes via literal-first stat fallback in pathRecord
+- fix(validation): visible reuse marker and discriminated freshness-barrier rejections (SPEC-1494)
+- fix(update-status): actionable stale-bindings rejection and AC2 next-action assertion (SPEC-1372)
+- fix(update-status): harden autofill classifier and receipt rebind fallback
+- fix(update-status): rebind autofilled traceability and regenerate stale matrices (SPEC-1372)
+- fix(package-handoff): gate ownership fallback on the whole bullet, name exact reason codes
+- fix(package-handoff): accept prose ownership descriptions and name rejected paths in blockers
+
+### Refactoring
+- refactor(tools): purge MCP surface to the 19-tool value core (SPEC-1721)
+
+### Chores
+- chore(website): refresh product proof
+- chore(planu): SPEC-1597 implementing checkpoint
+- chore(planu): SPEC-1439 implementing checkpoint
+- chore(planu): SPEC-1452 implementing checkpoint
+
+
 ## [5.7.5] - 2026-08-31
 
 ### Bug Fixes

package/README.md

@@ -3,7 +3,7 @@
 **The high-performance SDD stack for AI coding agents.**
 
 [![npm version](https://img.shields.io/npm/v/@planu/cli?color=blue&label=npm)](https://www.npmjs.com/package/@planu/cli)
-![Node](https://img.shields.io/badge/node-%3E%3D24.0.0-green)
+![Node](https://img.shields.io/badge/node-%3E%3D22.13.0-green)
 ![Rust](https://img.shields.io/badge/core-rust-orange)
 ![License](https://img.shields.io/badge/license-proprietary-blue)
 
@@ -21,7 +21,7 @@ Planu is a Spec Driven Development stack for AI coding agents: an MCP server and
 - **Local change detection** — observes project changes without requiring a hosted configuration service.
 - **Unified Spec Format** — Requirements and technical details in a single, context-efficient `spec.md`.
 - **Atomic Integrity** — Indestructible writes and **Freeze-on-done** immutability (P0).
-- **32 official MCP tools** for the public SDD surface, with advanced workflows kept in skills, CLI commands, and internal pipelines.
+- **19 official MCP tools** for the public SDD surface, with advanced workflows kept in skills, CLI commands, and internal pipelines.
 - **Multi-agent compatible** — Optimized for Claude Code, Cursor, Windsurf, and Gemini CLI.
 
 ---
@@ -41,7 +41,7 @@ Add to your MCP client config (Claude Desktop: `~/Library/Application Support/Cl
 }
 ```
 
-**Requirements:** Node.js >= 24. The native Rust core is bundled and auto-detected for macOS (Intel/M1), Linux, and Windows.
+**Requirements:** Node.js >= 22.13. The native Rust core is bundled and auto-detected for macOS (Intel/M1), Linux, and Windows.
 
 **Upgrade safety:** stop every running Planu process before upgrading. Current releases use a single transactional SQLite lock authority with monotonic fencing; concurrent mixed-version execution is intentionally unsupported because older file-lock clients cannot participate in the same atomic protocol.
 

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"858730d3bc7c59966cbff5c34cae03fa636843eb"}
+{"schemaVersion":1,"commit":"239ab5e0b6df0ae6aae7e6a1a7ec9d699e1a66b8"}

package/dist/cli/commands/package-handoff.js

@@ -1,10 +1,25 @@
-// cli/commands/package-handoff.ts — planu package-handoff <specId> (SPEC-1621)
+// cli/commands/package-handoff.ts — planu package-handoff <specId> (SPEC-1621, durable poll SPEC-1240)
 import { parseArgs } from 'node:util';
 import { resolve } from 'node:path';
 import { handlePackageHandoff } from '../../tools/package-handoff.js';
+import { handleGetJob } from '../../tools/jobs/handlers.js';
 import { formatToolResult } from '../formatter.js';
 import { detectProjectId } from '../project-detector.js';
 import { red } from '../colors.js';
+const TERMINAL_STATES = new Set(['completed', 'failed', 'cancelled', 'dead-letter']);
+const POLL_INTERVAL_MS = 250;
+const POLL_BUDGET_MS = 60_000;
+async function pollToTerminal(operationId, projectId, workspaceId) {
+    const deadlineAt = Date.now() + POLL_BUDGET_MS;
+    for (;;) {
+        const jobResult = await handleGetJob({ operationId, projectId, workspaceId });
+        const job = jobResult.structuredContent.job;
+        if (TERMINAL_STATES.has(job.state) || Date.now() >= deadlineAt) {
+            return job;
+        }
+        await new Promise((res) => setTimeout(res, POLL_INTERVAL_MS));
+    }
+}
 export const packageHandoffCommand = {
     name: 'package-handoff',
     description: 'Generate the operational handoff package artifact for a spec',
@@ -28,13 +43,23 @@ export const packageHandoffCommand = {
         const projectPath = values['project-path'];
         const projectId = values['project-id'] ??
             detectProjectId(projectPath ? resolve(projectPath) : undefined);
-        const result = await handlePackageHandoff({ projectId, specId });
-        if (result.isError) {
-            process.stderr.write(`${red(formatToolResult(result, flags))}\n`);
+        const submission = await handlePackageHandoff({ projectId, specId });
+        if (submission.isError) {
+            process.stderr.write(`${red(formatToolResult(submission, flags))}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const ack = submission.structuredContent;
+        const job = await pollToTerminal(ack.operationId, projectId, ack.workspaceId);
+        if (job.state !== 'completed') {
+            const hint = ack.recoveryAction
+                ? ' Run restart_job (or resubmit) to retry.'
+                : ' Run get_job to inspect the failure, or resubmit.';
+            process.stderr.write(`${red(`Handoff job ${ack.operationId} ended as ${job.state}.`)}${job.error ? ` ${job.error}` : ''}${hint}\n`);
             process.exitCode = 1;
             return;
         }
-        const output = formatToolResult(result, flags);
+        const output = formatToolResult(job.result, flags);
         if (output) {
             process.stdout.write(output + '\n');
         }

package/dist/config/compliance-profiles.json

@@ -12,7 +12,18 @@
     ]
   },
   "hipaa": {
-    "keywords": ["health", "medical", "patient", "phi", "ehr", "clinical", "diagnosis", "treatment", "hipaa", "healthcare"],
+    "keywords": [
+      "health",
+      "medical",
+      "patient",
+      "phi",
+      "ehr",
+      "clinical",
+      "diagnosis",
+      "treatment",
+      "hipaa",
+      "healthcare"
+    ],
     "criteria": [
       "Protected Health Information (PHI) is encrypted at rest using AES-256 or equivalent",
       "PHI transmission is secured with TLS 1.2+ encryption",
@@ -24,7 +35,19 @@
     ]
   },
   "pci-dss": {
-    "keywords": ["payment", "card", "credit", "debit", "checkout", "billing", "stripe", "transaction", "pci", "cvv", "pan"],
+    "keywords": [
+      "payment",
+      "card",
+      "credit",
+      "debit",
+      "checkout",
+      "billing",
+      "stripe",
+      "transaction",
+      "pci",
+      "cvv",
+      "pan"
+    ],
     "criteria": [
       "Cardholder data (PAN, CVV) is never stored in plaintext",
       "Payment card data is masked in logs and UI displays",
@@ -36,7 +59,17 @@
     ]
   },
   "soc2": {
-    "keywords": ["security", "availability", "confidentiality", "integrity", "audit", "compliance", "soc2", "soc 2", "trust"],
+    "keywords": [
+      "security",
+      "availability",
+      "confidentiality",
+      "integrity",
+      "audit",
+      "compliance",
+      "soc2",
+      "soc 2",
+      "trust"
+    ],
     "criteria": [
       "Access control policy is documented and enforced with least-privilege principle",
       "System availability is monitored with defined SLA targets and incident response",

package/dist/config/environment-schema.json

@@ -85,6 +85,20 @@
       "sensitivity": "private",
       "default": null
     },
+    {
+      "name": "PLANU_HANDOFF_CORE_BUDGET_MS",
+      "type": "number",
+      "scope": "runtime",
+      "sensitivity": "public",
+      "default": null
+    },
+    {
+      "name": "PLANU_HANDOFF_ENRICHMENT_BUDGET_MS",
+      "type": "number",
+      "scope": "runtime",
+      "sensitivity": "public",
+      "default": null
+    },
     {
       "name": "PLANU_HOST",
       "type": "string",
@@ -141,6 +155,13 @@
       "sensitivity": "private",
       "default": null
     },
+    {
+      "name": "PLANU_PRE_PUSH_SCRIPTS_LANE",
+      "type": "boolean",
+      "scope": "test",
+      "sensitivity": "public",
+      "default": null
+    },
     {
       "name": "PLANU_PROJECT_DATA_DIR",
       "type": "string",

package/dist/config/hook-templates/planu-review-panel-trigger.sh

@@ -4,7 +4,7 @@
 #
 # Wired as a PreToolUse hook for the Bash tool.
 # When Claude Code is about to run a git diff or review command and the diff is
-# large (>500 LOC), this hook prints a suggestion to use multi_teammate_review.
+# large (>500 LOC), this hook suggests the panel review skill.
 # It NEVER blocks execution — exit 0 always.
 
 set -uo pipefail
@@ -26,8 +26,7 @@ if [[ "$LOC" -gt "$THRESHOLD" ]]; then
   echo ""
   echo "💡 Planu tip: This diff is ${LOC} LOC (threshold: ${THRESHOLD})."
   echo "   Consider running the 5-specialist panel review for thorough analysis:"
-  echo "   → multi_teammate_review({ projectPath: \"$(pwd)\", diff: \"<paste diff here>\" })"
-  echo "   Or use the /planu-multi-teammate-review skill."
+  echo "   → use the /planu-multi-teammate-review skill."
   echo ""
 fi
 

package/dist/config/hook-templates/planu-session-safeguard.sh

@@ -6,21 +6,28 @@ mkdir -p "$(dirname "$log")"
 {
   echo "[$(date -u +%FT%TZ)] PreCompaction safeguard fired"
   cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
-  current=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
-  case "$current" in
-    ""|HEAD|main|master|develop|release|production)
-      # SPEC-1379: never autopush protected branches — mirrors PROTECTED_BRANCHES
-      # in src/engine/session-safeguard/autopush.ts. --no-verify below is safe
-      # ONLY because of this guard; remove one, remove both.
-      echo "skip: protected or detached ($current)"
-      ;;
-    *)
-      # No --force: the remote rejects any non-fast-forward push, so this can
-      # never overwrite remote history. --end-of-options hardens against
-      # refnames that start with a dash.
-      git push --no-verify --end-of-options origin "$current" 2>&1 || echo "push failed or nothing to push"
-      ;;
-  esac
+  if [ -n "${PLANU_NO_AUTOPUSH:-}" ] || [ -f "${CLAUDE_PROJECT_DIR:-.}/.claude/no-autopush" ]; then
+    echo "skip: autopush opt-out active"
+  else
+    current=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+    case "$current" in
+      ""|HEAD|main|master|develop|release|production)
+        # SPEC-1379: never autopush protected branches — mirrors PROTECTED_BRANCHES
+        # in src/engine/session-safeguard/autopush.ts.
+        echo "skip: protected or detached ($current)"
+        ;;
+      *)
+        if git rev-parse --verify --quiet "refs/remotes/origin/$current" >/dev/null; then
+          # No --force: the remote rejects any non-fast-forward push, so this can
+          # never overwrite remote history. --end-of-options hardens against
+          # refnames that start with a dash.
+          git push --end-of-options origin "$current" 2>&1 || echo "push failed or nothing to push"
+        else
+          echo "skip: no upstream for $current (no-upstream)"
+        fi
+        ;;
+    esac
+  fi
 } >> "$log" 2>&1
 
 exit 0

package/dist/config/official-sdd-tools.d.ts

@@ -1,4 +1,4 @@
 /** Single editable authority for the official local SDD tool surface. */
-export declare const OFFICIAL_SDD_TOOL_NAMES: readonly ['planu_status', 'session_checkpoint', 'facilitate', 'init_project', 'clarify_requirements', 'create_spec', 'list_specs', 'challenge_spec', 'check_readiness', 'update_status', 'update_status_batch', 'request_changes', 'estimate', 'package_handoff', 'validate', 'get_job', 'watch_job', 'cancel_job', 'restart_job', 'reconcile_spec', 'create_rule', 'create_skill', 'skill_search', 'configure_code_graph', 'code_graph_status', 'submit_feedback', 'triage_feedback', 'resolve_feedback', 'sync_feedback', 'feedback_status', 'bump_spec_version', 'migrate_legacy_spec'];
+export declare const OFFICIAL_SDD_TOOL_NAMES: readonly ['init_project', 'facilitate', 'create_spec', 'list_specs', 'update_status', 'update_status_batch', 'validate', 'challenge_spec', 'check_readiness', 'bump_spec_version', 'reconcile_spec', 'migrate_legacy_spec', 'package_handoff', 'planu_status', 'session_checkpoint', 'estimate', 'request_changes', 'get_job', 'restart_job'];
 export declare function readCanonicalToolNames(): string[];
 //# sourceMappingURL=official-sdd-tools.d.ts.map

package/dist/config/official-sdd-tools.js

@@ -1,37 +1,24 @@
 /** Single editable authority for the official local SDD tool surface. */
 export const OFFICIAL_SDD_TOOL_NAMES = [
-    'planu_status',
-    'session_checkpoint',
-    'facilitate',
     'init_project',
-    'clarify_requirements',
+    'facilitate',
     'create_spec',
     'list_specs',
-    'challenge_spec',
-    'check_readiness',
     'update_status',
     'update_status_batch',
-    'request_changes',
-    'estimate',
-    'package_handoff',
     'validate',
-    'get_job',
-    'watch_job',
-    'cancel_job',
-    'restart_job',
-    'reconcile_spec',
-    'create_rule',
-    'create_skill',
-    'skill_search',
-    'configure_code_graph',
-    'code_graph_status',
-    'submit_feedback',
-    'triage_feedback',
-    'resolve_feedback',
-    'sync_feedback',
-    'feedback_status',
+    'challenge_spec',
+    'check_readiness',
     'bump_spec_version',
+    'reconcile_spec',
     'migrate_legacy_spec',
+    'package_handoff',
+    'planu_status',
+    'session_checkpoint',
+    'estimate',
+    'request_changes',
+    'get_job',
+    'restart_job',
 ];
 export function readCanonicalToolNames() {
     return [...OFFICIAL_SDD_TOOL_NAMES];

package/dist/config/registries/hosts/codex.json

@@ -3,42 +3,26 @@
   "name": "Codex",
   "capabilities": { "interactiveUI": false, "askUserQuestion": false, "freeTier": false, "mcpFull": true },
   "supportedTools": [
-    "planu_status",
-    "session_checkpoint",
-    "facilitate",
     "init_project",
-    "clarify_requirements",
+    "facilitate",
     "create_spec",
     "list_specs",
-    "challenge_spec",
-    "check_readiness",
     "update_status",
     "update_status_batch",
-    "request_changes",
-    "estimate",
-    "package_handoff",
     "validate",
-    "get_job",
-    "watch_job",
-    "cancel_job",
-    "restart_job",
-    "reconcile_spec",
-    "create_rule",
-    "create_skill",
-    "skill_search",
-    "configure_code_graph",
-    "code_graph_status",
-    "submit_feedback",
-    "triage_feedback",
-    "resolve_feedback",
-    "sync_feedback",
-    "feedback_status",
+    "challenge_spec",
+    "check_readiness",
     "bump_spec_version",
-    "migrate_legacy_spec"
+    "reconcile_spec",
+    "migrate_legacy_spec",
+    "package_handoff",
+    "planu_status",
+    "session_checkpoint",
+    "estimate",
+    "request_changes",
+    "get_job",
+    "restart_job"
   ],
-  "unsupportedTools": ["challenge_spec", "red_team"],
-  "restrictedTools": {
-    "challenge_spec": "Requires interactive UI — use planu_facilitate instead",
-    "approve_spec": "Requires reviewer token — use planu_facilitate instead"
-  }
+  "unsupportedTools": [],
+  "restrictedTools": {}
 }

package/dist/config/registries/hosts/opencode.json

@@ -9,12 +9,7 @@
     "planMode": true,
     "nativeHooks": true
   },
-  "workspaceMarkers": [
-    "opencode.json",
-    ".opencode/",
-    "~/.opencode/",
-    "OPENCODE_HOME"
-  ],
+  "workspaceMarkers": ["opencode.json", ".opencode/", "~/.opencode/", "OPENCODE_HOME"],
   "supportedTools": [
     "list_specs",
     "validate",

package/dist/config/server-instructions.js

@@ -87,27 +87,6 @@ export const SERVER_INSTRUCTIONS = [
     '- When creating multiple specs at once, present ALL specs for review and let the user approve/reject each one individually.',
     '- The reviewNotes field stores a history of all feedback — implementers can see what was requested and why.',
     '',
-    'SKILL DISCOVERY — proactive search, mandatory in these situations:',
-    '1. AFTER init_project: call skill_search for EACH technology in the detected stack.',
-    '   - Use the actual detected values: language, framework, database, key stack entries.',
-    '   - Works for ANY stack: Python, Go, Rust, Java, Ruby, PHP, .NET — not just JavaScript.',
-    '   - Example: stack has [Django, PostgreSQL, Celery] → call skill_search("django"), skill_search("postgresql").',
-    '   - Example: stack has [Next.js, Tailwind, Prisma] → call skill_search("nextjs"), skill_search("prisma").',
-    '   - Present the top 5 results grouped by technology and offer to install the most relevant.',
-    '   - ALSO search for design/marketing skills when the project has brand or product signals:',
-    '     * Signals: projectPath contains "landing"/"marketing"/"brand", stack has "website"/"saas"/"startup",',
-    '       apps[] has marketing-named entries, or README mentions logo/brand/landing.',
-    '     * When detected: call skill_search("logo design"), skill_search("banner design"),',
-    '       skill_search("brand identity"), skill_search("og image"), skill_search("favicon generator").',
-    '     * Present these alongside technical skills — visual assets matter as much as code.',
-    '2. BEFORE implementing any repeatable pattern: call skill_search with the pattern name.',
-    '   - "add authentication" → skill_search("authentication " + detected_framework)',
-    '   - "setup CI/CD" → skill_search("github actions") or skill_search("gitlab ci")',
-    '3. When the user mentions any technology by name: call skill_search with that term.',
-    '- If a matching skill is found: show it, offer to install with skill_install.',
-    '- If no skill found: proceed normally and note there are no community skills for that technology yet.',
-    '- Explain: "Skills are community-curated guides that encode best practices for this technology."',
-    '',
     'RESPONSE FORMAT — MANDATORY for all tool results:',
     '- NEVER show raw JSON.stringify output to the user — always format as readable markdown',
     '- Use emojis for visual hierarchy: ✅ success, ⚠️ warning, ❌ error, 🚀 next steps, 📊 stats',

package/dist/config/skill-templates/planu-context-assets.md

@@ -67,17 +67,14 @@ Do not create either when the information is one-off, speculative, or already co
    - explicit trigger
    - concrete steps or constraints
    - verification command when applicable
-4. Use Planu host-aware tools:
-   - `create_rule` for mandatory constraints
-   - `create_skill` for reusable workflows
-5. Use `host: "auto"` unless the user explicitly targets a host.
-6. Prefer updating an existing Planu-owned asset over creating a duplicate.
+4. Write the rule or skill file directly to the target host path (e.g. `.claude/rules/`, `.claude/skills/`).
+5. Prefer updating an existing Planu-owned asset over creating a duplicate.
 
 ## Quality bar
 
 - Rules must be enforceable and written as constraints.
 - Skills must describe when to invoke, what to inspect, what to do, and what output to produce.
-- Do not reference legacy MCP tools that are not part of the 14-tool public core.
+- Do not reference legacy MCP tools that are not part of the 19-tool public core.
 - Do not create broad "misc" skills.
 - Do not preserve dead workflows "just in case".
 

package/dist/config/skill-templates/planu-implement.md

@@ -23,8 +23,8 @@ Use this skill once a spec is `approved` and implementation is about to begin.
 
 The normative tool-call sequence for this phase:
 
-1. **Package the handoff** — call `package_handoff` to build the operating contract for the implementer: objective, BDD acceptance criteria, files to modify/create, ownership, test plan, risks, out-of-scope, current state, next action. Persist it outside chat history
-2. **Move to implementing** — call `update_status(implementing)` only after the handoff package exists
+1. **Package the handoff** — call `package_handoff` to submit a durable job that builds the operating contract for the implementer: objective, BDD acceptance criteria, files to modify/create, ownership, test plan, risks, out-of-scope, current state, next action. Poll it to completion with `get_job` (use `restart_job` if it ends failed); the package is persisted outside chat history
+2. **Move to implementing** — call `update_status(implementing)` only after `get_job` reports the handoff package as completed
 3. **Isolate the work** — implement inside an isolated git worktree created from the current base branch, never on the shared checkout
 4. **Write revert-proof tests** — for every guard or fix, write the test first, revert the source change and watch the test fail, then restore the source and confirm it passes. Report the observed failure output, not just the final green run
 5. **No narrative comments** — code is self-documenting; no step-by-step comments, no `(SPEC-NNNN: ...)` rationale blocks, no TODO/FIXME markers

package/dist/config/skill-templates/planu-multi-teammate-review.md

@@ -21,22 +21,18 @@ Use this skill when you want a thorough, multi-perspective code review:
 - Before merging a large or risky PR (>200 LOC changed)
 - When a PR touches security-sensitive code (auth, payments, data access)
 - When a reviewer is unavailable and you need a comprehensive analysis
-- When the default `review_pr` output is insufficient and you need specialist depth
+- When a single-pass review is insufficient and you need specialist depth
 
 **Trigger phrases**: "panel review", "thorough review", "5-agent review", "deep review", "run the specialist panel"
 
-## How to invoke the tool
+## How this skill runs the review
 
-```
-multi_teammate_review({
-  projectPath: "/absolute/path/to/project",
-  diff: "<unified diff text>",          // preferred: paste the output of git diff
-  prNumber: 42,                          // optional: for context in the report header
-  branch: "feat/my-feature",            // optional: for context
-  commitRange: "main..HEAD",             // optional: for context
-  spec: "<linked spec content>"          // optional: helps the arbitrator detect spec drift
-})
-```
+This skill runs the panel directly — it is not an MCP tool call. Gather the review inputs below, then run the panel yourself following the specialist roles described in this skill:
+
+- `projectPath` — absolute path to the project
+- `diff` — unified diff text (preferred: paste the output of `git diff`)
+- `prNumber`, `branch`, or `commitRange` — optional context for the report header
+- `spec` — optional linked spec content, enables spec-drift detection in the Maintainability specialist's report
 
 At least one of `diff`, `prNumber`, `branch`, or `commitRange` must be provided.
 

package/dist/config/skill-templates/planu-release.md

@@ -31,13 +31,8 @@ Use this skill when all done specs are merged to main and you want to publish a
 
 1. **Check state** — calls `planu_status` to confirm no specs are `implementing` or `review`
 2. **Determine version bump** — analyzes commits since last release: `feat` → minor, `fix` → patch, breaking changes → major
-3. **Generate changelog** — calls `generate_changelog` to create the release notes
-4. **Create release** — calls `create_release({ version, notes })` which:
-   - Bumps `package.json` version
-   - Writes `CHANGELOG.md` entry
-   - Creates git tag `vX.Y.Z`
-   - Publishes to npm (`npm publish --access public`)
-   - Pushes tag to origin
+3. **Run the local gate** — run `pnpm check:preflight` and fix anything it flags
+4. **Release** — run `pnpm release:local`, which bumps `package.json`, writes the `CHANGELOG.md` entry, tags the commit, publishes to npm, and pushes the tag
 5. **Confirm** — reports the published version and npm URL
 
 ## Usage

package/dist/config/skill-templates/planu-validate.md

@@ -25,10 +25,10 @@ Use this skill after implementation is complete, before marking a spec as done,
 
 1. **Find active spec** — calls `planu_status` to identify the current `implementing` spec
 2. **Submit validation** — call `validate({ specId })` and capture its durable acknowledgement: `operationId`, `projectId`, `workspaceId`, and `cursor`
-3. **Wait for completion** — call `watch_job` with those identifiers and the latest cursor; repeat while state is non-terminal
+3. **Wait for completion** — poll `get_job` with those identifiers and the latest cursor; repeat while state is non-terminal
 4. **Inspect the result** — require state `completed`, then read `job.result.structuredContent`; stop and report `failed`, `dead-letter`, or `cancelled` jobs
-5. **Health check** — call `spec_health_check({ specId })` for structural quality
-6. **Auto-fix** — call `auto_fix_validation` for automatically fixable issues, then submit and await a new validation job
+5. **Fix gaps** — for each failing criterion, fix the underlying code or test
+6. **Re-validate** — call `validate({ specId })` again and poll `get_job` until it reaches a terminal state; use `restart_job` if the job itself failed or was cancelled rather than the criteria
 7. **Report** — present a structured pass/fail report from the completed job result
 
 ## Output format

package/dist/config/spec-templates/crud-rest-api/template.json

@@ -3,7 +3,11 @@
   "description": "Full CRUD REST API for a domain entity with validation, pagination, and error handling",
   "variables": [
     { "name": "entity", "description": "Name of the domain entity (e.g. Product, User, Order)", "default": "Entity" },
-    { "name": "base_path", "description": "Base URL path for the resource (e.g. /api/products)", "default": "/api/entities" },
+    {
+      "name": "base_path",
+      "description": "Base URL path for the resource (e.g. /api/products)",
+      "default": "/api/entities"
+    },
     { "name": "id_type", "description": "Type of the entity ID field (uuid, number)", "default": "uuid" }
   ],
   "tags": ["crud", "rest-api", "backend", "database"]

package/dist/config/spec-templates/file-upload-s3/template.json

@@ -5,7 +5,11 @@
     { "name": "provider", "description": "Cloud storage provider (s3, gcs, r2)", "default": "s3" },
     { "name": "bucket_name", "description": "Name of the storage bucket", "default": "uploads" },
     { "name": "max_size_mb", "description": "Maximum allowed file size in megabytes", "default": "10" },
-    { "name": "allowed_types", "description": "Comma-separated list of allowed MIME types", "default": "image/jpeg,image/png,application/pdf" }
+    {
+      "name": "allowed_types",
+      "description": "Comma-separated list of allowed MIME types",
+      "default": "image/jpeg,image/png,application/pdf"
+    }
   ],
   "tags": ["file-upload", "s3", "storage", "backend"]
 }