showdar-skills 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.17.0]
+
+### Additional unpublished changes
+
+- Added portable native `showdar-tdd` companion with evidence-based RED → GREEN → REFACTOR; integrated into Build/Plan/Test/Feature/Recover without adding a workflow stage.
+- Canonical default plan and spec documents now live under `docs/showdar/plans/` and `docs/showdar/specs/`; existing repository locations still win.
+- Updated developer/backend/qa/full profiles and 26-skill catalog, migration guidance, and regression coverage.
+
+
+### Added
+- Renamed native portable `showdar-refine` to **`showdar-brainstorm`**, without a legacy CLI alias.
+- Adaptive Markdown plan persistence and verification-backed task resume for the Brainstorm → Plan → Build workflow.
+- Safe, hash-checked migration for CLI-owned legacy native skills and commands.
+
+### Notes
+- Plan files do not replace workflow checkpoints or imply approval, Git, publication or deployment authority.
+
 ## [0.16.0]
 
 ### Added

package/MIGRATION.md

@@ -1,3 +1,17 @@
+# Further v0.17.0 changes (pre-release)
+
+`showdar-tdd` is a new optional companion installable with `showdar add tdd --ai cursor`; developer/backend/qa/full profiles include it. Existing installations retain their selection until explicitly updated. Canonical default plan and approved-spec documents now live under `docs/showdar/plans/` and `docs/showdar/specs/`. Existing project documentation conventions are never migrated or overwritten automatically. TDD is evidence-based RED → GREEN → REFACTOR where runnable tests exist, not a source of implicit Git or deployment authority.
+
+# Upgrade from v0.16.0 to v0.17.0
+
+The native skill `showdar-refine` is retired, and `showdar-brainstorm` is its sole replacement. **No CLI alias**: `showdar add refine` and `showdar add showdar-refine` are rejected. Use `showdar add brainstorm` or update the project profile.
+
+For CLI-managed installs, `showdar init --profile developer --ai cursor` or `showdar add brainstorm --ai cursor` migrates matching owned v0.16 native files and commands only when their recorded hashes still match. If a managed file was modified, migration stops without deleting user changes. Independently installed skills (e.g. via `npx skills add`) have no Showdar ownership record: inspect and update them with their original installer.
+
+Plans may stay in chat for small tasks. Complex, staged or cross-session plans can be saved to a repository's existing canonical plan path (default `docs/showdar/plans/<feature>.md`) with task IDs, dependencies and verification ledger. Build checks actual source/tests before completing tasks. A plan never stores authorization or replaces lifecycle checkpoints.
+
+---
+
 # Migrating to 0.8.0
 
 0.8.0 adds local declarative extensibility (extension packs, custom

package/README.md

@@ -43,10 +43,17 @@ showdar doctor
 ## 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-brainstorm`: conditional questioning for material ambiguity. After brainstorming starts, a complete Decision Brief must receive explicit approval before implementation; skip when work is already defined.
+- `showdar-tdd`: verified RED → GREEN → REFACTOR for bounded testable behavior tasks; callable directly or used within Build when installed. Never invent a failing test, and declare a reason/alternative check when no runnable harness exists.
 - `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.
+Use `showdar add brainstorm` or `/showdar-brainstorm`. The retired skill name is not a CLI alias. Existing v0.16.0 installs should update their profile; Showdar-managed legacy copies are migrated only when unchanged. Independent Skills CLI installs must be updated with that installer.
+
+Durable specs default to `docs/showdar/specs/<feature>.md` after full-spec approval, unless the project has an existing canonical convention. For longer work, `showdar-plan` may persist a plan in the repository's canonical plans location (default `docs/showdar/plans/<feature>.md`) with stable task IDs and a verification ledger. `showdar-build` resumes from that plan, but a checkbox is not proof and a plan is not Git or implementation authority.
+
+Native usage: `showdar add tdd --ai cursor`, then `/showdar-tdd` where supported. For automatic Build use, select a profile including TDD (developer/backend/qa/full) or add it explicitly.
+
+Companions are native-discoverable and first-class installable skills, not primary lifecycle routes. `showdar-feature` consults brainstorm 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
 

package/docs/REFERENCE.md

@@ -167,8 +167,8 @@ guidance, including re-adding an existing skill. Global installs keep native dis
 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.
+introduce workflow selection. Profiles contain primitives plus portable companions: `full` contains all
+18 primitives and 4 companions; the insurance profile remains unchanged.
 
 Before the first local-write task source edit, the coding agent must run
 `showdar guard --mutation local-write --json` and require `ok=true` and
@@ -215,7 +215,7 @@ source edits.
 
 ## Why Showdar?
 
-- **18 focused primitive skills** plus 4 adaptive workflow skills (22 installable), including an opt-in insurance domain profile.
+- **18 focused primitive skills**, 4 portable companions and 4 adaptive workflow skills (26 installable), including an opt-in insurance domain profile.
 - **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.
@@ -387,20 +387,19 @@ paths are refreshed or removed.
 
 ## Profiles
 
-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.
+Role-specific profiles improve routing precision. Profiles install selected primitive
+and portable companion skills; workflows remain opt-in through `showdar add <workflow>`.
+`full` includes every primitive and companion, but does not eagerly load every skill body.
 
 | Profile | Skills | Best for |
 | --- | ---: | --- |
 | `minimal` | 8 | Focused everyday assistance |
-| `developer` | 12 | General application development |
-| `backend` | 14 | APIs, services, and runtime operations |
-| `qa` | 9 | Testing and quality workflows |
-| `product` | 6 | Product, requirements, and design work |
+| `developer` | 16 | General application development |
+| `backend` | 18 | APIs, services, and runtime operations |
+| `qa` | 13 | Testing and quality workflows |
+| `product` | 9 | Product, requirements, and design work |
 | `insurance` | 3 | Insurance terminology, business flows, and UI/API review |
-| `full` | 18 | All primitive capabilities |
+| `full` | 22 | All primitive and companion capabilities |
 
 Legacy aliases remain compatible:
 
@@ -411,10 +410,23 @@ web    -> developer
 
 New manifests store the canonical `developer` profile.
 
+## Test-driven implementation and document layout
+
+The `showdar-tdd` companion is included in developer/backend/qa/full profiles, or can be installed individually with `showdar add tdd --ai cursor`. It runs one scoped RED (reproduced behavior failure), GREEN (passing focused test), REFACTOR (focused test stays passing) cycle at a time and hands actual proof to `showdar-build`. `showdar-test` independently selects integration, regression and E2E coverage; Review remains a separate quality gate. No fabricated RED logs and no ceremonial tests for documentation-only or missing-harness work.
+
+Adaptive documentation persistence uses a project's existing canonical docs first; if none exists, durable approved specs default to `docs/showdar/specs/<feature>.md` and multi-session execution plans default to `docs/showdar/plans/<feature>.md`. Smaller tasks can remain in chat. A saved plan is not execution authorization and task checkboxes require fresh code/test evidence.
+
+```text
+docs/showdar/
+  specs/<feature>.md
+  plans/<feature>.md
+```
+
 ## Skill catalog
 
-All 18 primitive entries are first-class Showdar skills. Four workflow skills
-compose them; see [Workflow skills](#workflow-skills).
+All 18 primitive entries and 4 portable companions are installable Showdar skills.
+Four workflow skills compose the primitive stages; see [Workflow skills](#workflow-skills).
+`showdar-tdd` is a companion used inside the Build stage when suitable; it does not change the workflow-state stage list.
 
 ### Analysis and planning
 
@@ -438,6 +450,7 @@ compose them; see [Workflow skills](#workflow-skills).
 | Skill | Use when |
 | --- | --- |
 | `showdar-test` | Choosing or implementing automated tests for behavior, regressions, integration, E2E, or coverage. |
+| `showdar-tdd` (companion) | Implementing a bounded behavioral change with real RED → GREEN → REFACTOR evidence; direct invocation `/showdar-tdd` is available where native skills support it. |
 | `showdar-quality` | Planning QA/QC scenarios, risk coverage, regression scope, compatibility checks, or bug-report evidence. |
 | `showdar-review` | Reviewing code or diffs for general correctness, architecture, performance, maintainability, or tests. |
 
@@ -748,9 +761,9 @@ Use `showdar add insurance-workflows --ai codex` and
 that wants all three, `showdar init --profile insurance --ai codex` installs the set.
 
 Accepted names are the short form (`debug`, `feature`, `insurance-domain`)
-or the canonical form (`showdar-debug`, `showdar-feature`). The release ships exactly 18 primitive
-skills plus 4 workflow skills (22 installable total); profiles install
-primitive sets only. There is no `showdar workflow ...` command. `showdar add`
+or the canonical form (`showdar-debug`, `showdar-feature`). The release ships exactly 18 primitive,
+4 companion and 4 workflow skills (26 installable total); built-in profiles select primitive
+and companion skills but do not include workflows. 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.16.0",
+  "version": "0.17.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","showdar-setup","showdar-refine","showdar-domain-model"]}
+{"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-brainstorm","showdar-domain-model","showdar-tdd"]}

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","showdar-setup","showdar-refine","showdar-domain-model"]}
+{"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-brainstorm","showdar-domain-model","showdar-tdd"]}

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","showdar-setup","showdar-refine","showdar-domain-model"]}
+{"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-brainstorm","showdar-tdd","showdar-domain-model"]}

package/profiles/product.json

@@ -1 +1 @@
-{"skills":["showdar-understand","showdar-requirements","showdar-plan","showdar-design","showdar-quality","showdar-review","showdar-setup","showdar-refine","showdar-domain-model"]}
+{"skills":["showdar-understand","showdar-requirements","showdar-plan","showdar-design","showdar-quality","showdar-review","showdar-setup","showdar-brainstorm","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","showdar-setup","showdar-refine","showdar-domain-model"]}
+{"skills":["showdar-understand","showdar-requirements","showdar-quality","showdar-test","showdar-debug","showdar-review","showdar-ship","showdar-recover","showdar-git","showdar-setup","showdar-brainstorm","showdar-domain-model","showdar-tdd"]}

package/skills/{showdar-refine → showdar-brainstorm}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-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.
+name: showdar-brainstorm
+description: Use when brainstorming a feature, challenging assumptions, comparing real alternatives, and approving the complete spec before implementation.
 ---
 
-# Showdar Refine
+# Showdar Brainstorm
 
 ## Purpose
 
@@ -44,6 +44,12 @@ description: Use when a feature idea or implementation request has unresolved pr
 
 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.
 
+## Plan handoff
+
+- Read `references/handoff-plan.md` when moving from brainstorming to implementation planning.
+- Pass the accepted Decision Brief revision, decision IDs and acceptance criteria to `showdar-plan`. Durable specs follow existing canonical locations; the plan is a separate artifact whose persistence is adaptive.
+- A full-spec approval is necessary after brainstorming but does not mark plan tasks as done or grant Git/write authority.
+
 ## Workflow
 
 - Start read-only: inspect request, canonical spec/ticket, relevant repository context and existing ADR/glossary.
@@ -55,7 +61,7 @@ Read `references/questioning.md` and `references/approval-handoff.md` only when
 - 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.
+- After approval, prefer an existing canonical spec or ticket; save to docs/showdar/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.

package/skills/{showdar-refine → showdar-brainstorm}/references/approval-handoff.md

@@ -6,6 +6,6 @@ States: skipped, needs-input, ready-for-approval, approved. Do not silently prom
 
 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.
+Adaptive persistence: update existing canonical spec/ticket only with approval, otherwise write docs/showdar/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-brainstorm/references/handoff-plan.md

@@ -0,0 +1,8 @@
+# Brainstorm to Plan handoff
+
+- Start with repository context and one meaningful unresolved decision at a time. Ask questions until material ambiguity is resolved.
+- Draft an explicit Decision Brief (goals, non-goals, decision IDs, alternatives, acceptance notes, unresolved risks).
+- A reply to one question does not authorize the entire spec. Request approval for the *whole* current brief revision.
+- If no material ambiguity existed, explicitly skip brainstorming and use existing approved requirements; do not generate ceremonial specs.
+- If approved, hand off stable decision IDs, approved revision and canonical spec/ticket path if persisted to `showdar-plan`.
+- Brainstorm approval does not authorize writes, commits, merges, deployment or plan task completion.

package/skills/showdar-build/SKILL.md

@@ -60,6 +60,31 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 - 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.
 
+## Test-driven implementation
+
+- Use installed `showdar-tdd` for behavior-changing tasks when tests can be run at a meaningful boundary; the companion is optional, not a new workflow stage. If missing, follow the same evidence-first RED → GREEN → REFACTOR contract directly with `showdar-test` support.
+- RED: add a minimal behavioral test and run it against current code. Confirm it fails for the expected missing behavior/defect rather than a broken fixture, imports or configuration.
+- GREEN: make the smallest production change that makes the test pass; rerun the same targeted test and inspect negative/error cases.
+- REFACTOR: improve production/test code only within the agreed task boundaries, rerun the targeted tests and affected checks to keep GREEN.
+- Document actual commands and observed RED, GREEN and REFACTOR results against the plan task ID. Never fabricate a failing run or mark `[x]` when proof is absent.
+- When TDD cannot meaningfully apply (docs-only, generated assets, unavailable test harness), explicitly record why and execute an honest alternate verification. Do not write ceremonial tests.
+- `showdar-test` still owns broad test-level strategy and integration/E2E verification, and `showdar-review` still reviews final diffs.
+
+## Execute and resume a task plan
+
+- Read `references/plan-execution.md` before using a persisted plan to track or resume tasks.
+- Discover the canonical implementation plan and approved spec first. If no durable plan is appropriate, use the agreed in-chat plan; never manufacture a file requirement for a small change.
+- Compare plan revision, linked spec and decision IDs, actual source, dependencies, and prior verification receipts before editing.
+- Treat checked boxes as *claims* requiring code/test evidence, never as proof or authorization. If prior evidence is stale or missing, classify as `implemented-unverified`, inspect the implementation, then verify it before writing new code.
+- Pick the earliest unmet dependency-ready task, implement its bounded change, and run the exact relevant verification plus checks needed for affected contracts.
+- Only after behavior exists and required proof succeeds may its task be marked `[x]`, together with an evidence ledger receipt containing actual command/scenario, outcome, changed files and commit/revision context when available.
+- If proof is blocked, failed or unavailable, keep `[ ]` and record `blocked` or `implemented-unverified`; never mark a task done just because code was edited.
+- Progress updates to Markdown are writes governed by the same Git preflight and foreign-file protections as source code. If file writes cannot be performed safely, report status in chat instead of falsifying a plan.
+- If plan or spec has materially drifted, stop the affected task, report the conflict and return to `showdar-plan` or `showdar-brainstorm` for the relevant decision; do not silently reshape scope during Build.
+- A saved plan supplements, but never replaces, workflow-state checkpoints, full-spec approval, Git authorization, or separate Test/Review evidence.
+- When interrupted, return verified/unverified task IDs, proof, blockers, plan revision/path and first ready task so `showdar-recover` or another agent can resume without guessing.
+
+
 ## Workflow
 
 ### Phase 1 — pre-change check

package/skills/showdar-build/references/plan-execution.md

@@ -0,0 +1,22 @@
+# Executing and resuming Markdown plans
+
+## Locate and reconcile
+- Discover the current canonical plan through repo instructions, task description and specs; `docs/showdar/plans/<feature>.md` is a fallback, not a search constraint.
+- Verify the linked product spec's approval if brainstorming was triggered, plan revision, current Git branch/status, and affected dependencies.
+- Check each `TASK-NNN` checkbox against actual implemented behavior, diff and reliable test receipts. A checked task can be stale. A task left unchecked may already be implemented, so inspect before redoing.
+- Classify: `not-started`, `implemented-unverified`, `verified-complete`, `blocked`, or `superseded`. The checkbox represents `verified-complete` only.
+
+## Per-task loop
+1. Choose the earliest unmet task whose declared dependencies are verified. Do not infer a dependency is satisfied from its checkbox alone.
+2. Inspect current implementation and run a minimal confirming test to avoid duplication.
+3. For testable behavior work, execute a scoped RED → GREEN → REFACTOR cycle with `showdar-tdd` if installed, or equivalent evidence-first steps directly. Capture each run under the same task ID. If exempt, record a defensible reason and alternate proof.
+4. Apply the smallest scoped change using the repository's Git preflight and policy checks.
+5. Run the task's proof checks and relevant broader checks. Record *actual* commands/results, RED/GREEN/REFACTOR receipts when applicable, and source revision when available.
+6. For verified-complete, check `[x]` and add a concise receipt to the plan ledger *only when the plan file can safely be edited*. If unavailable, leave the artifact untouched and report progress in chat.
+7. For failed or missing proof, leave `[ ]`, classify blocker/unverified state and report the next safe action. Do not mark an unverified task complete.
+
+## Replan and resume
+- Mismatched product decision, interface contract or incompatible plan revision: stop affected implementation and reopen that decision with Plan/Brainstorm; do not silently broaden change scope.
+- Keep unchanged task IDs across revisions; explicitly mark superseded tasks and stale receipts without erasing their history.
+- Plan Markdown is not executable orchestration, not user approval, not a workflow-state checkpoint and not a Git permission record.
+- On interruption report exact task IDs, state, relevant test evidence, plan path/revision, remaining blockers and the earliest verified dependency-ready task.

package/skills/showdar-design/SKILL.md

@@ -60,10 +60,16 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 
 - 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.
+- When a design decision would materially change approved behavior, ask to reopen just that decision; use installed `showdar-brainstorm` 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.
 
+## Brainstorm and plan handoff
+
+- Preserve the accepted behavior and constraints from `showdar-brainstorm` when creating design guidance.
+- Pass relevant design outcomes into `showdar-plan` without marking implementation task checkboxes as done or treating design approval as execution authority.
+
+
 ## Workflow
 
 ### Mode selection

package/skills/showdar-feature/SKILL.md

@@ -49,15 +49,30 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 
 - 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 materially unclear and the optional `showdar-brainstorm` 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.
+- Use the existing canonical spec/ticket when present; persist a new `docs/showdar/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.
 
+## Adaptive TDD companion
+
+- `showdar-tdd` is an optional companion for the `showdar-build` implementation loop, not a new candidate stage or workflow-state schema field.
+- For behavior changes with runnable tests, Build should hand the smallest task and acceptance criteria to TDD, retain RED/GREEN/REFACTOR receipts and follow with `showdar-test` and `showdar-review`.
+- If TDD cannot run, record why and use task-appropriate alternate proof. Do not skip verification or imply an unavailable companion was invoked.
+
+## Resumable plan handoff
+
+- When the `showdar-plan` stage is selected, prefer the repository's canonical plan location for complex or cross-session work; bounded work may keep a short plan in chat.
+- Supply `showdar-build` with the approved spec reference, persisted plan path and revision (or explicit in-chat brief), stable task IDs, dependencies and required verification.
+- A saved task checkbox is neither an approval nor a workflow stage completion receipt; the receiving Build agent must revalidate current repo and evidence.
+- On session changes or interruptions use `showdar-recover` to reconcile plan tasks with actual source and tests before continuing.
+- Do not add new workflow-state schema fields or treat plan persistence as a substitute for serialized workflow checkpoints.
+
+
 ## Workflow
 
 ### Phase 1 — determine needed stages

package/skills/showdar-plan/SKILL.md

@@ -55,10 +55,24 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 
 - 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.
+- If a materially different choice is required, stop and reopen only affected decisions through `showdar-brainstorm` 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.
 
+## Adaptive Plan Persistence and handoff
+
+- Read `references/plan-persistence.md` when a durable plan or cross-session handoff is needed; `examples/persisted-plan.md` illustrates the shape, not a mandatory template.
+- Locate the repository's canonical ticket/plan first. Reuse a matching existing artifact; never create a duplicate solely because its path differs from `docs/showdar/plans/`.
+- For bounded work contained in one session, a short in-chat plan is sufficient. For complex, staged, multi-agent or cross-session work, propose a Markdown plan at the canonical location, defaulting to `docs/showdar/plans/<feature>.md` only if no convention exists.
+- Before creating or modifying a plan file, obtain authorization for that write and pass Git preflight; if blocked, provide the proposed plan in chat without claiming it was persisted.
+- Reference the approved spec/ticket and its revision where one exists. If `showdar-brainstorm` was triggered, do not designate a plan execution-ready until the entire Decision Brief revision has explicit user approval.
+- Assign stable `TASK-NNN` identifiers to ordered tasks with `- [ ]` checkboxes; include requirement/decision IDs, dependency IDs, scope, edge behavior, exact existing proof commands or explicitly manual checks, and acceptance conditions.
+- Planning alone never checks any task. The plan's `ready` status records preparedness, not implementation authority or proof.
+- Store plan revision, state, linked spec revision, risks, verification ledger, blockers and next dependency-ready task. Never fabricate approvals, command output, commit SHA or test results.
+- Revising scope requires identifying affected tasks and increasing plan revision. Preserve stable IDs for unchanged outcomes, keep historical proof while marking stale receipts invalid, and never silently amend an approved product decision.
+- Handoff states the exact plan path/revision or in-chat brief, persistence status (skipped/proposed/written), unresolved blockers and next actionable task.
+
+
 ## Workflow
 
 ### Phase 1 — normalize the requirement
@@ -86,6 +100,7 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 ### Phase 5 — decompose execution
 - Order tasks by dependency and independent reviewability.
 - Each task states files/symbols, behavior, error/edge behavior, test, and verification command.
+- For testable behavior tasks, include an expected RED → GREEN → REFACTOR sequence and the test boundary/command; where unavailable, document why and choose an honest alternative proof, never fake RED output.
 - Keep task boundaries small enough that a reviewer could approve one and reject the next.
 
 ### Phase 6 — self-review

package/skills/showdar-plan/examples/persisted-plan.md

@@ -0,0 +1,37 @@
+# Example: Invitation RSVP editing implementation plan
+
+> Illustrative schema only. Replace examples with evidence from the actual repository; never invent a test command, approval or commit SHA.
+
+- Plan revision: 1
+- Status: ready
+- Canonical spec: existing approved invitation spec (identify its path/revision in the real project)
+- Goal: authenticated hosts can edit RSVP configuration
+- Non-goals: guest authentication redesign and database replacement
+- Existing evidence: to be populated from repository inspection
+- Approach: validate and authorize patch at service boundary; preserve guest read contract
+- Risk/rollback: host-only feature flag; avoid breaking guest payload
+
+## Ordered tasks
+
+- [ ] **TASK-001** — Validate and authorize host updates.
+  - Depends on: none
+  - Acceptance: authorized patch succeeds; wrong owner, invalid payload and expired deadline fail
+  - Files/symbols: name verified API and service symbols during planning
+  - TDD: expected RED is denied-owner update test; GREEN is minimal authorization/validation; REFACTOR reruns unchanged behavior proof.
+  - Proof: existing project integration test command (discover exact command before execution)
+- [ ] **TASK-002** — Refresh host UI after successful mutation.
+  - Depends on: TASK-001
+  - Acceptance: host shows saved values; failed save preserves previous values and explains failure
+  - Proof: repository-native component test and manual negative path where needed
+
+## Verification ledger
+
+| Task ID | State | Command / scenario | Result | Source ref | Evidence gap |
+| --- | --- | --- | --- | --- | --- |
+| TASK-001 | pending | not run | not verified | unknown | awaiting implementation |
+| TASK-002 | pending | not run | not verified | unknown | depends on TASK-001 |
+
+## Open decisions and next step
+
+- Blocker: none assumed by the example; verify against the real spec
+- Next: TASK-001 after confirming execution authorization and Git preflight

package/skills/showdar-plan/references/plan-persistence.md

@@ -0,0 +1,25 @@
+# Adaptive Plan Persistence
+
+## Choose a location
+1. Read repo instructions and discover existing plan/ticket conventions. Existing canonical artifacts take priority.
+2. Short, single-session work stays in chat. For staged, cross-session or multi-agent work, propose a Markdown plan at the canonical plan path; use `docs/showdar/plans/<feature>.md` only when the repo has no convention.
+3. A request for advice/plan is not blanket permission to write files. Present the proposed path/content and acquire authorization as needed, then run Git preflight. If the write is blocked, leave the proposal in chat.
+4. Link the approved spec/ticket and revision. An unapproved brainstorm draft cannot become an execution-ready plan.
+
+## Durable plan contract
+- Header includes goal, plan revision, status (`proposed` / `ready` / `in-progress` / `blocked` / `completed`), spec path/reference and spec revision if applicable.
+- Include non-goals, concrete current-state evidence, chosen approach/trade-offs, risks/rollbacks and unresolved decisions.
+- Every task has stable `TASK-NNN` ID, unchecked `- [ ]`, dependency IDs, covered acceptance/decision IDs, file/symbol scope, observable behavior, edge/error cases and exact existing proof commands or a clearly labeled manual check.
+- Add a verification ledger with task ID, actual command/check, outcome, environment/ref when known and gaps. Planned checks are not actual verification.
+- Plan a RED → GREEN → REFACTOR loop for testable behavior changes. Link intended failing assertion, test command, minimum production change, and proof after refactoring. For non-applicable work label the exemption and alternate verification, without inventing a failing run.
+- Mark the first dependency-ready, not-yet-proven task as the next action; do not simply pick the first unchecked item when its prerequisites are unmet.
+
+## Ownership and completion
+- Only implementation plus passing required proof permits checking `[x]`. Absent, failed, skipped, or stale proof leaves `[ ]` and is reported as blocked or implemented-unverified.
+- A checked box is not itself proof. Repo code/tests and fresh evidence override stale narration.
+- When decisions change, increment plan revision, preserve unchanged task IDs, track superseded work and invalidate affected evidence explicitly; never erase historical results.
+- The approved spec governs product behavior; the plan does not grant Git mutation permission, merge authority or deployment privileges.
+- Workflow-state checkpoint JSON remains an independent execution record with no plan-path additions.
+
+## Handoff
+Report plan path/revision (or chat-only), what was proven, blocked/unverified task IDs, exact proof and next dependency-ready task. Never silently persist if the user only asked for a read-only plan.

package/skills/showdar-recover/SKILL.md

@@ -51,6 +51,21 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 - Re-run relevant verification before declaring recovered work complete.
 - Conflict resolution must preserve semantic intent from both sides, not just remove markers.
 
+## Recover TDD evidence
+
+- For partially completed tasks, inspect actual tests/code and the RED/GREEN/REFACTOR ledger when present. Treat old test logs and checkboxes as hints; rerun relevant proof before declaring verified-complete.
+- If interrupted in RED, make no assumption that implementation started. If interrupted in GREEN or REFACTOR, check the code against acceptance and rerun targeted test before further edits.
+- When the companion is absent, resume with the same evidence contract through Build/Test; do not fabricate a historical RED run.
+
+## Resume from persisted plans
+
+- Locate the canonical plan and matching approved spec, if present. Never presume `docs/showdar/plans/` is canonical when the repo specifies another path.
+- Compare stable task IDs, recorded revision, task checkboxes and evidence ledger with current Git changes and executable proof.
+- A checked task with stale or missing proof is `implemented-unverified`. Preserve existing and unrelated user edits and reverify rather than automatically repeating the implementation.
+- Identify the first unmet dependency-ready task, then hand it to `showdar-build`. If plan and spec conflict, stop and request a targeted plan revision.
+- Do not treat a plan file as Git/implementation authority or rewrite progress without normal preflight.
+
+
 ## Workflow
 
 ### Phase 1 — reconstruct goal

package/skills/showdar-requirements/SKILL.md

@@ -59,11 +59,17 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 ## 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.
+- If blocking product or architectural choices remain and `showdar-brainstorm` 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.
 
+## Brainstorm handoff
+
+- Reuse the complete approved Decision Brief from `showdar-brainstorm` rather than interviewing again; preserve stable decision IDs and revision.
+- If brainstorming occurred but full-spec approval is absent, stop before claiming requirements are implementation-ready.
+
+
 ## Workflow
 
 ### Phase 1 — establish the source of truth

package/skills/showdar-review/SKILL.md

@@ -53,6 +53,13 @@ description: Use when reviewing code or diffs for general correctness, architect
 - Propose glossary/ADR changes through installed `showdar-domain-model` only when a real accepted domain or architectural decision has changed.
 - Reviewing code does not authorize editing domain docs or overriding approval decisions.
 
+## Saved-plan review checks
+
+- Where relevant, compare the code diff against the canonical plan revision, linked approved spec and task evidence ledger.
+- Flag tasks whose checkboxes claim completion but whose behavior or verification receipts do not substantiate that claim.
+- Return findings linked to task IDs; Review does not grant permission to change plan state or approved decisions.
+
+
 ## Workflow
 
 ### Phase 1 — understand intent and diff

package/skills/showdar-setup/SKILL.md

@@ -20,7 +20,7 @@ description: Use when onboarding a repository, auditing project context, or prop
 
 ## When not to use
 
-- A single feature needs questions: use showdar-refine.
+- A single feature needs questions: use showdar-brainstorm.
 - An existing contract needs implementation: use the appropriate lifecycle skill.
 - The user only wants the interactive CLI installer: use showdar setup.
 

package/skills/showdar-tdd/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: showdar-tdd
+description: Use when implementing a testable behavior change or regression through a verified RED, GREEN, and REFACTOR cycle with executable evidence.
+---
+
+# Showdar TDD
+
+## Mandatory Git preflight for task-owned writes
+
+Before any test, source, config or documentation write, respect the repository's Git policy and inspect worktree state. On a protected integration branch, prepare a task branch with `showdar git-start --type <type> --name "<task>"` when the CLI is present. Before every write, require `showdar guard --mutation local-write --json` to return `ok=true` and `data.allowed=true`. If blocked, stop before editing. If the Showdar CLI is unavailable in a skills-only installation, perform the equivalent manual Git/policy preflight; never download it automatically, and never infer commit, merge, push or deployment authority.
+
+## Purpose
+
+- Deliver a bounded behavior change with evidence-backed RED → GREEN → REFACTOR.
+- Use executable behavior tests to constrain production code rather than test internal structure.
+- Keep each iteration small, reversible and aligned with the approved spec or task plan.
+- Produce task-linked proof that `showdar-build` can use without claiming unverified completion.
+- This is a portable companion skill; it does not introduce a new workflow-state stage.
+
+## When to use
+
+- The user explicitly invokes `showdar-tdd` for an actionable, testable change.
+- `showdar-build` is implementing a bounded behavior task and a runnable test boundary exists.
+- A regression with known root cause needs a test that fails before its fix.
+- A public contract, parser, business rule, state transition, or UI interaction needs demonstrable behavior proof.
+
+## When not to use
+
+- User requests only test strategy or test coverage assessment; use `showdar-test`.
+- Root cause is unknown; investigate via `showdar-debug` before coding a guessed fix.
+- Work is documentation-only, generated-only, or a pure visual reference lacking an executable harness.
+- An already-verified implementation merely needs independent checks; use `showdar-test`.
+- Requirements are materially ambiguous or approved scope is missing after brainstorming; return to the appropriate decision gate.
+
+## Inputs and assumptions
+
+- Read task acceptance criteria, current approved spec and plan task ID when supplied.
+- Inspect repository manifests, test setup and current behavior before selecting a test command.
+- Determine the actual behavioral boundary, owners and affected consumers.
+- Discover the existing test framework; do not invent package scripts or command names.
+- Read `references/red-green-refactor.md` for the evidence and exemption contract.
+- For behavior examples, read `examples/behavior-change.md` when helpful.
+
+## Non-negotiable rules
+
+- Confirm required full-spec approval if `showdar-brainstorm` was triggered; no new approval ceremony for already specified changes.
+- RED means a newly written behavioral test actually failed for the expected missing behavior; syntax, imports, environment or flaky fixture errors do not count.
+- Do not write production implementation before obtaining a meaningful RED when a reproducible harness is available.
+- GREEN means the same focused test passes after the smallest adequate implementation.
+- REFACTOR follows GREEN, changes structure without changing intended behavior, and reruns the focused tests to prove they remain green.
+- Keep one behavior/invariant per cycle; for multiple independent behaviors, repeat the cycle.
+- Do not weaken assertions, remove tests, fake outputs, mock away the behavior under test or swallow exceptions to get GREEN.
+- Preserve unrelated working-tree changes and public contracts; do not reset, clean, commit, push or merge without explicit authority.
+- When a test cannot be run, report the constraint and alternate verification; never fabricate RED, GREEN or REFACTOR receipts.
+- A checkbox, narrative or previous agent claim is not evidence of a passing test.
+
+## Workflow
+
+### Phase 1 — scope a single observable behavior
+- Read the current plan and linked spec; identify the earliest dependency-ready task.
+- Name the user-visible success condition and at least one important negative/error case.
+- Confirm existing code/test coverage and the smallest reliable test boundary.
+- If required evidence, approval or Git state is missing, stop before mutation.
+
+### Phase 2 — RED: capture a meaningful failure
+- Write the smallest new or modified automated test expressing the required behavior.
+- Run the exact targeted command against current production code.
+- Record the task ID, test location, command, expected failing assertion and observed failure.
+- If the test passes unexpectedly, determine whether behavior already exists or the test is invalid; never pretend it failed.
+- If it fails due to harness/setup/environment, repair or report the harness before claiming RED.
+
+### Phase 3 — GREEN: implement minimally
+- Change the smallest coherent production surface that satisfies the observed failing behavior.
+- Rerun the same targeted test; record the actual outcome.
+- Confirm relevant negative, boundary and error behavior rather than adding broad unrelated code.
+- If not green, iterate on the same scoped behavior without broad speculative refactors.
+
+### Phase 4 — REFACTOR: keep behavior green
+- Clean duplication, naming and ownership within the approved task only when beneficial.
+- Run the same targeted test again and ensure the observed behavior remains green.
+- If refactoring introduces failures, correct them or revert that refactor without discarding user changes.
+- Run relevant adjacent tests, typecheck/lint/build according to the repository and affected risk.
+
+### Phase 5 — handoff the proof
+- Report the task ID, changed tests and production files, exact RED/GREEN/REFACTOR evidence, broadened checks and residual gaps.
+- Only when the required proof succeeded may `showdar-build` mark the corresponding plan task `[x]` and update its verification ledger under normal Git preflight.
+- Leave a missing, failed or unverified test as `[ ]`; do not claim task completion.
+- Keep the separate `showdar-test` verification and `showdar-review` stages; TDD is not a substitute for them.
+
+## Decision points
+
+- Existing implementation already meets the new test? Stop and inspect requirements; do not manufacture a RED by breaking code.
+- Only a manual environment can demonstrate behavior? State the TDD exemption and use honest manual/contract proof.
+- Test scope spans infrastructure? Prefer the lowest effective integration level that still exercises the contract.
+- UI/native timing concerns? Use controllable event/clock boundaries rather than arbitrary sleeps.
+- Requirements or public compatibility changed during GREEN? Stop the affected task and request a revised approved decision.
+- Missing TDD companion elsewhere? `showdar-build` may follow this contract directly; never claim a companion ran when absent.
+
+## Stack detection
+
+- React/Next.js/Vite: inspect the existing Vitest/Jest/component test setup and server/client boundaries.
+- React Native: respect gesture, navigation, native and lifecycle boundaries; use installed RN testing tools.
+- Flutter: use existing `flutter test` / widget / integration-test setup only after confirming project commands.
+- Backend: choose unit for pure rules and integration for persistence/auth/protocol semantics.
+- Unsupported stacks: use repository-native tests or explicitly report no runnable test harness.
+
+## Failure modes
+
+- Claiming RED from an import error, failing unrelated suite or omitted test execution.
+- Writing implementation first and then constructing an artificial failing test narrative.
+- Accepting GREEN after weakening assertions, stubbing the very contract under test or dropping error cases.
+- Refactoring outside the task scope to make a green check look more comprehensive.
+- Checking plan tasks done based on source edits without verified proof.
+- Forcing ceremonial TDD on design mockups, docs-only tasks or unavailable harnesses.
+
+## Stop conditions
+
+- Stop when the scoped behavior has RED, GREEN and post-REFACTOR proof plus suitable broader checks.
+- Stop and report blocked if the harness or expected failure cannot be reproduced honestly.
+- Stop before unapproved spec changes, protected Git mutations, release or deployment actions.
+- If the task is already complete, report evidence without inventing a new test-first cycle.
+
+## Escalation conditions
+
+- Ask about unresolved product, auth, data or compatibility choices that materially alter behavior.
+- Return to debugging for unknown root causes or nondeterministic failures.
+- Return to plan/brainstorm for changed architecture or approved requirements.
+- Request permission before modifying unrelated user-owned files or rewriting canonical plans.
+
+## Verification
+
+- Confirm every stated test command exists and was run, or identify the unverified gap.
+- Distinguish intentional assertion RED from broken runner/configuration.
+- Verify focused behavior passes after both GREEN and REFACTOR.
+- Check relevant boundary, error and adjacent contract coverage.
+- Compare implementation against linked task/spec and report accidental scope expansion.
+
+## Output contract
+
+- **Task and invariant** — plan task ID when available, linked requirement and chosen test boundary.
+- **RED** — test/command, expected assertion, observed failure or explicit exemption.
+- **GREEN** — minimal implementation and actual passing test/command.
+- **REFACTOR** — scope of cleanup and actual post-refactor passing result.
+- **Broader checks** — commands and outcomes; distinguish unrun checks from passed checks.
+- **Handoff** — paths changed, remaining risks and plan completion recommendation, not invented authority.
+
+## Anti-patterns
+
+- Mandating an E2E test for a rule already proved at unit/integration boundary.
+- Treating test-first as a textual checklist instead of an executed failing test.
+- Confusing generated test files with a repeatable automated harness.
+- Hiding environmental failures by claiming TDD passed.
+- Treating a passing test as authority to merge, publish or skip review.
+
+## Example
+
+- In a pricing rule task, write a test asserting an exclusive upper bound and run it before changing the rate lookup. The test must fail for the expected boundary behavior.
+- Implement the smallest correct bracket comparison, prove the test now passes, clean naming without changing the contract and rerun the test.
+- Report RED, GREEN, REFACTOR commands/results to Build for task-ledger update. If no test framework exists, report the exemption and alternate verification rather than inventing output.

package/skills/showdar-tdd/examples/behavior-change.md

@@ -0,0 +1,20 @@
+# Example: rate-table exclusive upper bound (illustrative only)
+
+Task: TASK-002 — fee lookup uses a `[min, max)` bracket where `max` is exclusive.
+
+RED:
+- Write an assertion that a key equal to `max` must not match a bracket.
+- Run the repository's **existing** targeted test command against current production code.
+- Observe the intended assertion failure. A command failing because the test tool is missing is not valid RED.
+
+GREEN:
+- Make the smallest code change to implement `key >= min && key < max`.
+- Run the same focused test command and confirm it passes.
+
+REFACTOR:
+- Improve duplication/naming within the pricing change only, if needed.
+- Rerun the focused tests, relevant full suite and typecheck as appropriate.
+
+Handoff:
+- Record the exact executed commands and results under TASK-002's verification ledger.
+- Never check a task complete from this example alone; this document is explanatory, not test output.

package/skills/showdar-tdd/references/red-green-refactor.md

@@ -0,0 +1,28 @@
+# RED → GREEN → REFACTOR contract
+
+## Prerequisites
+- Confirm current approved behavior and a single task or observable invariant.
+- Determine the lowest test level that exercises the real contract and name an existing executable test command.
+- Check Git preflight before writing the test file. This companion never bypasses showdar guard or branch policy.
+
+## Evidence for RED
+- Add the smallest test targeting missing behavior, then run it **before** production edits.
+- The test must fail for a specific expected behavioral assertion. Test loader, dependency, setup, syntax, flaky timing and unrelated failures do **not** establish RED.
+- Record test path, command, observed failing assertion, environment and task ID. If the command cannot run, stop or document an exemption.
+- If the test already passes, verify whether functionality exists and whether requirements are satisfied; do not deliberately sabotage code to fake a failing test.
+
+## Evidence for GREEN
+- Implement only enough production behavior to satisfy the failure while honoring adjacent contracts.
+- Run the same targeted command and record its **actual** passing result. Do not weaken/delete assertions or replace the real boundary with a permissive mock.
+- Validate the meaningful negative path. Leave work unverified if the test remains flaky or has not run.
+
+## Evidence for REFACTOR
+- When structurally useful, refactor production or test code inside the approved task scope without changing requirements.
+- Run the same focused test again, then relevant broader suite/typecheck/lint/build checks. Record both actual results.
+- If no refactor is needed, explicitly note that and rerun the focused test to verify the final state.
+
+## Exemptions and handoff
+- A pure Markdown edit, visual specification without app harness, generated-only artifact or unavailable runner may be unsuitable for automated TDD. Record exact cause and credible alternate proof; don't write hollow tests.
+- Keep test strategy and integration/E2E coverage under showdar-test, final review under showdar-review.
+- For a persisted `docs/showdar/plans/<feature>.md` plan, record per-task RED, GREEN and REFACTOR receipts in its verification ledger **only after Git preflight** and do not mark `[x]` until full required proof exists.
+- Never invent commands, results, current source revisions or approvals. The plan ledger cannot grant Git, build or release authority.

package/skills/showdar-test/SKILL.md

@@ -51,6 +51,20 @@ Before any task-owned source/config/test/docs write, apply `showdar-git` branch
 - Keep test-only shortcuts out of production APIs.
 - Do not use snapshot-only assertions for critical behavior.
 
+## Relationship with showdar-tdd
+
+- `showdar-tdd` owns the tight RED → GREEN → REFACTOR implementation loop for a bounded behavior task, if the companion is installed.
+- This skill owns test strategy, selecting the correct boundary, regression, integration and E2E coverage and independent verification; it is not replaced by TDD.
+- When TDD is active, require genuine expected RED evidence (not configuration failure), a passing GREEN test and another passing test after REFACTOR. If the companion is absent, these behavior-first rules still apply.
+- Do not demand artificial RED proofs for docs-only work, generated assets, existing behavior re-verification or no runnable harness; state an alternative verified check.
+
+## Task-plan verification handoff
+
+- When a task plan exists, derive relevant proof cases from its task IDs, acceptance notes and linked approved spec.
+- Send concrete command/scenario and pass/fail evidence back to `showdar-build` for progress ledger updates; Test alone does not mark plan tasks completed.
+- Never treat a checked box as a test result, and never certify skipped, stale or blocked proof.
+
+
 ## Workflow
 
 ### Phase 1 — state the invariant

package/src/adapter-renderers.js

@@ -4,7 +4,7 @@ const RUNTIME_GUIDANCE = `Automatic Showdar selection: route the current request
 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.
 Before ANY task-owned source/config/test/docs write, execute Git preflight even if the router selected build directly. On integration/default branches inspect repository policy and EXECUTE \`showdar git-start --type <type> --name <task>\` (not just --dry-run), or equivalent repository-safe branch preparation. Then EXECUTE \`showdar guard --mutation local-write --json\` and require ok=true AND data.allowed=true BEFORE invoking any file-writing tool. If blocked, STOP before editing. On a matching task branch run guard without creating a new branch. Recheck before each later mutating stage. Do not infer permission from \`showdar route\`. If the CLI is unavailable, manually inspect Git and confirm the appropriate task branch or documented direct-work policy; never silently write on develop/main. Dirty ownership/branch collisions require inspection; never infer stash/reset/restore/clean. Guard and git-start do not authorize source edits, commit, merge or push. Completion means verify and report.
-Companions are portable and do not compete for canonical lifecycle primary: showdar-setup onboards a project, showdar-refine is a conditional pre-implementation decision gate requiring explicit approval of the whole spec when triggered, and showdar-domain-model maintains accepted glossary/ADR knowledge only after approved changes. If a companion is not installed, never imply it ran. Shared project context: before project work, read the relevant existing files under docs/agents/ (project.md, issue-tracker.md, verification.md, domain.md) when present. These are project-specific conventions, not mutation authority. Use the canonical glossary and ADRs when present; do not invent them. If project context is missing or stale, read repository evidence and suggest invoking installed showdar-setup when useful; showdar setup in the CLI is only an interactive skill installer.`;
+Companions are portable and do not compete for canonical lifecycle primary: showdar-setup onboards a project, showdar-brainstorm is a conditional pre-implementation decision gate requiring explicit approval of the whole spec when triggered, and showdar-domain-model maintains accepted glossary/ADR knowledge only after approved changes, and showdar-tdd is an optional RED → GREEN → REFACTOR companion within showdar-build for testable behavior tasks (not a lifecycle stage). If a companion is not installed, never imply it ran. Shared project context: before project work, read the relevant existing files under docs/agents/ (project.md, issue-tracker.md, verification.md, domain.md) when present. These are project-specific conventions, not mutation authority. Use the canonical glossary and ADRs when present; do not invent them. If project context is missing or stale, read repository evidence and suggest invoking installed showdar-setup when useful; showdar setup in the CLI is only an interactive skill installer.`;
 
 const CANONICAL_ROUTE_ORDER = [
   ['map repository architecture, dependencies, or impact', 'showdar-understand'],

package/src/catalog.js

@@ -21,7 +21,8 @@ export const SKILLS = [
 
 export const COMPANION_SKILLS = [
   { id: 'showdar-setup', kind: 'companion', domain: 'onboarding', description: 'Use when onboarding a repository, auditing project context, or proposing grounded glossary and agent documentation improvements.' },
-  { id: 'showdar-refine', kind: 'companion', domain: 'refinement', description: 'Use when a feature idea or implementation request has unresolved product or architecture decisions that require interactive refinement and explicit spec approval.' },
+  { id: 'showdar-brainstorm', kind: 'companion', domain: 'brainstorming', description: 'Use when brainstorming feature ideas, challenging assumptions, comparing alternatives, and approving a complete spec before implementation.' },
+  { id: 'showdar-tdd', kind: 'companion', domain: 'tdd', description: 'Use when implementing a testable behavior change or regression through a verified RED, GREEN, and REFACTOR cycle with executable evidence.' },
   { id: 'showdar-domain-model', kind: 'companion', domain: 'domain', description: 'Use when clarifying shared domain terminology, maintaining an evidence-backed glossary, or documenting confirmed architectural decisions as ADRs.' },
 ];
 
@@ -50,10 +51,10 @@ const ids = (...values) => values;
 
 export const PROFILES = {
   minimal: ids('showdar-understand', 'showdar-plan', 'showdar-build', 'showdar-debug', 'showdar-test', 'showdar-review', 'showdar-recover', 'showdar-git'),
-  developer: ids('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'),
-  backend: ids('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'),
-  qa: ids('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'),
-  product: ids('showdar-understand', 'showdar-requirements', 'showdar-plan', 'showdar-design', 'showdar-quality', 'showdar-review', 'showdar-setup', 'showdar-refine', 'showdar-domain-model'),
+  developer: ids('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-brainstorm', 'showdar-domain-model', 'showdar-tdd'),
+  backend: ids('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-brainstorm', 'showdar-domain-model', 'showdar-tdd'),
+  qa: ids('showdar-understand', 'showdar-requirements', 'showdar-quality', 'showdar-test', 'showdar-debug', 'showdar-review', 'showdar-ship', 'showdar-recover', 'showdar-git', 'showdar-setup', 'showdar-brainstorm', 'showdar-domain-model', 'showdar-tdd'),
+  product: ids('showdar-understand', 'showdar-requirements', 'showdar-plan', 'showdar-design', 'showdar-quality', 'showdar-review', 'showdar-setup', 'showdar-brainstorm', 'showdar-domain-model'),
   insurance: ids('showdar-insurance-domain', 'showdar-insurance-workflows', 'showdar-insurance-review'),
   full: [...SKILLS, ...COMPANION_SKILLS].map((skill) => skill.id),
 };

package/src/project.js

@@ -170,6 +170,34 @@ async function generateCommandFiles({ baseRoot, skillIds, target, commandRoot, p
 }
 
 // Legacy custom commands collided with native /showdar-setup skill invocation.
+// The retired skill is not a runnable alias. Delete only pristine managed copies.
+function isLegacyBrainstormPath(relative) {
+  return typeof relative === 'string' &&
+    (/(^|\/)skills\/showdar-refine$/.test(relative) ||
+      /(^|\/)commands\/showdar\/refine\.md$/.test(relative));
+}
+
+async function inspectLegacyBrainstormFiles({ baseRoot, manifest, scope, homeRoot = homedir(), managedRoots = [] }) {
+  const entries = (manifest?.files ?? []).filter(entry => isLegacyBrainstormPath(entry.path));
+  const results = [];
+  for (const entry of entries) {
+    const target = safeOwnedPath(baseRoot, entry.path, managedRoots);
+    if (!target || !isManagedDeletionTarget(baseRoot, target, scope, homeRoot, manifest)) {
+      throw new Error('Unsafe retired Showdar skill path: ' + entry.path);
+    }
+    await assertSafeManagedPath(baseRoot, target, managedRoots);
+    if (await exists(target) && await hashTree(target) !== entry.hash) {
+      throw new Error('Modified retired Showdar skill; preserve user changes before migrating: ' + entry.path);
+    }
+    results.push({ path: entry.path, target });
+  }
+  return results;
+}
+
+function migrateBrainstormSelection(ids) {
+  return [...new Set(ids.map(id => id === 'showdar-refine' ? 'showdar-brainstorm' : id))];
+}
+
 function isLegacySetupCommandPath(relative) {
   return typeof relative === 'string' && /(^|\/)commands\/showdar-setup\.md$/.test(relative);
 }
@@ -196,7 +224,9 @@ async function inspectLegacySetupCommands({ baseRoot, manifest, scope, homeRoot
 }
 
 async function removeLegacySetupCommands(entries) {
-  for (const entry of entries) await rm(entry.target, { force: true });
+  // Entries have already passed ownership/path and hash checks; native skill
+  // directories require recursive removal, legacy commands are regular files.
+  for (const entry of entries) await rm(entry.target, { recursive: true, force: true });
 }
 
 async function initInstallation({
@@ -305,6 +335,9 @@ async function initInstallation({
       if (isLegacySetupCommandPath(entry.path) && await exists(targetPath) && await hashTree(targetPath) !== entry.hash) {
         throw new Error('Modified legacy Showdar setup command; resolve the conflict before migrating: ' + entry.path);
       }
+      if (isLegacyBrainstormPath(entry.path) && await exists(targetPath) && await hashTree(targetPath) !== entry.hash) {
+        throw new Error('Modified retired Showdar skill; preserve user changes before migrating: ' + entry.path);
+      }
       staleTargets.push(targetPath);
     }
   }
@@ -717,6 +750,23 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
       : [],
   });
   const legacyPaths = new Set(legacyCommands.map(entry => entry.path));
+  const migrationManagedRoots = migrationScope === 'global'
+    ? [...new Set([
+        ...NATIVE_TARGETS.map(t => globalSkillRootFor(t, { homeRoot: home })),
+        ...NATIVE_TARGETS.filter(t => globalCommandRootForTarget(t, { homeRoot: home })).map(t => globalCommandRootForTarget(t, { homeRoot: home })),
+      ])]
+    : [];
+  // On explicit add brainstorm, migrate preexisting CLI-owned v0.16 skill/commands;
+  // other adds leave the old managed selection until an explicit profile upgrade.
+  const migratingBrainstorm = skillId === 'showdar-brainstorm' && existingManifest?.skills?.includes('showdar-refine');
+  const retiredFiles = migratingBrainstorm
+    ? await inspectLegacyBrainstormFiles({ baseRoot: migrationRoot, manifest: existingManifest, scope: migrationScope, homeRoot: home, managedRoots: migrationManagedRoots })
+    : [];
+  const retiredPaths = new Set(retiredFiles.map(entry => entry.path));
+  const removedPaths = new Set([...legacyPaths, ...retiredPaths]);
+  const migratedSkills = migratingBrainstorm
+    ? migrateBrainstormSelection(existingManifest.skills)
+    : existingManifest?.skills ?? [];
   const effectiveAi = ai ?? existingManifest?.ai ?? 'universal';
   const effectiveScope = scope ?? existingManifest?.scope ?? 'project';
   if (effectiveAi !== 'all' && !NATIVE_TARGETS.includes(effectiveAi)) throw new Error(`Unknown AI target "${effectiveAi}".`);
@@ -754,19 +804,19 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
     }
     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 (commandRoot) await generateCommandFiles({ baseRoot, skillIds: migratedSkills, 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 (instruction.kind === 'block') await writeManagedBlock(file, migratedSkills);
+      else if (instruction.kind === 'file') await writeCursorRule(file, migratedSkills);
     }
-    await removeLegacySetupCommands(legacyCommands);
-    const files = new Map((existingManifest.files ?? []).filter(f => !legacyPaths.has(f.path)).map(f => [f.path, f]));
+    await removeLegacySetupCommands([...legacyCommands, ...retiredFiles]);
+    const files = new Map((existingManifest.files ?? []).filter(f => !removedPaths.has(f.path)).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, packageVersion, commands: (existingManifest.commands ?? []).filter(c => !legacyPaths.has(c.path)), files: [...files.values()] });
+      { ...existingManifest, packageVersion, skills: migratedSkills, commands: (existingManifest.commands ?? []).filter(c => !removedPaths.has(c.path)), files: [...files.values()] });
     return { skill: skillId, root: '', destination: '', added: false, scope: effectiveScope, ai: effectiveAi, profile: existingManifest.profile };
   }
 
@@ -813,7 +863,7 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
     }
   }
 
-  const allSkillIds = [...new Set([...(existingManifest?.skills ?? []), skillId])];
+  const allSkillIds = [...new Set([...migratedSkills, skillId])];
   const newCommands = [];
   const harnessTargets = [...new Set([...(existingManifest?.commandHarness ?? []), ...commandHarnesses.map(c => c.target)])];
   for (const target of harnessTargets) {
@@ -823,8 +873,8 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
     newCommands.push(...generated.map(c => ({ target, name: c.shortName, path: manifestPathFor(baseRoot, c.destination) })));
   }
 
-  await removeLegacySetupCommands(legacyCommands);
-  const merged = new Map((existingManifest?.files ?? []).filter(e => !legacyPaths.has(e.path)).map((e) => [e.path, e]));
+  await removeLegacySetupCommands([...legacyCommands, ...retiredFiles]);
+  const merged = new Map((existingManifest?.files ?? []).filter(e => !removedPaths.has(e.path)).map((e) => [e.path, e]));
   for (const f of files) merged.set(f.path, f);
 
   const instructionFile = existingManifest?.instructions ?? (effectiveScope === 'project' ? instructionSurfaceFor(effectiveAi === 'all' ? 'universal' : effectiveAi, cwd) : null);
@@ -840,7 +890,7 @@ export async function addSkill({ cwd, skill, ai = null, scope = null, home = hom
     targets: [...new Set([...(existingManifest?.targets ?? []), ...targets])],
     skills: allSkillIds,
     satisfiedByGlobal: existingManifest?.satisfiedByGlobal ?? [],
-    commands: [...new Map([...(existingManifest?.commands ?? []).filter(c => !legacyPaths.has(c.path)), ...newCommands].map(c => [c.path, c])).values()],
+    commands: [...new Map([...(existingManifest?.commands ?? []).filter(c => !removedPaths.has(c.path)), ...newCommands].map(c => [c.path, c])).values()],
     files: [...merged.values()],
     instructions: instructionFile ? { file: instructionFile.file, kind: instructionFile.kind } : null,
     commandHarness,

package/src/validate.js

@@ -336,8 +336,8 @@ export async function validateRepository(packageRoot) {
 
   if (SKILLS.length !== PRIMITIVE_COUNT || PRIMITIVE_COUNT !== 18) errors.push(`primitive skill count must remain 18 (found ${SKILLS.length})`);
   if (WORKFLOW_SKILLS.length !== WORKFLOW_COUNT || WORKFLOW_COUNT !== 4) errors.push(`workflow skill count must be 4 (found ${WORKFLOW_SKILLS.length})`);
-  if (COMPANION_SKILLS.length !== COMPANION_COUNT || COMPANION_COUNT !== 3) errors.push(`companion skill count must be 3 (found ${COMPANION_SKILLS.length})`);
-  if (ALL_SKILLS.length !== TOTAL_COUNT || TOTAL_COUNT !== 25) errors.push(`total installable skill count must be 25 (found ${ALL_SKILLS.length})`);
+  if (COMPANION_SKILLS.length !== COMPANION_COUNT || COMPANION_COUNT !== 4) errors.push(`companion skill count must be 4 (found ${COMPANION_SKILLS.length})`);
+  if (ALL_SKILLS.length !== TOTAL_COUNT || TOTAL_COUNT !== 26) errors.push(`total installable skill count must be 26 (found ${ALL_SKILLS.length})`);
 
   for (const error of validateCapabilities().errors) errors.push(`capabilities: ${error}`);