showdar-skills 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -4,7 +4,68 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## [0.6.0]
+
+### Added
+
+- Portable workflow execution state (`src/workflow-state.js`): versioned
+  JSON checkpoint schema (schemaVersion 1) with stage selection, evidence
+  receipts, structured skip, interruption, and resume. State never persists
+  authority; resume always re-resolves through Phase 6G. Caller/harness
+  owns persistence; no filesystem store, backend, or telemetry.
+- Workflow checkpoint documentation in all four workflow skills
+  (feature, bugfix, release, incident): serialization,
+  interruption/resume, stale-checkpoint blocking, and stage vs workflow
+  completion semantics.
+- Workflow-state policy validation in `src/validate.js`: catalog coverage,
+  no authority fields in checkpoints, no harness or storage coupling.
+
+### Changed
+
+- Four workflow skills now describe adaptive state semantics instead of
+  ephemeral-only tracking.
+- Workflow completion explicitly distinguishes stage completion (primitive
+  evidence and stop conditions) from workflow completion (all selected
+  stages completed or validly skipped, no blockers, required verification
+  satisfied).
+
+### Safety
+
+- Checkpoint state never persists authority-derived fields.
+- Caller owns checkpoint persistence; Showdar chooses no storage.
+- Stale checkpoints block with `replanRequired` rather than continuing.
+
+## [0.5.0]
+
+### Added
+
+- Native per-harness adapter layer over the unchanged portable core
+  (15 primitives + 4 workflows, 19 total installable skills).
+- Generated OpenCode slash commands
+  (`.opencode/commands/showdar/`): one direct command per installed skill
+  plus a generic `/showdar/skill` aggregator reflecting the installed set.
+- Generated Claude Code slash commands
+  (`.claude/commands/showdar/`): one direct command per installed skill
+  plus a generic `/showdar/skill` aggregator reflecting the installed set.
+- Claude Code `CLAUDE.md` managed-block integration from the canonical
+  instruction body.
+- Cursor native `.cursor/rules/showdar.mdc` rule (Apply Intelligently,
+  `alwaysApply: false`, no globs) from the canonical instruction body.
+- Canonical adapter renderers (`src/adapter-renderers.js`) for
+  instructions, direct commands, and the generic aggregator.
+- Adapter lifecycle and ownership validation: doctor/status checks for
+  active instruction surfaces, generated commands, and aggregators;
+  stale Showdar-owned artifact cleanup on target switching.
+
+### Changed
+
+- Installer manages harness-native command and instruction artifacts
+  alongside portable skills.
+- Doctor/status validate active adapter artifacts; global installs do not
+  require instruction files and non-command hosts do not require commands.
+- `--ai all` is a compatibility aggregate: all skill roots, OpenCode and
+  Claude commands, and only the canonical `AGENTS.md` instruction block
+  (no `CLAUDE.md` block, no Cursor rule).
 
 ## [0.4.0]
 

package/MIGRATION.md

@@ -1,3 +1,50 @@
+# Migrating to 0.6.0
+
+0.6.0 adds portable workflow execution state (`src/workflow-state.js`,
+schemaVersion 1) over the unchanged 15 primitives, 4 workflows, and Phase 6G
+authority.
+
+- Existing 0.5 installs and configs remain valid; no adapter or config
+  migration is required.
+- The four workflows now support explicit portable execution state:
+  stage selection and progression, evidence-backed skipping, stage vs
+  workflow completion, interruption, and resume.
+- Checkpoints are plain JSON at schemaVersion 1. Persistence is owned by
+  the caller or harness; Showdar 0.6 defines no state directory, backend,
+  session registry, or telemetry.
+- Resume always re-resolves current context through Phase 6G. Stale
+  checkpoints return `BLOCKED` with `replanRequired` instead of silently
+  continuing.
+- Checkpoints never persist authority. No migration of prior route or
+  authority state exists or is needed.
+- No config change is required. Callers that never persist a checkpoint
+  keep the previous ephemeral-only behavior.
+
+# Migrating to 0.5.0
+
+0.5.0 adds a thin native adapter layer over the unchanged portable core.
+Existing 0.4 `.showdar.json` v2 configs remain valid; no schema bump is
+required (adapter metadata is additive and optional).
+
+- Re-running `showdar init ...` may add native adapter artifacts for the
+  selected harness. Existing skill content remains unchanged when hashes
+  match.
+- Claude: 0.5 adds the `CLAUDE.md` managed block plus native Showdar
+  command files under `.claude/commands/showdar/`.
+- Cursor: 0.5 adds `.cursor/rules/showdar.mdc` (Apply Intelligently,
+  `alwaysApply: false`, no globs).
+- OpenCode: existing command behavior is extended through the canonical
+  generated command lifecycle (one direct command per installed skill plus
+  `/showdar/skill`).
+- `--ai all` is a defined compatibility aggregate: all skill roots,
+  OpenCode and Claude commands, and only the `AGENTS.md` block (no
+  `CLAUDE.md` block, no Cursor rule).
+- Global scope installs skills and OpenCode/Claude commands where
+  applicable, with no managed global instruction files.
+- Removal deletes only Showdar-owned adapter artifacts and managed blocks;
+  user content outside Showdar markers remains intact.
+- Portable skill/workflow semantics and Phase 6G authority are unchanged.
+
 # Migrating to 0.4.0
 
 0.4.0 adds four optional workflow skills over the unchanged 15 primitives:

package/README.md

@@ -89,16 +89,97 @@ instructions.
 | Cursor | `.cursor/skills/` | `~/.cursor/skills/` | Supported installation target |
 | Claude Code | `.claude/skills/` | `~/.claude/skills/` | Supported installation target |
 
-Universal uses `.agents/skills/`. Explicit harness targets use their native
-skill directories. Codex and Universal intentionally share `.agents/skills/`.
-OpenCode additionally receives native `/showdar/...` command files in
-`.opencode/commands/showdar/` (project) and
-`~/.config/opencode/commands/showdar/` (global).
-
 "Supported installation target" means skills install to the harness-native
 directory. It does not promise identical implicit invocation, cloud,
 agent/subagent, or MCP behavior across harnesses.
 
+## Adapter model
+
+The portable core (15 primitives + 4 workflows) never changes per harness.
+A thin native adapter layer renders harness-specific entry surfaces only:
+
+```text
+portable Showdar semantics
+  -> canonical renderers
+  -> harness adapter
+  -> native instruction/command surface
+```
+
+Adapters do NOT change routing, grant authority, rewrite `SKILL.md`
+semantics, or fork workflows per harness.
+
+## Native instruction surfaces (project scope)
+
+| Target | Instruction surface |
+| --- | --- |
+| `universal` | `AGENTS.md` managed block |
+| `codex` | `AGENTS.md` managed block |
+| `opencode` | `AGENTS.md` managed block |
+| `claude` | `CLAUDE.md` managed block |
+| `cursor` | `.cursor/rules/showdar.mdc` |
+
+One native instruction surface per explicit target. The Cursor rule uses
+Apply Intelligently metadata (`alwaysApply: false`, no globs) and carries
+the same canonical semantic body as the `AGENTS.md`/`CLAUDE.md` blocks.
+
+## Native command surfaces
+
+| Target | Commands |
+| --- | --- |
+| `opencode` | Native `/showdar/<skill>` |
+| `claude` | Native `/showdar/<skill>` |
+| `codex` | None (skill invocation only) |
+| `cursor` | None (rule discovery only) |
+| `universal` | None (skill discovery only) |
+
+`/showdar/skill` is generated for OpenCode/Claude as generic
+installed-skill discovery. Commands are generated dynamically from the
+installed skill set: `minimal` yields 8 direct commands plus the generic
+entry; adding `feature` yields 9 plus generic. All 19 commands never exist
+unless all 19 skills are installed.
+
+## Native install examples
+
+```bash
+showdar init --ai opencode
+showdar init --ai claude
+showdar init --ai cursor
+showdar add feature --ai claude
+showdar add debug --ai opencode
+```
+
+OpenCode project install produces `.opencode/skills/...`,
+`.opencode/commands/showdar/...`, and the `AGENTS.md` managed block.
+Claude produces `.claude/skills/...`, `.claude/commands/showdar/...`, and
+the `CLAUDE.md` managed block. Cursor produces `.cursor/skills/...` and
+`.cursor/rules/showdar.mdc` with no generated commands.
+
+## `--ai all` compatibility policy
+
+`--ai all` is a compatibility aggregate. It installs all native skill
+roots, generates OpenCode and Claude commands, and writes only the
+canonical `AGENTS.md` instruction block. It does NOT generate the
+`CLAUDE.md` Showdar block or the Cursor rule, avoiding duplicate Showdar
+instruction ingestion across compatibility-aware hosts. For native-optimal
+Claude/Cursor behavior use explicit `--ai claude` or `--ai cursor`.
+
+## Global scope
+
+Global installs provide skills everywhere and OpenCode/Claude commands
+where applicable, with no managed global instruction files. This is
+deliberate in 0.5.0:
+
+| Global target | Contents |
+| --- | --- |
+| `universal` | skills only |
+| `codex` | skills only |
+| `opencode` | skills + commands |
+| `claude` | skills + commands |
+| `cursor` | skills only |
+| `all` | all skill roots + OpenCode/Claude commands |
+
+No global `AGENTS.md`, `CLAUDE.md`, or Cursor rule is managed.
+
 ## Project and global installation
 
 Global CLI installation and global skill installation are separate decisions.
@@ -304,6 +385,64 @@ primitive (`showdar-review`, `showdar-debug`, `showdar-test`). Phase 6G remains
 the authority source; workflows consume it and never mint it. Workflows are
 opt-in through `showdar add <workflow>`; profiles install primitive sets only.
 
+## Workflow execution state (0.6.0)
+
+```text
+portable workflow
+  -> workflow-state
+  -> primitive evidence/stop conditions
+  -> current Phase 6G resolution
+  -> next stage / blocked / complete
+```
+
+Workflow state (`src/workflow-state.js`, schemaVersion 1) is a portable,
+versioned JSON checkpoint: `workflowId`, selected stages, active stage,
+completed stages, skipped stages, evidence receipts, blockers, next stage,
+`status` (`NEW`/`READY`/`ACTIVE`/`COMPLETE`/`INTERRUPTED`/`BLOCKED`), and a
+deterministic monotonic `revision` counter. Timestamps
+(`createdAt`/`updatedAt`/receipt timestamps) are metadata and provenance only.
+
+Workflow state is NOT authority, memory, router intent, or a persistence
+backend. It never persists authority-derived fields
+(`primaryCapability`, `authorizedAction`, `mutationPermission`,
+`routeAuthority` or equivalents). Checkpoint JSON may be stored by a
+caller or harness anywhere; Showdar 0.6 does not choose or manage storage.
+
+Evidence receipts are compact copies of primitive evidence at stage
+completion (`kind`, `quality`, `source`, `detail`, timestamp, optional
+provenance). Quality follows `claimed < observed < verified`; `failed` and
+`missing` remain meaningful negative states. High-sensitivity evidence
+(change, tests, build, package, compatibility, regression proof, release
+readiness) may require re-verification after resume; old evidence is not
+permanently valid.
+
+Safe resume is always:
+
+```text
+checkpoint
+  -> deserialize + validate
+  -> resolve current request/context through Phase 6G
+  -> compatibility/freshness checks
+  -> READY or BLOCKED + replanRequired
+```
+
+A checkpoint alone can never authorize continuation. Previously authorized
+mutation is never restored from a checkpoint. When the current Phase 6G
+resolution no longer matches the checkpoint, resume returns `BLOCKED` with
+`replanRequired` instead of silently continuing.
+
+Per-workflow skip policy (evidence-backed, never severity or wording alone):
+
+- Feature: requirements/plan/design may be skipped only with policy-backed
+  evidence; build, test, and review always run.
+- Bugfix: debug may be skipped only with verified root-cause evidence;
+  symptom description alone is insufficient; investigation-only requests stop
+  without mutation.
+- Release: readiness does not imply deployment; ops loads only with explicit
+  target plus execution authorization.
+- Incident: severity never grants production mutation; recovery and
+  verification remain gated by current authority.
+
 ## A typical software workflow
 
 ```text

package/bin/showdar.js

@@ -32,7 +32,7 @@ function scopeAfter(args) {
 function printHelp(version, command = null) {
   const scopeUsage = '[--scope <project|global>]';
   if (command === 'init') {
-    console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>]\n\nDefaults: scope project, profile full, AI target universal.\nProject scope writes native skills and project .showdar.json. Global scope writes verified user skill directories and ~/.showdar/global.json without project files. Codex and universal use .agents/skills in project scope and ~/.agents/skills in global scope; cursor uses .cursor/skills in project scope and ~/.cursor/skills in global scope; --ai all writes each shared destination once.\n\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
+    console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>]\n\nDefaults: scope project, profile full, AI target universal.\nProject scope writes native skills, one native instruction surface, and project .showdar.json. Global scope writes verified user skill directories and ~/.showdar/global.json without instruction files. Codex and universal use .agents/skills in project scope and ~/.agents/skills in global scope; cursor uses .cursor/skills in project scope and ~/.cursor/skills in global scope; --ai all writes each shared destination once, generates OpenCode and Claude commands, and writes only the AGENTS.md block.\n\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
     return;
   }
   if (['status', 'doctor', 'remove'].includes(command)) {
@@ -86,10 +86,9 @@ async function main() {
     const ai = valueAfter(args, '--ai', 'universal');
     const skillIds = resolveProfile(requestedProfile);
     if (isDeprecatedProfile(requestedProfile)) console.warn(`Warning: profile "${requestedProfile}" is deprecated; use "${profile}".`);
-    const commandNames = ai === 'opencode' || ai === 'all' ? COMMANDS : [];
     const result = scope === 'global'
-      ? await initGlobal({ homeRoot: homedir(), packageRoot, profile, ai, skillIds, commandNames, packageVersion: version })
-      : await initProject({ projectRoot, packageRoot, profile, ai, skillIds, commandNames, packageVersion: version });
+      ? await initGlobal({ homeRoot: homedir(), packageRoot, profile, ai, skillIds, packageVersion: version })
+      : await initProject({ projectRoot, packageRoot, profile, ai, skillIds, packageVersion: version });
     console.log(`Showdar Skills installed.\nScope: ${scope}\nProfile: ${profile}\nAI: ${ai}\nTargets: ${result.targets.join(', ')}\nSkills: ${result.skills}\nOpenCode commands: ${result.commands}`);
     if (scope === 'project') {
       console.log(`Requested: ${result.requestedSkills}\nInstalled in project: ${result.installedSkills}\nSatisfied by global: ${result.satisfiedByGlobal}\nSkipped duplicate copies: ${result.skippedDuplicates}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },

package/skills/showdar-bugfix/SKILL.md

@@ -53,8 +53,12 @@ description: Use when resolving an observed defect end-to-end, adaptively sequen
 
 - Load one primitive at a time; hand off only when its stop condition is met.
 - Each primitive's own SKILL.md governs its stage; do not copy primitive instructions here.
-- Track ephemeral state only: candidate stages, selected stages, active stage, completed evidence, next stage or complete.
-- No persistent checkpoint or resume infrastructure in this version.
+- Track portable workflow state (`src/workflow-state.js`): candidate stages, selected stages, active stage, completed evidence receipts, skipped stages with structured reason plus evidence plus policy, next stage or complete, status, revision.
+- Checkpoint by serializing state to plain JSON; caller or harness owns persistence. No filesystem or backend store is implied.
+- Interrupt explicitly to preserve completed plus skipped plus evidence state without inventing completion.
+- Resume by validating the checkpoint, re-resolving current context through Phase 6G, checking workflow compatibility, then continuing or blocking with replan-required.
+- Stored state never authorizes continuation; debug may be skipped only with proven root-cause evidence under policy, never from symptom description alone.
+- Stage completion comes from primitive evidence and stop conditions; workflow completion requires root cause proven plus fix implemented plus verification plus review.
 
 ## Decision points
 

package/skills/showdar-feature/SKILL.md

@@ -56,8 +56,12 @@ description: Use when implementing a complete feature end-to-end, adaptively seq
 
 - Load one primitive at a time; hand off only when its stop condition is met.
 - Each primitive's own SKILL.md governs its stage; do not copy primitive instructions here.
-- Track ephemeral state only: candidate stages, selected stages, active stage, completed evidence, next stage or complete.
-- No persistent checkpoint or resume infrastructure in this version.
+- Track portable workflow state (`src/workflow-state.js`): candidate stages, selected stages, active stage, completed evidence receipts, skipped stages with structured reason plus evidence plus policy, next stage or complete, status, revision.
+- Checkpoint by serializing state to plain JSON; caller or harness owns persistence. No filesystem or backend store is implied.
+- Interrupt explicitly to preserve completed plus skipped plus evidence state without inventing completion.
+- Resume by validating the checkpoint, re-resolving current context through Phase 6G, checking workflow compatibility, then continuing or blocking with replan-required.
+- Stored state never authorizes continuation; skip requires policy plus evidence, never severity or wording alone.
+- Stage completion comes from primitive evidence and stop conditions; workflow completion requires every selected stage completed or validly skipped, no blockers, and required verification satisfied.
 
 ## Decision points
 

package/skills/showdar-incident/SKILL.md

@@ -57,8 +57,12 @@ description: Use when investigating and recovering from an active operational in
 
 - Load one primitive at a time; hand off only when its stop condition is met.
 - Each primitive's own SKILL.md governs its stage; do not copy primitive instructions here.
-- Track ephemeral state only: candidate stages, selected stages, active stage, completed evidence, next stage or complete.
-- No persistent checkpoint or resume infrastructure in this version.
+- Track portable workflow state (`src/workflow-state.js`): candidate stages, selected stages, active stage, completed evidence receipts, skipped stages with structured reason plus evidence plus policy, next stage or complete, status, revision.
+- Checkpoint by serializing state to plain JSON; caller or harness owns persistence. No filesystem or backend store is implied.
+- Interrupt explicitly to preserve completed plus skipped plus evidence state without inventing completion.
+- Resume by validating the checkpoint, re-resolving current context through Phase 6G, checking workflow compatibility, then continuing or blocking with replan-required.
+- Stored state never authorizes continuation; severity never grants production mutation, and ops loads only with explicit environment plus action authority.
+- Stage completion comes from primitive evidence and stop conditions; workflow completion requires recovery plus verification per policy, not merely diagnosis.
 
 ## Decision points
 

package/skills/showdar-release/SKILL.md

@@ -54,8 +54,12 @@ description: Use when preparing, validating, or executing a release lifecycle, a
 
 - Load one primitive at a time; hand off only when its stop condition is met.
 - Each primitive's own SKILL.md governs its stage; do not copy primitive instructions here.
-- Track ephemeral state only: candidate stages, selected stages, active stage, completed evidence, next stage or complete.
-- No persistent checkpoint or resume infrastructure in this version.
+- Track portable workflow state (`src/workflow-state.js`): candidate stages, selected stages, active stage, completed evidence receipts, skipped stages with structured reason plus evidence plus policy, next stage or complete, status, revision.
+- Checkpoint by serializing state to plain JSON; caller or harness owns persistence. No filesystem or backend store is implied.
+- Interrupt explicitly to preserve completed plus skipped plus evidence state without inventing completion.
+- Resume by validating the checkpoint, re-resolving current context through Phase 6G, checking workflow compatibility, then continuing or blocking with replan-required.
+- Stored state never authorizes continuation; ops is skipped under readiness-only policy and never implied by release completion.
+- Stage completion comes from primitive evidence and stop conditions; workflow completion means readiness verification per policy, not implicit deployment.
 
 ## Decision points
 

package/src/adapter-renderers.js

@@ -0,0 +1,88 @@
+import { ALL_SKILLS } from './catalog.js';
+
+const CANONICAL_ROUTE_ORDER = [
+  ['map repository architecture, dependencies, or impact', 'showdar-understand'],
+  ['plan implementation of agreed behavior and scope', 'showdar-plan'],
+  ['design product UI, UX, responsive layout, accessibility, or visual polish', 'showdar-design'],
+  ['implement or refactor an agreed application change', 'showdar-build'],
+  ['debug an observed bug, crash, regression, build, or performance failure', 'showdar-debug'],
+  ['choose or implement automated tests and coverage', 'showdar-test'],
+  ['review code or diffs for general correctness, architecture, performance, maintainability, or tests', 'showdar-review'],
+  ['upgrade dependencies, frameworks, runtimes, or platforms', 'showdar-upgrade'],
+  ['check release, artifact, or handoff readiness', 'showdar-ship'],
+  ['recover interrupted or partial engineering work', 'showdar-recover'],
+  ['perform local Git inspection, staging, commit, merge, rebase, or conflict work', 'showdar-git'],
+  ['define product behavior, business rules, ambiguity, or acceptance criteria', 'showdar-requirements'],
+  ['plan QA scenarios, risk coverage, regression, compatibility, or bug evidence', 'showdar-quality'],
+  ['assess threats, attack surface, trust boundaries, auth, secrets, exposure, or exploitability', 'showdar-security'],
+  ['inspect or change CI/CD, containers, environments, deployment, observability, rollback, or runtime operations', 'showdar-ops'],
+  ['implement a complete feature end-to-end across multiple lifecycle stages', 'showdar-feature'],
+  ['resolve an observed defect end-to-end', 'showdar-bugfix'],
+  ['prepare, validate, or execute a release lifecycle', 'showdar-release'],
+  ['investigate or recover from an active operational incident', 'showdar-incident'],
+];
+
+function getSkillDescription(skillId) {
+  const skill = ALL_SKILLS.find((s) => s.id === skillId);
+  return skill?.description ?? '';
+}
+
+export function renderShowdarInstruction(skillIds) {
+  const wanted = new Set(skillIds);
+  const routes = CANONICAL_ROUTE_ORDER
+    .filter(([, id]) => wanted.has(id))
+    .map(([intent, id]) => `- ${intent} -> \`${id}\``);
+  for (const id of [...wanted].sort()) {
+    if (!CANONICAL_ROUTE_ORDER.some(([, known]) => known === id)) {
+      routes.push(`- ${getSkillDescription(id)} -> \`${id}\``);
+    }
+  }
+  return `${routes.join('\n')}\n`;
+}
+
+export function renderShowdarCommand(skillId) {
+  const description = getSkillDescription(skillId);
+  return `---
+description: ${description}
+---
+
+Load and follow \`${skillId}\`.
+Ground in the current repository.
+Request: \$ARGUMENTS
+`;
+}
+
+export function renderShowdarAggregator(skillIds) {
+  const sorted = [...new Set(skillIds)].sort((a, b) => a.localeCompare(b));
+  const ids = sorted.join(', ');
+  return `---
+description: Invoke a specific Showdar flagship skill explicitly
+---
+Select exactly one requested Showdar skill and follow it: ${ids}. Whole-task intent (complete feature, end-to-end fix, release lifecycle, active incident) selects a workflow; single primitive intent stays primitive. If the requested name is ambiguous, choose the smallest matching skill from this list and say which one was selected.
+
+Request: \$ARGUMENTS
+`;
+}
+
+export function renderCursorRuleBody(skillIds) {
+  const body = renderShowdarInstruction(skillIds).trimEnd();
+  return `---
+description: Showdar skill and workflow routing guidance for software-engineering tasks
+alwaysApply: false
+---
+
+${body}
+`;
+}
+
+export function renderManagedBlock(skillIds, kind) {
+  const body = renderShowdarInstruction(skillIds).trimEnd();
+  if (kind === 'block') {
+    const START = '<!-- showdar-skills:start -->';
+    const END = '<!-- showdar-skills:end -->';
+    return `${START}\n## Showdar Skills routing\n\nUse the smallest Showdar skill that fully matches the current task. Do not load unrelated Showdar skills.\n\n${body}\n\nFor debugging, gather evidence before modifying code. For shipping or destructive operations, require explicit user approval and fresh verification. Never print or commit secrets.\n${END}\n`;
+  } else if (kind === 'file') {
+    return renderCursorRuleBody(skillIds);
+  }
+  return body;
+}

package/src/adapters.js

@@ -3,6 +3,29 @@ import { homedir } from 'node:os';
 
 export const NATIVE_TARGETS = ['codex', 'opencode', 'cursor', 'claude', 'universal'];
 
+export const ADAPTERS = {
+  universal: {
+    instruction: { kind: 'block', file: 'AGENTS.md' },
+    commands: null,
+  },
+  codex: {
+    instruction: { kind: 'block', file: 'AGENTS.md' },
+    commands: null,
+  },
+  opencode: {
+    instruction: { kind: 'block', file: 'AGENTS.md' },
+    commands: { destination: ['.opencode', 'commands', 'showdar'] },
+  },
+  claude: {
+    instruction: { kind: 'block', file: 'CLAUDE.md' },
+    commands: { destination: ['.claude', 'commands', 'showdar'] },
+  },
+  cursor: {
+    instruction: { kind: 'file', file: path.join('.cursor', 'rules', 'showdar.mdc') },
+    commands: null,
+  },
+};
+
 const ROOTS = {
   codex: ['.agents', 'skills'],
   opencode: ['.opencode', 'skills'],
@@ -19,6 +42,11 @@ const GLOBAL_ROOTS = {
   universal: ({ homeRoot }) => path.join(homeRoot, '.agents', 'skills'),
 };
 
+const GLOBAL_COMMAND_ROOTS = {
+  opencode: ({ homeRoot }) => path.join(homeRoot, '.config', 'opencode', 'commands', 'showdar'),
+  claude: ({ homeRoot }) => path.join(homeRoot, '.claude', 'commands', 'showdar'),
+};
+
 export function resolveTargets(ai) {
   if (ai === 'all') return [...NATIVE_TARGETS];
   if (!NATIVE_TARGETS.includes(ai)) throw new Error(`Unknown AI target "${ai}". Expected codex, opencode, cursor, claude, universal, or all.`);
@@ -52,10 +80,40 @@ export const COMPATIBILITY_MATRIX = {
   universal: { project: true, global: true },
 };
 
+export function commandRootFor(target, projectRoot) {
+  const adapter = ADAPTERS[target];
+  if (!adapter?.commands?.destination) return null;
+  return path.join(projectRoot, ...adapter.commands.destination);
+}
+
+export function globalCommandRootForTarget(target, { homeRoot = homedir() } = {}) {
+  const resolver = GLOBAL_COMMAND_ROOTS[target];
+  if (!resolver) return null;
+  return resolver({ homeRoot });
+}
+
 export function opencodeCommandRoot(projectRoot) {
-  return path.join(projectRoot, '.opencode', 'commands', 'showdar');
+  return commandRootFor('opencode', projectRoot);
 }
 
 export function globalCommandRootFor({ homeRoot = homedir() } = {}) {
-  return path.join(homeRoot, '.config', 'opencode', 'commands', 'showdar');
-}
+  return globalCommandRootForTarget('opencode', { homeRoot });
+}
+
+export function claudeCommandRoot(projectRoot) {
+  return commandRootFor('claude', projectRoot);
+}
+
+export function globalClaudeCommandRootFor({ homeRoot = homedir() } = {}) {
+  return globalCommandRootForTarget('claude', { homeRoot });
+}
+
+export function instructionSurfaceFor(target, projectRoot) {
+  const adapter = ADAPTERS[target];
+  if (!adapter?.instruction) return null;
+  return {
+    kind: adapter.instruction.kind,
+    file: adapter.instruction.file,
+    targetPath: path.join(projectRoot, adapter.instruction.file),
+  };
+}