@jabworks/condux 0.1.1 → 0.3.0

package/skills/technical-spec/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: technical-spec
+description: Use when a feature plan, design session, or implementation milestone is complete and the decisions, API contracts, implementation details, and quirks should be persisted for future reference. Also use when the user says "save spec", "document this", "write up what we decided", or "spec this out".
+disable-model-invocation: true
+---
+
+# Save Tech Spec
+
+## Overview
+
+Persists feature decisions, API contracts, implementation details, and quirks into a structured, queryable spec tree. One folder per feature, one file per concern — future sessions load only what they need. Specs are living contracts: `/preflight`'s Drift Check compares the implementation against them at end-of-task.
+
+## Spec Folder Layout
+
+All specs live under one `specs/` tree at the **git root**, mirroring the
+repo structure. The scaffold script detects the nearest package root (walking
+up from CWD to the git root, finding the first `package.json`, `Cargo.toml`,
+`go.mod`, or `pyproject.toml`) and uses its path *relative to the git root*
+to place the spec.
+
+```
+<git-root>/specs/
+  {feature-slug}/           # cross-cutting, or scaffolded from the repo root
+  apps/web/
+    {feature-slug}/         # scaffolded while working in apps/web
+      index.md              # TOC, last updated, commit hash, changelog  ← scaffold creates this
+      decisions.md          # Design decisions with context + rationale
+      api.md                # Endpoints, types, external APIs consumed
+      fields.md             # Field mappings: BE/3rd-party → UI, or forwarding chains
+      implementation.md     # Key files, patterns, how it hangs together
+      quirks.md             # Edge cases, gotchas, known issues
+```
+
+Slugs are kebab-case and acronym-aware: `WanConfig` → `wan-config`,
+`UIFormControls` → `ui-form-controls`.
+
+In a single-package repo the package root is the git root, so specs land at
+`specs/<slug>/`. In a monorepo working on `apps/web`, they land at
+`specs/apps/web/<slug>/` — one browsable tree, with a natural home for
+cross-cutting features at `specs/<slug>/`.
+
+Existing specs co-located inside packages (`apps/web/specs/…`) are not
+auto-migrated — `git mv` them into the root tree if you want them unified.
+
+Only create files that have actual content. Don't create empty files.
+
+## Workflow
+
+```dot
+digraph save_spec {
+    rankdir=TB;
+    "Infer feature name from context" [shape=box];
+    "Feature name clear?" [shape=diamond];
+    "Ask user for feature name" [shape=box];
+    "Notify user — confirm before writing" [shape=box];
+    "User approves?" [shape=diamond];
+    "Stop" [shape=box];
+    "Run scaffold.sh <feature>" [shape=box];
+    "Output: exists or created?" [shape=diamond];
+    "Write content files, update index.md Contents" [shape=box];
+    "Read index.md, update changed files only" [shape=box];
+    "Ask: open live HTML preview?" [shape=diamond];
+    "Locate + run plan-review annotate-server.js on the spec dir" [shape=box];
+    "Tell user: Ctrl+C when done reviewing" [shape=box];
+    "Done" [shape=doublecircle];
+
+    "Infer feature name from context" -> "Feature name clear?";
+    "Feature name clear?" -> "Notify user — confirm before writing" [label="yes"];
+    "Feature name clear?" -> "Ask user for feature name" [label="no"];
+    "Ask user for feature name" -> "Notify user — confirm before writing";
+    "Notify user — confirm before writing" -> "User approves?";
+    "User approves?" -> "Stop" [label="no"];
+    "User approves?" -> "Run scaffold.sh <feature>" [label="yes"];
+    "Run scaffold.sh <feature>" -> "Output: exists or created?";
+    "Output: exists or created?" -> "Write content files, update index.md Contents" [label="created"];
+    "Output: exists or created?" -> "Read index.md, update changed files only" [label="exists"];
+    "Write content files, update index.md Contents" -> "Ask: open live HTML preview?";
+    "Read index.md, update changed files only" -> "Ask: open live HTML preview?";
+    "Ask: open live HTML preview?" -> "Locate + run plan-review annotate-server.js on the spec dir" [label="yes"];
+    "Ask: open live HTML preview?" -> "Done" [label="no"];
+    "Locate + run plan-review annotate-server.js on the spec dir" -> "Tell user: Ctrl+C when done reviewing";
+    "Tell user: Ctrl+C when done reviewing" -> "Done";
+}
+```
+
+## Required Notifications
+
+Always announce and confirm before writing or editing. Never silently modify files.
+
+New spec:
+```
+About to save tech spec for `wan-config` → specs/wan-config/
+Proceed? [y/n]
+```
+
+Updating existing spec:
+```
+Updating spec for `wan-config` (last saved: 2026-06-20, commit abc1234)
+Files to update: decisions.md, quirks.md
+Proceed? [y/n]
+```
+
+## Running the Scaffold Script
+
+The script lives next to this skill file. Find it relative to where this SKILL.md was loaded from:
+
+```bash
+bash path/to/skill/references/scaffold.sh "WanConfig"
+```
+
+The script outputs one line:
+- `created:/abs/path/to/specs/wan-config commit:abc1234 date:2026-06-24` — new spec, `index.md` written
+- `exists:/abs/path/to/specs/wan-config commit:abc1234 date:2026-06-24` — spec already exists
+
+Parse `commit`, `date`, and the **absolute spec path** from the output — use the absolute path when writing content files and launching the preview server.
+
+## After Scaffold: Writing Content Files
+
+Read [references/templates.md](references/templates.md) for the structure of each file.
+
+- Write only files that have real content
+- After writing, update the `## Contents` section in `index.md` with links to the files you created
+
+## Updating an Existing Spec
+
+When scaffold output is `exists:`:
+1. Read `index.md` to see current state and which files exist
+2. Update only files with new or changed content
+3. Bump `Last updated` and `Commit` in `index.md` using values from scaffold output
+4. Append to the `## Changelog` in `index.md`
+
+## Live HTML Preview & Review (Optional)
+
+Spec preview is served by the **plan-review** skill's annotate server in
+directory mode — the same annotation UI used for plan review, so the user can
+not only read the spec live but select text, attach notes per file, and submit
+a decision.
+
+After writing spec files, ask:
+
+```
+Spec saved. Want a live HTML preview? It renders all spec files, updates as you edit, and lets you annotate. [y/n]
+```
+
+If yes, locate the plan-review server script:
+
+```bash
+find ~/.claude ~/.codex ~/.agents -name "annotate-server.js" -path "*plan-review*" 2>/dev/null | head -1
+```
+
+Run it in the background, pointing at the spec folder:
+
+```bash
+node /path/to/plan-review/references/annotate-server.js specs/wan-config
+```
+
+It opens the browser automatically, lists every top-level `.md` in the folder
+(Contents tab), watches for file changes, and re-renders live. If the user
+submits a decision, it lands in `specs/<slug>/review.feedback.md` with notes
+grouped by file — read it and action it:
+
+- **Approve** — the spec is accurate; nothing to do.
+- **Request Revisions** — fix the spec files per the notes.
+
+Spec review is accept-or-fix, so the bar shows only these two verdicts (the
+plan-only "Reject / don't build it" verdict is hidden in directory mode). If
+the spec's whole premise is wrong, the user leaves a note saying so and stops
+the server — treat that as a cue to discuss before rewriting, not a routine
+revision.
+
+Tell the user:
+
+```
+Preview running. Edit your spec files and the browser updates live.
+Annotate and submit a decision, or just press Ctrl+C in the terminal when done.
+```
+
+The server is in-memory only — no HTML files are written to disk (only the
+feedback file, if a decision is submitted).
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Skipping the notification/confirmation | Always announce before writing, wait for approval |
+| Not using scaffold output for date/commit | Parse them from the script — don't run git separately |
+| Rewriting all files on update | Read `index.md` first, only touch files with new content |
+| Vague decisions | Each decision needs context + rationale + consequences |
+| Creating empty placeholder files | Only create a file when it has real content |
+| Forgetting to update index.md Contents | Always link to files you create |

package/skills/technical-spec/evals/trigger_eval.json

@@ -0,0 +1,23 @@
+[
+  { "query": "save spec", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "document what we decided", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "spec this out", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "persist the api contract and the quirks we found", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "write up the field mappings from backend to UI", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "update the spec for wan-config", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "scaffold a spec folder for this feature", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "whats the format for quirks.md", "should_trigger": true, "expected_skill": "technical-spec", "kind": "in-context" },
+  { "query": "record the decision rationale for future sessions", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "bump the index.md changelog for the spec", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "save the design as a tech spec with live preview", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "sepc this out pls", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "write up what we decided about the milestone", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "update the spec with what we built", "should_trigger": true, "expected_skill": "technical-spec" },
+  { "query": "load the spec for checkout before we start the task", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "browse the specs tree", "should_trigger": true, "expected_skill": "spec-browser" },
+  { "query": "where is the spec for the auth feature", "should_trigger": true, "expected_skill": "spec-browser" },
+  { "query": "design the feature first before documenting", "should_trigger": true, "expected_skill": "discovery" },
+  { "query": "generate openapi yaml from the routes", "should_trigger": false, "expected_skill": null },
+  { "query": "write jsdoc comments for this module", "should_trigger": false, "expected_skill": null },
+  { "query": "host our swagger docs somewhere", "should_trigger": false, "expected_skill": null }
+]

package/skills/technical-spec/references/scaffold.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Scaffolds a new tech spec directory for a feature.
+# Usage: scaffold.sh <FeatureName or feature-name>
+# Output (one line):
+#   created:<absolute-spec-path> commit:<hash> date:<YYYY-MM-DD>
+#   exists:<absolute-spec-path>  commit:<hash> date:<YYYY-MM-DD>
+#
+# Spec location: <git-root>/specs/<pkg-relpath>/<slug>/
+# pkg-relpath = path of the nearest package root (first directory above CWD
+# with package.json, Cargo.toml, go.mod, or pyproject.toml) relative to the
+# git root — empty when they coincide, giving <git-root>/specs/<slug>/.
+# All specs live under the root specs/ tree, mirroring the repo structure.
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: scaffold.sh <feature-name>" >&2
+  exit 1
+fi
+
+INPUT="$*"
+
+# PascalCase or spaces → kebab-case, acronym-aware: dashes go only at
+# lower/digit→Upper and UPPER→Upper+lower boundaries, so AOGrcIntegration →
+# ao-grc-integration and UIFormControls → ui-form-controls. Kebab input
+# passes through unchanged.
+SLUG=$(echo "$INPUT" \
+  | sed 's/\([a-z0-9]\)\([A-Z]\)/\1-\2/g' \
+  | sed 's/\([A-Z]\)\([A-Z][a-z]\)/\1-\2/g' \
+  | tr '[:upper:]' '[:lower:]' \
+  | tr ' _' '-' \
+  | tr -s '-' \
+  | sed 's/^-//; s/-$//')
+
+if [[ -z "$SLUG" || ! "$SLUG" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+  echo "ERROR: feature name must produce a kebab-case slug (letters, numbers, and hyphens only): $INPUT" >&2
+  exit 1
+fi
+
+DATE=$(date +%Y-%m-%d)
+COMMIT=$(git rev-parse --short HEAD 2>/dev/null || echo "no-git")
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+[[ -z "$REPO_ROOT" ]] && REPO_ROOT="${PWD}"
+
+# ---------------------------------------------------------------------------
+# Detect package root: nearest dir with a package manifest, up to git root.
+# Used only to compute the path relative to the git root — specs themselves
+# always live under <git-root>/specs/, mirroring the repo structure.
+# ---------------------------------------------------------------------------
+detect_spec_base() {
+  local dir="${PWD}"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "$dir/package.json" || -f "$dir/Cargo.toml" || \
+          -f "$dir/go.mod"       || -f "$dir/pyproject.toml" ]]; then
+      echo "$dir"
+      return
+    fi
+    [[ "$dir" == "$REPO_ROOT" ]] && break
+    dir=$(dirname "$dir")
+  done
+  echo "$REPO_ROOT"
+}
+
+SPEC_BASE=$(detect_spec_base)
+PKG_REL="${SPEC_BASE#"$REPO_ROOT"}"
+PKG_REL="${PKG_REL#/}"
+if [[ -n "$PKG_REL" ]]; then
+  SPEC_DIR="$REPO_ROOT/specs/$PKG_REL/$SLUG"
+else
+  SPEC_DIR="$REPO_ROOT/specs/$SLUG"
+fi
+
+case "$SPEC_DIR" in
+  "$REPO_ROOT/specs/"*) ;;
+  *) echo "ERROR: resolved spec path escapes $REPO_ROOT/specs: $SPEC_DIR" >&2; exit 1 ;;
+esac
+
+if [[ -d "$SPEC_DIR" ]]; then
+  echo "exists:$SPEC_DIR commit:$COMMIT date:$DATE"
+  exit 0
+fi
+
+mkdir -p "$SPEC_DIR"
+
+cat > "$SPEC_DIR/index.md" <<EOF
+# $INPUT — Tech Spec
+
+**Last updated:** $DATE
+**Commit:** $COMMIT
+**Status:** draft
+
+## Contents
+
+## Changelog
+- $DATE ($COMMIT): Initial spec
+EOF
+
+echo "created:$SPEC_DIR commit:$COMMIT date:$DATE"

package/skills/technical-spec/references/templates.md

@@ -0,0 +1,159 @@
+# Spec File Templates
+
+Copy-paste templates for each spec file. Omit sections that don't apply — don't leave empty headings.
+
+---
+
+## index.md
+
+```markdown
+# {Feature Name} — Tech Spec
+
+**Last updated:** {YYYY-MM-DD}
+**Commit:** {short-hash}
+**Status:** draft | review | stable
+
+## Contents
+- [Decisions](decisions.md) — why we built it this way
+- [API](api.md) — contracts, endpoints, types
+- [Fields](fields.md) — field mappings: BE/3rd-party → UI
+- [Implementation](implementation.md) — how it works, key files
+- [Quirks](quirks.md) — edge cases and gotchas
+
+## Changelog
+- {YYYY-MM-DD} ({short-hash}): Initial spec
+```
+
+---
+
+## decisions.md
+
+```markdown
+# Decisions — {Feature Name}
+
+## {Decision Title}
+
+**Date:** {YYYY-MM-DD}
+**Status:** accepted | superseded | deprecated
+
+### Context
+Why this decision needed to be made. What constraints or requirements drove it.
+
+### Decision
+What was decided, stated clearly.
+
+### Rationale
+Why this over the alternatives. Include alternatives considered and why they were rejected.
+
+### Consequences
+What changes as a result — positive and negative trade-offs.
+```
+
+---
+
+## api.md
+
+```markdown
+# API — {Feature Name}
+
+## Endpoints
+
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| GET | /api/... | ... | Bearer |
+
+## Key Types / Schemas
+
+\`\`\`typescript
+interface ExampleType {
+  id: string;
+  // ...
+}
+\`\`\`
+
+## External APIs Consumed
+
+| Service | Purpose | Notes |
+|---------|---------|-------|
+| {Service} | {What we use it for} | {Rate limits, quirks} |
+```
+
+---
+
+## fields.md
+
+```markdown
+# Fields — {Feature Name}
+
+Document which fields flow from source (BE or 3rd-party API) to destination (UI or your BE),
+with descriptions so you can glance at the spec instead of traversing the codebase.
+
+## Response Fields — {Endpoint or Source Name}
+
+> Source: `GET /api/...` or `{ThirdParty} → BE → FE`
+
+| Source Field | UI Label / FE Key | Type | Nullable | Description |
+|---|---|---|---|---|
+| `user_full_name` | Full Name | `string` | no | Display name shown in profile card |
+| `created_at` | Created | `string (ISO 8601)` | no | Formatted to `MMM D, YYYY` in UI |
+| `metadata.region` | Region | `string` | yes | Omitted from UI when null |
+
+### Forwarding Chain (3rd-party → BE → FE)
+
+Use this sub-section when your BE proxies a 3rd-party API and renames fields.
+
+| 3rd-party Field | BE Field | FE Key | Notes |
+|---|---|---|---|
+| `usr_nm` | `username` | `username` | Renamed at BE layer |
+| `acct_bal` | `accountBalance` | `balance` | Converted cents → dollars at BE |
+
+## Request Fields — {Endpoint or Action Name}
+
+> Sent from FE to `POST /api/...`
+
+| FE Key | BE Field | Type | Required | Description |
+|---|---|---|---|---|
+| `email` | `email` | `string` | yes | Validated client-side before send |
+| `preferredName` | `preferred_name` | `string` | no | Optional; omitted if empty |
+```
+
+---
+
+## implementation.md
+
+```markdown
+# Implementation — {Feature Name}
+
+## Overview
+One paragraph on how the feature works end-to-end.
+
+## Key Files
+
+| File | Role |
+|------|------|
+| `src/...` | ... |
+
+## Data Flow
+Step-by-step description of how data moves through the system.
+
+## Patterns Used
+Non-obvious patterns, abstractions, or conventions introduced.
+
+## Dependencies
+Internal modules or external packages this feature leans on heavily.
+```
+
+---
+
+## quirks.md
+
+```markdown
+# Quirks — {Feature Name}
+
+## {Quirk Title}
+
+**Severity:** low | medium | high
+**Discovered:** {date or commit}
+
+Description of the edge case, gotcha, or known issue. Include what triggers it and how it's handled or worked around.
+```

package/skills/test-first-development/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: test-first-development
+description: "Tests-first development — write tests before implementation. Opt-in only. Get one upfront consent (write tests first + auto-run), then run the cycle without re-asking. Still always ask before updating existing test specs. Never silently rewrite test specs to match new behavior. Trigger when the user explicitly asks for tests-first, picks it at a workflow checkpoint, or when implementing logic with clear input/output behavior. Also triggers whenever an existing test spec is about to be edited to make it pass — that decision runs through this skill."
+argument-hint: "<what to test>"
+---
+
+# /test-first-development
+
+Tests first, implementation second. But only when you've asked for it.
+
+## Usage
+
+```
+/test-first-development $ARGUMENTS
+```
+
+## The Ask Rules
+
+**One upfront consent, then work.** At skill start, ask once:
+
+```
+"Tests-first for this task: I'll write failing tests, auto-run them
+ through each red-green-refactor cycle, and implement against them.
+ Ok to proceed?"
+```
+
+Wait for yes. After that, do **not** re-ask before writing new tests or
+running them — the cycle needs fast red-green feedback, and re-asking at
+every step is noise. If invoked from a `/workflow` checkpoint where the
+user already picked "Write tests first", that pick *is* the consent —
+start immediately.
+
+**The one standing exception — updating existing test specs.** Always ask
+before modifying any existing test file:
+
+```
+"This change affects existing test specs — want me to update them,
+ or review the diffs first?"
+```
+
+Never silently update an existing spec. That is a decision point every time.
+
+## The RED-GREEN-REFACTOR Cycle
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                      TDD CYCLE                                  │
+├──────────────────────────────────────────────────────────────────┤
+│  RED                                                            │
+│  → Write the failing test                                       │
+│  → Run it — it must fail before moving on                       │
+│    (a test that passes immediately proves nothing)              │
+│                                                                  │
+│  GREEN                                                          │
+│  → Write the minimal implementation to make it pass            │
+│  → Run it — it must pass before moving on                       │
+│                                                                  │
+│  REFACTOR                                                       │
+│  → Clean up without changing behavior                           │
+│  → Run the tests again — they must still pass                   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Run only the relevant test file(s) during the cycle — the full suite
+belongs to `/finalize`.
+
+## What Makes a Good Test
+
+```
+✓ Tests behavior, not implementation details
+✓ One clear assertion per test
+✓ Descriptive name: "should return error when token is expired"
+✓ Tests edge cases discovered during thinking, not after
+✓ Independent — doesn't rely on other tests running first
+
+✗ Tests internal function calls or private methods
+✗ Tests that only pass because of the implementation you just wrote
+✗ Vague names: "test1", "should work"
+✗ Tests that need other tests to run first
+```
+
+## Updating Existing Test Specs
+
+This is the most dangerous operation in TDD. Silently rewriting specs to make a bug fix pass is how bugs get buried.
+
+Before touching any existing test file:
+
+1. Show the current spec and what would change
+2. Explain why the change is necessary (behavior change vs. test was wrong)
+3. Wait for explicit approval
+
+```
+Legitimate reasons to update a spec:
+  ✓ The feature behavior intentionally changed (product decision)
+  ✓ The test was testing the wrong thing (implementation detail)
+  ✓ The test was brittle/flaky and needs a better assertion
+
+NOT legitimate:
+  ✗ "The test was failing so I updated it to match the new output"
+  ✗ "The behavior changed as a side effect of the fix"
+```
+
+## When TDD Applies (and When It Doesn't)
+
+```
+Good candidates for TDD:
+  ✓ Pure functions with clear inputs/outputs
+  ✓ Utility logic (date formatting, currency, validation)
+  ✓ API handlers with predictable request/response shapes
+  ✓ Bug fixes where a failing test proves the bug exists
+
+Poor candidates (don't force TDD here):
+  ✗ UI layout and visual components
+  ✗ Framework glue code (wiring up routes, registering providers)
+  ✗ One-off scripts or migrations
+  ✗ Prototyping — test after shape is clear
+```
+
+## See Also
+
+- `references/rationalization-table.md` — common rationalizations for skipping tests-first and why they're wrong

package/skills/test-first-development/evals/trigger_eval.json

@@ -0,0 +1,22 @@
+[
+  { "query": "write tests first for this", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "tdd this feature", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "test-first for the parser module", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "write failing tests before implementing", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "red green refactor cycle please", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "can you do this test driven", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "write unit tests for the date helpers before you code them", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "update the failing test to match the new behavior", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "the test is failing so just fix the test", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "should I tdd ui components", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "you already asked once, dont re-ask each cycle right?", "should_trigger": true, "expected_skill": "test-first-development", "kind": "in-context" },
+  { "query": "bug: prove it with a failing test then fix it", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "tets first plz", "should_trigger": true, "expected_skill": "test-first-development" },
+  { "query": "add tests for the existing legacy code", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "implement the currency formatter utility", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "write e2e tests with playwright for the flow", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "run the tests", "should_trigger": true, "expected_skill": "finalize" },
+  { "query": "why is this test flaky", "should_trigger": true, "expected_skill": "root-cause-analysis" },
+  { "query": "jest config setup for the monorepo", "should_trigger": true, "expected_skill": "workflow" },
+  { "query": "wheres the coverage report hosted", "should_trigger": false, "expected_skill": null }
+]

package/skills/test-first-development/references/rationalization-table.md

@@ -0,0 +1,16 @@
+# Tests-First Rationalization Table
+
+Common rationalizations agents (and developers) use to skip writing tests — and why they're wrong.
+
+| Rationalization                                        | Reality                                                                                                                                      | Counter                                                                                         |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| "This change is too small to need a test"              | Small changes break things too. The test takes 2 minutes.                                                                                    | Write the test. It documents the behavior even if it never catches a regression.                |
+| "I'll write tests after the implementation is working" | Tests written after are biased by the implementation you built. You test what you know works, not what could break.                          | Tests first force you to think about edge cases before you're anchored to an implementation.    |
+| "The existing tests cover this"                        | They cover the old behavior. The new behavior needs its own test.                                                                            | Add a test for the new behavior. Don't assume coverage.                                         |
+| "This is just UI, tests don't apply"                   | Logic in UI components (conditional rendering, state transitions, handlers) can and should be tested. Layout doesn't need tests. Logic does. | Separate the logic from the layout. Test the logic.                                             |
+| "We're moving fast, we'll add tests later"             | "Later" doesn't come. The feature ships, the next feature starts, the tests never get written.                                               | Tests now are cheaper than debugging later. The test is part of the task, not optional cleanup. |
+| "The type system already catches this"                 | Types catch shape errors. Tests catch behavioral errors. These are different things.                                                         | Types and tests are complementary, not substitutes.                                             |
+| "Running tests takes too long"                         | Running the specific test for the specific change takes seconds.                                                                             | Run only the relevant test file, not the full suite.                                            |
+| "I need to update the spec to make the test pass"      | If you're rewriting the spec to match new output, you're not fixing a bug — you're hiding one.                                               | Stop. Explain what changed and why. Get explicit approval before touching existing specs.       |
+| "This is a prototype, no tests needed"                 | Prototypes become production code. Untested prototypes become untested production code.                                                      | Decide: is this throwaway? If yes, delete it. If it might ship, test the core logic.            |
+| "The test is too hard to write"                        | If the test is hard to write, the code is too coupled or too complex.                                                                        | Hard-to-test code is a design smell. Simplify the code, then write the test.                    |