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

package/skills/shared/sdd/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: sdd
+description: "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the SDD dispatcher and front door, in any language. States the method, reads the user's register from 02-DOCS, and routes to the right phase: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel on demand. Use it to start a feature, to govern the whole flow, or when unsure which phase you are in. NOT a single phase itself (it dispatches), NOT the workspace harness (that is `harness`), NOT a stack build skill."
+tags: [sdd, spec, workflow, plan]
+recommends: [sdd-init, constitution, specify]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# sdd — the ai-hub Spec-Driven Development dispatcher
+
+*The front door for building software the ai-hub way: intent in, shipped-and-verified software out, with the spec, plan and decisions recorded into the project's living knowledge model as you go.*
+
+`sdd` is the **engineering counterpart of the `harness`**. The harness runs the chaos → knowledge loop (inbox → `02-DOCS` wiki). `sdd` runs the **intent → shipped software** loop, and it writes the artifacts of that loop — constitution, specs, plans, decisions — into the same `02-DOCS/wiki/sdd/` so the project's knowledge grows with every feature instead of leaking into chat history.
+
+This skill does **not** do a phase itself. It is the dispatcher: it names the method, reads which register you want (technical or with analogies), tells you which phase you are in, and hands off to the phase skill that owns the work. Each phase skill, when it finishes, points you at the next one — so once you enter the chain you rarely come back here.
+
+## The method in one breath
+
+Spec-Driven Development (SDD, GitHub Spec Kit lineage) says: **decide what and why before how, write it down, and let each written artifact gate the next step.** You do not jump from a sentence in chat to a pull request. You move through ordered phases, each producing a durable artifact that the next phase reads. The payoff is that the *intent* is reviewable before any code exists, drift is caught at a gate instead of in production, and the whole thing is legible to the next person (or the next session) because it lives in `02-DOCS`, not in a scrollback.
+
+If you only remember one rule: **the artifact is the contract.** Code is checked against the plan, the plan against the spec, the spec against the constitution. When they disagree, you fix the disagreement before writing more code — you do not let the code silently win.
+
+## Step zero: calibrate the SDD runtime
+
+Before the first non-trivial feature in a repo, run `../sdd-init/SKILL.md`. It detects the stack, package manager, test runners, scripts, monorepo signals and review budget, refreshes `.ai-hub/skill-registry.json`, and writes:
+
+```text
+02-DOCS/wiki/sdd/config.yaml
+```
+
+If `config.yaml` is missing and the request is more than a tiny one-line change, route to `sdd-init` before `specify`. This is not the same as `init`: `init` profiles the user/workspace; `sdd-init` calibrates the technical SDD runtime.
+
+## The chained phase map
+
+The canonical chain runs left to right. Solid arrows are the default path; you move forward when the current phase's exit gate passes.
+
+```text
+constitution ─(once per project)─┐
+                                 ▼
+   sdd-init ─(once per repo/runtime)─┐
+                                     ▼
+   proposal? ─► specify ─► clarify ─► plan ─► tasks ─► analyze ─► implement ─► verify ─► review ─► ship ─► archive
+                                                         ▲
+                                          on demand ─────┴─────────────────────
+                                          debug · worktrees · parallel
+```
+
+| Phase | Owns | Writes | Tier | Sibling skill |
+| --- | --- | --- | --- | --- |
+| **sdd-init** | Technical runtime calibration: stack, tests, commands, registry, budgets | `02-DOCS/wiki/sdd/config.yaml`, `.ai-hub/skill-registry.*` | light | `../sdd-init/SKILL.md` |
+| **proposal** | Optional pre-execution briefing for ambiguous/architectural/risky work | `02-DOCS/wiki/sdd/proposals/<slug>.md` | — | handled by `../specify/SKILL.md` when needed |
+| **constitution** | Project non-negotiables: stack canon, quality bars, conventions | `02-DOCS/wiki/sdd/constitution.md` | heavy | `../constitution/SKILL.md` |
+| **specify** | Turn a fuzzy intent into a spec — what & why, no how | `02-DOCS/wiki/sdd/specs/<slug>.md` | balanced | `../specify/SKILL.md` |
+| **clarify** | Surface ambiguities / edge cases, ask, bake answers back in | updates the spec | balanced | `../clarify/SKILL.md` |
+| **plan** | Technical plan: architecture, interfaces, data flow, tests, risks | `02-DOCS/wiki/sdd/plans/<slug>.md` | heavy | `../plan/SKILL.md` |
+| **tasks** | Break the plan into ordered, independently-verifiable tasks | task list in the plan artifact | balanced | `../tasks/SKILL.md` |
+| **analyze** | Consistency gate: constitution ↔ spec ↔ plan ↔ tasks (report only) | a gap report | heavy | `../analyze/SKILL.md` |
+| **implement** | Execute tasks with checkpoints; TDD discipline embedded | logs to `02-DOCS/wiki/sdd/decisions.md` | balanced | `../implement/SKILL.md` |
+| **verify** | Post-build gate: run the stack's checks + done-checks + acceptance | evidence | balanced | `../verify/SKILL.md` |
+| **review** | Adversarial code review — give and receive with rigor | review notes | heavy | `../review/SKILL.md` |
+| **ship** | Close the branch: PR / merge / cleanup. **Git authorship = Daner Alejandro Salazar Colorado** | the merge/PR and archive bundle | light | `../ship/SKILL.md` |
+| **debug** | Root-cause diagnosis: reproduce → isolate → fix → verify | a diagnosis | heavy | `../debug/SKILL.md` |
+| **worktrees** | Isolate feature work in a branch/worktree before executing a plan | an isolated workspace | light | `../worktrees/SKILL.md` |
+| **parallel** | Fan out independent tasks across subagents, gather results | merged results | per-unit | `../parallel/SKILL.md` |
+
+> The **Tier** column is the *default* model tier each phase routes to when **per-phase model
+> routing** is enabled — see "Per-phase model routing" below. It is off by default and changes
+> nothing about the chain or the gates; it only decides which model does the work.
+
+> If a phase skill above does not yet exist in this repo, the chain still holds — do that phase's work inline following the method here, and skip the broken handoff. Never invent a sibling that is not installed.
+
+## The invoke rule — route to the phase that fits
+
+When a request lands, do not start typing code. Place it on the map first, then invoke the phase skill that owns it.
+
+> **The new-feature gate (hard).** The moment the user is thinking about a new feature or change — "add…", "build…", "it should also…", "quiero añadir…" — it goes to `specify` first, *even if a stack skill (nextjs/fastapi/flutter/react…) also fired and could just build it*. **No feature code is written — by any skill — until a spec AND a plan exist and the user has approved them.** A stack skill about to build an unspec'd, non-trivial feature must stop and route here. The only exception is a genuinely one-line, low-risk change; name it and skip.
+
+1. **No `02-DOCS/wiki/sdd/config.yaml` and this is non-trivial?** → `sdd-init`.
+2. **No constitution yet AND this project will grow — or its frontmatter says `status: draft` (the one `ai-hub onboard` writes)?** → `constitution` once, then come back to the chain.
+3. **Ambiguous / architectural / risky change before spec?** → optional proposal artifact via `specify`.
+4. **A new idea, fuzzy, no spec on disk?** → `specify`.
+5. **A spec exists but feels risky / has open questions?** → `clarify`.
+6. **A clarified spec, no technical plan?** → `plan`.
+7. **A plan with no task breakdown?** → `tasks`.
+8. **Tasks exist, about to code, want a safety check?** → `analyze`.
+9. **Green light to build?** → `implement` (it embeds strict TDD from config and calls `parallel`/`worktrees` when useful).
+10. **Code written, claiming it works?** → `verify`, then `review`, then `ship`/archive.
+11. **Something is broken mid-flight?** → `debug`, then resume where you were.
+
+If you genuinely cannot tell which phase you are in, ask the user one question: *"Do we have a written spec for this yet?"* The answer puts you before or after `specify`, and the rest follows.
+
+### Skip rules (be honest about them)
+
+- A **one-line, low-risk change** (typo, copy tweak, config bump) does not need the full chain. Say so, do it, and verify. The method serves shipping, not ceremony.
+- `constitution` runs **once per project**, not per feature. If `02-DOCS/wiki/sdd/constitution.md` exists, read it as guardrails and move on — unless it is still `status: draft`: then complete it first.
+- `clarify` and `analyze` are **gates, not paperwork**. If a spec is genuinely unambiguous and tiny, name that out loud and pass through — but the bias is to run them, because skipped gates are where drift hides.
+
+## Autopilot mode — run the whole chain on one up-front yes
+
+By default the chain pauses at its gates (spec approval, plan approval). **Autopilot** trades those
+per-phase stops for a **single up-front consent**: the user says "take it all the way" once, and the
+chain runs `specify → clarify → plan → tasks → analyze → implement → verify → review` end to end
+**without asking to continue between phases** — still writing every artifact (spec, plan, decisions)
+to `02-DOCS/wiki/sdd/` as it goes, so the work stays reviewable after the fact.
+
+**How it turns on:**
+
+- `specify` **offers it at the brainstorm boundary** ("¿lo llevo hasta el final yo solo, o paramos en cada fase?"). A yes engages autopilot for this feature.
+- Or set `sdd.autopilot: true` in `02-DOCS/wiki/sdd/config.yaml` to default it on (still surfaced once per feature).
+
+**The up-front yes IS the gate.** It satisfies the new-feature gate's "spec + plan approved before code" — approval was granted in advance, for the whole run. Do not re-ask phase by phase.
+
+**Autopilot still STOPS for these — not "continue?" nags, real forks:**
+
+- **Genuine ambiguity** that would change scope, a goal, or an acceptance criterion (never guess the product).
+- **A hard failure** it can't resolve (a red test it can't green → `debug`; an `analyze` contradiction).
+- **Destructive / irreversible / outward-facing actions** — push, merge, delete, secrets. `ship` (PR/merge) still confirms: autopilot drives the **build**, not the **release**.
+
+Run the fan-out on the `developer` subagent as usual, and narrate in the `orient` voice: name each phase as it passes and show its artifact, one line each. Autopilot changes **when you ask**, never **what gets written** — every artifact and gate-check still happens; you just don't block on a human between them.
+
+## Read the register first
+
+Before dispatching, read `technical_level` in `02-DOCS/wiki/harness/user-profile.md` — exactly as every ai-hub skill does. It picks the register (technical terms, or plain words with analogies); it never changes whether the gates exist. Speak in the `orient` voice:
+
+- **At each phase:** name the phase, give one line of *why this phase now*, do it, show the artifact.
+- **At gates** (clarify / analyze / decisions): ask only the questions that actually change the outcome, each with its trade-off and a recommendation.
+
+If there is no profile yet, use analogies and ask once **"technical or with analogies?"** before dispatching, and persist the answer — that is `init`'s job and `sdd` honors it.
+
+## Per-phase model routing (opt-in)
+
+Different phases reward different models: architecture and adversarial review want the strongest
+one; scaffolding and git plumbing don't. SDD can route each phase to a **tier** — `heavy`
+(deep reasoning), `balanced` (execution), `light` (mechanical) — that resolves to a concrete
+model in `02-DOCS/wiki/sdd/config.yaml` under `models`. The default mapping is the **Tier**
+column above (quality-biased: heavy on constitution/plan/analyze/review/debug, balanced on
+execution, light on ship/worktrees/sdd-init).
+
+It is **off by default** (`models.enabled: false`). When the user opts in, each phase applies it
+two ways: **programmatically** — dispatching `Task`/`parallel` subagents on the tier's model
+(real routing, e.g. Claude Code) — and **advisorily** — announcing the recommended switch at the
+phase boundary, in one line, for inline work and assistants that can't switch
+programmatically. Never switch unasked, never claim a switch a tool can't make, and skip routing
+on trivial one-line changes. The `sdd` dispatcher itself never routes (staying on the session
+model); `parallel` has no fixed tier (each unit inherits the tier of its work). Full protocol,
+per-assistant mechanism, and the provider→model table: `references/model-routing.md`.
+
+## Where the artifacts live (and why it matters)
+
+Every phase writes under `02-DOCS/wiki/sdd/` so the feature's reasoning outlives the chat:
+
+```text
+02-DOCS/wiki/sdd/
+├── config.yaml              ← repo runtime calibration from sdd-init
+├── constitution.md          ← project non-negotiables (once)
+├── proposals/<slug>.md      ← optional pre-execution briefing
+├── specs/<slug>.md          ← one spec per feature
+├── plans/<slug>.md          ← one plan per feature (tasks live inside)
+├── progress/<slug>.md       ← append-only apply progress
+├── verifications/<slug>-YYYY-MM-DD.md
+├── archive/<slug>/          ← final report, state, verify/review/ship records
+├── sessions/<date>-<slug>.md
+└── decisions.md             ← append-only log of decisions taken while building
+```
+
+Index these in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under an `sdd/` topic, so every other skill reads them before working in the area. The harness maintains and improves these files just like any other wiki topic — `sdd` produces them, the harness keeps them honest.
+
+```markdown
+# 02-DOCS/wiki/index.md
+## Knowledge map
+| Topic | Where | What |
+| --- | --- | --- |
+| sdd/ | 02-DOCS/wiki/sdd/ | Constitution, specs, plans, decisions for spec-driven feature work |
+```
+
+## Stack handoff
+
+`sdd` and its phases are **process, not stack**. Concrete tooling — test runners, lint/type/build, framework idioms — belongs to the stack skills. `plan` defers stack specifics, `implement` borrows the stack skill's testing approach, and `verify` runs the stack skill's checks. Route to the stack that matches the work: `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`. Visual/UX work routes to `../design/SKILL.md` and copy to `../marketing/SKILL.md`.
+
+## Skill registry and compact skill rules
+
+The registry is the cheap index:
+
+```text
+.ai-hub/skill-registry.json
+.ai-hub/skill-registry.md
+```
+
+Use it to choose the few relevant skill paths for the current phase/stack. Do not load the whole catalog. Before dispatching subagents, digest selected skills into 4-5 compact rules and include them in the brief. Each phase reports `skill_resolution`: which skills were used, which were missing, fallback behavior, and the compact rules handed to subagents.
+
+## Standard result envelope
+
+Every SDD phase ends with the same parseable block so the dispatcher can chain phases without interpreting a novel:
+
+```json result-envelope
+{
+  "status": "complete|blocked|failed",
+  "executive_summary": "one short paragraph",
+  "artifact": "path/to/artifact-or-none",
+  "next_recommended": "sdd-init|specify|clarify|plan|tasks|analyze|implement|verify|review|ship",
+  "risk": "low|medium|high",
+  "model": { "tier": "heavy|balanced|light", "resolved": "model-id", "routing": "on|off" },
+  "skill_resolution": {
+    "used": [],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": []
+  },
+  "evidence": []
+}
+```
+
+If a phase cannot produce the envelope because the user stopped it mid-flight, write a session summary instead.
+
+## Session summary / compaction recovery
+
+When a session is long, about to pause, or context is at risk, write:
+
+```text
+02-DOCS/wiki/sdd/sessions/<date>-<slug>.md
+```
+
+Include current phase, active artifacts, last verdict, completed tasks, next steps, risks, useful commands, and the current `skill_resolution`. This lets the next agent resume from artifacts instead of scrollback.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality / fix |
+| --- | --- |
+| "I get the feature, I'll just start coding." | That is the failure SDD prevents. At minimum write the spec; the artifact is the contract. |
+| "`sdd` should write the spec itself." | No. `sdd` dispatches. Invoke `specify` — it owns the spec and asks the right questions. |
+| "Clarify and analyze are bureaucracy, skip them." | Skipped gates are where drift hides. Run them; only pass through if the change is genuinely trivial and you say so. |
+| "The user wants it short, so I'll skip the gates to be terse." | Short changes the words, not the method. Fewer words, same gates. |
+| "I'll keep the plan in chat, it's faster." | Chat is not durable. Write it under `02-DOCS/wiki/sdd/` or the next session is blind. |
+| "I'll skip `sdd-init`; I remember the test command." | The runtime contract belongs in `config.yaml`, not memory. |
+| "I'll load every skill into the subagent." | That contaminates context. Use registry -> selected paths -> compact rules. |
+| "The phase wrote a nice summary, so no envelope needed." | The envelope is the phase contract. Add it. |
+| "Run constitution again for this feature." | Constitution is once per project. If it exists, read it as guardrails and move on. |
+| "Ship now, I'll add Co-Authored-By: Claude." | `ship` enforces Daner Alejandro Salazar Colorado-only authorship. No Claude co-author, no generated-with footer. |
+| "Invoke the `release` phase." | There is no such phase. Never invent a sibling — the chain is the chain. |
+| "Routing sounds useful, I'll switch to the heavy model on my own." | Routing is opt-in (`models.enabled:false`). Don't switch models unless the user turned it on. |
+| "I'll tell them I switched to Opus." (on an assistant with no per-subagent model) | Announce the recommended tier; never claim a switch the tool can't make. Honesty over magic. |
+
+## Start here
+
+- **New project, nothing on disk yet** → `../sdd-init/SKILL.md` for runtime calibration, `../constitution/SKILL.md` for non-negotiables, then `../specify/SKILL.md`.
+- **Existing project, no SDD config** → `../sdd-init/SKILL.md`, then route by phase.
+- **Existing project, new feature** → `../specify/SKILL.md` (or proposal first if risky/architectural).
+
+Then follow the arrows: each phase ends by pointing at the next, all the way to `ship`.

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

@@ -0,0 +1,60 @@
+# Eval harness — `sdd`
+
+Evaluates the `sdd` dispatcher (the ai-hub Spec-Kit front door) on two axes: **triggering**
+(does it fire when a feature should run the spec-driven flow, and stay quiet when a
+single phase or a different skill owns the request) and **capability** (does loading it
+measurably improve how the agent opens and routes the work). Cases live in `cases.yaml`.
+These run via an **agent harness**, not a pure shell script — a human or driver agent
+feeds prompts to Claude Code and judges the result against the rubrics.
+
+## What's in `cases.yaml`
+
+- `should_trigger` (7) — prompts that MUST invoke `sdd`, including non-obvious phrasings
+  ("which step am I on", "decide what and why, write it down, then build") with no SDD
+  jargon.
+- `should_not_trigger` (6) — near-misses that must route elsewhere. Each carries a
+  `route_to` naming the correct sibling (`specify`, `constitution`, `ship`, `harness`,
+  `debug`, `nextjs`).
+- `capability` (2) — scenarios with `must_include` rubrics graded WITH vs WITHOUT the skill.
+
+## A. Triggering eval
+
+1. Load **only** `sdd` into the agent (no other ai-hub skills available, so routing is honest).
+2. For each `should_trigger` prompt: open a fresh session, paste the prompt verbatim, and
+   record whether `sdd` activates — a pass means it names the method, places the request on
+   the phase map, and routes to a phase (it should NOT start writing the spec or coding
+   itself). Run **3–5 trials** per prompt.
+3. For each `should_not_trigger` prompt: same procedure, but a **pass** = `sdd` does NOT
+   fire. Where a `route_to` sibling is named, sanity-check the prompt genuinely belongs there
+   (e.g. "write the spec" → `specify`, "open the PR and merge" → `ship`).
+4. Score: a prompt passes if the **majority of its trials** go the expected way.
+
+**Pass bar:** ≥ 90% trigger accuracy across all `should_trigger` + `should_not_trigger`
+prompts (at most 1 of the 13 may misbehave).
+
+## B. Capability eval
+
+1. **Without the skill:** fresh session, skill NOT loaded, give the `scenario` prompt. Save output A.
+2. **With the skill:** fresh session, `sdd` loaded, same prompt. Save output B.
+3. Grade each output against that scenario's `must_include` points — count points clearly covered.
+4. Repeat across **3 trials** per scenario per condition and average the coverage.
+
+**Pass bar:** WITH the skill covers **≥ 80%** of `must_include` points; WITHOUT the skill is
+materially lower (target a ≥ 30-point gap). If the skill doesn't measurably beat the baseline,
+the skill — or these rubrics — needs work.
+
+## Judging notes (honest caveats)
+
+- This is **LLM-as-judge / human-in-the-loop**, not deterministic. Use a consistent grader
+  (same model + rubric) across A/B to keep the comparison fair.
+- The headline differentiators for `sdd`: it **dispatches, it does not perform a phase**; it
+  states the method ("the artifact is the contract"), reads the **register** (`technical_level`)
+  and speaks in the orient voice (never skipping gates), presents the **chained phase map**, applies the **invoke
+  rule** and the **skip rules** honestly, and writes artifacts under `02-DOCS/wiki/sdd/`.
+- Key confusables to watch: "write the spec" is `specify`, not `sdd`; "set the principles" is
+  `constitution`; "open the PR" is `ship`; "build 01-TOOLS/02-DOCS" is `harness`. If the agent
+  does the phase work itself instead of routing, that's a fail even if the output looks good.
+- Because `sdd` is the front door, some phase siblings may not yet be installed. A correct
+  response still routes by name and does the phase inline if the sibling is absent — it must
+  never invent a phase that isn't in the chain.
+- Run after any edit to `SKILL.md` or its `description`, since both axes are sensitive to wording.

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

@@ -0,0 +1,90 @@
+skill: sdd
+
+# Cases for the ai-hub Spec-Kit "sdd" dispatcher / front door.
+# sdd states the SDD method, reads the user's register (the register) from
+# AGENTS.md, and ROUTES to the right phase skill in
+# the chain constitution -> specify -> clarify -> plan -> tasks -> analyze ->
+# implement -> verify -> review -> ship (debug/worktrees/parallel on demand).
+# It does NOT perform a single phase itself and is NOT the workspace harness.
+
+should_trigger:
+  - prompt: "I want to build this feature properly, spec-driven, from idea to shipped. Where do I start?"
+    why: "Canonical SDD entry: explicit 'spec-driven' + 'idea to shipped' is exactly what the dispatcher routes — it should name the method and hand off to constitution/specify, not start coding."
+
+  - prompt: "Quiero llevar esta idea a producción haciéndolo bien, paso a paso."
+    why: "Spanish 'de la idea a producción, haciéndolo bien, paso a paso' is the intent->shipped loop the dispatcher governs; it should place the request on the phase map and route to specify."
+
+  - prompt: "I'm somewhere in the middle of building a feature and I've lost track of which step I'm on. Can you orient me?"
+    why: "Non-obvious: no SDD jargon, but 'which step am I on' is precisely the dispatcher's 'which phase are you in' job — it asks the one orienting question (is there a written spec?) and routes."
+
+  - prompt: "Run the full sdd flow on this new authentication requirement."
+    why: "Direct request to run the chained flow — the dispatcher owns the flow and routes the first phase; it should not try to do every phase inline itself."
+
+  - prompt: "I have a one-paragraph idea for a notifications feature. Take it all the way to a PR the disciplined way."
+    why: "Fuzzy idea + 'all the way to a PR' + 'disciplined' implies the whole chain; the dispatcher should start at specify and explain the gates rather than jumping to implementation."
+
+  - prompt: "Before we touch code, I want a proper process: decide what and why, write it down, then build. Set that up."
+    why: "Describes SDD by definition (what/why before how, write it down) without the acronym — a deliberately non-obvious trigger the dispatcher must claim and route from."
+
+  - prompt: "What's the right order to do this feature in, and which phase skill handles each part?"
+    why: "Asks for the phase map and the per-phase ownership — the dispatcher's core deliverable; it should produce the chain and the routing rule."
+
+  - prompt: "We have an existing repo and no SDD config yet. Start the SDD flow properly before we write a spec."
+    why: "The dispatcher should notice the missing runtime calibration and route to sdd-init before specify on non-trivial work."
+
+  - prompt: "I want planning and review to run on the strongest model but implementation on a cheaper one. Set that up for our SDD flow."
+    why: "Per-phase model routing is an SDD concern the dispatcher owns: it should name the tier system (heavy/balanced/light), point at the models block in .specify/config.yaml written by sdd-init, and note it is opt-in — not start coding."
+
+should_not_trigger:
+  - prompt: "Write the spec for the new export-to-CSV feature."
+    route_to: "specify"
+    why: "A concrete request to PRODUCE the spec is a single phase the dispatcher hands off — specify owns writing specs and asking the focused questions. sdd only routes."
+
+  - prompt: "Set this repo's non-negotiable engineering principles and stack canon."
+    route_to: "constitution"
+    why: "Capturing project-wide non-negotiables is the constitution phase, which runs once per project. The dispatcher would point here, but the work itself belongs to the constitution skill."
+
+  - prompt: "All the code is written and tests pass — open the PR and merge it."
+    route_to: "ship"
+    why: "Closing the branch (PR/merge/cleanup, human-only authorship) is the ship phase. No dispatching needed; this is squarely ship's job."
+
+  - prompt: "Audita mi proyecto y monta el docs/tools y el docs/."
+    route_to: "harness"
+    why: "Workspace control plane (docs/tools/docs/ scaffolding/audit) is the harness, not the SDD engineering flow. sdd writes its artifacts INTO docs/ but does not build the harness."
+
+  - prompt: "There's a failing test and I don't know why — help me find the root cause before I change anything."
+    route_to: "debug"
+    why: "Root-cause diagnosis of a specific failure is the on-demand debug phase. The dispatcher references it, but a direct 'find the root cause' request goes straight to debug, not through routing."
+
+  - prompt: "Scaffold a new Next.js app with the App Router and Tailwind."
+    route_to: "nextjs"
+    why: "A concrete stack build with a named framework is the nextjs stack skill. sdd is process, not stack; it would defer build specifics to nextjs rather than fire itself."
+
+capability:
+  - scenario: "A developer whose profile says the register: technical says: 'I've got a rough idea for a feature and I want to build it the spec-driven way, end to end. Where do I begin?' Show how the dispatcher opens the engagement."
+    must_include:
+      - "States the SDD method in brief: decide what & why before how, write it down, each artifact gates the next ('the artifact is the contract')"
+      - "Reads (or notes it should read) the register from AGENTS.md and, being technical, uses technical terms directly with a one-line why per step rather than long explanations or analogies"
+      - "Presents the chained phase map: sdd-init -> constitution -> proposal? -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship -> archive, with debug/worktrees/parallel on demand"
+      - "Includes sdd-init as step zero when .specify/config.yaml is missing, and explains that it detects test commands, strict TDD and manifest.yaml"
+      - "Applies the invoke rule: a fuzzy idea with no spec on disk routes to specify (and notes constitution runs once per project if not yet present)"
+      - "Does NOT itself write the spec or start coding — it hands off to the specify phase skill (../specify/SKILL.md)"
+      - "Notes that artifacts will be written under .specify/ (specs/, plans/, decisions.md) and indexed in the root AGENTS.md Knowledge map"
+      - "Mentions standard result envelopes with status, artifact, next_recommended, risk, skill_resolution and evidence"
+      - "Defers concrete stack tooling (test runner, build, framework idioms) to the relevant stack skill rather than prescribing it here"
+
+  - scenario: "A user says: 'It's a tiny copy change in the footer — do I really have to run this whole spec/plan/tasks ceremony?' Show how the dispatcher handles the skip case honestly."
+    must_include:
+      - "Applies the skip rule: a one-line, low-risk change does not need the full chain, and says so explicitly"
+      - "Still requires a verification step after the change (the method serves shipping, not ceremony, but evidence before claiming done remains)"
+      - "Does not abandon the method for genuinely risky work — distinguishes trivial from non-trivial and is honest about which this is"
+      - "If git authorship comes up, notes ship enforces human-only authorship (no Co-Authored-By Claude, no generated-with footer)"
+
+  - scenario: "A user asks: 'Can SDD use a cheaper model for the boring phases and the strong one for the hard ones? How do I turn that on?' Show how the dispatcher explains per-phase model routing."
+    must_include:
+      - "Names the three tiers — heavy (deep reasoning), balanced (execution), light (mechanical) — and that each phase has a default tier"
+      - "States the default quality-biased mapping: heavy on constitution/plan/analyze/review/debug, balanced on specify/clarify/tasks/implement/verify, light on ship/worktrees/sdd-init"
+      - "Says routing is OFF by default (models.enabled:false) and lives in the models block of .specify/config.yaml, written by sdd-init; turning it on is the user's choice"
+      - "Explains the two application layers: programmatic (dispatching Task/parallel subagents on the tier's model, e.g. Claude Code) and advisory (announcing the recommended switch at the phase boundary, in one line)"
+      - "Is honest about limits: never switches unasked, never claims a model switch an assistant cannot make, and skips routing on trivial one-line changes"
+      - "Points to references/model-routing.md for the full protocol, per-assistant mechanism, and provider→model table rather than inventing model names inline"

package/skills/shared/sdd/references/model-routing.md

@@ -0,0 +1,194 @@
+# Per-phase model routing — the protocol
+
+*Different SDD phases ask for different kinds of thinking. Architecture and adversarial
+review reward the strongest model; scaffolding and git plumbing don't. This is the protocol
+that lets each phase run on the model its work deserves — cheaper where it's safe, strong
+where it matters — without surprising anyone and without faking a switch a tool can't make.*
+
+This file is the **single source of truth** for the behavior. `sdd-init` writes the profile,
+`sdd` summarizes it, and every phase skill points here for the procedure. If the three ever
+disagree, this file wins.
+
+## Why this exists
+
+By default every SDD phase runs on whatever model the session happens to be on. That's either
+wasteful (running `ship`'s `git push` on the most expensive model) or risky (running an
+architecture `plan` on the cheapest one). Routing assigns each phase a **tier** and lets the
+phase put its work on the right model. It is **opt-in**: until the user turns it on, nothing
+changes and nothing is announced.
+
+## The three tiers (provider-neutral)
+
+Tiers are abstract so the profile survives a provider switch. A phase only ever names a tier;
+the concrete model is resolved from config.
+
+| Tier | For | Typical work |
+| --- | --- | --- |
+| **heavy** | deep reasoning | architecture, consistency gates, adversarial review, root-cause diagnosis |
+| **balanced** | execution | writing specs, code, tests, breaking work into tasks, interpreting check output |
+| **light** | mechanical / high-volume / exploration | scaffolding, file sweeps, scans, git plumbing, repo detection |
+
+## The profile (lives in `02-DOCS/wiki/sdd/config.yaml`)
+
+`sdd-init` writes this block. It is the canonical shape — keep it byte-for-byte in sync with
+the Config Shape in `../../sdd-init/SKILL.md` and the table in `../SKILL.md`.
+
+```yaml
+models:
+  enabled: false              # opt-in master switch; false = honor the session model, announce nothing
+  provider: anthropic         # which provider the tiers below resolve to
+  tiers:
+    heavy: claude-opus-4-8
+    balanced: claude-sonnet-4-6
+    light: claude-haiku-4-5-20251001
+  phases:
+    constitution: heavy
+    specify: balanced
+    clarify: balanced
+    plan: heavy
+    tasks: balanced
+    analyze: heavy
+    implement: balanced
+    verify: balanced
+    review: heavy
+    ship: light
+    debug: heavy
+    worktrees: light
+    sdd-init: light
+  overrides: {}               # per-phase tier overrides set by the user; preserved across re-calibration
+```
+
+**Master switch.** `enabled: false` (the default) means routing does nothing: honor the
+session model, never announce a switch, never nag. Everything below applies only when
+`enabled: true`.
+
+**Two phases are deliberately absent from `phases`:**
+
+- `sdd` (the dispatcher) — routing decisions are cheap; it stays on the session model.
+- `parallel` — it has no fixed tier. Each fanned-out subagent inherits the tier of the *kind
+  of work* its unit does (an implement-type unit → `balanced`; a scan/research unit → `light`;
+  a deep-reasoning unit → `heavy`).
+
+## Default phase → tier mapping (quality-biased) and why
+
+| Phase | Tier | Why |
+| --- | --- | --- |
+| constitution | heavy | Sets the project's non-negotiables — highest leverage, worth the best reasoning. |
+| specify | balanced | Drafts the what/why spec through dialogue; not architecture. |
+| clarify | balanced | Ranks and asks the few high-leverage questions; not architecture. |
+| plan | heavy | Architecture, interfaces, data flow, risks — the heaviest cognitive load. |
+| tasks | balanced | Decomposes the plan into verifiable tasks; structured but mechanical. |
+| analyze | heavy | Adversarial consistency gate across constitution ↔ spec ↔ plan ↔ tasks. |
+| implement | balanced | The bulk of TDD execution — cost-sensitive, quality sufficient. |
+| verify | balanced | Runs the checks and interprets failures with judgment. |
+| review | heavy | Adversarial diff reading — where the strongest model pays off most. |
+| ship | light | Close the branch: PR / merge / cleanup — mechanical. |
+| debug | heavy | Root-cause diagnosis — deep reasoning. |
+| worktrees | light | Isolate the workspace (git) — mechanical. |
+| sdd-init | light | Repo detection and calibration — mechanical. |
+
+The user owns this. They change a phase by adding it to `models.overrides` (e.g.
+`overrides: { implement: heavy }`), which wins over `phases`.
+
+## How a phase applies the profile (the procedure)
+
+Run this at the start of any SDD phase, after reading the user profile:
+
+1. **Read** `models` from `02-DOCS/wiki/sdd/config.yaml`. If the block is absent or
+   `enabled: false` → **do nothing**: honor the session model, say nothing about models.
+2. **Resolve the tier** for this phase: `models.overrides[phase]` if present, else
+   `models.phases[phase]`. (`parallel` resolves a tier per unit instead — see below.)
+3. **Resolve the model**: `models.tiers[tier]` for the active `models.provider`.
+4. **Apply, in two layers:**
+   - **Programmatic (real routing, where the assistant supports delegation).** When the phase
+     delegates work to a subagent (the `Task`/Agent tool) or fans out via `parallel`, set that
+     subagent's `model` to the resolved model. This is real routing regardless of the session
+     model and is the most reliable application — prefer it.
+   - **Advisory (all assistants, inline work).** If the resolved model differs from the current
+     session model and the work isn't being delegated, **announce** it at the phase boundary,
+     in one line (below), and give the switch command for the active
+     assistant (mechanism table below). Never block — the human may decline and continue.
+5. **Skip routing entirely** for a one-line / trivial change, exactly as the SDD skip rule says
+   for the rest of the chain. Ceremony serves shipping, not the other way around.
+6. **Record** the model actually used in the phase's result envelope (`model` field, below).
+   Log it to `02-DOCS/wiki/sdd/decisions.md` only when the choice actually mattered (e.g. you
+   overrode a tier for a hard plan) — not on every phase.
+
+### How to announce a switch
+
+Announcing never changes whether routing happens. A programmatic dispatch is silent. When the user must act, say it in one line, in the `orient` voice: the tier, the model, the one-word why, and the switch command (e.g. "para esta fase conviene opus: `/model opus`"). Explain the tier system or how to override it in config only when the user asks.
+
+## Per-assistant switch mechanism
+
+We route programmatically only where the assistant exposes a per-subagent model. Everywhere
+else routing is advisory — announce the tier, the user switches in their tool.
+
+| Assistant | Programmatic (delegation) | Advisory (inline) |
+| --- | --- | --- |
+| **Claude Code** | `model` on the `Task`/Agent tool and on `parallel` subagents (`opus`/`sonnet`/`haiku`) | `/model <name>` for the session |
+| **Codex CLI** | — (solo-agent) | model flag / `model` in config |
+| **Cursor** | native subagent model where exposed | model picker in the UI |
+| **Gemini CLI** | — (experimental) | model flag |
+| **Copilot / Windsurf / Cline / others** | — | announce the tier; user switches in the tool's model selector |
+
+When the active assistant has **no** way to switch, still announce the recommended tier so the
+human can decide — but **never claim a switch happened**. Honesty over magic.
+
+## Provider → concrete models (repoint the tiers here)
+
+To target another provider, change `models.provider` and set `models.tiers` to that row.
+
+| provider | heavy | balanced | light |
+| --- | --- | --- | --- |
+| `anthropic` | `claude-opus-4-8` | `claude-sonnet-4-6` | `claude-haiku-4-5-20251001` |
+| `openai` | `gpt-5.1` (or current flagship) | `gpt-5.1-mini` | `gpt-5.1-nano` |
+| `google` | `gemini-2.5-pro` | `gemini-2.5-flash` | `gemini-2.5-flash-lite` |
+| `openrouter` | a strong model slug | a mid model slug | a cheap/free model slug |
+
+These are starting points — set them to whatever your account actually has. The tiers are the
+contract; the concrete names are yours to edit.
+
+## The `developer` subagent (the installed implementation worker)
+
+ai-hub installs a **`developer`** subagent into every assistant that supports file-based agents
+(Claude Code `.claude/agents/`, Cursor, OpenCode, Gemini, Copilot, Junie, Kiro, Codex) when the
+harness is installed. It is the concrete embodiment of "run the fan-out on a smaller model":
+
+- It is pinned to the **balanced** tier — **Sonnet** for Anthropic-backed tools, the provider's
+  mid model elsewhere (Gemini Flash, GPT-mini). It is **never** `light`/Haiku — that tier is too
+  weak to build with. The floor for implementation is balanced.
+- The tier is chosen at **onboarding** (`init`, Step 4): balanced (default) or heavy. It is stored
+  in `.ai-hub/developer.json` and the installer writes the per-target agent file with the resolved
+  model on every (re)install/sync. If onboarding never asks, the install-time default is balanced.
+- `implement` and `parallel` **dispatch implementation/fan-out work to this agent**, so the
+  session model orchestrates while the cheaper-but-capable model does the bulk of the typing.
+- On assistants without file-based agents (Amp, Zed, Windsurf, Cline, Roo, Continue, Aider, Jules,
+  Antigravity), there is no agent file — the developer tier is advisory there, like the rest of
+  routing. The per-target model id is an editable default (see the provider table above).
+
+## Result-envelope `model` field
+
+Every phase's result envelope carries the model it ran on, so the chain is auditable:
+
+```json
+{
+  "status": "complete",
+  "model": { "tier": "heavy", "resolved": "claude-opus-4-8", "routing": "on|off" },
+  "...": "rest of the standard envelope"
+}
+```
+
+When routing is off, emit `"model": { "routing": "off" }` (no tier/resolved) — don't invent a
+tier you didn't use.
+
+## Honesty rules / anti-patterns → STOP
+
+| Rationalization | Reality |
+| --- | --- |
+| "Routing sounds good, I'll switch models even though the user never enabled it." | It's opt-in. `enabled: false` (and a missing block) means honor the session model and say nothing. |
+| "I'll tell the user I switched to Opus." (on an assistant with no programmatic switch) | You can't switch there. Announce the tier and the command; never claim a switch you didn't make. |
+| "The user wants it short, so I'll skip routing." | Short changes words, not behavior. Route the same; announce only when the user must act. |
+| "It's a one-line typo fix but the phase is `review`, so → heavy." | Skip routing on trivial changes, like the rest of the chain. Don't spin up the expensive model for a copy tweak. |
+| "I'll log the model on every phase." | Log to `decisions.md` only when the model choice mattered. The envelope `model` field already records the routine case. |
+| "config has no `models` block, I'll assume the defaults are active." | A missing block means routing is **off**. Defaults describe what `sdd-init` *writes*, not an implicit on-state. |
+| "Two parallel units, I'll run both on the phase's tier." | `parallel` has no fixed tier. Give each unit the tier of its own work. |