showdar-skills 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,69 @@ 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
+
+- First-class workflow skill model: 15 primitives (`kind: primitive`) plus 4
+  workflows (`kind: workflow`) for 19 total installable skills.
+- `showdar-feature`: adaptive end-to-end feature implementation over
+  understand, requirements, plan, design, build, test, and review stages.
+- `showdar-bugfix`: adaptive defect resolution over understand, debug, build,
+  test, and review stages, including investigation-only mode.
+- `showdar-release`: release readiness versus execution separation over
+  quality, security, ship, and authority-gated ops stages.
+- `showdar-incident`: operational incident investigation and recovery over
+  understand, debug, recover, verification, and authority-gated ops stages.
+- `showdar add feature|bugfix|release|incident` installs workflows through the
+  existing installer; short names normalize like primitives.
+- Workflow composition and safety validation: stage references resolve to
+  known primitives, workflows never stage another workflow or themselves,
+  and workflow SKILL.md files stay lean by referencing primitives.
+
+### Changed
+
+- Catalog distinguishes primitive and workflow skills; `getSkill` and
+  `normalizeSkillName` resolve all 19 installable skills.
+- `showdar validate` reports primitive/workflow/total counts
+  (`15 primitives, 4 workflows, 19 total`).
+- `showdar add` normalization supports workflow IDs and short names.
+- OpenCode `skill.md` command lists all 19 skills with a whole-task versus
+  single-primitive selection guard.
+- AGENTS.md managed routing block includes workflow routes when installed.
+
 ## [0.3.0]
 
 ### Added

package/MIGRATION.md

@@ -1,3 +1,51 @@
+# 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:
+
+```bash
+showdar add feature
+showdar add bugfix
+showdar add release
+showdar add incident
+```
+
+- 0.3.0 `.showdar.json` v2 configs remain valid; no config-version migration
+  is required.
+- All 15 primitive IDs remain unchanged.
+- Profile behavior and composition are unchanged: `minimal` (8), `developer`
+  (12), `backend` (14), `qa` (9), `product` (6), `full` (15 primitives).
+- Workflows are additive and optional; they complement rather than replace
+  primitives. Nothing is removed.
+- No Phase 6G routing migration is required; the authority engine and the
+  15-capability primitive taxonomy are unchanged.
+- Single primitive requests keep resolving to primitives; whole-task or
+  lifecycle requests may select a workflow.
+
 # Migrating to 0.3.0
 
 ## Skill install roots

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/showdar-skills?logo=npm)](https://www.npmjs.com/package/showdar-skills)
 [![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue?logo=opensourceinitiative&logoColor=white)](./LICENSE)
-[![15 skills](https://img.shields.io/badge/skills-15-6f42c1)](#skill-catalog)
+[![19 skills](https://img.shields.io/badge/skills-19-6f42c1)](#skill-catalog)
 
 Production-grade software engineering skills for coding agents. Showdar covers
 the full lifecycle—from requirements and planning through implementation, QA,
@@ -42,7 +42,7 @@ you want all capabilities available.
 
 ## Why Showdar?
 
-- **15 focused skills** instead of one oversized agent prompt.
+- **15 focused primitive skills** plus 4 adaptive workflow skills (19 installable) instead of one oversized agent prompt.
 - **Lifecycle coverage** from product rules to implementation, verification,
   security, operations, release readiness, and Git completion.
 - **Intent-based discovery** that selects the workflow matching the request.
@@ -72,9 +72,12 @@ SKILL.md
           only when needed
 ```
 
-The 15 skills are not eagerly loaded as full prompts. Lightweight descriptions
-help the agent choose one skill; that skill then loads its workflow and deeper
-knowledge progressively.
+The 15 primitive skills are not eagerly loaded as full prompts. Lightweight
+descriptions help the agent choose one skill; that skill then loads its
+workflow and deeper knowledge progressively. Workflow skills add a portable
+orchestration layer: a workflow selects the lifecycle stages a task actually
+needs and composes primitives one at a time, without duplicating their
+instructions.
 
 ## Supported agents
 
@@ -86,16 +89,97 @@ knowledge progressively.
 | 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.
@@ -130,8 +214,10 @@ paths are refreshed or removed.
 
 ## Profiles
 
-Role-specific profiles improve routing precision. `full` exposes every skill,
-but still does not eagerly load every skill body.
+Role-specific profiles improve routing precision. Profiles install primitive
+skill sets; workflow skills are opt-in through `showdar add <workflow>` and
+are not silently included in any profile. `full` exposes every primitive
+skill, but still does not eagerly load every skill body.
 
 | Profile | Skills | Best for |
 | --- | ---: | --- |
@@ -140,7 +226,7 @@ but still does not eagerly load every skill body.
 | `backend` | 14 | APIs, services, and runtime operations |
 | `qa` | 9 | Testing and quality workflows |
 | `product` | 6 | Product, requirements, and design work |
-| `full` | 15 | All capabilities |
+| `full` | 15 | All primitive capabilities |
 
 Legacy aliases remain compatible:
 
@@ -153,7 +239,8 @@ New manifests store the canonical `developer` profile.
 
 ## Skill catalog
 
-All 15 entries are first-class Showdar skills.
+All 15 primitive entries are first-class Showdar skills. Four workflow skills
+compose them; see [Workflow skills](#workflow-skills).
 
 ### Analysis and planning
 
@@ -195,6 +282,109 @@ All 15 entries are first-class Showdar skills.
 | `showdar-recover` | Interrupted or partial engineering work must be reconstructed from repository evidence before continuing. |
 | `showdar-git` | Performing local Git inspection, staging, commits, branch integration, conflicts, cleanup, or explicitly requested remote Git actions. |
 
+## Workflow skills
+
+Four workflow skills orchestrate primitives adaptively; they are not fixed
+pipelines and they grant no extra authority:
+
+| Skill | Use when |
+| --- | --- |
+| `showdar-feature` | Implementing a complete feature end-to-end. |
+| `showdar-bugfix` | Resolving an observed defect end-to-end. |
+| `showdar-release` | Preparing, validating, or executing a release lifecycle. |
+| `showdar-incident` | Investigating or recovering from an active operational incident. |
+
+How a workflow runs:
+
+```text
+Workflow
+  -> selects needed lifecycle stages
+  -> invokes/composes primitive skills one at a time
+  -> primitives retain their own semantics
+  -> Phase 6G remains the authority source
+```
+
+Properties:
+
+- Adaptive, not fixed pipelines: stages marked `?` below are skipped when
+  evidence permits.
+- Intended for whole-task and lifecycle requests.
+- Focused primitive requests remain primitive.
+- Workflow identity never grants mutation or deployment authority.
+- Risk and severity never grant production authority.
+- Workflows do not create a second router or authority engine.
+
+### showdar-feature
+
+```bash
+showdar add feature
+```
+
+Typical candidate flow:
+
+```text
+understand -> requirements? -> plan? -> design? -> build -> test -> review
+```
+
+Skip requirements when behavior is already defined, plan for genuinely
+focused work, and design when no architecture or UX decision exists.
+Verification is never skipped to move faster. Ops is not implied.
+
+### showdar-bugfix
+
+```bash
+showdar add bugfix
+```
+
+Typical:
+
+```text
+understand -> debug? -> build -> test -> review
+```
+
+If the root cause is already proven, debug may be skipped. If the request is
+diagnosis only, build is not implied and the workflow stops after
+`showdar-debug`.
+
+### showdar-release
+
+```bash
+showdar add release --scope global --ai claude
+```
+
+Typical:
+
+```text
+quality -> security? -> ship -> ops only with explicit target + authorization
+```
+
+Readiness must not imply deployment. `showdar-ship` stays delivery
+verification; `showdar-ops` loads only with an explicit target plus execution
+authorization.
+
+### showdar-incident
+
+```bash
+showdar add incident
+```
+
+Typical:
+
+```text
+understand -> debug -> recover -> verification -> ops only when explicitly authorized
+```
+
+Diagnose before mutating when the cause is unknown. Severity must not imply
+production mutation. The workflow never auto-deploys or restarts production
+from risk alone.
+
+Workflows compose primitives: they select only the stages the evidence
+requires, skip defined or decision-free stages, load one primitive at a time,
+and stop when evidence or authority is missing. Single primitive requests stay
+primitive (`showdar-review`, `showdar-debug`, `showdar-test`). Phase 6G remains
+the authority source; workflows consume it and never mint it. Workflows are
+opt-in through `showdar add <workflow>`; profiles install primitive sets only.
+
 ## A typical software workflow
 
 ```text
@@ -255,17 +445,23 @@ OpenCode exposes native commands after initialization with `--ai opencode` or
 
 ## Adding a single skill
 
-Install one primitive skill without re-running a whole profile:
+Install one skill without re-running a whole profile:
 
 ```bash
 showdar add debug
 showdar add showdar-security
 showdar add test --ai cursor
 showdar add review --scope global --ai claude
+showdar add feature
+showdar add bugfix --ai cursor
+showdar add release --scope global --ai claude
+showdar add incident
 ```
 
-Accepted names are the short form (`debug`) or the canonical form
-(`showdar-debug`). The release ships exactly 15 primitive skills. `showdar add`
+Accepted names are the short form (`debug`, `feature`) or the canonical form
+(`showdar-debug`, `showdar-feature`). The release ships exactly 15 primitive
+skills plus 4 workflow skills (19 installable total); profiles install
+primitive sets only. There is no `showdar workflow ...` command. `showdar add`
 is idempotent, preserves the configured profile, supports `--ai`/`--scope`
 overrides, and refuses to overwrite a foreign same-name skill directory that
 Showdar does not own.

package/bin/showdar.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
-import { AI_TARGETS, PROFILE_ALIASES, PROFILES, SKILLS, canonicalProfile, isDeprecatedProfile, resolveProfile } from '../src/catalog.js';
+import { AI_TARGETS, PRIMITIVE_COUNT, PROFILE_ALIASES, PROFILES, SKILLS, TOTAL_COUNT, WORKFLOW_COUNT, canonicalProfile, isDeprecatedProfile, resolveProfile } from '../src/catalog.js';
 import { addSkill, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, removeGlobal, removeProject } from '../src/project.js';
 import { validateRepository } from '../src/validate.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)) {
@@ -69,7 +69,7 @@ async function main() {
 
   if (command === 'validate') {
     const result = await validateRepository(packageRoot);
-    if (result.ok) console.log(`Showdar validation OK (${SKILLS.length} skills).`);
+    if (result.ok) console.log(`Showdar validation OK (${PRIMITIVE_COUNT} primitives, ${WORKFLOW_COUNT} workflows, ${TOTAL_COUNT} total).`);
     else {
       console.log(`Showdar validation FAILED (${result.errors.length} errors).`);
       for (const error of result.errors) console.log(`- ${error}`);
@@ -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/commands/opencode/showdar/skill.md

@@ -1,6 +1,6 @@
 ---
 description: Invoke a specific Showdar flagship skill explicitly
 ---
-Select exactly one requested Showdar skill and follow it: `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`, or `showdar-ops`. If the requested name is ambiguous, choose the smallest matching skill from this list and say which one was selected.
+Select exactly one requested Showdar skill and follow it: `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-feature`, `showdar-bugfix`, `showdar-release`, or `showdar-incident`. 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

package/package.json

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

package/skills/showdar-bugfix/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: showdar-bugfix
+description: Use when resolving an observed defect end-to-end, adaptively sequencing understand, debug, build, test, and review stages based on whether root cause is already proven.
+---
+
+# Showdar Bugfix
+
+## Purpose
+
+- Resolve an observed defect safely from evidence to verified fix.
+- Include diagnosis only when the root cause is actually unknown.
+- Skip implementation when the user asked only for investigation.
+- Hand work to one primitive at a time; load the next only when needed.
+
+## When to use
+
+- The user asks to resolve a defect end-to-end.
+- A failure is observed: crash, regression, wrong behavior, build failure, performance fault.
+- Examples: "fix the login crash", "resolve the checkout regression".
+
+## When not to use
+
+- Single primitive intent stays primitive: "why does this crash" is `showdar-debug` unless the user asks to fix it end-to-end.
+- Investigation-only requests stay at `showdar-debug`; do not force `showdar-build`.
+- Interrupted or broken work-state recovery is `showdar-recover`, not this workflow; use recover only for work-state semantics, not ordinary bugs.
+- Once this workflow is active, do not spawn another parent workflow unless the request contains a genuinely separate workflow task.
+- This workflow never recursively invokes itself.
+
+## Inputs and assumptions
+
+- Observed failure and reproduction path, when available.
+- Current repository conventions and change surface are discoverable.
+- Authority comes from the existing Phase 6G engine; this workflow consumes authority results and never mints authority.
+- Candidate stages: `showdar-understand`, `showdar-debug`, `showdar-build`, `showdar-test`, `showdar-review`.
+
+## Non-negotiable rules
+
+- Symptom description alone is not mutation authority.
+- Do not treat a symptom as permission to edit; require root-cause evidence or explicit fix authorization.
+- Investigation-only requests do not proceed to `showdar-build`.
+- End-to-end fixes always include verification; never skip it to move faster.
+- Stop when required evidence is missing instead of guessing.
+
+## Workflow
+
+### Phase 1 — determine needed stages
+
+- Root cause unknown: `showdar-understand`, then `showdar-debug`, then `showdar-build`, then `showdar-test`, then `showdar-review`.
+- Root cause already proven: `showdar-understand`, then `showdar-build`, then `showdar-test`, then `showdar-review`.
+- Investigation only: `showdar-debug` alone, then report findings without mutation.
+
+### Phase 2 — execute progressively
+
+- Load one primitive at a time; hand off only when its stop condition is met.
+- Each primitive's own SKILL.md governs its stage; do not copy primitive instructions here.
+- Track ephemeral state only: candidate stages, selected stages, active stage, completed evidence, next stage or complete.
+- No persistent checkpoint or resume infrastructure in this version.
+
+## Decision points
+
+- Is the root cause proven with evidence? If yes, `showdar-debug` may be skipped.
+- Did the user ask only for diagnosis? If yes, stop after `showdar-debug`.
+- Is the failure actually interrupted work-state? If yes, hand off to `showdar-recover` instead.
+- Auth, secrets, or exposure involved? Add `showdar-security` as an orthogonal specialist.
+
+## Stack detection
+
+- Defer to each selected primitive's own stack detection.
+
+## Failure modes
+
+- Editing from symptom description without root-cause evidence.
+- Forcing implementation when only diagnosis was requested.
+- Confusing ordinary bugs with work-state recovery.
+- Loading all primitives eagerly instead of progressively.
+
+## Stop conditions
+
+- Stop when the request is actually a single primitive task and hand off to that primitive.
+- Stop before destructive, irreversible, production, credential, publishing, or deployment actions unless explicitly authorized.
+- Stop when required evidence is missing.
+- Stop when the fix is verified and reviewed.
+
+## Escalation conditions
+
+- Ask for reproduction steps when the failure cannot be reproduced.
+- Ask for explicit fix authority when evidence is thin.
+- Escalate suspected security exposure with evidence, without exploit amplification.
+
+## Verification
+
+- Reproduce before and after where practical.
+- End-to-end fixes include `showdar-test` evidence and `showdar-review` findings addressed.
+- State what was executed and what remains unverified.
+
+## Output contract
+
+- Root-cause evidence and selected stages.
+- Fix location and behavior change.
+- Verification gaps or residual risk.
+
+## Anti-patterns
+
+- Symptom-to-patch without diagnosis.
+- Mandatory debug stage even when the cause is proven.
+- Mandatory build stage for investigation-only requests.
+- Copying primitive SKILL.md content into this file.
+
+## Example
+
+**Checkout total regressed after discount change**
+
+- Evidence: failure observed, root cause unknown.
+- Selected: `showdar-understand`, then `showdar-debug` (isolated to discount ordering), then `showdar-build`, then `showdar-test`, then `showdar-review`.
+- Investigation-only variant would stop after `showdar-debug` with findings and no mutation.