showdar-skills 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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]
 
 ### Added

package/MIGRATION.md

@@ -1,3 +1,28 @@
+# 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.

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.5.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },

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),
+  };
+}

package/src/project.js

@@ -2,9 +2,19 @@ import { access, cp, mkdir, readFile, readdir, rename, rm, writeFile } from 'nod
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import path from 'node:path';
-import { globalCommandRootFor, globalSkillRootFor, NATIVE_TARGETS, opencodeCommandRoot, resolveTargets, resolveSkillRoot, skillRootFor } from './adapters.js';
-import { normalizeSkillName } from './catalog.js';
+import {
+  ADAPTERS,
+  NATIVE_TARGETS,
+  resolveTargets,
+  skillRootFor,
+  globalSkillRootFor,
+  commandRootFor,
+  globalCommandRootForTarget,
+  instructionSurfaceFor,
+} from './adapters.js';
+import { normalizeSkillName, ALL_SKILLS } from './catalog.js';
 import { assertSafeManagedPath, lstatWithoutSymlink, safeOwnedPath } from './path-safety.js';
+import { renderManagedBlock, renderShowdarCommand, renderShowdarAggregator } from './adapter-renderers.js';
 
 const PROJECT_MANIFEST = '.showdar.json';
 const START = '<!-- showdar-skills:start -->';
@@ -54,59 +64,47 @@ async function writeTextAtomic(target, value) {
   await rename(tmp, target);
 }
 
-function managedBlock(skillIds) {
-  const routes = [
-    ['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'],
-  ].filter(([, id]) => skillIds.includes(id));
-  const lines = routes.map(([intent, skill]) => `- ${intent} -> \`${skill}\``).join('\n');
-  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${lines}\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}`;
-}
-
 function stripManagedBlock(content) {
   const start = content.indexOf(START);
   if (start === -1) return content;
   const end = content.indexOf(END, start);
-  if (end === -1) throw new Error('AGENTS.md contains an incomplete Showdar managed block. Repair it manually before continuing.');
+  if (end === -1) throw new Error('Managed file contains an incomplete Showdar managed block. Repair it manually before continuing.');
   const before = content.slice(0, start).trimEnd();
   const after = content.slice(end + END.length).trimStart();
   return [before, after].filter(Boolean).join('\n\n');
 }
 
-async function writeAgentsBlock(projectRoot, skillIds) {
-  const target = path.join(projectRoot, 'AGENTS.md');
-  await assertSafeManagedPath(projectRoot, target);
-  const current = (await exists(target)) ? await readFile(target, 'utf8') : '';
+async function writeManagedBlock(filePath, skillIds) {
+  await assertSafeManagedPath(path.dirname(filePath), filePath);
+  const current = (await exists(filePath)) ? await readFile(filePath, 'utf8') : '';
   const clean = stripManagedBlock(current).trimEnd();
-  const block = managedBlock(skillIds);
-  await writeTextAtomic(target, clean ? `${clean}\n\n${block}\n` : `${block}\n`);
+  const block = renderManagedBlock(skillIds, 'block');
+  await writeTextAtomic(filePath, clean ? `${clean}\n\n${block}\n` : `${block}\n`);
 }
 
-async function removeAgentsBlock(projectRoot) {
-  const target = path.join(projectRoot, 'AGENTS.md');
-  await assertSafeManagedPath(projectRoot, target);
-  if (!(await exists(target))) return;
-  const current = await readFile(target, 'utf8');
+async function removeManagedBlock(filePath) {
+  await assertSafeManagedPath(path.dirname(filePath), filePath);
+  if (!(await exists(filePath))) return;
+  const current = await readFile(filePath, 'utf8');
   const clean = stripManagedBlock(current).trim();
-  if (clean) await writeTextAtomic(target, `${clean}\n`);
-  else await rm(target, { force: true });
+  if (clean) await writeTextAtomic(filePath, `${clean}\n`);
+  else await rm(filePath, { force: true });
+}
+
+async function writeCursorRule(filePath, skillIds) {
+  await assertSafeManagedPath(path.dirname(filePath), filePath);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const content = renderManagedBlock(skillIds, 'file');
+  await writeTextAtomic(filePath, content);
+}
+
+async function removeCursorRule(filePath) {
+  await assertSafeManagedPath(path.dirname(filePath), filePath);
+  if (!(await exists(filePath))) return;
+  const current = await readFile(filePath, 'utf8');
+  if (current.includes('Showdar skill and workflow routing')) {
+    await rm(filePath, { force: true });
+  }
 }
 
 function ownedPathSet(manifest) {
@@ -139,20 +137,49 @@ async function copyOwned({ baseRoot, source, destination, priorOwned, newFiles,
   newFiles.push({ path: relative, hash: await hashTree(destination) });
 }
 
-async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0', scope, skillRootForTarget, commandRoot, managedRoots = [], homeRoot = homedir(), globalSkillRootForTarget = null }) {
+async function generateCommandFiles({ baseRoot, skillIds, target, commandRoot, priorOwned, newFiles, managedRoots = [] }) {
+  const files = [];
+  for (const skillId of skillIds) {
+    const shortName = skillId.replace(/^showdar-/, '');
+    const destination = path.join(commandRoot, `${shortName}.md`);
+    const relative = manifestPathFor(baseRoot, destination);
+    if ((await exists(destination)) && !priorOwned.has(relative)) {
+      throw new Error(`Refusing to overwrite existing non-Showdar-managed command: ${destination}`);
+    }
+    await mkdir(path.dirname(destination), { recursive: true });
+    const content = renderShowdarCommand(skillId);
+    await writeTextAtomic(destination, content);
+    newFiles.push({ path: relative, hash: await hashTree(destination) });
+    files.push({ destination, skillId, shortName });
+  }
+  const aggregatorDest = path.join(commandRoot, 'skill.md');
+  const aggregatorRel = manifestPathFor(baseRoot, aggregatorDest);
+  if ((await exists(aggregatorDest)) && !priorOwned.has(aggregatorRel)) {
+    throw new Error(`Refusing to overwrite existing non-Showdar-managed command: ${aggregatorDest}`);
+  }
+  await mkdir(path.dirname(aggregatorDest), { recursive: true });
+  const aggregatorContent = renderShowdarAggregator(skillIds);
+  await writeTextAtomic(aggregatorDest, aggregatorContent);
+  newFiles.push({ path: aggregatorRel, hash: await hashTree(aggregatorDest) });
+  files.push({ destination: aggregatorDest, skillId: 'aggregator', shortName: 'skill' });
+  return files;
+}
+
+async function initInstallation({
+  baseRoot, manifestPath, packageRoot, profile, ai, skillIds, packageVersion = '0.2.0',
+  scope, homeRoot = homedir(),
+}) {
   await mkdir(baseRoot, { recursive: true });
   await assertSafeManagedPath(baseRoot, baseRoot);
   await assertSafeManagedPath(baseRoot, manifestPath);
-  if (agentsRoot) await assertSafeManagedPath(agentsRoot, path.join(agentsRoot, 'AGENTS.md'));
+
   const targets = resolveTargets(ai);
   const prior = await readManifest(manifestPath, baseRoot);
   const priorOwned = ownedPathSet(prior);
   const desiredPaths = new Set();
 
-  const skillRoots = uniqueRoots(targets, skillRootForTarget);
-  const globalManifest = scope === 'project' && globalSkillRootForTarget
-    ? await readManifest(globalManifestPath(homeRoot), homeRoot)
-    : null;
+  const skillRoots = uniqueRoots(targets, (t) => scope === 'project' ? skillRootFor(t, baseRoot) : globalSkillRootFor(t, { homeRoot }));
+  const globalManifest = scope === 'project' ? await readManifest(globalManifestPath(homeRoot), homeRoot) : null;
   const globalOwned = ownedPathSet(globalManifest);
   const globalSatisfaction = [];
   const installedSkillIds = new Set();
@@ -167,13 +194,13 @@ async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoo
   for (const { root, target } of skillRoots) {
     for (const skillId of skillIds) {
       const destination = path.join(root, skillId);
-      await assertSafeManagedPath(baseRoot, destination, managedRoots);
+      await assertSafeManagedPath(baseRoot, destination);
       const relative = manifestPathFor(baseRoot, destination);
       const destinationExists = await exists(destination);
-      const globalPath = globalSkillRootForTarget ? path.join(globalSkillRootForTarget(target), skillId) : null;
-      if (globalPath) await assertSafeManagedPath(homeRoot, globalPath);
-      const globalRelative = globalPath ? manifestPathFor(homeRoot, globalPath) : null;
-      const globalAvailable = Boolean(globalPath && globalOwned.has(globalRelative) && await exists(globalPath));
+      const globalPath = path.join(globalSkillRootFor(target, { homeRoot }), skillId);
+      await assertSafeManagedPath(homeRoot, globalPath);
+      const globalRelative = manifestPathFor(homeRoot, globalPath);
+      const globalAvailable = Boolean(globalOwned.has(globalRelative) && await exists(globalPath));
       if (scope === 'project' && globalAvailable && !destinationExists) {
         skippedDuplicates += 1;
         globallySatisfiedSkillIds.add(skillId);
@@ -184,24 +211,38 @@ async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoo
       }
     }
   }
-  if (targets.includes('opencode')) {
-    const root = commandRoot();
-    for (const name of commandNames) {
-      const destination = path.join(root, `${name}.md`);
-      await assertSafeManagedPath(baseRoot, destination, managedRoots);
-      desiredPaths.add(manifestPathFor(baseRoot, destination));
+
+  const managedRoots = scope === 'global'
+    ? [...new Set([
+        ...NATIVE_TARGETS.map((t) => globalSkillRootFor(t, { homeRoot })),
+        ...NATIVE_TARGETS.filter((t) => globalCommandRootForTarget(t, { homeRoot })).map((t) => globalCommandRootForTarget(t, { homeRoot })),
+      ])]
+    : [];
+  const commandHarnesses = [];
+  for (const target of targets) {
+    const adapter = ADAPTERS[target];
+    if (adapter?.commands?.destination) {
+      const root = scope === 'project' ? commandRootFor(target, baseRoot) : globalCommandRootForTarget(target, { homeRoot });
+      if (root) {
+        for (const skillId of skillIds) {
+          const shortName = skillId.replace(/^showdar-/, '');
+          desiredPaths.add(manifestPathFor(baseRoot, path.join(root, `${shortName}.md`)));
+        }
+        desiredPaths.add(manifestPathFor(baseRoot, path.join(root, 'skill.md')));
+        commandHarnesses.push({ target, root });
+      }
     }
   }
 
   const staleTargets = [];
   for (const entry of prior?.files ?? []) {
-    const target = safeOwnedPath(baseRoot, entry.path, managedRoots);
-    if (target && !desiredPaths.has(entry.path)) {
-      await assertSafeManagedPath(baseRoot, target, managedRoots);
-      staleTargets.push(target);
+    const targetPath = safeOwnedPath(baseRoot, entry.path, managedRoots);
+    if (targetPath && !desiredPaths.has(entry.path)) {
+      await assertSafeManagedPath(baseRoot, targetPath, managedRoots);
+      staleTargets.push(targetPath);
     }
   }
-  for (const target of staleTargets) await rm(target, { recursive: true, force: true });
+  for (const stale of staleTargets) await rm(stale, { recursive: true, force: true });
 
   const files = [];
   for (const { destination, skillId } of skillDestinations) {
@@ -210,15 +251,29 @@ async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoo
     installedSkillIds.add(skillId);
   }
 
-  if (targets.includes('opencode')) {
-    const root = commandRoot();
-    for (const name of commandNames) {
-      const source = path.join(packageRoot, 'commands', 'opencode', 'showdar', `${name}.md`);
-      if (!(await exists(source))) throw new Error(`OpenCode command asset not found: ${name}`);
-      await copyOwned({ baseRoot, source, destination: path.join(root, `${name}.md`), priorOwned, newFiles: files, managedRoots });
-    }
+  const commandsGenerated = [];
+  for (const { target, root } of commandHarnesses) {
+    const generated = await generateCommandFiles({
+      baseRoot,
+      skillIds,
+      target,
+      commandRoot: root,
+      priorOwned,
+      newFiles: files,
+      managedRoots,
+    });
+    commandsGenerated.push(...generated.map((g) => ({ ...g, target })));
   }
 
+  // --ai all is a compatibility aggregate: write ONLY the canonical AGENTS.md
+  // managed block. Explicit --ai claude / --ai cursor remain native-optimal.
+  const instructionTarget = scope === 'project'
+    ? (ai === 'all' ? 'universal' : targets[0])
+    : null;
+  const instructionFile = instructionTarget
+    ? instructionSurfaceFor(instructionTarget, baseRoot)
+    : null;
+
   const manifest = {
     version: 2,
     scope,
@@ -228,16 +283,37 @@ async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoo
     targets,
     skills: [...skillIds],
     satisfiedByGlobal: globalSatisfaction,
-    commands: targets.includes('opencode') ? [...commandNames] : [],
+    commands: commandsGenerated.map((c) => ({ target: c.target, name: c.shortName, path: manifestPathFor(baseRoot, c.destination) })),
     files,
+    instructions: instructionFile ? { file: instructionFile.file, kind: instructionFile.kind } : null,
+    commandHarness: commandHarnesses.map((c) => c.target),
   };
+
   await assertSafeManagedPath(baseRoot, manifestPath);
   await mkdir(path.dirname(manifestPath), { recursive: true });
   await writeJsonAtomic(manifestPath, manifest);
-  if (agentsRoot) await writeAgentsBlock(agentsRoot, skillIds);
+
+  if (scope === 'project' && prior?.instructions?.file && instructionFile?.file !== prior.instructions.file) {
+    const staleInstruction = path.join(baseRoot, prior.instructions.file);
+    if (prior.instructions.kind === 'block') {
+      await removeManagedBlock(staleInstruction);
+    } else if (prior.instructions.kind === 'file') {
+      await removeCursorRule(staleInstruction);
+    }
+  }
+
+  if (scope === 'project' && instructionFile) {
+    if (instructionFile.kind === 'block') {
+      await writeManagedBlock(instructionFile.targetPath, skillIds);
+    } else if (instructionFile.kind === 'file') {
+      await writeCursorRule(instructionFile.targetPath, skillIds);
+    }
+  }
+
   const result = await inspectInstallation({
-    baseRoot, manifestPath, agentsRoot, scope, homeRoot,
-    globalSkillRootForTarget,
+    baseRoot, manifestPath, scope, homeRoot, targets: manifest.targets,
+    instructionFile,
+    commandHarnesses,
   });
   return {
     ...result,
@@ -248,45 +324,37 @@ async function initInstallation({ baseRoot, manifestPath, agentsRoot, packageRoo
   };
 }
 
-export async function initProject({ projectRoot, homeRoot = homedir(), packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0' }) {
+export async function initProject({ projectRoot, homeRoot = homedir(), packageRoot, profile, ai, skillIds, packageVersion = '0.2.0' }) {
   return initInstallation({
     baseRoot: projectRoot,
     manifestPath: path.join(projectRoot, PROJECT_MANIFEST),
-    agentsRoot: projectRoot,
     packageRoot,
     profile,
     ai,
     skillIds,
-    commandNames,
     packageVersion,
     scope: 'project',
     homeRoot,
-    skillRootForTarget: (target) => skillRootFor(target, projectRoot),
-    globalSkillRootForTarget: (target) => globalSkillRootFor(target, { homeRoot }),
-    commandRoot: () => opencodeCommandRoot(projectRoot),
   });
 }
 
-export async function initGlobal({ homeRoot = homedir(), packageRoot, profile, ai, skillIds, commandNames = [], packageVersion = '0.2.0' }) {
-  const managedRoots = [...new Set(NATIVE_TARGETS.map((target) => globalSkillRootFor(target, { homeRoot }))), globalCommandRootFor({ homeRoot })];
+export async function initGlobal({ homeRoot = homedir(), packageRoot, profile, ai, skillIds, packageVersion = '0.2.0' }) {
   return initInstallation({
     baseRoot: homeRoot,
     manifestPath: globalManifestPath(homeRoot),
-    agentsRoot: null,
     packageRoot,
     profile,
     ai,
     skillIds,
-    commandNames,
     packageVersion,
     scope: 'global',
-    skillRootForTarget: (target) => globalSkillRootFor(target, { homeRoot }),
-    commandRoot: () => globalCommandRootFor({ homeRoot }),
-    managedRoots,
+    homeRoot,
   });
 }
 
-async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope, managedRoots = [], homeRoot = homedir(), globalSkillRootForTarget = null }) {
+async function inspectInstallation({
+  baseRoot, manifestPath, scope, homeRoot, targets, instructionFile, commandHarnesses,
+}) {
   let manifest;
   try { manifest = await readManifest(manifestPath, baseRoot); }
   catch (error) { return { installed: true, healthy: false, scope, profile: null, ai: null, targets: [], skills: 0, requestedSkills: 0, installedSkills: 0, satisfiedByGlobal: 0, commands: 0, issues: [error.message], warnings: [] }; }
@@ -295,20 +363,18 @@ async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope,
   const issues = [];
   const warnings = [];
   const projectOwned = ownedPathSet(manifest);
-  const targets = manifest.targets?.length ? manifest.targets : manifest.ai ? resolveTargets(manifest.ai) : [];
+  const effectiveTargets = manifest.targets?.length ? manifest.targets : manifest.ai ? resolveTargets(manifest.ai) : [];
   const skillIds = manifest.skills ?? [];
-  const globalManifest = scope === 'project' && globalSkillRootForTarget
-    ? await readManifest(globalManifestPath(homeRoot), homeRoot)
-    : null;
+  const globalManifest = scope === 'project' ? await readManifest(globalManifestPath(homeRoot), homeRoot) : null;
   const globalOwned = ownedPathSet(globalManifest);
   const globalSatisfiedPaths = new Set();
   const installedSkillIds = new Set();
   const globallySatisfiedSkillIds = new Set();
   const recordedGlobalSkills = new Set((manifest.satisfiedByGlobal ?? []).map((entry) => entry?.skill).filter(Boolean));
 
-  if (scope === 'project' && globalSkillRootForTarget) {
-    const projectRoots = uniqueRoots(targets, (target) => skillRootFor(target, baseRoot));
-    const globalRoots = uniqueRoots(targets, globalSkillRootForTarget);
+  if (scope === 'project') {
+    const projectRoots = uniqueRoots(effectiveTargets, (target) => skillRootFor(target, baseRoot));
+    const globalRoots = uniqueRoots(effectiveTargets, (target) => globalSkillRootFor(target, { homeRoot }));
     const globalSkills = new Set();
     for (const { root } of globalRoots) {
       const prefix = `${manifestPathFor(homeRoot, root)}/`;
@@ -332,7 +398,7 @@ async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope,
         const projectRelative = manifestPathFor(baseRoot, projectPath);
         const projectExists = await exists(projectPath);
         const projectIsOwned = projectOwned.has(projectRelative);
-        const globalPath = path.join(globalSkillRootForTarget(target), skillId);
+        const globalPath = path.join(globalSkillRootFor(target, { homeRoot }), skillId);
         const globalRelative = manifestPathFor(homeRoot, globalPath);
         await assertSafeManagedPath(baseRoot, projectPath);
         await assertSafeManagedPath(homeRoot, globalPath);
@@ -359,9 +425,9 @@ async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope,
   }
 
   for (const entry of manifest.files ?? []) {
-    const target = safeOwnedPath(baseRoot, entry.path, managedRoots);
+    const target = safeOwnedPath(baseRoot, entry.path);
     if (!target) { issues.push(`Invalid managed path: ${entry.path}`); continue; }
-    await assertSafeManagedPath(baseRoot, target, managedRoots);
+    await assertSafeManagedPath(baseRoot, target);
     if (!(await exists(target))) {
       if (!globalSatisfiedPaths.has(entry.path)) issues.push(`Missing managed path: ${entry.path}`);
       continue;
@@ -370,13 +436,58 @@ async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope,
     if (actual !== entry.hash) issues.push(`Managed path drift detected: ${entry.path}`);
   }
 
-  if (agentsRoot) {
-    const agentsFile = path.join(agentsRoot, 'AGENTS.md');
-    await assertSafeManagedPath(agentsRoot, agentsFile);
-    if (!(await exists(agentsFile))) issues.push('Missing AGENTS.md routing block');
-    else {
-      const text = await readFile(agentsFile, 'utf8');
-      if (!text.includes(START) || !text.includes(END)) issues.push('Missing Showdar AGENTS.md managed block');
+  if (scope === 'project' && instructionFile) {
+    const filePath = instructionFile.targetPath ?? path.join(baseRoot, instructionFile.file);
+    if (instructionFile.kind === 'block') {
+      if (!(await exists(filePath))) {
+        issues.push(`Missing managed instruction block: ${instructionFile.file}`);
+      } else {
+        const text = await readFile(filePath, 'utf8');
+        if (!text.includes(START) || !text.includes(END)) {
+          issues.push(`Missing Showdar managed block in ${instructionFile.file}`);
+        }
+      }
+    } else if (instructionFile.kind === 'file') {
+      if (!(await exists(filePath))) {
+        issues.push(`Missing managed instruction file: ${instructionFile.file}`);
+      } else {
+        const text = await readFile(filePath, 'utf8');
+        if (!text.includes('Showdar skill and workflow routing')) {
+          issues.push(`Missing Showdar instruction content in ${instructionFile.file}`);
+        }
+      }
+    }
+  }
+
+  if (manifest.commandHarness?.length) {
+    for (const harness of manifest.commandHarness) {
+      const commandRoot = scope === 'project' ? commandRootFor(harness, baseRoot) : globalCommandRootForTarget(harness, { homeRoot });
+      if (!commandRoot) continue;
+      for (const cmd of manifest.commands ?? []) {
+        if (cmd.target !== harness) continue;
+        const dest = path.join(commandRoot, `${cmd.name}.md`);
+        const rel = manifestPathFor(baseRoot, dest);
+        const owned = projectOwned.has(rel);
+        if (!(await exists(dest))) {
+          if (!owned) continue;
+          issues.push(`Missing generated command: ${dest}`);
+        } else if (owned) {
+          const actual = await hashTree(dest);
+          const entry = manifest.files?.find((f) => f.path === rel);
+          if (entry && actual !== entry.hash) {
+            issues.push(`Generated command drift detected: ${dest}`);
+          }
+        }
+      }
+      const aggregatorDest = path.join(commandRoot, 'skill.md');
+      const aggregatorRel = manifestPathFor(baseRoot, aggregatorDest);
+      if (await exists(aggregatorDest)) {
+        const actual = await hashTree(aggregatorDest);
+        const entry = manifest.files?.find((f) => f.path === aggregatorRel);
+        if (entry && actual !== entry.hash) {
+          issues.push(`Generated aggregator drift detected: ${aggregatorDest}`);
+        }
+      }
     }
   }
 
@@ -389,19 +500,26 @@ async function inspectInstallation({ baseRoot, manifestPath, agentsRoot, scope,
     targets: manifest.targets ?? [],
     skills: skillIds.length,
     requestedSkills: skillIds.length,
-    installedSkills: scope === 'project' && globalSkillRootForTarget ? installedSkillIds.size : skillIds.length,
-    satisfiedByGlobal: scope === 'project' && globalSkillRootForTarget ? globallySatisfiedSkillIds.size : 0,
+    installedSkills: scope === 'project' ? installedSkillIds.size : skillIds.length,
+    satisfiedByGlobal: scope === 'project' ? globallySatisfiedSkillIds.size : 0,
     commands: (manifest.commands ?? []).length,
     issues,
     warnings,
   };
 }
 
-async function removeInstallation({ baseRoot, manifestPath, agentsRoot, managedRoots = [] }) {
+async function removeInstallation({ baseRoot, manifestPath, scope, homeRoot = homedir() }) {
   await assertSafeManagedPath(baseRoot, manifestPath);
   let manifest;
   try { manifest = await readManifest(manifestPath, baseRoot); }
   catch { manifest = null; }
+  const managedRoots = scope === 'global'
+    ? [...new Set([
+        ...NATIVE_TARGETS.map((t) => globalSkillRootFor(t, { homeRoot })),
+        ...NATIVE_TARGETS.filter((t) => globalCommandRootForTarget(t, { homeRoot })).map((t) => globalCommandRootForTarget(t, { homeRoot })),
+      ])]
+    : [];
+
   for (const entry of manifest?.files ?? []) {
     const target = safeOwnedPath(baseRoot, entry.path, managedRoots);
     if (target) {
@@ -409,25 +527,49 @@ async function removeInstallation({ baseRoot, manifestPath, agentsRoot, managedR
       await rm(target, { recursive: true, force: true });
     }
   }
+
+  if (scope === 'project' && manifest?.instructions) {
+    const filePath = path.join(baseRoot, manifest.instructions.file);
+    if (manifest.instructions.kind === 'block') {
+      await removeManagedBlock(filePath);
+    } else if (manifest.instructions.kind === 'file') {
+      await removeCursorRule(filePath);
+    }
+  }
+
   await assertSafeManagedPath(baseRoot, manifestPath);
   await rm(manifestPath, { force: true });
-  if (agentsRoot) await removeAgentsBlock(agentsRoot);
 }
 
 export async function inspectProject(projectRoot, { homeRoot = homedir() } = {}) {
+  const manifest = await readManifest(path.join(projectRoot, PROJECT_MANIFEST), projectRoot);
+  const targets = manifest?.targets ?? (manifest?.ai ? resolveTargets(manifest.ai) : []);
+  const instructionFile = manifest?.instructions ? { ...manifest.instructions, targetPath: path.join(projectRoot, manifest.instructions.file) } : null;
+  const commandHarnesses = manifest?.commandHarness ?? [];
   return inspectInstallation({
     baseRoot: projectRoot,
     manifestPath: path.join(projectRoot, PROJECT_MANIFEST),
-    agentsRoot: projectRoot,
     scope: 'project',
     homeRoot,
-    globalSkillRootForTarget: (target) => globalSkillRootFor(target, { homeRoot }),
+    targets,
+    instructionFile,
+    commandHarnesses,
   });
 }
 
 export async function inspectGlobal({ homeRoot = homedir() } = {}) {
-  const managedRoots = [...new Set(NATIVE_TARGETS.map((target) => globalSkillRootFor(target, { homeRoot }))), globalCommandRootFor({ homeRoot })];
-  return inspectInstallation({ baseRoot: homeRoot, manifestPath: globalManifestPath(homeRoot), agentsRoot: null, scope: 'global', managedRoots });
+  const manifest = await readManifest(globalManifestPath(homeRoot), homeRoot);
+  const targets = manifest?.targets ?? (manifest?.ai ? resolveTargets(manifest.ai) : []);
+  const commandHarnesses = manifest?.commandHarness ?? [];
+  return inspectInstallation({
+    baseRoot: homeRoot,
+    manifestPath: globalManifestPath(homeRoot),
+    scope: 'global',
+    homeRoot,
+    targets,
+    instructionFile: null,
+    commandHarnesses,
+  });
 }
 
 export async function addSkill({ cwd, skill, ai = null, scope = null, home = homedir(), packageRoot, packageVersion = '0.2.0' }) {
@@ -443,10 +585,19 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
   if (!NATIVE_TARGETS.includes(effectiveAi)) throw new Error(`Unknown AI target "${effectiveAi}".`);
   if (effectiveScope !== 'project' && effectiveScope !== 'global') throw new Error(`Unknown scope "${effectiveScope}".`);
 
-  const root = resolveSkillRoot({ ai: effectiveAi, scope: effectiveScope, cwd, home });
+  if (existingManifest?.skills?.includes(skillId)) {
+    return { skill: skillId, root: '', destination: '', added: false, scope: effectiveScope, ai: effectiveAi, profile: existingManifest.profile };
+  }
+
+  const root = effectiveScope === 'global'
+    ? globalSkillRootFor(effectiveAi, { homeRoot: home })
+    : skillRootFor(effectiveAi, cwd);
   const destination = path.join(root, skillId);
   const managedRoots = effectiveScope === 'global'
-    ? [...new Set(NATIVE_TARGETS.map((t) => globalSkillRootFor(t, { homeRoot: home }))), globalCommandRootFor({ homeRoot: home })]
+    ? [...new Set([
+        ...NATIVE_TARGETS.map((t) => globalSkillRootFor(t, { homeRoot: home })),
+        ...NATIVE_TARGETS.filter((t) => globalCommandRootForTarget(t, { homeRoot: home })).map((t) => globalCommandRootForTarget(t, { homeRoot: home })),
+      ])]
     : [];
   const manifestPath = effectiveScope === 'global' ? globalManifestPath(home) : path.join(cwd, PROJECT_MANIFEST);
 
@@ -462,34 +613,91 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
   const files = [];
   await copyOwned({ baseRoot, source, destination, priorOwned, newFiles: files, managedRoots });
 
+  const targets = [effectiveAi];
+  const commandHarnesses = [];
+  for (const target of targets) {
+    const adapter = ADAPTERS[target];
+    if (adapter?.commands?.destination) {
+      if (effectiveScope === 'project') {
+        commandHarnesses.push({ target, root: commandRootFor(target, cwd) });
+      } else {
+        const globalRoot = globalCommandRootForTarget(target, { homeRoot: home });
+        if (globalRoot) commandHarnesses.push({ target, root: globalRoot });
+      }
+    }
+  }
+
+  const newCommands = [];
+  for (const { target, root } of commandHarnesses) {
+    const shortName = skillId.replace(/^showdar-/, '');
+    const dest = path.join(root, `${shortName}.md`);
+    const rel = manifestPathFor(baseRoot, dest);
+    if ((await exists(dest)) && !priorOwned.has(rel)) {
+      throw new Error(`Refusing to overwrite existing non-Showdar-managed command: ${dest}`);
+    }
+    await mkdir(path.dirname(dest), { recursive: true });
+    const content = renderShowdarCommand(skillId);
+    await writeTextAtomic(dest, content);
+    files.push({ path: rel, hash: await hashTree(dest) });
+    newCommands.push({ target, name: shortName, path: rel });
+  }
+
+  if (commandHarnesses.length > 0) {
+    for (const { target, root } of commandHarnesses) {
+      const aggregatorDest = path.join(root, 'skill.md');
+      const aggregatorRel = manifestPathFor(baseRoot, aggregatorDest);
+      const addAllSkillIds = [...new Set([...(existingManifest?.skills ?? []), skillId])];
+      const aggregatorContent = renderShowdarAggregator(addAllSkillIds);
+      if ((await exists(aggregatorDest)) && !priorOwned.has(aggregatorRel)) {
+        throw new Error(`Refusing to overwrite existing non-Showdar-managed command: ${aggregatorDest}`);
+      }
+      await mkdir(path.dirname(aggregatorDest), { recursive: true });
+      await writeTextAtomic(aggregatorDest, aggregatorContent);
+      files.push({ path: aggregatorRel, hash: await hashTree(aggregatorDest) });
+      newCommands.push({ target, name: 'skill', path: aggregatorRel });
+    }
+  }
+
   const merged = new Map((existingManifest?.files ?? []).map((e) => [e.path, e]));
   for (const f of files) merged.set(f.path, f);
+
+  const allSkillIds = [...new Set([...(existingManifest?.skills ?? []), skillId])];
+  const instructionFile = existingManifest?.instructions ?? (effectiveScope === 'project' ? instructionSurfaceFor(effectiveAi, cwd) : null);
+  const commandHarness = [...new Set([...(existingManifest?.commandHarness ?? []), ...commandHarnesses.map((c) => c.target)])];
+
   const manifest = {
     version: existingManifest?.version ?? 2,
     scope: effectiveScope,
     packageVersion,
     profile: existingManifest?.profile ?? null,
-    ai: ai ?? existingManifest?.ai ?? 'universal',
-    targets: [effectiveAi],
-    skills: [...new Set([...(existingManifest?.skills ?? []), skillId])],
+    ai: effectiveAi,
+    targets,
+    skills: allSkillIds,
     satisfiedByGlobal: existingManifest?.satisfiedByGlobal ?? [],
-    commands: existingManifest?.commands ?? [],
+    commands: [...(existingManifest?.commands ?? []), ...newCommands],
     files: [...merged.values()],
+    instructions: instructionFile ? { file: instructionFile.file, kind: instructionFile.kind } : null,
+    commandHarness,
   };
+
   await mkdir(path.dirname(manifestPath), { recursive: true });
   await writeJsonAtomic(manifestPath, manifest);
-  if (effectiveScope === 'project') {
-    const allSkillIds = manifest.skills;
-    await writeAgentsBlock(cwd, allSkillIds);
+
+  if (effectiveScope === 'project' && instructionFile) {
+    if (instructionFile.kind === 'block') {
+      await writeManagedBlock(path.join(cwd, instructionFile.file), allSkillIds);
+    } else if (instructionFile.kind === 'file') {
+      await writeCursorRule(path.join(cwd, instructionFile.file), allSkillIds);
+    }
   }
+
   return { skill: skillId, root, destination, added: !alreadyTracked || !existed, scope: effectiveScope, ai: effectiveAi, profile: manifest.profile };
 }
 
 export async function removeProject(projectRoot) {
-  await removeInstallation({ baseRoot: projectRoot, manifestPath: path.join(projectRoot, PROJECT_MANIFEST), agentsRoot: projectRoot });
+  await removeInstallation({ baseRoot: projectRoot, manifestPath: path.join(projectRoot, PROJECT_MANIFEST), scope: 'project' });
 }
 
 export async function removeGlobal({ homeRoot = homedir() } = {}) {
-  const managedRoots = [...new Set(NATIVE_TARGETS.map((target) => globalSkillRootFor(target, { homeRoot }))), globalCommandRootFor({ homeRoot })];
-  await removeInstallation({ baseRoot: homeRoot, manifestPath: globalManifestPath(homeRoot), agentsRoot: null, managedRoots });
-}
+  await removeInstallation({ baseRoot: homeRoot, manifestPath: globalManifestPath(homeRoot), scope: 'global', homeRoot });
+}

package/src/validate.js

@@ -306,26 +306,66 @@ export async function validateRepository(packageRoot) {
     for (const id of text.match(/showdar-[a-z-]+/g) ?? []) if (!known.has(id)) errors.push(`${relative} references unknown skill ${id}`);
   }
 
-  const commandMap = {
-    understand: 'showdar-understand', plan: 'showdar-plan', design: 'showdar-design', build: 'showdar-build',
-    debug: 'showdar-debug', test: 'showdar-test', review: 'showdar-review', upgrade: 'showdar-upgrade',
-    ship: 'showdar-ship', recover: 'showdar-recover', git: 'showdar-git',
-    requirements: 'showdar-requirements', quality: 'showdar-quality', security: 'showdar-security', ops: 'showdar-ops',
-  };
-  for (const [command, skill] of Object.entries(commandMap)) {
-    const relative = `commands/opencode/showdar/${command}.md`;
-    const file = path.join(packageRoot, relative);
-    if (!(await exists(file))) { errors.push(`missing OpenCode command: ${relative}`); continue; }
-    const text = await readFile(file, 'utf8');
-    if (!text.includes('$ARGUMENTS')) errors.push(`${relative} does not accept $ARGUMENTS`);
-    if (!text.includes(skill)) errors.push(`${relative} does not route to ${skill}`);
+  const { ADAPTERS } = await import('./adapters.js');
+  const {
+    renderShowdarInstruction,
+    renderShowdarCommand,
+    renderShowdarAggregator,
+    renderCursorRuleBody,
+    renderManagedBlock,
+  } = await import('./adapter-renderers.js');
+
+  for (const [target, adapter] of Object.entries(ADAPTERS)) {
+    if (!['codex', 'opencode', 'cursor', 'claude', 'universal'].includes(target)) {
+      errors.push(`adapter references unknown AI target: ${target}`);
+    }
+    if (adapter.commands && !Array.isArray(adapter.commands.destination)) {
+      errors.push(`adapter ${target} has invalid command destination`);
+    }
+  }
+
+  const sampleIds = ['showdar-debug', 'showdar-test'];
+  const instructionA = renderShowdarInstruction(sampleIds);
+  const instructionB = renderShowdarInstruction([...sampleIds].reverse());
+  if (instructionA !== instructionB) errors.push('canonical instruction renderer is not deterministic');
+  if (renderShowdarCommand('showdar-debug') !== renderShowdarCommand('showdar-debug')) {
+    errors.push('canonical command renderer is not deterministic');
+  }
+  const aggregator = renderShowdarAggregator(sampleIds);
+  if (!aggregator.includes('$ARGUMENTS')) errors.push('generated aggregator does not accept $ARGUMENTS');
+  for (const id of sampleIds) if (!aggregator.includes(id)) errors.push(`generated aggregator does not list ${id}`);
+  const commandBody = renderShowdarCommand('showdar-debug');
+  if (!commandBody.includes('$ARGUMENTS')) errors.push('generated command does not accept $ARGUMENTS');
+  if (!commandBody.includes('showdar-debug')) errors.push('generated command does not route to showdar-debug');
+
+  const agentsBlock = renderManagedBlock(sampleIds, 'block');
+  const claudeBlock = renderManagedBlock(sampleIds, 'block');
+  const cursorRule = renderCursorRuleBody(sampleIds);
+  if (!agentsBlock.includes('showdar-skills:start') || !agentsBlock.includes('showdar-skills:end')) {
+    errors.push('AGENTS managed block is missing markers');
+  }
+  if (!claudeBlock.includes('showdar-skills:start') || !claudeBlock.includes('showdar-skills:end')) {
+    errors.push('CLAUDE managed block is missing markers');
   }
-  const skillCommand = path.join(packageRoot, 'commands', 'opencode', 'showdar', 'skill.md');
-  if (!(await exists(skillCommand))) errors.push('missing OpenCode command: commands/opencode/showdar/skill.md');
-  else {
-    const text = await readFile(skillCommand, 'utf8');
-    if (!text.includes('$ARGUMENTS')) errors.push('commands/opencode/showdar/skill.md does not accept $ARGUMENTS');
-    for (const id of known) if (!text.includes(id)) errors.push(`commands/opencode/showdar/skill.md does not list ${id}`);
+  if (!cursorRule.includes('alwaysApply: false')) errors.push('Cursor rule must use Apply Intelligently metadata');
+  if (cursorRule.includes('alwaysApply: true')) errors.push('Cursor rule must not use alwaysApply:true');
+
+  const commandDir = path.join(packageRoot, 'commands', 'opencode', 'showdar');
+  if (await exists(commandDir)) {
+    for (const entry of await readdir(commandDir, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        const text = await readFile(path.join(commandDir, entry.name), 'utf8');
+        for (const id of text.match(/showdar-[a-z-]+/g) ?? []) {
+          if (!known.has(id)) errors.push(`commands/opencode/showdar/${entry.name} references unknown skill ${id}`);
+        }
+      }
+    }
+  }
+
+  for (const [profile, ids] of Object.entries(PROFILES)) {
+    for (const id of ids) {
+      if (!primitives.has(id)) errors.push(`profile ${profile} must reference only primitive skills (found ${id})`);
+    }
   }
 
   return { ok: errors.length === 0, errors, warnings };