showdar-skills 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.12.0]
+
+### Added
+
+- Canonical `showdar route --stdin|--prompt [--json]` runtime bridge projecting lifecycle primary, advisors, the seven public Intent keys, advisory domain matches, and installed/missing skill availability.
+- Specialized domain discovery overlay using deterministic Unicode phrase matching over `router/skill-map.yaml` inline trigger arrays; insurance terminology, underwriting/rating flows, and insurer API/UI review map to `showdar-insurance-domain`, `showdar-insurance-workflows`, and `showdar-insurance-review` without granting authority.
+- `showdar git-start --type --name [--base] [--dry-run] [--json]` for deterministic safe local task-branch preparation without inferred staging, commit, merge, or push.
+- Task branch isolation guidance: branch-before-edit on integration/default branches, repository-policy priority, one branch per coherent task, and conservative dirty-worktree blocking.
+
+### Changed
+
+- Managed harness instructions and commands invoke the canonical runtime router with native/static fallback when the CLI is unavailable.
+- Init/add guidance reflects the complete installed set; add refreshes existing commands and instructions even when the skill is already installed.
+- Showdar Git documents one branch per coherent task, repository-policy priority, and explicit completion/integration authority.
+- Task completion defaults to verify and report; merge and push each require their own explicit authority.
+
+### Safety / Compatibility
+
+- Domain discovery does not grant authority and never replaces the lifecycle primary or rewrites Intent/mutation.
+- Phase 6G authority, state, evidence, trace, and manifest contracts unchanged; no engine vendoring into projects.
+- No implicit branch commit/merge/push; no automatic stash, reset, restore, or clean.
+- Existing v0.11 projects remain compatible; no migration required.
+
 ## [0.11.0]
 
 ### Added

package/README.md

@@ -40,6 +40,88 @@ Claude Code as supported installation targets. Choose `backend`, `qa`, or
 `product` when that gives discovery a more precise context; use `full` when
 you want all capabilities available.
 
+## Runtime routing and task branches
+
+```bash
+printf '%s\n' 'Implement the approved underwriting form and add tests' | showdar route --stdin --json
+showdar route --prompt "Explain insurance terminology"
+showdar git-start --dry-run --type feature --name "IDP-123 Add pricing form"
+showdar git-start --type feature --name "IDP-123 Add pricing form"
+```
+
+Prefer `--stdin` for arbitrary or multiline prompts. Supply stdin as literal data;
+never interpolate request text into a shell command. Both commands support `--json`
+with a schemaVersion 1 envelope (`command`, `ok`, `data`, `warnings`, `errors`).
+
+`route` is read-only. It consumes the existing Phase 6G authority resolver and thin
+route, projecting exactly the seven public Intent keys plus lifecycle primary and
+advisors. It never exposes internal capabilities, frames or authority diagnostics.
+It neither authorizes work nor creates a branch. It preserves canonical advisor
+semantics: a security-review phrase is not guaranteed to become a security advisor.
+
+Domain discovery is a separate advisory overlay using the canonical
+`router/skill-map.yaml` inline trigger arrays and grouped domain catalog metadata.
+It uses deterministic Unicode phrase matching, not lifecycle scoring. Insurance
+terminology can recommend `showdar-insurance-domain`, underwriting/rating business
+flows `showdar-insurance-workflows`, and insurer API/UI terminology review
+`showdar-insurance-review`. These skills do not replace lifecycle primaryCapability,
+rewrite Intent/mutation, or grant authority. The existing ASCII/token ranking
+helper is unsuitable for Vietnamese phrase discovery. No duplicate trigger table
+or second authority engine is introduced.
+
+When `.showdar.json` exists, availability checks managed native skill files and
+recorded, still-present globally satisfied skills. Missing lifecycle primary,
+advisors and domain matches are reported separately with `showdar add <name>`
+suggestions; another installed skill never substitutes for the canonical route.
+Without a project manifest, `managed` is false and installed/missing fields are
+null (unknown), not fabricated. Invalid manifests fail explicitly. Explicit named
+installed skills may load directly; this adds no mutation authority.
+
+Managed project guidance invokes `showdar route --stdin --json` for automatic
+selection, then loads the installed lifecycle skill, domain overlays and advisors.
+The runtime bridge requires the `showdar` CLI in the harness environment. If it is
+unavailable, native skill descriptions/static discovery are the fallback. No npm
+install, npx fetch, package dependency mutation or remote download happens.
+Projects receive only existing skills/commands/instructions/manifest; no wholesale
+`src/`, `engine/` or `router/` copy. Init and add regenerate complete installed-set
+guidance, including re-adding an existing skill. Global installs keep native discovery
+and do not write project AGENTS.md or CLAUDE.md.
+
+The four workflows remain native discoverable/installable skills; `route` does not
+introduce workflow selection. Profiles remain primitive-only: `full` contains all
+18 primitives, and the insurance profile remains unchanged.
+
+Before the first local-write task source edit on develop/development/dev/main/master
+or the repository default/integration branch, prepare a task branch. Priority is
+repository instructions/documented convention, explicit current user instruction,
+clearly detected convention, then Showdar defaults. Explicit trunk/direct-work policy
+wins. One coherent task uses one branch across plan/build/test/review. Completion
+means verify and report; commit, merge and push need their own authority.
+
+`git-start` prepares local branch state only. Types: feature (new capability), fix
+(defect), refactor (internal structure), test, docs, chore (tooling/config), release,
+hotfix (explicit urgent production repair). Slugs are lowercase, hyphenated, ticket
+preserving and bounded; task text is passed as data and never executed.
+
+Base resolution uses explicit `--base`, repository-local `showdar.gitBase`, established
+local develop/development/dev, then local default/main/master. The helper does not
+parse prose instructions or create develop. Read policy first and supply its base
+when convention differs. Local Git config `showdar.gitBranchPrefix` supports custom
+prefixes; `showdar.gitDirectWork=true` records an explicit direct-work convention.
+Hotfix requires a convention via `--base` or `showdar.gitBase`.
+
+Dry-run validates Git state/type/slug/base/collision and changes no refs. Execution
+revalidates, then creates/switches only a task branch. Already on the matching branch
+is a no-op; another task branch is blocked. An existing target is reused automatically
+only when its tip equals both current HEAD and base; divergent/ambiguous targets stop
+without overwriting history. Detached HEAD and active Git operations stop.
+
+Dirty worktrees are blocked before any switch: the helper cannot prove ownership.
+Confirmed current-task-only changes may use equivalent repository-specific branch
+preparation after explicit ownership inspection. No automatic stash/reset/restore/clean,
+staging, commit, merge or push occurs. Branch preparation itself does not authorize
+source edits.
+
 ## Why Showdar?
 
 - **18 focused primitive skills** plus 4 adaptive workflow skills (22 installable), including an opt-in insurance domain profile.

package/bin/showdar.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { startTaskBranch, formatGitStart } from '../src/git-start.js';
+import { routeRequest, formatRoute } from '../src/runtime-route.js';
 import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
@@ -33,6 +36,14 @@ function scopeAfter(args) {
 
 function printHelp(version, command = null) {
   const scopeUsage = '[--scope <project|global>]';
+  if (command === 'route') {
+    console.log('Usage: showdar route (--stdin | --prompt <text>) [--json]');
+    return;
+  }
+  if (command === 'git-start') {
+    console.log('Usage: showdar git-start --type <type> --name <task> [--base <branch>] [--dry-run] [--json]');
+    return;
+  }
   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, 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;
@@ -45,7 +56,7 @@ function printHelp(version, command = null) {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n\nExamples:\n  showdar add debug\n  showdar add showdar-security\n  showdar add test --ai cursor\n  showdar add review --scope global --ai claude\n\nDefault scope: project. Default AI target: universal, or the configured .showdar.json value when present.`);
     return;
   }
-  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\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>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar route (--stdin | --prompt <text>) [--json]\n  showdar git-start --type <type> --name <task> [--base <branch>] [--dry-run] [--json]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
 }
 
 async function main() {
@@ -59,10 +70,33 @@ async function main() {
     console.log(version);
     return;
   }
-  if (args.includes('--help') || args.includes('-h')) return printHelp(version, command);
+  if (!['route', 'git-start'].includes(command) && (args.includes('--help') || args.includes('-h'))) return printHelp(version, command);
 
   const scope = ['init', 'status', 'doctor', 'remove', 'add'].includes(command) ? scopeAfter(args) : null;
 
+  if (command === 'git-start') {
+    const { values } = parseArgs({ args: args.slice(1), options: { type: { type: 'string' }, name: { type: 'string' }, base: { type: 'string' }, 'dry-run': { type: 'boolean' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
+    if (values.help) return printHelp(version, command);
+    const data = startTaskBranch({ cwd: projectRoot, type: values.type, name: values.name, base: values.base, dryRun: values['dry-run'] });
+    console.log(values.json ? JSON.stringify({ schemaVersion: 1, command, ok: true, data, warnings: [], errors: [] }, null, 2) : formatGitStart(data));
+    return;
+  }
+
+  if (command === 'route') {
+    const { values } = parseArgs({ args: args.slice(1), options: { stdin: { type: 'boolean' }, prompt: { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
+    if (values.help) return printHelp(version, command);
+    if (Boolean(values.stdin) === (values.prompt !== undefined)) throw new Error('Select exactly one of --stdin or --prompt.');
+    let prompt = values.prompt;
+    if (values.stdin) {
+      process.stdin.setEncoding('utf8');
+      prompt = '';
+      for await (const chunk of process.stdin) prompt += chunk;
+    }
+    const data = await routeRequest({ prompt, cwd: projectRoot, packageRoot });
+    console.log(values.json ? JSON.stringify({ schemaVersion: 1, command, ok: true, data, warnings: [], errors: [] }, null, 2) : formatRoute(data));
+    return;
+  }
+
   if (command === 'list') {
     if (args.includes('--extensions')) {
       const isJson = args.includes('--json');
@@ -342,6 +376,9 @@ async function main() {
 }
 
 main().catch((error) => {
-  console.error(`showdar: ${error.message}`);
+  const command = process.argv[2];
+  if (['route', 'git-start'].includes(command) && process.argv.slice(3).includes('--json')) {
+    console.log(JSON.stringify({ schemaVersion: 1, command, ok: false, data: null, warnings: [], errors: [{ code: 'INVALID_REQUEST', message: error.message }] }, null, 2));
+  } else console.error(`showdar: ${error.message}`);
   process.exitCode = 1;
 });

package/package.json

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

package/router/skill-map.yaml

@@ -38,7 +38,7 @@ routes:
     triggers: ["resume interrupted implementation", "recover partial work", "session stopped", "continue partial work", "missing context"]
     skill: showdar-recover
   git:
-    triggers: ["commit", "stage only task files", "merge branch", "rebase branch", "cherry-pick commit", "git conflict", "push branch", "clean merged branches", "finish git workflow"]
+    triggers: ["commit", "stage only task files", "merge branch", "rebase branch", "cherry-pick commit", "git conflict", "push branch", "clean merged branches", "finish git workflow", "start task branch", "create feature branch", "create fix branch", "branch for this task"]
     skill: showdar-git
   requirements:
     triggers: ["requirements", "business rules", "acceptance criteria", "user stories", "use cases", "requirement matrix", "missing requirement", "ambiguity"]

package/skills/showdar-git/SKILL.md

@@ -46,6 +46,29 @@ This skill owns repository state transitions, not source-code review or GitHub a
 - Push, tag, remote deletion, pull with mutation, GitHub operations, and release actions require explicit intent.
 - Report exactly what changed after each Git mutation.
 
+## Task branch isolation
+
+Before the first task-owned source edit for a local-write engineering task, inspect Git state (`git status --short`, current branch, branch history and repository policy). Direct develop/main edits are not the default: on develop, development, dev, main, master or the default/integration branch, prepare a dedicated task branch before source mutation.
+
+Priority: repository instructions/documented branching convention; explicit current user instruction; clearly detected existing convention; Showdar safe default. Explicit trunk-based/direct-work policy wins: do not impose GitFlow. Branch preparation does not authorize source mutation.
+
+Use one branch per coherent task across understand, requirements, plan, design, build, test and review. Continue the current task branch; never create a branch per skill or nested branches.
+
+Default types: new user-visible capability → `feature`; observed defect → `fix`; internal restructuring → `refactor`; tests only → `test`; documentation only → `docs`; tooling/config/maintenance → `chore`; release preparation → `release`; explicit urgent production repair → `hotfix`. Names use a bounded lowercase hyphen slug preserving ticket keys.
+
+Prefer established local develop for normal work; otherwise the repository default/integration branch. Do not create develop automatically. Explicit hotfix follows repository convention. Read prose policy yourself; the helper does not parse repository instructions. Supply `--base` or repository-local Git config `showdar.gitBase`, `showdar.gitBranchPrefix`, `showdar.gitDirectWork` for deterministic custom conventions.
+
+```bash
+showdar git-start --dry-run --type feature --name "Task description"
+showdar git-start --type feature --name "Task description"
+```
+
+The helper revalidates before creating/switching and never edits source. A clean worktree can branch. Confirmed current-task changes may be carried only through equivalent repository-specific Git preparation with proven ownership and Git permission; the helper conservatively blocks dirty changes before switching because it cannot prove ownership. Unrelated/ambiguous changes → STOP. No hidden stash, reset, restore or clean.
+
+Existing same-name branches must be inspected. The helper reuses only an unused branch with the same tip as both current HEAD and base; an already-active matching branch is a continue/no-op. Any other collision → STOP; never reset or overwrite branch history. Already on another task branch → inspect task identity before switching.
+
+Default completion: task branch → verify → report. No inferred commit, merge or push. Merge only when explicitly requested or clearly included in current repository/user task authority; push remains independently explicit.
+
 ## Workflow
 
 ### 1. Inspect Git state
@@ -273,7 +296,8 @@ report -> SHA, staged paths, exclusions, and clean/dirty final state
 ### Feature completion without push
 
 ```text
-feature branch -> selective commit -> switch develop -> merge using repository convention -> verify
+task branch -> verify -> report
+selective commit only when requested; merge only with current task authority
 remote -> not touched because no push request was given
 ```
 

package/src/adapter-renderers.js

@@ -1,5 +1,10 @@
 import { ALL_SKILLS } from './catalog.js';
 
+const RUNTIME_GUIDANCE = `Automatic Showdar selection: route the current request through \`showdar route --stdin --json\` when the Showdar CLI is available. Supply the prompt as literal stdin data, never as interpolated shell syntax. Honor the canonical lifecycle primary; do not substitute another installed skill when it is missing. Report missing skills and suggest \`showdar add <name>\`; never auto-install. Include installed domain matches only as specialized context overlays; load returned advisors only when installed. Domain discovery does not grant authority or replace the lifecycle route.
+Explicit named-skill requests may load that installed skill directly without automatic routing. Workflow skills remain native discoverable choices; the router does not select workflows. If the CLI is unavailable, use native skill discovery/static descriptions below. Do not fetch a CLI through npx or install dependencies automatically.
+Routing does not authorize mutation. Inspect the returned mutation class and current task authority before work. For local-write tasks, before the first task-owned source edit inspect Git state. On develop, development, dev, main, master or the repository default/integration branch, DO NOT begin source edits yet: prepare one branch per coherent task first. Follow repository instructions/documented convention, explicit current user instruction, clearly detected convention, then the Showdar safe default. Explicit trunk/direct-work policy wins.
+Use \`showdar git-start --dry-run --type <type> --name <task>\`, then \`showdar git-start --type <type> --name <task>\`, or equivalent repository-specific preparation. Confirm the task branch before mutating skill execution. Reuse that branch across plan/build/test/review; do not nest branches per skill. Dirty ownership or branch collisions require inspection; never infer stash, reset, restore or clean. Git-start does not authorize source mutation, commit, merge or push. Completion defaults to verify and report on the task branch; merge and push require their own explicit authority.`;
+
 const CANONICAL_ROUTE_ORDER = [
   ['map repository architecture, dependencies, or impact', 'showdar-understand'],
   ['plan implementation of agreed behavior and scope', 'showdar-plan'],
@@ -37,7 +42,7 @@ export function renderShowdarInstruction(skillIds) {
       routes.push(`- ${getSkillDescription(id)} -> \`${id}\``);
     }
   }
-  return `${routes.join('\n')}\n`;
+  return `${routes.join('\n')}\n\n${RUNTIME_GUIDANCE}\n`;
 }
 
 export function renderShowdarCommand(skillId) {
@@ -48,6 +53,7 @@ description: ${description}
 
 Load and follow \`${skillId}\`.
 Ground in the current repository.
+${RUNTIME_GUIDANCE}
 Request: \$ARGUMENTS
 `;
 }
@@ -60,6 +66,8 @@ 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.
 
+${RUNTIME_GUIDANCE}
+
 Request: \$ARGUMENTS
 `;
 }

package/src/git-start.js

@@ -0,0 +1,87 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+export const TASK_BRANCH_TYPES = ['feature', 'fix', 'refactor', 'test', 'docs', 'chore', 'release', 'hotfix'];
+
+function git(cwd, args, optional = false) {
+  try { return execFileSync('git', ['--no-optional-locks', ...args], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10000 }).trim(); }
+  catch (error) {
+    if (optional && error.status === 1) return null;
+    throw new Error(`Git operation failed (${args[0]}): ${error.stderr?.toString().trim() || error.message}`);
+  }
+}
+
+export function taskSlug(name, type) {
+  if (typeof name !== 'string' || !name.trim()) throw new Error('--name requires a task name.');
+  const words = name.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').split('-');
+  // Drop a redundant task verb, including one following a useful ticket key.
+  const offset = /^[a-z]+$/.test(words[0]) && /^\d+$/.test(words[1] ?? '') ? 2 : 0;
+  if ([type, 'add'].includes(words[offset])) words.splice(offset, 1);
+  const slug = words.join('-').slice(0, 80).replace(/-+$/g, '');
+  if (!slug) throw new Error('Task name contains no safe branch characters.');
+  return slug;
+}
+
+function inspect({ cwd, type, name, base }) {
+  if (!TASK_BRANCH_TYPES.includes(type)) throw new Error(`Invalid task type. Expected ${TASK_BRANCH_TYPES.join(', ')}.`);
+  const root = git(cwd, ['rev-parse', '--show-toplevel']);
+  const current = git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD'], true);
+  if (!current) throw new Error('Detached HEAD: choose a repository branch before git-start.');
+  const head = git(root, ['rev-parse', 'HEAD']);
+  const dirty = git(root, ['status', '--porcelain=v1', '--untracked-files=all']);
+  for (const marker of ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'rebase-merge', 'rebase-apply', 'BISECT_LOG', 'sequencer']) {
+    const file = git(root, ['rev-parse', '--git-path', marker]);
+    if (existsSync(path.resolve(root, file))) throw new Error(`Active Git operation: ${marker}.`);
+  }
+  const config = key => git(root, ['config', '--local', '--get', key], true);
+  const prefix = config('showdar.gitBranchPrefix') ?? type;
+  const branch = `${prefix}/${taskSlug(name, type)}`;
+  git(root, ['check-ref-format', '--branch', branch]);
+  if (branch.startsWith('-')) throw new Error('Invalid task branch.');
+  const configuredBase = config('showdar.gitBase');
+  const defaultRef = git(root, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], true)?.replace(/^origin\//, '');
+  const localBranch = value => value && !value.startsWith('-') && git(root, ['show-ref', '--verify', '--quiet', `refs/heads/${value}`], true) !== null;
+  if (base && !localBranch(base)) throw new Error('Explicit --base must be an existing local branch.');
+  if (configuredBase && !localBranch(configuredBase)) throw new Error('Configured showdar.gitBase must be an existing local branch.');
+  if (type === 'hotfix' && !base && !configuredBase) throw new Error('Hotfix requires --base or repository showdar.gitBase convention.');
+  const resolvedBase = base ?? configuredBase ?? ['develop', 'development', 'dev', defaultRef, 'main', 'master'].find(localBranch);
+  if (!resolvedBase) throw new Error('Cannot infer integration base; use --base with the repository convention.');
+  const baseHead = git(root, ['rev-parse', `refs/heads/${resolvedBase}`]);
+  const integration = new Set(['develop', 'development', 'dev', 'main', 'master', defaultRef, resolvedBase]);
+  let action;
+  if (current === branch) action = 'continue';
+  else {
+    if (dirty) throw new Error('Dirty worktree ownership is ambiguous. Preserve changes; git-start never stashes or carries unproven task changes.');
+    if (!integration.has(current)) throw new Error('Already on another task branch; continue that coherent task or select its integration branch explicitly.');
+    const direct = config('showdar.gitDirectWork');
+    if (direct !== null && !['true', 'false'].includes(direct)) throw new Error('showdar.gitDirectWork must be true or false.');
+    if (direct === 'true') action = 'direct';
+    else if (localBranch(branch)) {
+      const targetHead = git(root, ['rev-parse', `refs/heads/${branch}`]);
+      // Equal tips are the only automatically provable safe unused branch.
+      if (targetHead !== head || targetHead !== baseHead) throw new Error('Existing task branch collision: history/ownership is ambiguous.');
+      action = 'switch';
+    } else {
+      if (baseHead !== head && git(root, ['merge-base', '--is-ancestor', head, baseHead], true) === null) throw new Error('Current branch diverges from base; inspect repository history before branching.');
+      action = 'create';
+    }
+  }
+  return { root, current, head, base: resolvedBase, baseHead, branch, action, dirty: dirty ? 'present' : 'clean' };
+}
+
+export function startTaskBranch(options) {
+  const proposal = inspect(options);
+  if (options.dryRun || ['continue', 'direct'].includes(proposal.action)) return { ...proposal, dryRun: Boolean(options.dryRun) };
+  const fresh = inspect(options);
+  if (JSON.stringify(fresh) !== JSON.stringify(proposal)) throw new Error('Git state changed during preflight; retry after inspection.');
+  if (fresh.action === 'create') git(fresh.root, ['switch', '-c', fresh.branch, fresh.baseHead]);
+  else git(fresh.root, ['switch', fresh.branch]);
+  const current = git(fresh.root, ['branch', '--show-current']);
+  if (current !== fresh.branch) throw new Error('Task branch switch was not confirmed.');
+  return { ...fresh, dryRun: false, current };
+}
+
+export function formatGitStart(data) {
+  return `Task branch: ${data.branch}\nBase: ${data.base}\nAction: ${data.action}${data.dryRun ? ' (dry-run)' : ''}\nWorktree: ${data.dirty}\nBranch preparation does not authorize source edits, commit, merge or push.`;
+}

package/src/project.js

@@ -588,6 +588,23 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
   if (effectiveScope !== 'project' && effectiveScope !== 'global') throw new Error(`Unknown scope "${effectiveScope}".`);
 
   if (existingManifest?.skills?.includes(skillId)) {
+    const refreshedFiles = [];
+    const priorOwned = ownedPathSet(existingManifest);
+    for (const target of existingManifest.commandHarness ?? []) {
+      const commandRoot = effectiveScope === 'global' ? globalCommandRootForTarget(target, { homeRoot: home }) : commandRootFor(target, cwd);
+      if (commandRoot) await generateCommandFiles({ baseRoot, skillIds: existingManifest.skills, target, commandRoot, priorOwned, newFiles: refreshedFiles });
+    }
+    if (effectiveScope === 'project' && existingManifest.instructions) {
+      const instruction = existingManifest.instructions;
+      const file = path.join(cwd, instruction.file);
+      if (instruction.kind === 'block') await writeManagedBlock(file, existingManifest.skills);
+      else if (instruction.kind === 'file') await writeCursorRule(file, existingManifest.skills);
+    }
+    if (refreshedFiles.length) {
+      const files = new Map(existingManifest.files.map(f => [f.path, f]));
+      for (const f of refreshedFiles) files.set(f.path, f);
+      await writeJsonAtomic(effectiveScope === 'global' ? globalManifestPath(home) : path.join(cwd, PROJECT_MANIFEST), { ...existingManifest, files: [...files.values()] });
+    }
     return { skill: skillId, root: '', destination: '', added: false, scope: effectiveScope, ai: effectiveAi, profile: existingManifest.profile };
   }
 
@@ -629,41 +646,19 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
     }
   }
 
+  const allSkillIds = [...new Set([...(existingManifest?.skills ?? []), skillId])];
   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 harnessTargets = [...new Set([...(existingManifest?.commandHarness ?? []), ...commandHarnesses.map(c => c.target)])];
+  for (const target of harnessTargets) {
+    const root = effectiveScope === 'global' ? globalCommandRootForTarget(target, { homeRoot: home }) : commandRootFor(target, cwd);
+    if (!root) continue;
+    const generated = await generateCommandFiles({ baseRoot, skillIds: allSkillIds, target, commandRoot: root, priorOwned, newFiles: files, managedRoots });
+    newCommands.push(...generated.map(c => ({ target, name: c.shortName, path: manifestPathFor(baseRoot, c.destination) })));
   }
 
   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)])];
 
@@ -673,10 +668,10 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
     packageVersion,
     profile: existingManifest?.profile ?? null,
     ai: effectiveAi,
-    targets,
+    targets: [...new Set([...(existingManifest?.targets ?? []), ...targets])],
     skills: allSkillIds,
     satisfiedByGlobal: existingManifest?.satisfiedByGlobal ?? [],
-    commands: [...(existingManifest?.commands ?? []), ...newCommands],
+    commands: [...new Map([...(existingManifest?.commands ?? []), ...newCommands].map(c => [c.path, c])).values()],
     files: [...merged.values()],
     instructions: instructionFile ? { file: instructionFile.file, kind: instructionFile.kind } : null,
     commandHarness,

package/src/runtime-route.js

@@ -0,0 +1,99 @@
+import path from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { ALL_SKILLS, SKILLS } from './catalog.js';
+import { resolveIntentFromPrompt } from './intent-resolver/index.js';
+import { assertSafeManagedPath } from './path-safety.js';
+
+async function readJson(file) {
+  try {
+    const value = JSON.parse(await readFile(file, 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Manifest must be an object.');
+    return value;
+  }
+  catch (error) { if (error.code === 'ENOENT') return null; throw new Error(`Cannot read Showdar manifest: ${error.message}`); }
+}
+
+async function skillPresent(root, relative) {
+  const file = path.resolve(root, relative, 'SKILL.md');
+  await assertSafeManagedPath(root, file);
+  try { return (await stat(file)).isFile(); }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+// ponytail: inline JSON trigger arrays only; use a YAML parser if the canonical format changes.
+// The canonical map uses JSON-compatible inline trigger arrays. Read only that
+// documented subset; this is discovery data, never an authority input.
+export async function discoverDomain(prompt, packageRoot) {
+  const map = await readFile(path.join(packageRoot, 'router/skill-map.yaml'), 'utf8');
+  const specialized = new Set(SKILLS.filter(s => s.id !== `showdar-${s.domain}`).map(s => s.id));
+  const text = String(prompt).normalize('NFC').toLowerCase();
+  const matches = [];
+  for (const entry of map.matchAll(/^  [\w-]+:\n    triggers: (\[[^\n]*\])\n    skill: ([\w-]+)$/gm)) {
+    if (!specialized.has(entry[2])) continue;
+    const triggers = JSON.parse(entry[1]);
+    if (triggers.some(trigger => {
+      const phrase = trigger.normalize('NFC').toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      return new RegExp(`(?<![\\p{L}\\p{N}])${phrase}(?![\\p{L}\\p{N}])`, 'u').test(text);
+    }) || text.includes(entry[2])) matches.push(entry[2]);
+  }
+  return [...new Set(matches)].sort();
+}
+
+export function projectLifecycle(route) {
+  return { primary: route.primary.skill, advisors: [...route.advisors] };
+}
+
+export async function routeRequest({ prompt, cwd, packageRoot, home = homedir() }) {
+  if (typeof prompt !== 'string' || !prompt.trim()) throw new Error('A non-empty prompt is required. Use --stdin or --prompt.');
+  const canonical = resolveIntentFromPrompt(prompt);
+  const lifecycle = projectLifecycle(canonical);
+  const domain = { matches: await discoverDomain(prompt, packageRoot) };
+  await assertSafeManagedPath(cwd, path.join(cwd, '.showdar.json'));
+  const manifest = await readJson(path.join(cwd, '.showdar.json'));
+  const installed = new Set();
+  if (manifest) {
+    if (manifest.version !== 2 || !Array.isArray(manifest.skills) || !Array.isArray(manifest.files)) throw new Error('Invalid managed Showdar manifest v2.');
+    for (const id of manifest.skills) {
+      if (typeof id !== 'string' || !ALL_SKILLS.some(s => s.id === id)) continue;
+      for (const entry of manifest.files) {
+        if (typeof entry.path === 'string' && path.basename(entry.path) === id && await skillPresent(cwd, entry.path)) installed.add(id);
+      }
+    }
+    if (manifest.satisfiedByGlobal?.length) {
+      const globalPath = path.join(home, '.showdar/global.json');
+      await assertSafeManagedPath(home, globalPath);
+      const global = await readJson(globalPath);
+      const owned = new Set((global?.files ?? []).map(e => e.path));
+      for (const entry of manifest.satisfiedByGlobal) {
+        if (manifest.skills.includes(entry.skill) && typeof entry.path === 'string' && path.basename(entry.path) === entry.skill && owned.has(entry.path) && await skillPresent(home, entry.path)) installed.add(entry.skill);
+      }
+    }
+  }
+  return {
+    intent: canonical.intent,
+    lifecycle,
+    domain,
+    availability: {
+      managed: manifest !== null,
+      installed: manifest ? [...installed].sort() : null,
+      missingLifecyclePrimary: manifest ? !installed.has(lifecycle.primary) : null,
+      missingAdvisors: manifest ? lifecycle.advisors.filter(id => !installed.has(id)) : null,
+      missingDomainMatches: manifest ? domain.matches.filter(id => !installed.has(id)) : null,
+    },
+  };
+}
+
+export function formatRoute(data) {
+  const { lifecycle, domain, intent, availability: a } = data;
+  const lines = [`Lifecycle: ${lifecycle.primary}`, `Domain: ${domain.matches.join(', ') || 'none'}`, `Advisors: ${lifecycle.advisors.join(', ') || 'none'}`, `Mutation: ${intent.mutation}`];
+  lines.push(`Availability: ${!a.managed ? 'not-managed / unknown' : a.missingLifecyclePrimary ? 'lifecycle not installed' : 'lifecycle installed'}`);
+  if (a.managed) {
+    for (const id of [lifecycle.primary, ...lifecycle.advisors, ...domain.matches]) {
+      const present = a.installed.includes(id);
+      lines.push(`${id}: ${present ? 'installed' : 'not installed'}`);
+      if (!present) lines.push(`Suggested command: showdar add ${id.replace(/^showdar-/, '')}`);
+    }
+  }
+  return lines.join('\n');
+}