showdar-skills 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -6,6 +6,36 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.16.0]
+
+### Added
+
+- Three portable first-class companion skills: `showdar-setup`, `showdar-refine`, and `showdar-domain-model`; native skills-only users no longer need the CLI for onboarding, refinement, or glossary/ADR guidance.
+- Conditional refinement with explicit spec approval, adaptive Decision Brief persistence, and approval-bound architectural/domain documentation.
+
+### Changed
+
+- Companion catalog, profiles and validations support 25 installable skills while retaining 18 lifecycle primitives and 4 workflows.
+- Existing lifecycle skills consume approved briefs and canonical glossary/ADR context without adding a second router.
+- CLI installation migrates away from the legacy generated `/showdar-setup` command toward the portable skill with owned-file safety checks.
+
+
+## [0.15.1]
+
+### Fixed
+
+- Reject malformed or unauthorized managed paths before removing project files; block symlink-based command writes and preflight installation collisions before replacing existing skills.
+- Make extension pack updates fail closed on conflicts and installed drift, stage changes safely, restore the previous installation on failure, remove obsolete owned files and clean staging directories.
+- Separate source pack identity from installed-tree hashes to avoid false drift reports when source-only documentation is not installed.
+- Ensure adding an existing skill to another AI target installs that target, and return nonzero exit codes for failed JSON diagnostics.
+- Correct `create-pack` destination handling and adapt the Codex benchmark to the current structural routing contract.
+- Remove unused legacy scoring helpers from the thin router.
+
+### Tests
+
+- Add regression coverage for destructive manifest paths, symlink boundaries, failed replacements, pack drift and updates, CLI diagnostics, target switching, scaffold paths, and Codex benchmark guidance.
+
+
 ## [0.15.0]
 
 ### Changed

package/README.md

@@ -24,7 +24,7 @@ showdar doctor
 | Agent setup | Analyze the repository, propose grounded shared context, and update docs after approval. |
 | `doctor` | Check the installation and flag problems. |
 
-**OpenCode / Claude Code:** after installation, use `/showdar-setup` to audit the codebase and prepare project context. The agent previews a diff and requests approval before changes. **Cursor:** use `/showdar-setup` as a project slash command. **Codex:** ask the agent to audit this repository and set up Showdar project context.
+**Portable skills:** native agent discovery works with `npx skills add caongocquy/showdar-skills` without the Showdar CLI. Invoke `showdar-setup` by name (or `/showdar-setup` where the agent supports skill slash-invocation). **CLI:** `showdar setup` remains the interactive installer. The setup skill audits project context and proposes Glossary changes with explicit approval; ADRs require actual decisions.
 
 Already configured? Just give the coding agent a normal task, such as *"Fix the checkout validation bug and add regression tests."* Showdar guidance routes requests to the relevant installed skills; you do not need to call each skill manually.
 
@@ -40,6 +40,26 @@ showdar doctor
 
 **Install vs. configure:** `showdar init` installs/replaces a skill selection, `showdar add` extends it, and `showdar setup` is the interactive installer. Project context is created or enriched by the AI agent using repository evidence and explicit approval; the CLI `showdar setup` runs the interactive installer and does not generate project context.
 
+## Portable companions
+
+- `showdar-setup`: repository evidence audit, project context onboarding and optional glossary bootstrap; user approval before writing.
+- `showdar-refine`: conditional questioning for material ambiguity. After refinement starts, a complete Decision Brief must receive explicit approval before implementation; skip when work is already defined.
+- `showdar-domain-model`: read canonical terminology and ADRs when relevant; propose edits for accepted domain definitions or real architecture decisions, and write only after approval.
+
+Companions are native-discoverable and first-class installable skills, not primary lifecycle routes. `showdar-feature` consults refine only when decisions can alter behavior, and handoff reuses approved specs rather than asking again. Specs follow adaptive persistence: use existing canonical tickets/docs first; create a durable spec for complex cross-session work, and keep small same-session briefs in conversation.
+
+## Version and updates
+
+```bash
+showdar -v                 # Also supports --version and -V
+showdar update             # Auto-detect npm, pnpm, or Homebrew global installation
+showdar upgrade            # Alias of update
+showdar update --dry-run   # Preview without changing anything
+showdar update --manager npm   # Explicit override: npm, pnpm, brew
+```
+
+`update` upgrades the globally installed Showdar CLI via the detected package manager and does **not** automatically rewrite skill copies in existing projects. When a package manager cannot be safely identified (for example, local source checkouts or ephemeral `npx` installs), it stops and prints manual installation options. Installing only portable skills through `npx skills add` does not install the Showdar CLI. Use `showdar update-pack` for extension packs; it is separate from updating the CLI.
+
 ## How it works
 
 ```text
@@ -50,7 +70,7 @@ User task
   -> Execute / verify / report
 ```
 
-Showdar ships **18 primitive** and **4 workflow** skills, including optional insurance-domain coverage. Only relevant instructions and references are loaded as needed.
+Showdar ships **18 lifecycle primitives**, **3 portable companion** and **4 workflow** skills, including optional insurance-domain coverage. Only relevant instructions and references are loaded as needed.
 
 Before local source/config/docs changes, follow the project's Git policy and run `showdar guard --mutation local-write --json`; work on a task branch when required. Routing and onboarding do not grant permission to commit, merge, push, or deploy.
 

package/bin/showdar.js

@@ -8,11 +8,12 @@ import { routeRequest, formatRoute } from '../src/runtime-route.js';
 import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
-import { AI_TARGETS, PRIMITIVE_COUNT, PROFILE_ALIASES, PROFILES, SKILLS, TOTAL_COUNT, WORKFLOW_COUNT, canonicalProfile, isDeprecatedProfile, resolveProfile, getWorkflow, normalizeSkillName } from '../src/catalog.js';
+import { AI_TARGETS, COMPANION_SKILLS, PRIMITIVE_COUNT, PROFILE_ALIASES, PROFILES, SKILLS, TOTAL_COUNT, WORKFLOW_COUNT, canonicalProfile, isDeprecatedProfile, resolveProfile, getWorkflow, normalizeSkillName } from '../src/catalog.js';
 import { addPack, addSkill, addSkills, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, listExtensionsDetailed, removeGlobal, removePack, removeProject, validatePackSource, createPack, inspectPack, doctor, updatePack, readProjectOverrides } from '../src/project.js';
 import { formatPlanPreviewHuman, projectPackUpdatePreview } from '../src/pack-plan.js';
 import { assessCheckpointAgainstCandidate } from '../src/pack-inspect.js';
 import { validateRepository } from '../src/validate.js';
+import { detectGlobalRoots, planSelfUpdate, executeSelfUpdate } from '../src/self-update.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const COMMANDS = ['understand', 'plan', 'design', 'build', 'debug', 'test', 'review', 'upgrade', 'ship', 'recover', 'git', 'requirements', 'quality', 'security', 'ops', 'skill'];
@@ -50,6 +51,10 @@ function printHelp(version, command = null) {
     console.log('Usage: showdar guard --mutation <read-only|local-write> [--json]');
     return;
   }
+  if (command === 'update' || command === 'upgrade') {
+    console.log('Usage: showdar update [--manager npm|pnpm|brew] [--dry-run]\nAlias: showdar upgrade\nUpdates the globally installed Showdar CLI package; does not overwrite project-installed skills.');
+    return;
+  }
   if (command === 'setup') {
     console.log('Usage: showdar setup [--mode add|replace] [--profile name] [--skills comma,list] [--workflow comma,list] [--ai target] [--scope project|global] [--yes|--dry-run] [--json]');
     return;
@@ -66,7 +71,7 @@ function printHelp(version, command = null) {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <target>] [--scope <project|global>]\n  showdar add profile <profile> [--ai <target>] [--scope <project|global>]\n  showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--scope <project|global>]\n\nExamples:\n  showdar add git\n  showdar add showdar-git\n  showdar add profile insurance\n  showdar add workflow feature\n  showdar add workflow ./workflows/acme-release.json\n\nAdd preserves installed skills; init replaces the managed set. Built-in workflows add required stages.`);
     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 <target>] [--scope <project|global>]\n  showdar add profile <profile> [--ai <target>] [--scope <project|global>]\n  showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--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 guard --mutation <read-only|local-write> [--json]\n  showdar setup [--mode add|replace] [--profile <name>] [--skills <names>] [--workflow <names>] [--ai <target>] [--scope <project|global>] [--yes|--dry-run]\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 <target>] [--scope <project|global>]\n  showdar add profile <profile> [--ai <target>] [--scope <project|global>]\n  showdar add workflow <builtin-name|local-json-path> [--ai <target>] [--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 guard --mutation <read-only|local-write> [--json]\n  showdar -v | --version\n  showdar update [--manager npm|pnpm|brew] [--dry-run]\n  showdar upgrade [--manager npm|pnpm|brew] [--dry-run]\n  showdar setup [--mode add|replace] [--profile <name>] [--skills <names>] [--workflow <names>] [--ai <target>] [--scope <project|global>] [--yes|--dry-run]\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() {
@@ -76,12 +81,28 @@ async function main() {
   const version = await packageVersion();
 
   if (command === 'help' || command === '--help' || command === '-h') return printHelp(version);
-    if (command === '--version' || command === '-V') {
+  if (command === '--version' || command === '-V' || command === '-v') {
     console.log(version);
     return;
   }
   if (!['route', 'git-start', 'guard'].includes(command) && (args.includes('--help') || args.includes('-h'))) return printHelp(version, command);
 
+  if (command === 'update' || command === 'upgrade') {
+    const { values, positionals } = parseArgs({ args: args.slice(1), allowPositionals: true,
+      options: { manager: { type: 'string' }, 'dry-run': { type: 'boolean' } } });
+    if (positionals.length) throw new Error('Unexpected update arguments: ' + positionals.join(' '));
+    const manager = values.manager ?? null;
+    const roots = manager ? {} : detectGlobalRoots();
+    const plan = planSelfUpdate({ packageRoot, manager, roots });
+    console.log('Showdar Skills ' + version + ' (installed via ' + plan.manager + ')');
+    console.log('Update command: ' + [plan.command, ...plan.args].join(' '));
+    if (values['dry-run']) return;
+    await executeSelfUpdate(plan);
+    console.log('Showdar package update completed. Run showdar -v to verify the installed version.');
+    console.log('Project-installed skill copies are not changed. Refresh them separately using the existing Showdar installer.');
+    return;
+  }
+
   const scope = ['init', 'status', 'doctor', 'remove', 'add'].includes(command) ? scopeAfter(args) : null;
 
   if (command === 'setup' || (command === 'add' && args.includes('--interactive'))) {
@@ -177,7 +198,7 @@ async function main() {
       return;
     }
     console.log(`Profiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\n\nSkills:`);
-    for (const skill of SKILLS) console.log(`  ${skill.id}  [${skill.domain}]  ${skill.description}`);
+    for (const skill of [...SKILLS, ...COMPANION_SKILLS]) console.log(`  ${skill.id}  [${skill.kind}/${skill.domain}]  ${skill.description}`);
     return;
   }
 
@@ -252,11 +273,12 @@ async function main() {
         console.log(JSON.stringify({
           schemaVersion: 1,
           command: 'doctor',
-          ok: true,
+          ok: result.healthy,
           data: { ...result, checkpointCompatibility: 'not-assessed' },
           warnings: result.warnings ?? [],
           errors: [],
         }, null, 2));
+        if (!result.healthy) process.exitCode = 1;
         return;
       }
       console.log(`Extension diagnostics\nHealth: ${result.healthy ? 'OK' : 'BROKEN'}`);
@@ -265,6 +287,7 @@ async function main() {
       for (const issue of result.issues) console.log(`- ${issue}`);
       for (const warning of result.warnings ?? []) console.log(`warning: ${warning}`);
       if (!result.healthy) {
+        process.exitCode = 1;
         console.log(`Checkpoint compatibility: not-assessed (supply a checkpoint via inspect-pack --checkpoint)`);
         if (result.customWorkflows.length) console.log(`Note: checkpoints referencing changed workflow definitions will be revalidated on resume.`);
       }
@@ -356,6 +379,7 @@ async function main() {
     if (!packPath) throw new Error('Pack path is required. Usage: showdar validate-pack <local-path> [--json]');
     const isJson = args.includes('--json');
     const result = await validatePackSource({ cwd: projectRoot, source: packPath });
+    if (!result.ok) process.exitCode = 1;
     if (isJson) {
       console.log(JSON.stringify(result, null, 2));
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": {

package/profiles/backend.json

@@ -1 +1 @@
-{"skills":["showdar-understand","showdar-plan","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-upgrade","showdar-ship","showdar-recover","showdar-git","showdar-requirements","showdar-quality","showdar-security","showdar-ops"]}
+{"skills":["showdar-understand","showdar-plan","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-upgrade","showdar-ship","showdar-recover","showdar-git","showdar-requirements","showdar-quality","showdar-security","showdar-ops","showdar-setup","showdar-refine","showdar-domain-model"]}

package/profiles/developer.json

@@ -1 +1 @@
-{"skills":["showdar-understand","showdar-plan","showdar-design","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-upgrade","showdar-ship","showdar-recover","showdar-git","showdar-security"]}
+{"skills":["showdar-understand","showdar-plan","showdar-design","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-upgrade","showdar-ship","showdar-recover","showdar-git","showdar-security","showdar-setup","showdar-refine","showdar-domain-model"]}

package/profiles/full.json

@@ -1 +1 @@
-{"skills":["showdar-understand","showdar-plan","showdar-design","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-upgrade","showdar-ship","showdar-recover","showdar-git","showdar-requirements","showdar-quality","showdar-security","showdar-ops","showdar-insurance-domain","showdar-insurance-workflows","showdar-insurance-review"]}
+{"skills":["showdar-understand","showdar-plan","showdar-design","showdar-build","showdar-debug","showdar-test","showdar-review","showdar-upgrade","showdar-ship","showdar-recover","showdar-git","showdar-requirements","showdar-quality","showdar-security","showdar-ops","showdar-insurance-domain","showdar-insurance-workflows","showdar-insurance-review","showdar-setup","showdar-refine","showdar-domain-model"]}

package/profiles/product.json

@@ -1 +1 @@
-{"skills":["showdar-understand","showdar-requirements","showdar-plan","showdar-design","showdar-quality","showdar-review"]}
+{"skills":["showdar-understand","showdar-requirements","showdar-plan","showdar-design","showdar-quality","showdar-review","showdar-setup","showdar-refine","showdar-domain-model"]}

package/profiles/qa.json

@@ -1 +1 @@
-{"skills":["showdar-understand","showdar-requirements","showdar-quality","showdar-test","showdar-debug","showdar-review","showdar-ship","showdar-recover","showdar-git"]}
+{"skills":["showdar-understand","showdar-requirements","showdar-quality","showdar-test","showdar-debug","showdar-review","showdar-ship","showdar-recover","showdar-git","showdar-setup","showdar-refine","showdar-domain-model"]}

package/router/triggers.yaml

@@ -17,6 +17,7 @@ priority:
   - showdar-understand
   - showdar-test
   - showdar-build
+# Portable companions are invoked by native discovery or lifecycle skill guidance, not canonical priority.
 rules:
   - if root cause is unknown prefer showdar-debug over showdar-build
   - if requirements or change surface are unresolved prefer showdar-plan over showdar-build

package/skills/showdar-build/SKILL.md

@@ -51,6 +51,15 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 - Add/adjust tests at the lowest level that can fail for the intended regression/behavior.
 - Do not rewrite unrelated formatting or files.
 
+## Approved decision boundaries
+
+- Read the current approved feature brief, canonical glossary and relevant accepted ADRs if they exist.
+- When refinement has been triggered, require explicit approval of the whole brief revision before implementing; ordinary fully specified work does not incur a new approval gate.
+- Preserve agreed domain names, behavior and non-goals in code; do not change accepted decisions silently.
+- If implementation exposes a genuine conflict with an approved contract, stop and request approval for the affected decision before altering scope.
+- Invoke installed `showdar-domain-model` only for a meaningful shared glossary/architecture update, with a separate proposed diff and approval.
+- Do not assume `showdar route`, CLI install or workflow checkpoint grants mutation authority.
+
 ## Workflow
 
 ### Phase 1 — pre-change check

package/skills/showdar-design/SKILL.md

@@ -56,6 +56,14 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 - Maintain readable contrast, semantic labeling, focus order, reduced-motion behavior, and text scaling.
 - Prefer existing design tokens/components when they meet the requirement.
 
+## Approved design context
+
+- Locate an approved feature brief, established design system and relevant accepted ADRs before proposing UI changes.
+- Preserve approved behavior and product constraints instead of silently revising flow, terminology, or permission rules.
+- When a design decision would materially change approved behavior, ask to reopen just that decision; use installed `showdar-refine` when a real interview is needed.
+- If a shared term is newly accepted, propose canonical glossary updates through installed `showdar-domain-model` rather than duplicating vocabulary.
+- Do not manufacture ADRs for routine visual preferences or minor component decisions.
+
 ## Workflow
 
 ### Mode selection

package/skills/showdar-domain-model/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: showdar-domain-model
+description: Use when clarifying shared domain terminology, maintaining an evidence-backed glossary, or documenting confirmed architectural decisions as ADRs.
+---
+
+# Showdar Domain-Model
+
+## Purpose
+
+- Offer a standalone portable Agent Skill that works without any Showdar executable.
+- Reuse existing repository conventions and the user's authoritative requirements.
+- Separate observations, assumptions, proposals, approvals, and mutations.
+- Keep outcomes useful for the next engineering stage without creating a second router.
+
+## When to use
+
+- Several modules use inconsistent names for the same domain concept.
+- An agreed cross-feature definition, alias or state transition should be preserved.
+- A meaningful architectural choice has been explicitly decided with alternatives and trade-offs.
+
+## When not to use
+
+- An isolated variable rename does not change canonical terminology.
+- A UI preference has no project-wide architecture consequences.
+- No meaningful domain or architectural decision occurred.
+
+## Inputs and assumptions
+
+- Read repository instructions and user-provided context before proposing changes.
+- Prefer relevant source files, API schemas, tests, tickets, and existing documentation.
+- Record conflicting evidence and ask the user about decisions that change meaning.
+- Treat an existing artifact as canonical when repository conventions say so.
+
+## Non-negotiable rules
+
+- Never claim a user approved an unapproved proposal.
+- Do not infer permission to edit files, commit, push, merge, publish, or deploy.
+- Before edits, honor repository Git policy and prepare a safe task branch as required.
+- If the Showdar CLI is available, run showdar guard --mutation local-write --json and require ok=true and data.allowed=true.
+- If CLI is unavailable, perform Git and repository-policy checks manually; never auto-fetch a CLI with npx.
+- Respect existing files and user modifications; show proposed changes before writes.
+- Do not fabricate product decisions or source evidence.
+- Use native skill discovery in skills-only installations without assuming router, manifest or CLI.
+
+Read `references/glossary.md` and `references/adr.md` only when that depth of detail is needed; these references are packaged inside this skill for skills-only installers.
+
+## Workflow
+
+- Discover canonical glossary, ADR, domain docs and previous decisions first.
+- Read the smallest relevant context; separate domain facts from observed implementation.
+- For glossary candidates record term, definition, aliases, boundaries, source and conflicts.
+- Distinguish genuinely new terms from synonyms and legacy names.
+- For an ADR candidate record context, explicit decision, considered alternatives, consequences and evidence of approval.
+- Avoid ADRs describing implementation details that were never a chosen policy.
+- Present proposed targeted edits to the canonical locations before writing.
+- Request approval for proposed glossary/ADR changes and respect repo/Git write protections.
+- If approved, update the canonical glossary or append the next appropriate ADR without overwriting prior decisions.
+- For superseded ADRs preserve history and add explicit supersession links rather than quietly rewriting accepted decisions.
+- If no significant change exists, return a no-change report; do not generate documents.
+- Link feature specs to relevant domain terms and ADRs rather than copying full contents into each spec.
+
+## Decision points
+
+- Read when relevant; propose on material domain change; write only after approval.
+- Use existing GLOSSARY.md, docs/glossary.md or project convention; never create duplicates.
+- An ADR requires a confirmed choice with actual trade-offs, not merely an inferred pattern.
+- For minor terminology edits use glossary only; for technical policy trade-offs consider ADR.
+
+## Stack detection
+
+- Inspect manifests/configuration before assuming framework or tooling.
+- For web and mobile check navigation, state lifecycle, API contracts and accessibility concerns.
+- For backend check persistence, authentication, compatibility and operational boundaries.
+- For other stacks use available repository evidence rather than generalized guesses.
+
+## Failure modes
+
+- Treating installed tooling as proof of user authorization.
+- Reading one README and assuming it describes live behavior.
+- Creating duplicate markdown for topics with an existing canonical document.
+- Treating a proposed decision as accepted because it was presented to the user.
+
+## Stop conditions
+
+- Stop before persisting unconfirmed terminology or architectural choices.
+- Stop when proposal is approved and verified or when no changes are warranted.
+
+## Escalation conditions
+
+- Ask for authorization when a write would change user-owned canonical content.
+- Surface source conflicts affecting business correctness, money, security, privacy or data retention.
+- Stop before irreversible operations not explicitly requested.
+
+## Verification
+
+- Check that documented file paths exist when referenced.
+- Trace every concrete statement back to supplied material or observed repository evidence.
+- Report what was proposed, approved, modified and left unresolved distinctly.
+
+## Output contract
+
+- Canonical paths and evidence-linked terminology or decision changes.
+- Proposed diff with approval status, conflicts and deferred decisions.
+- Verification and consumers affected by the accepted changes.
+
+## Anti-patterns
+
+- Duplicate a glossary simply to satisfy a process checklist.
+- Use a hidden persistent state machine when portable text artifacts suffice.
+- Generate empty ADRs or unsupported architecture stories.
+- Begin implementation while approval is still outstanding.
+
+## Example
+
+- Define Package as the accepted insurance product unit and mark Plan as a legacy alias only with supporting evidence.
+- Record an accepted persistence strategy as an ADR after the user agrees to real alternatives.
+- Do not issue an ADR for switching a two-option field from dropdown to radio.

package/skills/showdar-domain-model/references/adr.md

@@ -0,0 +1,7 @@
+# Architecture Decision Records
+
+ADR proposal: context and forces, considered alternatives, chosen approach, consequences, owner/status, evidence and date where known.
+
+Only record genuinely accepted high-impact architecture choices. If decision authority is not clear, keep status proposed and request acceptance.
+
+When later superseded, preserve the original ADR and add explicit supersession references. Avoid rewriting historic outcomes to match current implementation.

package/skills/showdar-domain-model/references/glossary.md

@@ -0,0 +1,7 @@
+# Glossary discipline
+
+Canonical discovery order: repository instructions, existing glossary links, domain docs, specs, then conventional paths. Respect the location already used by the project.
+
+Each proposal states term, agreed definition, aliases/legacy names, scope, sources and affected consumers. Separate proposed language from user-approved language.
+
+Do not create empty templates; do not rename all code solely because a vocabulary change was proposed. Show the precise diff and request approval.

package/skills/showdar-feature/SKILL.md

@@ -45,6 +45,19 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 - Security may load as an orthogonal primitive (`showdar-security`) when the change touches auth, secrets, trust boundaries, or exposure.
 - Stop when required evidence is missing instead of guessing.
 
+## Conditional refinement gate (portable)
+
+- Before selecting implementation stages, assess whether the requested feature has material unresolved product, permission, state, data, or architecture decisions.
+- If the request is sufficiently defined, skip refinement with a concrete evidence reason; never force an interview for a local, low-risk or already approved change.
+- If materially unclear and the optional `showdar-refine` companion is installed, invoke it before implementation; ask one high-impact question at a time and produce a Decision Brief.
+- If the companion is missing, report it rather than claiming it ran; resolve blocking decisions with the user before continuing.
+- When refinement has been triggered, wait for explicit user approval of the *whole* proposed spec revision before entering `showdar-build`.
+- Carry approved decisions, non-goals, acceptance notes, unresolved questions and evidence into requirements/plan/design without repeating already answered questions.
+- Use the existing canonical spec/ticket when present; persist a new `docs/specs/` document only for durable or complex handoff after approval.
+- If later repository evidence contradicts an approved decision, reopen only the affected decision and obtain revision-specific approval.
+- Refer to installed `showdar-domain-model` for meaningful shared terminology or accepted architectural decisions, not as a required lifecycle stage.
+- This decision gate is portable guidance, not a new router, workflow-state stage, checkpoint authority, or implicit permission to mutate files.
+
 ## Workflow
 
 ### Phase 1 — determine needed stages

package/skills/showdar-insurance-domain/SKILL.md

@@ -38,6 +38,11 @@ translations such as policy → “chính sách” or premium → “cao
 cấp”. Do not equate application, quote, contract and
 certificate.
 
+## Project glossary integration
+
+- Prefer the project's existing canonical insurance glossary for agreed wording and aliases; local references are background, not authority over project decisions.
+- If shared terminology changes, propose updating the canonical glossary through `showdar-domain-model` when installed; never silently rewrite insurance product rules.
+
 ## Workflow
 
 1. Identify the requested module and known market, insurer, product, product version and API version. Unknown scope stays explicit; ask only for missing context that changes the answer.

package/skills/showdar-plan/SKILL.md

@@ -51,6 +51,14 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 - Do not invent requirements to make the architecture cleaner.
 - Avoid placeholders such as “handle errors appropriately” without defining the required behavior.
 
+## Refinement and domain decision contract
+
+- Read an available approved Decision Brief, canonical glossary and accepted ADRs before selecting the approach.
+- Treat approved alternatives and non-goals as constraints; avoid re-opening decisions merely to make the plan look cleaner.
+- If a materially different choice is required, stop and reopen only affected decisions through `showdar-refine` if installed, or request the user decision directly.
+- Use `showdar-domain-model` only to propose a meaningful new shared concept or approved high-impact architecture record.
+- Approval of a design never grants write, Git, release, or production authority.
+
 ## Workflow
 
 ### Phase 1 — normalize the requirement

package/skills/showdar-quality/SKILL.md

@@ -46,6 +46,12 @@ description: Use when planning QA/QC scenarios, risk coverage, regression scope,
 - Preserve requirement terminology and trace each scenario to a requirement, risk, change surface, or observed defect.
 - If a check belongs inside an automated test, state the boundary and hand implementation to `showdar-test`.
 
+## Decision coverage
+
+- Derive QA scenarios from existing approved spec and acceptance notes when present; do not invent missing product rules.
+- If refinement was triggered and approval is missing, flag the readiness blocker instead of pretending the spec is agreed.
+- Preserve canonical domain terminology when writing test scenarios; meaningful changes belong in an approved glossary proposal.
+
 ## Workflow
 
 ### Phase 1 — define the quality question

package/skills/showdar-refine/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: showdar-refine
+description: Use when a feature idea or implementation request has unresolved product or architecture decisions that require interactive refinement and explicit spec approval.
+---
+
+# Showdar Refine
+
+## Purpose
+
+- Offer a standalone portable Agent Skill that works without any Showdar executable.
+- Reuse existing repository conventions and the user's authoritative requirements.
+- Separate observations, assumptions, proposals, approvals, and mutations.
+- Keep outcomes useful for the next engineering stage without creating a second router.
+
+## When to use
+
+- A proposed feature has conflicting behaviors, missing states or business-rule choices.
+- Several viable architectural approaches differ in public contract, persistence or compatibility.
+- The user explicitly asks to brainstorm, grill, refine or challenge a feature concept.
+
+## When not to use
+
+- The task already has approved scope, acceptance and design decisions.
+- A localized bug has a proven root cause and agreed fix.
+- The user asks only for testing, review or operational status.
+
+## Inputs and assumptions
+
+- Read repository instructions and user-provided context before proposing changes.
+- Prefer relevant source files, API schemas, tests, tickets, and existing documentation.
+- Record conflicting evidence and ask the user about decisions that change meaning.
+- Treat an existing artifact as canonical when repository conventions say so.
+
+## Non-negotiable rules
+
+- Never claim a user approved an unapproved proposal.
+- Do not infer permission to edit files, commit, push, merge, publish, or deploy.
+- Before edits, honor repository Git policy and prepare a safe task branch as required.
+- If the Showdar CLI is available, run showdar guard --mutation local-write --json and require ok=true and data.allowed=true.
+- If CLI is unavailable, perform Git and repository-policy checks manually; never auto-fetch a CLI with npx.
+- Respect existing files and user modifications; show proposed changes before writes.
+- Do not fabricate product decisions or source evidence.
+- Use native skill discovery in skills-only installations without assuming router, manifest or CLI.
+
+Read `references/questioning.md` and `references/approval-handoff.md` only when that depth of detail is needed; these references are packaged inside this skill for skills-only installers.
+
+## Workflow
+
+- Start read-only: inspect request, canonical spec/ticket, relevant repository context and existing ADR/glossary.
+- Classify readiness from evidence; skip refinement when outcomes and important decisions are already specified.
+- If triggered, identify the single highest-impact unresolved decision rather than many decorative questions.
+- Ask one targeted question at a time; when helpful give two or three feasible options with consequences.
+- Challenge assumptions and negative paths, permissions, state, rollback, compatibility and data integrity.
+- Do not ask the user to repeat a decision already clearly recorded.
+- Draft a concise Decision Brief: goal, scope, non-goals, decisions with IDs, alternatives, acceptance notes and blockers.
+- Show the complete proposed spec and request explicit approval; a response to one question is not approval for the whole brief.
+- On changes, revise the brief and ask approval again; do not implement while waiting.
+- After approval, prefer an existing canonical spec or ticket; save to docs/specs only for complex durable handoffs with file approval.
+- For a small one-session task, keep the approved brief in conversation; never claim chat memory persists across sessions.
+- Handoff the approved brief and exact decisions to showdar-requirements or showdar-plan without repeating the interview.
+- If later evidence contradicts an accepted decision, reopen only affected decisions and request fresh approval.
+
+## Decision points
+
+- Trigger on material product/architecture ambiguity, not prompt length or number of modified files.
+- Skip only with explicit evidence of defined behavior and no blocking decision.
+- No architecture tradeoff? Do not invent alternatives merely to fill a matrix.
+- Approved design does not grant Git, file mutation or deployment authority.
+
+## Stack detection
+
+- Inspect manifests/configuration before assuming framework or tooling.
+- For web and mobile check navigation, state lifecycle, API contracts and accessibility concerns.
+- For backend check persistence, authentication, compatibility and operational boundaries.
+- For other stacks use available repository evidence rather than generalized guesses.
+
+## Failure modes
+
+- Treating installed tooling as proof of user authorization.
+- Reading one README and assuming it describes live behavior.
+- Creating duplicate markdown for topics with an existing canonical document.
+- Treating a proposed decision as accepted because it was presented to the user.
+
+## Stop conditions
+
+- Do not enter implementation without full spec approval once refinement has run.
+- Stop with needs-input when an unresolved decision materially changes implementation.
+- Stop with ready-for-approval until explicit user acceptance.
+- End as approved only after a clear confirmation of a specific brief or revision.
+
+## Escalation conditions
+
+- Ask for authorization when a write would change user-owned canonical content.
+- Surface source conflicts affecting business correctness, money, security, privacy or data retention.
+- Stop before irreversible operations not explicitly requested.
+
+## Verification
+
+- Check that documented file paths exist when referenced.
+- Trace every concrete statement back to supplied material or observed repository evidence.
+- Report what was proposed, approved, modified and left unresolved distinctly.
+
+## Output contract
+
+- Status: skipped | needs-input | ready-for-approval | approved.
+- Approved brief with decision IDs, alternatives, assumptions, acceptance notes and unresolved questions.
+- Next skill suggestion, evidence and persistence location if any; no invented approval authority.
+
+## Anti-patterns
+
+- Duplicate a glossary simply to satisfy a process checklist.
+- Use a hidden persistent state machine when portable text artifacts suffice.
+- Generate empty ADRs or unsupported architecture stories.
+- Begin implementation while approval is still outstanding.
+
+## Example
+
+- For checkout vouchers, ask whether stacking is allowed before choosing a pricing algorithm.
+- When the user accepts the complete voucher brief, hand off approved stacking and expiry rules.
+- An already-specified one-line validation change should skip refinement entirely.

package/skills/showdar-refine/references/approval-handoff.md

@@ -0,0 +1,11 @@
+# Approved Decision Brief and handoff
+
+A brief contains Goal, Context evidence, Scope, Non-goals, Decisions (stable DEC identifiers), Alternatives and trade-offs, Assumptions, Acceptance notes, Open questions, Approval revision and Next skill.
+
+States: skipped, needs-input, ready-for-approval, approved. Do not silently promote from needs-input or ready-for-approval.
+
+When triggered, request explicit acceptance of the whole brief, not approval inferred from individual answers. Never begin implementation from a draft.
+
+Adaptive persistence: update existing canonical spec/ticket only with approval, otherwise write docs/specs/<feature>.md when cross-session or complex handoff justifies it. In-session small approved briefs may remain in chat, but do not assume another session can recover the approval.
+
+Do not store mutation permissions inside a workflow checkpoint. Require fresh repository authority for writes, commits or publication.

package/skills/showdar-refine/references/questioning.md

@@ -0,0 +1,9 @@
+# Questioning and skip policy
+
+Read source evidence and previously accepted decisions first. Define a blocking decision as one whose alternatives materially affect product behavior, architecture, data integrity or compatibility.
+
+Ask one high-leverage question per response, optionally with two or three real alternatives. Prefer specific examples and negative paths over generic surveys.
+
+Skip if acceptance, behavior and significant decisions are already clear; do not force a feature into refinement for ceremony. When triggered, record explicit user acceptance of the entire resulting Decision Brief.
+
+If source evidence later contradicts the approved brief, reopen only the affected decision and request a revision-specific approval.

package/skills/showdar-requirements/SKILL.md

@@ -56,6 +56,14 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 - Present unresolved items under an explicit `Open questions` heading when stakeholder input is required.
 - Do not claim a requirement is ready merely because a happy path is described.
 
+## Approved-spec and refinement handoff
+
+- First inspect existing canonical spec/ticket and an approved Decision Brief when available; do not restart an interview for accepted decisions.
+- If blocking product or architectural choices remain and `showdar-refine` is installed, use it as a companion before claiming the requirement implementation-ready.
+- Once refinement was triggered, no implementation may begin until the user explicitly approves the complete spec.
+- Capture newly agreed shared terms for an optional `showdar-domain-model` glossary proposal; do not silently edit docs or infer approvals.
+- Preserve Decision Brief IDs and non-goals in acceptance criteria. Report missing approval or conflicting sources as blockers.
+
 ## Workflow
 
 ### Phase 1 — establish the source of truth