@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/php/references/type-system.md

@@ -0,0 +1,220 @@
+# PHP type system — depth
+
+Offloaded from SKILL.md. Patterns and edge cases for enums, docblock generics,
+`readonly`/`clone with`, property hooks, and asymmetric visibility. PHP 8.3 floor,
+8.4 default, 8.5 features flagged.
+
+## Enums: backed + interface + methods
+
+Enums are first-class types, not class constants. A backed enum maps each case to a scalar;
+a pure enum has no backing. Both can implement interfaces and carry methods and constants.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+interface HasLabel {
+    public function label(): string;
+}
+
+enum Priority: int implements HasLabel {
+    case Low    = 10;
+    case Normal = 20;
+    case High   = 30;
+
+    // Methods: behavior travels with the closed set.
+    public function label(): string {
+        return match ($this) {
+            self::Low    => 'Low priority',
+            self::Normal => 'Normal',
+            self::High   => 'High priority',
+        };
+    }
+
+    // A static "named constructor" over the raw value.
+    public static function fromScore(int $score): self {
+        return match (true) {
+            $score >= 30 => self::High,
+            $score >= 20 => self::Normal,
+            default      => self::Low,
+        };
+    }
+
+    // Enum constants are allowed.
+    const Default = self::Normal;
+}
+```
+
+Parsing rules:
+
+- `Priority::from(20)` returns the case or **throws** `\ValueError` on a bad value.
+- `Priority::tryFrom(99)` returns `null` on a bad value — use it for untrusted input.
+- `Priority::cases()` returns every case in declaration order — iterate for menus/seeders.
+- `$case->value` is the backing scalar; `$case->name` is the case name string.
+
+Comparison is by identity: `$a === Priority::High` (cases are singletons). Never compare
+`->value` when you mean the case.
+
+## Docblock generics for PHPStan
+
+The engine has no runtime generics; PHPStan and Psalm read `@template` annotations and
+enforce them at analysis time. The runtime type stays `array`/`mixed`.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @template TKey of array-key
+ * @template TValue
+ */
+final class TypedMap {
+    /** @var array<TKey, TValue> */
+    private array $items = [];
+
+    /**
+     * @param TKey   $key
+     * @param TValue $value
+     */
+    public function set(int|string $key, mixed $value): void {
+        $this->items[$key] = $value;
+    }
+
+    /**
+     * @param TKey $key
+     * @return TValue|null
+     */
+    public function get(int|string $key): mixed {
+        return $this->items[$key] ?? null;
+    }
+
+    /** @return list<TValue> */
+    public function values(): array {
+        return array_values($this->items);
+    }
+}
+```
+
+Useful pseudo-types PHPStan understands: `list<T>` (a 0-indexed sequential array),
+`array<K, V>`, `non-empty-array<...>`, `non-empty-string`, `int<0, max>`, `class-string<T>`,
+`callable(int): string`. Prefer `list<T>` over `array<int, T>` when the array is a sequence
+— it documents and enforces the no-gaps invariant.
+
+`@template T of SomeInterface` bounds the parameter; `@template-covariant` allows variance on
+read-only containers. Annotate `@implements`/`@extends` when a class implements a generic
+interface so the type flows through.
+
+## readonly rules and the with-er pattern
+
+`readonly` properties are write-once: assignable only from inside the declaring class scope,
+and only before they hold a value. A `readonly class` makes every property readonly implicitly.
+
+Constraints to know:
+
+- A readonly property has no default value and must be typed.
+- You cannot `unset()` or re-assign it, even inside the class.
+- Cloning copies the value, but a plain `clone` then re-assigning a readonly prop in
+  `__clone` is **not** allowed before 8.3; from 8.3 you may reinitialize a readonly property
+  inside `__clone`. From **8.5**, prefer `clone with`.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+final readonly class Point {
+    public function __construct(
+        public int $x,
+        public int $y,
+    ) {}
+
+    // Pre-8.5 with-er: build a new instance explicitly.
+    public function withX(int $x): self {
+        return new self($x, $this->y);
+    }
+}
+
+// 8.5+: clone with overrides named properties in one expression.
+$p2 = clone $p1 with ['x' => 10];   // y is copied, x is replaced
+```
+
+## Property hooks — edge cases (8.4+)
+
+A property may declare a `get` hook, a `set` hook, or both. A property with only a `get` hook
+and no backing assignment is **virtual** (computed, stores nothing).
+
+```php
+<?php
+
+declare(strict_types=1);
+
+final class User {
+    // Backed property with a guarded set and a normalizing get.
+    public string $email {
+        get => strtolower($this->email);
+        set (string $value) {
+            if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
+                throw new \InvalidArgumentException("invalid email: {$value}");
+            }
+            $this->email = $value;
+        }
+    }
+
+    // Virtual: no backing store, recomputed each read.
+    public string $domain {
+        get => substr($this->email, (int) strpos($this->email, '@') + 1);
+    }
+
+    public function __construct(string $email) {
+        $this->email = $email; // runs the set hook -> validation
+    }
+}
+```
+
+Gotchas:
+
+- Inside a hook, `$this->email` refers to the backing store, not the hook — no infinite loop
+  for a backed property. A **virtual** property (get-only, never assigned) must not reference
+  itself.
+- Hooks run on **every** access. Do not do I/O, queries, or state mutation in a `get` hook —
+  a field read becoming a side effect is a debugging trap. Use a named method instead.
+- Hooks are inheritable and can be declared in interfaces (an interface can require a property
+  with hooks).
+- PHPStan 2.1+ analyzes hooks; older analyzers will misreport them.
+
+## Asymmetric visibility matrix (8.4+)
+
+Read visibility and write (set) visibility are declared independently. Write visibility must
+be **equal to or narrower** than read visibility.
+
+| Declaration | Readable from | Writable from |
+|---|---|---|
+| `public int $n` | anywhere | anywhere |
+| `public protected(set) int $n` | anywhere | class + subclasses |
+| `public private(set) int $n` | anywhere | declaring class only |
+| `protected private(set) int $n` | class + subclasses | declaring class only |
+| `private int $n` | declaring class | declaring class |
+
+Use `public private(set)` for the common case: a value object whose fields are read freely
+but mutated only through intent-revealing methods (`deposit()`, `rename()`), without writing a
+getter for every field.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+final class Counter {
+    public function __construct(public private(set) int $count = 0) {}
+    public function increment(): void { $this->count++; } // only path that writes
+}
+
+$c = new Counter();
+echo $c->count;   // ok: public read
+// $c->count = 5; // Error: write is private(set)
+```
+
+`readonly` plus `private(set)` is redundant — `readonly` already forbids writes after init.
+Choose `private(set)` when you need controlled mutation, `readonly` when you need none.

package/skills/shared/php/scripts/verify.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a PHP project (superset of CI).
+#
+# Usage:
+#   cd <your-php-project-root>   # the directory containing composer.json
+#   ./verify.sh
+#
+# Runs: composer validate, php -l syntax lint, Pint/PHP-CS-Fixer (style, dry-run),
+# PHPStan analyse, and PHPUnit/Pest - each only if the tool/config is present.
+# Missing tools are skipped with a yellow warning (not a failure).
+# Real problems (invalid composer.json, syntax errors, style/analysis/test failures)
+# exit non-zero. Read-only: never mutates your source or runs a formatter in fix mode.
+#
+# Portability: stock macOS bash 3.2 (no mapfile, no associative arrays, no unguarded
+# array expansion under `set -u`). Exits 0 on a clean project and on an empty src tree.
+
+set -euo pipefail
+
+# Colors only when stdout is a TTY (keeps logs/CI output clean).
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+
+have()  { command -v "$1" >/dev/null 2>&1; }
+warn()  { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail()  { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()    { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info()  { printf -- '----- %s\n' "$*"; }
+
+# A binary may be a global on PATH or a project-local vendor/bin script. Resolve either.
+binof() {
+  if [ -x "vendor/bin/$1" ]; then printf 'vendor/bin/%s' "$1"; return 0; fi
+  if have "$1"; then printf '%s' "$1"; return 0; fi
+  return 1
+}
+
+# Must run from a project root.
+if [ ! -f composer.json ]; then
+  printf '%serror:%s no composer.json in %s - cd into your project root first.\n' \
+    "$RED" "$RESET" "$(pwd)" >&2
+  exit 2
+fi
+
+# Directories we lint/analyse, only those that exist.
+SRC_DIRS=""
+for d in src app lib tests; do
+  [ -d "$d" ] && SRC_DIRS="$SRC_DIRS $d"
+done
+
+# 1. composer validate - the manifest must be well-formed.
+info "composer validate"
+if have composer; then
+  if composer validate --strict --no-check-publish >/dev/null 2>&1; then
+    ok "composer.json valid"
+  else
+    # Re-run to surface the message, but a lockfile drift is a warning, not a hard fail.
+    if composer validate --no-check-publish >/dev/null 2>&1; then
+      warn "composer.json valid but not strict-clean (lock drift / metadata) - run: composer validate --strict"
+    else
+      fail "composer validate reported errors (run: composer validate)"
+    fi
+  fi
+else
+  warn "composer not found (https://getcomposer.org)"
+fi
+
+# 2. php -l syntax lint across the source tree. No files = nothing to do (clean exit).
+info "php -l (syntax lint)"
+if have php; then
+  if [ -z "$SRC_DIRS" ]; then
+    warn "no src/app/lib/tests directory to lint"
+  else
+    lint_failed=0
+    file_count=0
+    # find with -print0 + a while/read loop is bash-3.2 safe and space-safe.
+    while IFS= read -r -d '' f; do
+      file_count=$((file_count + 1))
+      if ! php -l "$f" >/dev/null 2>&1; then
+        php -l "$f" || true
+        lint_failed=1
+      fi
+    done < <(find $SRC_DIRS -name '*.php' -type f -print0 2>/dev/null)
+
+    if [ "$file_count" -eq 0 ]; then
+      warn "no .php files found under:$SRC_DIRS"
+    elif [ "$lint_failed" -ne 0 ]; then
+      fail "PHP syntax errors found"
+    else
+      ok "syntax clean ($file_count files)"
+    fi
+  fi
+else
+  warn "php not found - cannot lint/analyse/test"
+fi
+
+# 3. Style: Pint preferred, else PHP-CS-Fixer. Always dry-run / test mode (read-only).
+info "style (Pint / PHP-CS-Fixer)"
+if pint_bin="$(binof pint)"; then
+  if $pint_bin --test >/dev/null 2>&1; then
+    ok "pint clean"
+  else
+    fail "pint reports style issues (run: $pint_bin)"
+  fi
+elif fixer_bin="$(binof php-cs-fixer)"; then
+  if $fixer_bin fix --dry-run >/dev/null 2>&1; then
+    ok "php-cs-fixer clean"
+  else
+    fail "php-cs-fixer reports style issues (run: $fixer_bin fix)"
+  fi
+else
+  warn "no formatter found (composer require --dev laravel/pint)"
+fi
+
+# 4. PHPStan - only if a config exists (else we cannot know the intended level).
+info "phpstan"
+if [ -f phpstan.neon ] || [ -f phpstan.neon.dist ] || [ -f phpstan.dist.neon ]; then
+  if stan_bin="$(binof phpstan)"; then
+    if $stan_bin analyse --no-progress >/dev/null 2>&1; then
+      ok "phpstan clean"
+    else
+      $stan_bin analyse --no-progress || true
+      fail "phpstan reported issues"
+    fi
+  else
+    warn "phpstan config present but binary not found (composer require --dev phpstan/phpstan)"
+  fi
+else
+  warn "no phpstan.neon - skipping static analysis"
+fi
+
+# 5. Tests: Pest preferred, else PHPUnit - only if a test config/dir exists.
+info "tests (Pest / PHPUnit)"
+if [ -f phpunit.xml ] || [ -f phpunit.xml.dist ] || [ -f Pest.php ] || [ -d tests ]; then
+  if pest_bin="$(binof pest)"; then
+    if $pest_bin >/dev/null 2>&1; then ok "pest green"; else fail "pest failed (run: $pest_bin)"; fi
+  elif phpunit_bin="$(binof phpunit)"; then
+    if $phpunit_bin >/dev/null 2>&1; then ok "phpunit green"; else fail "phpunit failed (run: $phpunit_bin)"; fi
+  else
+    warn "tests present but no runner found (composer require --dev pestphp/pest)"
+  fi
+else
+  warn "no phpunit.xml / tests dir - skipping tests"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"

package/skills/shared/plan/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: plan
+description: "Use when an approved, clarified spec must become a technical blueprint before any code — the SDD phase between clarify and tasks: architecture, contracts, data flow, testing strategy, sequencing and risks, at structure altitude, never framework syntax. NOT the what/why spec (that is `specify`), NOT the ambiguity sweep (that is `clarify`), NOT the task breakdown (that is `tasks`), NOT the code (that is `implement`)."
+tags: [sdd, plan, design]
+recommends: [tasks]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# Plan — the technical blueprint between spec and tasks
+
+The spec says **what** and **why**. `plan` decides **how**: the components, the contracts between
+them, the data that flows, how each claim gets proven, and what is most likely to bite. It reads the
+clarified spec and the constitution, writes ONE artifact — `02-DOCS/wiki/sdd/plans/<slug>.md` — and
+hands off to `tasks`, which slices it into an ordered, independently-verifiable checklist.
+
+```text
+constitution → specify → clarify → [ plan ] → tasks → analyze → implement → verify → review → ship
+```
+
+## Decide structure, not syntax
+
+A plan names components, contracts, shapes and flows. It does not write the framework's route
+decorators, the ORM's session boilerplate or the test runner's flags — those are stack mechanics,
+owned by the stack skill (`../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`,
+`../flutter/SKILL.md`, `../postgresdb/SKILL.md`) at `implement` time. This altitude is what makes a
+plan reviewable against intent and slice-able by `tasks`; drop it and you get code no one approved.
+
+```text
+reservation.reserve(cartId: CartId) -> Reservation | OutOfStock | CartNotFound
+  - idempotent on cartId (calling twice returns the same Reservation)
+  - holds stock for 15 min, then auto-releases
+  - never partially reserves: all lines or none
+```
+
+That is the altitude. The stack skill later decides whether it becomes a POST handler with a
+Pydantic model or a Go method on a struct — it can, because the contract is unambiguous.
+
+## Entry gate
+
+1. **The spec** — `02-DOCS/wiki/sdd/specs/<slug>.md`. Missing → STOP, route to
+   `../specify/SKILL.md`. Still carrying `[NEEDS CLARIFICATION]` markers or open questions → STOP,
+   route to `../clarify/SKILL.md`. A plan built on an unclarified spec is a guess wearing a diagram,
+   and every phase downstream inherits the guess.
+2. **The constitution** — `02-DOCS/wiki/sdd/constitution.md` holds the project's non-negotiables
+   (stack canon, quality bars, conventions). Every architectural choice must be consistent with it;
+   where the design needs to bend a principle, say so with a reason instead of bending it silently.
+3. **The Knowledge map** — `02-DOCS/wiki/index.md` points at `02-DOCS/wiki/stack/*` and prior
+   plans/decisions. Reusing what the project already settled is the difference between a plan and
+   scope drift.
+4. **The profile** — `technical_level` in `02-DOCS/wiki/harness/user-profile.md` (see below).
+
+## What a plan contains
+
+The sections of the artifact, in order; fill them top-down, later ones lean on earlier ones. The
+fill-in skeleton with per-section guidance is `references/plan-template.md` — use it verbatim.
+
+| § | Section | The question it answers |
+| --- | --- | --- |
+| 0 | Global constraints | Which exact values must every task honor? (verbatim, not paraphrased — a context-isolated implementer and its reviewer see nothing else) |
+| 1 | Context & constraints | Which spec/constitution facts pin this design down? Cite (`spec §Acceptance #3`), don't re-paste |
+| 2 | Architecture | What are the components and how do they fit together? |
+| 3 | Interfaces & contracts | What does each component promise the others? |
+| 4 | Data model & flow | What data exists, where it lives, how it moves and changes? |
+| 5 | Testing strategy | How will we *prove* each part does what it claims? |
+| 6 | Sequencing & dependencies | In what order can this be built and verified? |
+| 7 | Risks & open decisions | What is most likely to be wrong, and what is still undecided? |
+
+Three of them carry the weight and fail quietly:
+
+- **§2 Architecture** — a box-and-arrow diagram, one sentence of single responsibility per
+  component, internal vs. external marked (the arrows are the seams you will test and parallelize).
+  State the **one** decision that matters most — sync vs. async, split service vs. monolith, read
+  model vs. single table — and defend it against a constraint from §1. If two designs are genuinely
+  viable, give both, the trade-off, *and* your recommendation; leaving the reader to choose is not a
+  plan.
+- **§5 Testing strategy** — per acceptance criterion: the level that proves it (unit / contract /
+  integration / e2e), what it asserts, what it fakes to stay fast. Deciding this before code exists
+  is what makes `implement`'s TDD possible. You choose the seams; the stack skill owns the tooling.
+- **§7 Risks** — ranked, each with trigger, impact, and the mitigation or spike that retires it. A
+  plan claiming zero risk is the riskiest one. Significant decisions taken while planning also get
+  appended to `02-DOCS/wiki/sdd/decisions.md`, so later phases can trace the *why*.
+
+## The artifact
+
+Write `02-DOCS/wiki/sdd/plans/<slug>.md`, `<slug>` matching the spec's slug exactly — one plan per
+spec, same name, because that is how `tasks`, `analyze` and `implement` find it. Then index it in
+`02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a pointer). If a plan for
+this slug already exists, update it in place and note what changed — never fork a `-v2`.
+
+## Model tier — `heavy` (opt-in routing)
+
+Architecture, interfaces, data flow and risk are the heaviest reasoning in the chain, so this
+phase's default tier is **`heavy`**. Routing is off unless `models.enabled: true` in
+`02-DOCS/wiki/sdd/config.yaml`; the resolution order, the announce rule and the model table live in
+`../sdd/references/model-routing.md`. Routing off or no profile → session model, silently.
+
+## Talking about the plan
+
+The artifact is complete regardless of who reads it: every section, each significant design choice
+justified with the trade-offs weighed. In chat, say only what the reader needs, in the `orient`
+voice: point to the file and give one line of *why* on the top architectural decision. The register
+comes from `technical_level` in `02-DOCS/wiki/harness/user-profile.md` (set by `../init/SKILL.md`):
+for a `non-technical` reader, explain the architecture with an everyday analogy and define each term
+inline. Ask only about constraints you cannot infer.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails / the fix |
+| --- | --- |
+| Writing the real code in the plan "because it's faster" | You dropped an altitude. Syntax is the stack skill's job at `implement`. Pull back to contracts. |
+| Planning around a spec that is "a bit fuzzy but I get the gist" | A plan on an unclarified spec is a guess. STOP, route to `clarify`, then plan. |
+| Testing strategy = "we'll write tests" | Not a strategy. Name the level per acceptance criterion and what each test fakes. |
+| Keeping risks short because they read negative | The plan that claims no risk is the riskiest. Rank the real ones, give each a mitigation. |
+| Picking the framework, ORM and config here | Stack canon lives in the constitution; mechanics live in the stack skill. Stay above the seam. |
+| Listing two designs and letting the reader choose | Decide. Alternatives ship only with a trade-off and a recommendation matched to the constitution. |
+| One big undifferentiated sequencing step | Then `tasks` cannot slice it and nothing is independently verifiable. Order it into checkable steps. |
+| Starting a fresh plan when one exists for the slug | Forked plans rot and later phases read the wrong one. Update in place, note the change. |
+
+## Always propose isolation before the build
+
+Once the plan is written, **always propose isolating the work in a git worktree/branch** before any
+code is implemented — every feature, not just the risky ones. One line:
+
+> *"Antes de implementar, ¿aíslo este trabajo en un worktree/rama propia (`../worktrees/SKILL.md`)
+> para no tocar tu rama actual? (recomendado)"*
+
+Accepted → hand to `../worktrees/SKILL.md` first. Declined → note it and continue. Already on the
+default branch (`main`/`master`) → isolation is **not** optional: say so and route to `worktrees`
+regardless. (`implement` re-checks this as a hard gate before its first commit.)
+
+## When NOT to use
+
+- Fuzzy idea, no spec yet → `../specify/SKILL.md`; ambiguity in an existing spec →
+  `../clarify/SKILL.md`; project-wide non-negotiables → `../constitution/SKILL.md`.
+- Slicing an approved plan into an ordered checklist → `../tasks/SKILL.md`.
+- Concrete framework/ORM/test-runner mechanics → the stack skill (`../fastapi/SKILL.md`,
+  `../nextjs/SKILL.md`, `../go/SKILL.md`, `../flutter/SKILL.md`, `../postgresdb/SKILL.md`).
+
+## Result envelope
+
+End with the parseable block every SDD phase shares, so the dispatcher can chain without
+interpreting prose (contract: `../sdd/SKILL.md`):
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "Technical plan derived from the clarified spec, with the isolation decision made.",
+  "artifact": "02-DOCS/wiki/sdd/plans/<slug>.md",
+  "next_recommended": "tasks",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["plan"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["The plan answers HOW; the spec owns WHAT.", "Name the isolation choice before the build starts."]
+  },
+  "evidence": ["plan path exists", "each spec acceptance criterion has an approach", "risks and rollback stated"]
+}
+```
+
+## Next in the chain
+
+Plan written, indexed, decisions logged → propose isolation (above), then hand off to
+**`../tasks/SKILL.md`**, which turns §6 into an ordered task list with a done-check per task. If
+planning surfaced an ambiguity the spec never resolved, loop back to **`../clarify/SKILL.md`** first.

package/skills/shared/plan/evals/README.md

@@ -0,0 +1,62 @@
+# Eval harness — `plan` skill
+
+These evals are run by an **agent harness** (an LLM agent with the ai-hub Spec-Kit + stack skill catalog
+available), not a byte-exact shell script. `cases.yaml` is the fixture; this file is the procedure.
+Grading is judgment-based — a human or a judge-agent scores against the rubrics.
+
+`plan` is a process skill (the fourth SDD phase). It is judged on **routing accuracy** (does it
+fire only when there's a clarified spec to design from) and **capability** (does the plan it
+produces stay at the right altitude and cover the seven sections).
+
+## 1. Triggering accuracy
+
+Goal: `plan` fires when the user wants a technical design from a clarified spec, and stays silent
+on the adjacent SDD phases and on stack-mechanics requests.
+
+1. Load **only** the `plan` skill description into the agent, plus the bare names of the sibling
+   skills for routing: the ai-hub Spec-Kit phases (constitution, specify, clarify, tasks, analyze,
+   implement, verify, review, ship, debug, worktrees, parallel) and the stack/other skills
+   (fastapi, nextjs, go, postgresdb, flutter, design, marketing, presentations,
+   course-storytelling, building-agents, secure-coding, deployment, harness, init). Do **not** load
+   any skill bodies.
+2. For each prompt in `should_trigger` and `should_not_trigger`, ask the agent which skill (if any)
+   it would invoke. Run **3–5 trials per prompt** at production temperature to catch flakiness.
+3. Score:
+   - `should_trigger` → PASS if `plan` is selected in the majority of trials.
+   - `should_not_trigger` → PASS if `plan` is **not** selected; bonus-correct if it routes to the
+     `route_to` sibling named in the case.
+4. **Pass bar: ≥ 90% of prompts pass** (at most 1 miss across the 13 prompts), and no
+   `should_not_trigger` prompt may fire `plan` in a majority of its trials. The two highest-value
+   near-misses to get right are `clarify` (the phase immediately before — an unclarified spec must
+   NOT trigger plan) and `tasks` (the phase immediately after).
+
+## 2. Capability uplift (with vs without)
+
+Goal: the skill measurably improves the plan, not just gates it.
+
+1. For the `capability` scenario, run the agent **twice**:
+   - **WITHOUT**: base agent, no `plan` skill loaded.
+   - **WITH**: same prompt, `plan` skill fully loaded (it may read its `references/plan-template.md`).
+2. Grade each output against the `must_include` checklist — count a point only if it is genuinely
+   satisfied, not merely gestured at. The load-bearing points are: the seven-section artifact at
+   the right path, language-neutral contracts (no framework code), a per-criterion testing
+   strategy, and a ranked risk register.
+3. Coverage = points satisfied / total points, per run.
+4. **Pass bar:**
+   - WITH-skill coverage **≥ 80%** of the rubric.
+   - WITH clearly beats WITHOUT. The signature uplift to look for: the WITHOUT run tends to write
+     framework code and a one-line "we'll add tests"; the WITH run stays stack-neutral, names test
+     levels per acceptance criterion, and produces a ranked risk register at the correct artifact
+     path.
+5. Run 2–3 trials per condition and average; note any rubric point the skill never produces — that
+   is a gap to fix in `SKILL.md` or `references/plan-template.md`.
+
+## Notes
+
+- Prompts deliberately vary phrasing; several omit the word "plan" so triggering rests on the
+  signal "clarified spec → technical design before code", not keyword matching.
+- Near-misses route to the genuinely correct sibling: fuzzy-idea → specify, vague-spec → clarify,
+  approved-plan-to-checklist → tasks, DDL/indexes → postgresdb, real handler+tests → go,
+  project-wide principles → constitution.
+- This is judgment-based, not byte-exact. Record trial counts and the judge (human or model)
+  alongside results for reproducibility.

package/skills/shared/plan/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: plan
+
+should_trigger:
+  - prompt: "We've got the signed-off spec for the checkout-reservation feature. Now design the architecture and how the pieces talk to each other before anyone codes."
+    why: "Clarified spec in hand, asking for architecture + component contracts before code — the exact intent → tasks slot this skill fills."
+  - prompt: "Write the implementation plan for the new notifications service: components, the contracts between them, the data flow, and how we'll test it."
+    why: "Names every plan section (architecture, interfaces, data flow, testing strategy) without naming the phase — squarely in scope."
+  - prompt: "How should we build this? I want the data model, where each thing lives, what's transactional, and the order we can build it in."
+    why: "Data model + consistency boundaries + sequencing is the plan artifact; phrased as a 'how do we build' question, the structure-not-syntax altitude."
+  - prompt: "Before we start the feature, lay out the testing strategy — which seams get unit vs integration tests and what we have to mock to stay fast."
+    why: "Choosing test LEVELS per seam and what to fake is plan's testing-strategy section (strategy, not tooling)."
+  - prompt: "What are the main risks in this design and what could go wrong once we wire it to the payments provider? Rank them with mitigations."
+    why: "Ranked risk register with triggers/mitigations is plan §7; the non-obvious framing is 'what could go wrong', not the word 'plan'."
+  - prompt: "We have the spec and the clarifications are all resolved. What's the blueprint to get from here to shipping?"
+    why: "Explicitly post-clarify, asking for the technical blueprint — the handoff point clarify → plan, no stack named."
+  - prompt: "Sketch the box-and-arrow architecture and the interface each component promises, keeping it stack-neutral so the FastAPI/Go choice comes later."
+    why: "Architecture diagram + language-neutral contracts above the seam is precisely plan's altitude and its defer-to-stack rule."
+
+should_not_trigger:
+  - prompt: "I have a fuzzy idea for a referrals feature but no spec yet. Help me pin down what we're building and why."
+    route_to: "specify"
+    why: "Requirements capture from a fuzzy intent — that's specify; there's no spec to plan from yet."
+  - prompt: "The spec is written but vague on edge cases and what happens on a partial failure. Help me surface the ambiguities and resolve them."
+    route_to: "clarify"
+    why: "De-risking an existing spec by surfacing ambiguities is clarify, the gate that must pass before plan."
+  - prompt: "The plan's approved. Break it into an ordered checklist where each item has a done-check I can verify independently."
+    route_to: "tasks"
+    why: "Slicing an approved plan into an ordered, verifiable task list is the tasks phase, not planning."
+  - prompt: "Write the actual SQL schema, the indexes, and the EXPLAIN-verified migration for the orders table."
+    route_to: "postgresdb"
+    why: "Concrete DDL/indexes/migration mechanics are below the plan's altitude — the postgresdb stack skill owns them."
+  - prompt: "Implement the Go HTTP handler and the table-driven tests for the reservation endpoint we planned."
+    route_to: "go"
+    why: "Writing the actual handler + test code is implement-time stack mechanics (go), not the structure-level plan."
+  - prompt: "What are our project-wide non-negotiables — the stack canon and quality bars every feature must respect?"
+    route_to: "constitution"
+    why: "Capturing project-wide principles is the constitution phase; plan reads it but doesn't author it."
+
+capability:
+  - scenario: "User says: 'We have a clarified spec for an order-reservation feature (reserve stock for a cart for 15 minutes, then auto-release; must be idempotent per cart; calls an external payments provider). Write the implementation plan.' The agent has read the spec and constitution."
+    must_include:
+      - "Writes the artifact to specs/<slug>/plan.md using the seven-section structure (context, architecture, interfaces, data model/flow, testing strategy, sequencing, risks)"
+      - "Architecture section names components with single responsibilities and marks the payments provider as EXTERNAL; states one top architectural decision with a reason tied to a constraint"
+      - "Interfaces section gives a language-neutral contract for reserve (inputs → outputs incl. error modes) and explicitly states the idempotent-on-cartId invariant and the 15-minute auto-release"
+      - "Data model + flow names entities at the model level (not DDL) and calls out the consistency/transactional boundary; defers concrete schema/indexes/migration to the postgresdb stack skill rather than writing SQL"
+      - "Testing strategy maps each acceptance criterion to a test level (unit/contract/integration/e2e), states what each asserts and what it mocks (e.g. the payments provider), and defers the test runner/tooling to the stack skill"
+      - "Risks section is ranked with trigger + impact + mitigation per risk (e.g. payments timeout, double-reservation race); does NOT claim zero risk"
+      - "Stays stack-neutral above the seam — no framework route decorators, ORM session code, or test-runner flags in the plan"
+      - "Ends by pointing to the tasks phase and notes indexing the plan in the root AGENTS.md Knowledge map"