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

package/skills/shared/idea-refinement/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: idea-refinement
+description: "Use when a rough product, service, workflow or feature idea needs divergent options and assumption pressure-testing before it becomes a spec. Produces a decision brief with alternatives, evidence gaps, Not Now and a cheap experiment. NOT requirements or acceptance criteria (`specify`), NOT market sizing (`market-research`)."
+tags: [ideation, idea-refinement, product-discovery, assumptions, decision-brief]
+recommends: [specify, market-research, competitor-watch, ab-testing]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# idea-refinement — make the idea earn its direction
+
+Use this before `specify`, while the question is still “which version of this idea is worth pursuing?” The output is not a backlog or a polished pitch. It is a short decision brief that widens the option space, exposes what is merely assumed, and recommends the cheapest sensible direction to test.
+
+Inspect any brief, notes, product or repository already supplied before asking questions. Ask one question at a time only when the answer would change the option space. The user may delegate a choice; “use your judgment” is valid authority when the decision is reversible and the assumptions are made visible.
+
+## The refinement loop
+
+```text
+FRAME → DIVERGE → CHALLENGE → CONVERGE → TEST
+```
+
+### 1. FRAME the real opportunity
+
+Write five lines, no solution language yet:
+
+- **Actor:** who is struggling, in what situation?
+- **Current workaround:** what do they do now, including “do nothing”?
+- **Desired progress:** what observable change would make this useful?
+- **Constraints:** time, money, channel, trust, regulation, existing product.
+- **Known / assumed:** separate evidence already seen from hypotheses that only sound plausible.
+
+If the idea is phrased as a feature (“an AI dashboard”), reframe it as a problem and outcome (“operators need to spot failed jobs before customers report them”). Keep the original idea as one candidate, not as the conclusion.
+
+### 2. DIVERGE deliberately
+
+Produce **five to eight meaningfully different directions**. Variants that only change colors, names, pricing tiers or implementation technology count as one direction.
+
+Choose two lenses that attack the largest uncertainty:
+
+- **Remove / replace / combine / reverse:** change the mechanism, not the wording.
+- **Job and workaround:** improve, automate or eliminate the thing people already do.
+- **Constraint inversion:** assume the budget, time, data or integration is unavailable.
+- **Trust ladder:** begin with advice, then approval, then automation; do not jump to full autonomy.
+- **Pre-mortem:** imagine the idea failed in six months and design away the most likely cause.
+- **Narrow wedge:** find the smallest audience and moment where the pain is strongest.
+
+For each direction give: target actor, promised progress, mechanism, largest assumption, and what makes it distinct. Do not advocate yet.
+
+### 3. CHALLENGE the attractive options
+
+Take the three strongest directions and try to disprove them. Check:
+
+- Does the pain happen often and cost enough to change behaviour?
+- Does the user control the data, budget and permissions the idea requires?
+- Is the proposal replacing a habit or tool with a worse switching cost?
+- What dependency, incentive or trust failure could make the value impossible?
+- Which claim could be tested this week without building the product?
+
+State the strongest objection fairly. If an option survives only because a critical fact is unknown, label it **unverified**, not “promising.” Route market-size and demand evidence to `../market-research/SKILL.md`; route a named-rival comparison to `../competitor-watch/SKILL.md`.
+
+### 4. CONVERGE with explicit criteria
+
+Choose three to five criteria that fit the situation, then compare the finalists on the same scale. Typical criteria are user value, evidence strength, time to learning, reversibility, distribution access and operational risk. Weight only when one criterion genuinely dominates; decorative arithmetic is not evidence.
+
+Make one recommendation with:
+
+- the direction and the dominant reason;
+- confidence: high / medium / low;
+- assumptions it depends on;
+- what was rejected and why;
+- the fact that would most likely reverse the choice.
+
+If two options remain genuinely tied, recommend the experiment that distinguishes them. Do not ask the user to choose between indistinguishable summaries.
+
+### 5. TEST before specifying
+
+Name the cheapest next test that can change the decision: five problem interviews, a concierge workflow, a fake-door measure with consent, a manual prototype, a pricing conversation, or a data audit. Define the signal that would support the direction and the signal that would kill it.
+
+Only after a direction survives does it hand off to `../specify/SKILL.md` for goals, scope, behaviour and acceptance criteria.
+
+## Decision brief
+
+```markdown
+# Idea decision — <working title>
+
+## Opportunity
+Actor · workaround · desired progress · constraints
+
+## Evidence and assumptions
+- Seen: ...
+- Assumed: ...
+
+## Directions considered
+1. ...
+
+## Comparison
+Same criteria across the three finalists.
+
+## Recommendation
+Direction · confidence · deciding reason · reversal fact.
+
+## Not Now
+Ideas deliberately excluded from the first test.
+
+## Next experiment
+Method · audience · support signal · kill signal · timebox.
+```
+
+## Anti-patterns
+
+| Smell | Correction |
+|---|---|
+| Brainstorming becomes an implementation plan | Stop at direction + falsifier; `plan` comes after an approved spec. |
+| A long questionnaire precedes any thinking | Inspect first; ask one decision-changing question at a time. |
+| A score hides missing evidence | Put the evidence gap beside the score and lower confidence. |
+| The starting idea returns as cosmetic variants | Change mechanism, trust, audience, workflow or constraint. |
+| Ideation continues after direction and falsifier are clear | Stop and run the cheapest distinguishing experiment. |
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)

package/skills/shared/idea-refinement/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — idea-refinement
+
+Routing must distinguish exploration before commitment from `specify`, market evidence, competitor monitoring, task breakdown and experiment statistics. The capability case passes only when the answer widens the idea space, attacks assumptions, converges transparently and ends with a falsifiable cheap experiment rather than a polished feature spec.

package/skills/shared/idea-refinement/evals/cases.yaml

@@ -0,0 +1,42 @@
+skill: idea-refinement
+
+should_trigger:
+  - prompt: "I have a vague idea for helping remote teams share what they know; explore several versions before we spec it."
+    why: "A rough product idea needs divergent directions and a choice before requirements."
+  - prompt: "No quiero que me des la razón: abre opciones y destroza los supuestos de esta idea de onboarding."
+    why: "Spanish request for option generation and assumption pressure-testing."
+  - prompt: "Tenemos una idea de automatizar soporte, pero aún no sabemos si debería aconsejar, pedir aprobación o actuar sola."
+    why: "The trust ladder is the key unresolved product direction."
+  - prompt: "Fes un pre-mortem de la idea i proposa cinc enfocaments realment diferents abans de triar-ne un."
+    why: "Catalan request for pre-mortem plus meaningful divergence."
+  - prompt: "Turn this feature-shaped idea into a problem, alternatives, Not Now list, and the cheapest experiment."
+    why: "Names the complete refinement artifact and test handoff."
+  - prompt: "We keep circling three product concepts; compare them on evidence, reversibility, and time to learning."
+    why: "Convergence across explicit criteria is owned here."
+
+should_not_trigger:
+  - prompt: "Write the approved feature spec with user stories and acceptance criteria."
+    route_to: specify
+    why: "The direction is chosen and now needs the WHAT/WHY contract."
+  - prompt: "Size the European payroll market with TAM, SAM, SOM and dated sources."
+    route_to: market-research
+    why: "Defensible market sizing and demand evidence, not ideation."
+  - prompt: "Track what Notion and Slite shipped this quarter and compare their moves."
+    route_to: competitor-watch
+    why: "Standing named-competitor intelligence."
+  - prompt: "Break the notifications spec into dependency-ordered implementation tasks."
+    route_to: tasks
+    why: "Execution decomposition occurs after spec and plan."
+  - prompt: "Design the sample size and guardrail metrics for our landing-page experiment."
+    route_to: ab-testing
+    why: "The direction is already an experiment needing statistical design."
+
+capability:
+  - scenario: "Refine a rough idea for an AI assistant that helps small agencies capture project knowledge without creating more admin work."
+    must_include:
+      - "Reframes the feature idea as actor, current workaround, desired progress, constraints, and separate evidence versus assumptions."
+      - "Produces five to eight materially different directions, including different trust or workflow mechanisms rather than cosmetic variants."
+      - "Pressure-tests the strongest directions for adoption, data, permission, switching-cost, dependency, and failure assumptions."
+      - "Compares finalists against the same explicit criteria and recommends one with confidence and a fact that could reverse the decision."
+      - "Includes a Not Now list so discarded scope does not leak into the first experiment."
+      - "Defines one cheap next experiment with both a support signal and a kill signal, then hands the survivor to specify."

package/skills/shared/implement/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: implement
+description: "Use when an approved plan and task list exist and it is time to turn them into working, tested code — the SDD phase after `analyze` and before `verify`. Enforces TDD: a failing test comes before the code that makes it pass, one task at a time, appended to a progress ledger that survives compaction. Delegates test tooling to the stack skill and fans disjoint tasks out via `parallel`. NOT spec writing (that is `specify`), NOT planning (that is `plan`), NOT the final lint/test/audit gate (that is `verify`)."
+tags: [sdd, implement, code]
+recommends: [verify]
+profiles: [core, full]
+origin: ai-hub
+---
+
+# implement — turn the task list into tested code
+
+You have a spec, a plan, and an ordered task list (from `specify` → `plan` → `tasks`), and the
+`analyze` gate has cleared. This skill does the building: it walks the tasks in order, writes each
+one **test-first**, stops to show its work after every task, and records the decisions it makes
+along the way. It is the *intent → shipped code* engine's hands — `verify` is the gate that comes
+after, not part of this skill.
+
+This is a **process skill**. It owns the discipline (red → green → refactor, checkpoints, decision
+logging, constitution adherence). It does **not** own the test tooling — pytest fixtures, `go test`
+table-drivers, Vitest/Playwright, `flutter test` — those belong to the stack skill, and you call
+into them rather than reinventing them.
+
+## Before you write a line of code
+
+Run this short gate. Skipping it is the most common way an implement session goes sideways.
+**This gate is a hard refuse, not a checklist to feel good about:** if it fails you stop and route
+back — you do not write feature code anyway.
+
+1. **The spec + plan must exist AND be approved.** Open the spec (`02-DOCS/wiki/sdd/specs/<slug>.md`),
+   the plan (`02-DOCS/wiki/sdd/plans/<slug>.md`, which holds the task list), and the constitution
+   (`02-DOCS/wiki/sdd/constitution.md`). If any is missing, **you are not allowed to implement** —
+   route back: no spec → `specify`; no plan → `plan`; no task list inside the plan → `tasks`;
+   unresolved `analyze` findings → resolve them first. If a spec/plan exists but the user has not
+   actually seen and **approved** it, get that approval first. Never "start coding to discover the
+   plan as you go", and never accept "just build it, skip the spec" on a non-trivial feature — name
+   the gate in one friendly line and route to `specify`. (Only a true one-line, low-risk change
+   earns a skip, and you say so.)
+2. **Read the SDD runtime config.** Open `02-DOCS/wiki/sdd/config.yaml`. If it is missing on
+   non-trivial work, stop and route to `sdd-init`. Use `testing.strict_tdd`,
+   `testing.commands.apply`, `testing.commands.verify`, `sdd.review_budget` and
+   `sdd.registry_path`. Do not choose a different test command from memory while config exists.
+3. **Read the skill registry.** Open `.ai-hub/skill-registry.json` if present. Select only the
+   relevant stack/process skills for this task, then digest them into compact rules. If the
+   registry is missing, run or recommend `npx ai-hub registry refresh` and record the fallback.
+4. **Read the register.** Open `02-DOCS/wiki/harness/user-profile.md` and read `technical_level`.
+   It picks technical terms or plain words with analogies at each checkpoint (see "Checkpoints"
+   below). No profile yet → use analogies, and ask before any irreversible step.
+5. **Confirm isolation.** Default branch open for this project → work on it. Closed → stop before
+   the first commit and ask: this branch, a new one, or unlock (`worktrees`)? Never branch on your
+   own; another session in this folder makes the worktree mandatory.
+6. **Scan the tasks for independence.** Mark which tasks share files/state and which are disjoint.
+   Disjoint clusters are candidates for `parallel`; everything else runs in order.
+
+## The loop — one task at a time
+
+For **each task** in the list, in order (or dispatched per the parallel rule below):
+
+```text
+RED      → write the smallest failing test that encodes the task's done-check. Run it. Watch it FAIL
+           for the right reason (assertion, not import error). A test that was never red proves nothing.
+GREEN    → write the least code that makes that test pass. No extra features, no "while I'm here".
+           Run the test. Watch it PASS.
+TRIANGULATE → add the smallest edge-case test that proves the behavior is not hard-coded
+           (only when config.testing.strict_tdd is true and the task has meaningful edge cases).
+REFACTOR → with the test green, clean up names/duplication/shape. Re-run; still green. Only now.
+CHECK    → re-read the task's done-check. Met? Constitution still honored? Decision worth logging?
+PROGRESS → append task/test/blocker/decision state to 02-DOCS/wiki/sdd/progress/<slug>.md.
+COMMIT   → commit this task as one logical unit (authorship = Daner Alejandro Salazar Colorado; see ship for the rule).
+REVIEW   → dispatch a fresh reviewer subagent over THIS task's commits (see "Per-task review gate").
+           Fold its Critical/Important findings back in before you move on; Minor can wait.
+CHECKPOINT → stop and show: what changed, test output, review verdict, the next task. Wait for the user.
+```
+
+The order is load-bearing. **Red before green** is not a suggestion — a test you write *after* the
+code tells you nothing about whether it can fail. **Refactor only on green** keeps every cleanup
+reversible against a passing bar. **Checkpoint after each task** is what makes this resumable and
+reviewable instead of a 2000-line surprise diff.
+
+### Four things you may never do to reach green
+
+The loop only means anything if green cannot be manufactured. These are absolute, and each one is a
+way people reach green without fixing anything:
+
+1. **Never weaken a test to make it pass.** Not broadening an assertion, not adding a skip, not
+   raising a tolerance, not deleting it. A test that looks wrong is a **spec conversation** — surface
+   it, don't bury it.
+2. **Never edit a test and the implementation in the same step to reach green.** Change one, run,
+   then the other. Simultaneous edits let you redefine correctness to match your bug without
+   noticing you did it.
+3. **Never mock the unit under test**, or mock so much that the test only exercises the mocks. Mock
+   boundaries you don't own — network, clock, filesystem, third-party SDK — never the logic you are
+   being paid to verify.
+4. **Never chase the coverage number.** Coverage detects untested code; it is not a target. A test
+   added to touch lines, with no meaningful assertion, is gaming — and mutation testing exists
+   precisely to catch it (`../testing-py/SKILL.md`, `../testing-web/SKILL.md`, `../testing-go/SKILL.md`).
+
+### The done-check is the contract
+
+Each task carries a done-check from the `tasks` phase ("returns 409 on duplicate email", "list
+renders empty state when zero items"). That sentence **is** your first failing test. Do not invent a
+looser check, and do not mark a task done because the code "looks right" — done means the done-check's
+test is green and the relevant acceptance criterion in the spec is satisfied.
+
+## Delegating the test tooling (do not reinvent it)
+
+Write the *intent* of the test here; get the *mechanics* from the stack skill. The discipline is
+yours; the fixtures, runners and idioms are theirs.
+
+| Stack | Where the test mechanics live | What you delegate |
+| --- | --- | --- |
+| FastAPI / async Python | `../fastapi/references/testing.md` | `ASGITransport` in-process client, `dependency_overrides`, transactional rollback fixture, `pytest-asyncio` |
+| Go services | `../go/references/testing.md` | table-driven subtests, `httptest`, interface fakes, golden files, `errors.Is` checks |
+| Next.js / React | `../nextjs/references/testing.md` | Vitest + Testing Library for units, Playwright for flows, server-action / React Server Components testing |
+| Flutter | `../flutter/references/testing.md` | `flutter test` widget tests, `pump`/`pumpAndSettle`, golden tests, mocked repositories |
+
+If the feature spans two stacks (a Next.js front-end calling a FastAPI back-end), each task names its
+stack and pulls that stack's testing reference — you do not mix idioms inside one task.
+
+## Skill digestion and resolution
+
+When a task or subagent needs skill context, use the registry path from config:
+
+```text
+.ai-hub/skill-registry.json
+```
+
+Select the smallest set of skills that match the task. Digest each selected skill into 4-5 compact rules that affect this task. A task brief or checkpoint includes:
+
+```text
+Selected skills: fastapi, postgresdb, implement
+Compact rules:
+- Use the configured apply command from config.yaml.
+- Red test first; verify it fails for the right reason.
+- Keep DB migrations expand-contract when touching production tables.
+Skill resolution:
+- used: [...]
+- missing: [...]
+- fallback: [...]
+```
+
+If a skill is referenced but unavailable, say so and record the fallback. Do not silently pretend it was used.
+
+## Apply progress
+
+Maintain an append-only progress file:
+
+```text
+02-DOCS/wiki/sdd/progress/<slug>.md
+```
+
+Entry shape:
+
+```markdown
+## T004 — 2026-06-02
+- status: complete
+- red: `pytest tests/auth/test_login.py::test_bad_password_returns_401` failed for expected missing route
+- green: same test passed
+- triangulation: blank title returns 422
+- files: app/auth.py, tests/auth/test_login.py
+- decision: none
+- blocker: none
+```
+
+This file is what makes resumes and archive reliable. Never rewrite old entries; append corrections as new entries.
+
+### Resume & recovery — trust the ledger, not memory
+
+The progress file is the source of truth across compaction and restarts:
+
+- **A task recorded `status: complete` here is DONE — never re-dispatch it.** Re-running completed
+  tasks (re-implementing, re-committing) is the single most expensive recovery failure: it rebuilds
+  work that already exists and can clobber later commits.
+- **After a compaction or a fresh session, reconstruct state from this ledger + `git log`, not from
+  memory.** Read the progress entries and the commit history first; resume at the first task not
+  marked complete. If the ledger and the working tree disagree, believe the tree and append a
+  correction entry — do not silently re-run.
+
+## Running independent tasks in parallel
+
+When two or more tasks are genuinely disjoint — **no shared files, no shared state, no ordering
+dependency** — fan them out with `parallel` rather than serializing. The rule of thumb:
+
+- **Serialize** when a later task imports, edits, or asserts against an earlier task's output, or
+  when they touch the same file.
+- **Parallelize** when each task could be done by a different person who never talks to the others
+  (e.g. "add the `users` repository" and "add the `invoices` repository" in separate modules).
+
+Each parallel branch still runs its own full red → green → refactor loop and reports back its diff +
+test output. You merge the branches, then run the *combined* test suite before the next checkpoint —
+green-in-isolation is not green-together. Hand the orchestration to `parallel`; keep the TDD
+discipline inside each branch.
+
+**Dispatch implementation work to the `developer` subagent.** ai-hub installs a `developer` agent
+pinned to the balanced tier (Sonnet by default, chosen at onboarding, never `light`). When you
+delegate a task or fan out via `parallel`, dispatch it to that agent (e.g. Claude Code
+`subagent_type: developer`) so the bulk of TDD execution runs on the cheaper-but-capable model
+while you stay on the session model to orchestrate. Full rationale: `../sdd/references/model-routing.md`.
+
+### The dispatch contract (carriers, statuses, escalation)
+
+A dispatched worker is **context-isolated** — it sees only what you hand it, not your session. Make
+each dispatch self-sufficient and make its return machine-checkable:
+
+- **Carry the task, not your context.** Hand the worker its task brief, its **Interfaces** block
+  (`Consumes`/`Produces`, exact signatures — from `tasks`), and the plan's **§0 Global Constraints**.
+  Anything not in those three is invisible to it. Prefer **file paths over pasted text** (use
+  `scripts/task-brief` and `scripts/review-package`, below) — pasted briefs and diffs stay resident
+  in your context and get re-read every turn.
+- **Model is REQUIRED on every dispatch.** Always set the subagent's model explicitly (the
+  `developer` agent already pins balanced). An omitted model silently inherits the session's model —
+  usually the most expensive one — which is the quiet way fan-out cost explodes.
+- **The worker reports one of four statuses** (it does not guess when unsure):
+  - `DONE` — done-check green, `Produces` contract met.
+  - `DONE_WITH_CONCERNS` — green, but it flagged a risk/assumption for you to adjudicate.
+  - `BLOCKED` — cannot proceed (failing dependency, contradiction, missing access). Stops; does not
+    hack around it.
+  - `NEEDS_CONTEXT` — a `Consumes`/constraint it needed was not in the brief. Stops; names what's missing.
+- **Never force the same model to retry unchanged.** On `BLOCKED`/`NEEDS_CONTEXT` you must *change
+  something* before re-dispatching: add the missing context/interface, fix the dependency, or
+  escalate the tier (balanced → heavy) for a genuinely hard sub-problem. Re-running an identical
+  prompt on an identical model is how a loop burns budget without progress.
+
+## Per-task review gate
+
+After a task is committed and before its checkpoint, run a **small, fresh-eyes review of that task
+alone** — catching over-/under-building while it is one commit cheap to fix, instead of waiting for
+the whole-branch review when it is buried in a large diff. It is a mid-build gate, not the finish
+line (see the boundary below).
+
+How to run it:
+
+1. **Package the diff as a file, not a paste.** `scripts/review-package <BASE> <HEAD>` where `BASE`
+   is the task's *recorded* base sha (never `HEAD~1` — that drops every commit but the last of a
+   multi-commit task). It writes the commit list + `--stat` + full diff to one file.
+2. **Dispatch a fresh reviewer subagent** (context-isolated — it must NOT inherit your session
+   reasoning). Hand it: the review-package *path*, the task's **done-check**, the task's
+   **Interfaces → Produces** contract, and the plan's **§0 Global Constraints**. With routing on,
+   balanced is the floor; escalate to heavy for a risky/security-touching task. The frozen brief
+   lives in `references/per-task-review.md`.
+3. **It returns two verdicts in one pass:** *spec compliance* (missing / extra / misunderstood vs the
+   done-check + Produces) and *code quality* — every finding tagged severity
+   (`Critical`/`Important`/`Minor`) with `file:line` evidence.
+4. **Fold `Critical`/`Important` back in now**; `Minor` may wait for the end-of-branch review.
+
+**Anti-pre-judging (hard rule).** The dispatch must never tell the reviewer what *not* to flag,
+pre-rate a finding's severity, or explain why a choice is fine ("the plan chose X, treat as Minor").
+A stated rationale never downgrades a finding — that is laundering your own bias through the reviewer.
+Hand it the evidence and the contract; let it judge.
+
+**Boundary — this does not replace the end gates.** `verify` still runs the *whole* suite and the
+acceptance criteria once at the end, and `review` still reads the *whole* diff adversarially once
+before `ship`. The per-task gate is the cheap early pass; the broad reviews remain. Skip the per-task
+gate on a genuinely trivial task (a one-line change), like the rest of the chain.
+
+## Model tier — `balanced` (opt-in routing)
+
+This phase's default model tier is **`balanced`** — it is the bulk of TDD execution: cost-sensitive, with quality balanced handles well. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch in one line when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model (this is where routing pays off most — fan-out runs on `balanced` while a hard sub-problem can be escalated to `heavy`). Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
+## Checkpoints — what to say
+
+Speak in the `orient` voice, in the register `technical_level` sets. At each checkpoint show: the
+task, tests green or red, the one *why* behind any non-obvious choice, and the next task. Ask only
+where the plan genuinely forked, and confirm before deviating from the plan or doing anything
+irreversible.
+
+How short you are **never** changes the engineering. TDD, the done-checks, the constitution and
+decision logging hold for every reader.
+
+## Logging decisions (the 02-DOCS trail)
+
+When you make a choice the plan did not fully specify — a library, a data shape, an error contract, a
+deviation from the plan — append it to `02-DOCS/wiki/sdd/decisions.md` (append-only; create it if
+absent and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic). One entry:
+
+```text
+## YYYY-MM-DD — <short title>  (feature: <slug>, task: <n>)
+Context   — what forced the choice
+Options    — the 2–3 real alternatives weighed
+Decision   — what you chose
+Why        — the trade-off that decided it
+```
+
+Log the **non-obvious** ones — the choices a reviewer would otherwise have to reverse-engineer from
+the diff. Do not log "named the variable `count`". If a decision contradicts the constitution, you do
+not get to log your way around it: stop (see red flags).
+
+## Staying inside the constitution
+
+`02-DOCS/wiki/sdd/constitution.md` holds the project's non-negotiables (stack canon, quality bars,
+naming, security posture). Every task you implement must honor it. If a task can only be done by
+breaking a constitutional rule, that is a contradiction the `analyze` phase should have caught —
+surface it and stop; do not quietly violate the constitution to make a test pass. The constitution
+outranks the plan, and the plan outranks your in-the-moment preference.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality |
+| --- | --- |
+| "I'll write the tests after, once the code settles" | Then the test only confirms what you built, not what was asked. Red first, always. |
+| "This task is trivial, skip the failing test" | Trivial code breaks too, and the next task may lean on it. Smallest red test still goes first. |
+| "I'm here anyway, I'll also fix that other thing" | Scope creep buries the diff and breaks the done-check contract. One task, one commit. |
+| "The test passed first try without ever being red" | It tests nothing. Make it fail on purpose, then make it pass. |
+| "I'll batch ten tasks into one big commit to save time" | You just made the work unreviewable and un-resumable. One logical unit per task. |
+| "The constitution's rule doesn't fit here, I'll bend it" | The constitution outranks you. Surface the conflict; don't bend it silently. |
+| "These two tasks touch the same file but I'll parallelize anyway" | Shared file = shared state = merge pain and lost work. Serialize them. |
+| "Refactor now, the test is still red" | Never refactor on red — you can't tell a cleanup from a regression. Get green first. |
+| "I'll mark it done, the code looks correct" | Done = the done-check's test is green and the acceptance criterion holds. Looks ≠ green. |
+| "I'll just write the .env so the integration test runs" | Never. Secrets are the user's; mock/stub the boundary or use a test fixture. |
+
+## Red flags — stop and re-route
+
+- **No plan or no task list** → you cannot implement intent you haven't planned. Route to `plan` /
+  `tasks`.
+- **Unresolved `analyze` findings** (contradiction between constitution ↔ spec ↔ plan ↔ tasks) →
+  resolve them before any code; they will only get more expensive after the diff exists.
+- **A task forces a constitution violation** → surface it, stop, kick it back to `analyze`/`plan`.
+- **You're on the default branch** → stop before the first commit and ask: branch or default branch (`worktrees`).
+- **A test won't go red** (wrong reason — import error, syntax) → fix the test before trusting it.
+- **The combined suite is red after a parallel merge** → do not checkpoint as done; debug with
+  `debug` before continuing.
+- **You're tempted to disable/skip a failing test to "make progress"** → that's the bug talking.
+  Diagnose with `debug`; never ship around a red test.
+
+## Checklist (copy per task)
+
+```text
+- [ ] Read the task's done-check; it is my first test's assertion
+- [ ] RED: smallest test written, run, fails for the RIGHT reason
+- [ ] GREEN: least code to pass; test now green
+- [ ] REFACTOR: cleaned up on green; still green
+- [ ] Constitution honored; no banned pattern introduced
+- [ ] Non-obvious decision (if any) logged to 02-DOCS/wiki/sdd/decisions.md
+- [ ] Apply progress appended to 02-DOCS/wiki/sdd/progress/<slug>.md
+- [ ] Skill resolution recorded (used/missing/fallback/compact rules)
+- [ ] Committed as one logical unit (authorship = Daner Alejandro Salazar Colorado)
+- [ ] Checkpoint shown in the orient voice; next task named
+```
+
+## Result envelope
+
+End every implementation checkpoint or completed batch with:
+
+```json result-envelope
+{
+  "status": "complete",
+  "executive_summary": "Implemented task(s) with red/green/triangulate/refactor evidence.",
+  "artifact": "02-DOCS/wiki/sdd/progress/<slug>.md",
+  "next_recommended": "implement|verify",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["implement"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Use config testing commands.", "Append progress after every task."]
+  },
+  "evidence": ["red test output", "green test output", "progress entry path"]
+}
+```
+
+## What this skill is NOT
+
+- **Not the lint/type/audit gate.** Per-task tests prove the task; the *whole-suite* run plus
+  lint/type/security audit and acceptance-criteria sign-off is `verify`'s job. Don't claim the
+  feature is done here — that claim belongs to `verify`, on evidence.
+- **Not spec or plan writing.** If you find the plan is wrong mid-build, stop and amend it via
+  `plan`; don't silently re-architect inside a commit.
+- **Not the deep-debug protocol.** When a test fails for a reason you don't understand, switch to
+  `debug` (reproduce → isolate → hypothesize → fix → verify) instead of guessing.
+
+## Where you are in the chain
+
+`constitution` → `specify` → `clarify` → `plan` → `tasks` → `analyze` → **implement** → `verify` →
+`review` → `ship`. On-demand from here: `debug` (a test fails mysteriously), `worktrees` (need
+isolation), `parallel` (independent tasks to fan out).
+
+**Next:** when every task's done-check is green and committed, go to `verify` — run the stack skill's
+`scripts/verify.sh`, confirm the spec's acceptance criteria, and let evidence (not assertion) declare
+the feature done.
+
+## Orientación (siempre)
+
+Habla con la voz de `orient`: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según `technical_level` en `02-DOCS/wiki/harness/user-profile.md`. Cierra cada turno con el **bloque-brújula** (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). **Nunca termines en seco.** Protocolo completo: skill `orient` → `skills/orient/references/orientation-contract.md`. (Defiere a `suggest` el "¿instalo la skill que falta?".)
+

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

@@ -0,0 +1,56 @@
+# Eval harness — `implement` skill
+
+Run by an **agent harness** (an LLM agent with the Skill tool), not a pure shell script.
+`cases.yaml` is the fixture; this README is the honest run procedure. Three things to measure:
+**triggering** (should fire), **anti-triggering** (must not fire), and **capability** (does the
+skill make the build better).
+
+`implement` is a process skill — it ships no `scripts/verify.sh`. It is judged on its safety rails
+(test-first ordering, per-task checkpoints, decision logging, constitution adherence), not on a
+deterministic command.
+
+## 1. Triggering accuracy
+
+For each prompt in `should_trigger` and `should_not_trigger`:
+
+1. Start a fresh agent session with the `implement` skill available in the catalog, plus its named
+   routing siblings (`verify`, `tasks`, `debug`, `worktrees`, and the stack skills such as
+   `fastapi`) present but not the subject — so routing is realistic.
+2. Feed the prompt verbatim. Do **not** hint that a skill exists.
+3. Observe whether the agent invokes the `implement` skill.
+4. Run **3–5 trials** per prompt (LLM routing is stochastic); record the fire rate.
+
+Pass conditions:
+- Every `should_trigger` prompt fires `implement` in **≥ 90%** of trials.
+- Every `should_not_trigger` prompt does **not** fire it in ≥ 90% of trials, and the agent prefers
+  the named `route_to` sibling. The boundaries to watch: `tasks` (makes the list, doesn't build it),
+  `verify` (the final whole-suite gate, not per-task tests), `debug` (mysterious failures), and the
+  stack skills (concrete test tooling). A near-miss leaking into `implement` is a harder failure
+  than a missed trigger — fix the description boundary before shipping.
+
+## 2. Capability uplift (with vs without)
+
+For the `capability` scenario:
+
+1. **Without skill:** run the scenario in a clean session, no `implement` skill loaded. Capture the
+   answer.
+2. **With skill:** run the same prompt with `implement` (and the named stack sibling) loaded.
+3. Grade both against the scenario's `must_include` checklist — one point per bullet that is
+   *concretely* present (e.g. an actual failing test shown first, not just the phrase "test-first").
+4. Use 3 trials each side; average the coverage.
+
+Pass conditions:
+- **With** the skill: `must_include` coverage **≥ 80%**.
+- **Measurable uplift:** with-skill coverage beats without-skill. The expected gaps in the
+  without-skill run are the ones this skill exists to close: writing the test *after* the code (or
+  skipping the red step), barrelling through multiple tasks with no checkpoint, hand-rolling a test
+  runner instead of delegating to the stack reference, omitting the decisions.md trail, and claiming
+  "done" without tying it to the done-check + acceptance criterion.
+
+## What a failing eval tells you
+
+- Trigger misses → the description's "Use when…" triggers are too narrow; widen the phrasings.
+- Near-miss leaks → the boundary against `tasks`/`verify`/`debug` is blurry in the description; sharpen
+  the NOT clauses.
+- Capability gaps → the SKILL.md body under-specifies the loop (red→green→refactor), the checkpoint,
+  the delegation, or the decision log; tighten the relevant section.