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

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

@@ -0,0 +1,93 @@
+skill: specify
+
+# Prompts that MUST load `specify`. The skill turns a fuzzy intent into a written
+# WHAT/WHY spec at specs/<slug>/spec.md — problem, goals/non-goals,
+# users, observable behaviour, testable acceptance criteria, points to clarify —
+# with zero implementation detail. It is NOT the technical plan (plan), NOT the
+# ambiguity sweep (clarify), NOT project-wide principles (constitution).
+should_trigger:
+  - prompt: "Write a spec for a bulk CSV import feature in our admin panel."
+    why: "Direct request to produce a specification for a feature — the skill's core job: WHAT/WHY at specs/<slug>/spec.md."
+
+  - prompt: "I want to add magic-link login but I haven't really thought it through yet — can you help me nail down what it should actually do?"
+    why: "A fuzzy intent that needs to become a spec (behaviour + acceptance criteria) before any planning; 'what it should do' is WHAT, not HOW."
+
+  - prompt: "Especifica la feature de notificaciones por email antes de que nos pongamos a construir nada."
+    why: "Spanish 'especifica … antes de construir' is the exact specify trigger — capture the spec before implementation, in the Spanish/English bilingual register."
+
+  - prompt: "Before we build it, capture the requirements for letting users export their data."
+    why: "Requirements capture for a feature, explicitly pre-build — the specify phase, even though the user never says the word 'spec'."
+
+  - prompt: "We just finished the project constitution. Now let's define the first feature: a referral program."
+    why: "Kicking off an SDD feature right after the constitution exists is precisely the constitution -> specify handoff this skill owns."
+
+  - prompt: "Draft a PRD for the new onboarding checklist — what it does and why, not how we'll code it."
+    why: "A PRD describing what/why and explicitly excluding the how is a spec; 'not how we'll code it' confirms the WHAT/WHY scope."
+
+  - prompt: "Everyone keeps jumping to the database design for the booking feature, but nobody has written down what it's even supposed to do. Sort that out."
+    why: "Someone jumped to HOW before WHAT is agreed; pulling it back to a behaviour/acceptance spec is the specify intervention."
+
+# NEAR-MISS prompts that must NOT load `specify`. Each routes to the genuinely
+# correct sibling. The recurring trap: anything that is the HOW (plan/stack),
+# the ambiguity sweep on an existing spec (clarify), or project-wide principles
+# (constitution) rather than the WHAT/WHY of one feature.
+should_not_trigger:
+  - prompt: "We already have the spec for magic-link login — now design the architecture, data flow, and testing strategy to build it."
+    route_to: "plan"
+    why: "A spec already exists and the ask is the technical HOW (architecture, data flow); that's the plan phase, not writing the spec."
+
+  - prompt: "Read our checkout spec and find the ambiguous bits and edge cases I haven't decided yet, then ask me about them."
+    route_to: "clarify"
+    why: "Surfacing ambiguities/edge cases in an EXISTING spec and resolving them is the de-risking clarify phase, distinct from authoring the spec."
+
+  - prompt: "Define our project's non-negotiable principles: stack canon, quality bars, and coding conventions."
+    route_to: "constitution"
+    why: "Project-wide guardrails/principles are the constitution, not a single feature's WHAT/WHY spec."
+
+  - prompt: "Build the bulk CSV import endpoint in FastAPI with Pydantic validation and tests."
+    route_to: "fastapi"
+    why: "Concrete implementation in a specific stack is build work delegated to the fastapi skill, the opposite of a no-implementation spec."
+
+  - prompt: "Design the type scale, colour palette, and layout for the onboarding checklist screen."
+    route_to: "design"
+    why: "Visual/UX design (pixels) is the design skill; specify owns the behavioural requirements, never the look."
+
+  - prompt: "Break the approved plan for the referral program into an ordered task list with done-checks."
+    route_to: "tasks"
+    why: "Decomposing an approved plan into verifiable tasks is the tasks phase; specify produces the upstream spec, not the task breakdown."
+
+# Concrete tasks the skill should guide, with a rubric to grade WITH vs WITHOUT
+# the skill loaded. A skill-guided answer holds WHAT/WHY discipline, asks one
+# question at a time, writes to the canonical path, and names open points; an
+# ungrounded answer typically leaks implementation and dumps questions at once.
+capability:
+  - scenario: "A user says: 'I want to add magic-link (passwordless) login.' There is a constitution at .specify/memory/constitution.md but no spec yet. Produce the spec."
+    must_include:
+      - "Reads the register from AGENTS.md and the constitution first, inferring everything it can before asking, then asks only contract-changing gaps — the whole FRONTIER in one numbered round, each with its recommendation, and nothing whose answer depends on another question open in that same round."
+      - "Stays strictly WHAT/WHY: no framework, token format, database table, endpoint shape, email provider, library, or file path appears in the spec — implementation-laden answers are flagged as points to clarify instead of guessed."
+      - "Produces the spec sections: Problem & why, Cost of not building it, The cheapest alternative, Goals, Non-goals / out of scope, Users & context, Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify — and neither of the two doubt sections is left as a formality: 'Cost of not building it' names a concrete consequence, and 'The cheapest alternative' names something that would solve most of it without building this, plus why that is not enough."
+      - "Writes testable acceptance criteria in Given/When/Then form that verify could later check (e.g. expired-link refusal, unknown-email revealing nothing)."
+      - "Writes the file to specs/<slug>/spec.md (kebab-case slug), indexes it in the root AGENTS.md Knowledge map under sdd/specs, and logs the spec creation to the canonical SDD decisions log at .planning/history.md."
+      - "Lists honest Points to clarify as the handoff rather than inventing values, and TYPES each one (pregunta abierta / suposición tomada / decisión diferida / área no formulable) so clarify knows whether to ask it, validate it, or leave it alone; a suposición carries its basis."
+      - "Ends by pointing to the clarify phase as the next step in the SDD chain."
+
+  - scenario: "A user pastes a rough one-liner: 'Let users export all their data as a download.' Show how you'd elicit and capture this without over-asking."
+    must_include:
+      - "Recovers the underlying problem/why rather than treating the feature request as the problem, and inherits any relevant constraints from the constitution."
+      - "Applies the 'would a different answer change the contract?' test, then splits what is left by dependency: independent gaps go out together in one round with recommendations, and any gap whose answer hinges on another still-open one is held for the next round rather than asked blind."
+      - "Captures observable behaviour (what the user sees/can do) and explicit non-goals / out-of-scope rather than implementation (no file format library, storage, or job-queue detail)."
+      - "Turns answers into binary acceptance criteria and defers unresolved items (e.g. data scope, retention, format) to typed Points to clarify instead of fabricating decisions, and checks the written file against the phase's exit gate before calling it done."
+      - "Notes that the spec is complete-enough-to-plan with open points remaining, and hands off to clarify — not to plan or implementation."
+      - "After the user answers a question, folds the answer in, states what changed, shows the revised spec, and asks for approval AGAIN — it does not treat the answer as approval of the spec, including when the user picked the recommended option."
+      - "If told to run the whole chain up front, records the approval as autopilot rather than item-by-item, and says the spec is the artifact to review after the fact."
+
+  - scenario: "A user opens with pure enthusiasm and no problem statement: 'Tengo una idea buenísima — quiero montar un dashboard con IA que resuma toda la actividad del equipo cada mañana.' Nothing exists yet. Show the FIRST response, verbatim. Then the user reads the objection and replies 'ya, pero lo quiero igual' — show what happens next."
+    must_include:
+      - "The first response opens with a one-sentence RESTATEMENT of the intent and the STRONGEST OBJECTION the assistant can actually articulate — never a verdict on the idea's quality ('great idea', 'makes sense', 'that would be really useful') in any language."
+      - "The objection is sourced from something checked — the repo, the wiki, prior specs, or a named fact about the situation — not from generic priors; and if after looking there is genuinely no objection, it says so in ONE line and moves on rather than manufacturing one to look rigorous."
+      - "Runs the FRAME block from idea-refinement before any question round: actor, current workaround INCLUDING doing nothing, desired progress, constraints, and known-vs-assumed separated."
+      - "Names at least one concrete thing it went and LOOKED AT before objecting — the repo, the wiki, an existing spec, a prior decision — or says plainly that it could not check anything and that the objection is therefore weaker."
+      - "Enumerates 'don't build it' as one of the directions, with its concrete consequence — not mentioned as a courtesy and not silently dropped."
+      - "Does not turn the objection into a refusal or a question round: it states the doubt and keeps going in the same turn, so the user gets both the reservation and the progress."
+      - "The spec it goes on to write carries 'Cost of not building it' and 'The cheapest alternative' with real content, and the assistant notes that spec:gate will refuse the spec if either is left empty."
+      - "On 'ya, pero lo quiero igual': does NOT re-argue and does NOT block — it accepts the decision, and says that the reason for proceeding against the objection gets written into the spec so the record shows the doubt was seen and overridden rather than never raised."

package/skills/shared/specify/references/eliciting-requirements.md

@@ -0,0 +1,117 @@
+# Eliciting requirements — infer first, then ask one thing
+
+The whole point of this skill is to reach a complete-enough spec with the
+fewest questions. That means inferring hard before asking, and asking surgically
+when you must. This reference holds the inference checklist and the elicitation
+patterns the SKILL body summarizes.
+
+## Inference checklist — answer these from existing material before asking
+
+Run down this list using the `constitution`, the existing wiki, sibling specs,
+and the intent itself. Only what survives as unknown becomes a question or a
+*point to clarify*.
+
+- **Problem** — does the intent already state the pain, or only the wanted
+  feature? If only the feature, the problem is the first thing to recover.
+- **Primary user** — who triggers this? The constitution's ICP / users article
+  usually answers it.
+- **Trigger** — what event or need makes someone want this? Often implicit in
+  the intent.
+- **Success** — what does the user get that they didn't have before? That's a
+  goal, in outcome terms.
+- **Boundaries** — what's adjacent but deliberately excluded? Derive non-goals
+  from the constitution's scope and quality bars.
+- **Happy path** — the common-case behaviour is usually inferable from the
+  intent; write it, then test it with the user.
+- **Edges** — empty / none / one / many / max, concurrent, repeated, expired,
+  unauthorized. Walk these mechanically; each is a candidate criterion.
+- **Errors** — what does the user see when it fails, and what must NOT be
+  revealed? Security/privacy constraints often live in the constitution.
+
+What you genuinely cannot resolve here is exactly what `clarify` exists for.
+Naming it is the correct outcome, not a failure.
+
+## The frontier pattern
+
+A gap earns a question only if a *different answer would change the contract*.
+Apply this test before asking:
+
+> "If they answer A vs B, does a goal, a user, the scope, or an acceptance
+> criterion change?" — No → don't ask; infer or type it as a point to clarify.
+> Yes → it is a question.
+
+Then decide *when* to ask it. Model the gaps as a tree: every decision branches
+into the decisions hanging off it. The **frontier** is every gap whose
+prerequisites are already settled — what you can ask now without guessing at
+answers you have not heard. Ask the whole frontier in one round; ask nothing
+that depends on an answer still pending in that same round.
+
+```text
+Round 1 (frontier: 3 independent gaps)
+❓ **Q1 — <title>**: <body, options if you have them>
+➡️ <your recommended answer>
+---
+❓ **Q2 — <title>**: …
+➡️ …
+---
+❓ **Q3 — <title>**: …
+➡️ …
+
+→ user answers → fold in → recompute the frontier → Round 2
+```
+
+Where the harness offers a native question selector, emit the round through it;
+otherwise emit the numbered text above. Same content either way.
+
+**Facts are yours, decisions are theirs.** A gap that needs a fact from the
+environment (a file, a config, a version) is legwork, not a question: go find
+it. Don't block the round on it — a running search is an unsettled prerequisite,
+so only its dependents wait. Ask the rest of the frontier now.
+
+**A frontier of one** is one question, and needs no apology. **A frontier of
+zero** is silence: never invent a question to look diligent.
+
+**If an answer redefines a question you already emitted this round**, say so and
+drop it. Re-ask it next round. An answer given under a premise that has since
+moved is worse than no answer, because it looks settled.
+
+Phrase by register:
+
+- **Non-technical** — plain language, one concept, offer a concrete
+  example to react to rather than an open void:
+  > "When someone's link has expired, should they be able to ask for a fresh
+  > one right there, or is that a separate step?"
+- **Technical** — terse, decision-shaped:
+  > "Expired-link recovery in scope, or defer?"
+
+Always: emit the round → wait → record each answer in its section → confirm it
+→ recompute the frontier. The thing to avoid was never two questions in
+one message; it was ten questions whose answers depend on each other, which is
+what crossing a dependency produces.
+
+## Turning answers into testable criteria
+
+Once you have an answer, convert it immediately to a Given/When/Then so it's not
+lost as prose:
+
+```text
+Answer: "Yes, they can request a new link from the expired page."
+becomes
+Given an expired link, When the user opens it, Then they see a "request a new
+link" action that issues a fresh one.
+```
+
+If the answer is fuzzy ("it should feel fast"), do not invent a number — push
+once for a concrete figure; if none is available, file it as a
+**suposición tomada** with its basis and its risk, which is what makes it
+something `clarify` can validate instead of re-ask.
+
+## When to stop
+
+Stop when the frontier is empty: every branch visited, nothing left silently
+assumed. Then run the exit gate (`npm run spec:gate <path>`) on the written
+file — the bound is a property of the artifact, not of your confidence.
+Lingering unknowns are fine, and belong in *Points to clarify*, typed. Over-asking to feel thorough is itself an anti-pattern: it burns the
+user's patience and pushes them to rubber-stamp answers they haven't thought
+through. A short spec with three honest open points beats a long spec with three
+fabricated ones.

package/skills/shared/specify/references/spec-template.md

@@ -0,0 +1,101 @@
+# Spec template
+
+Copy this into `02-DOCS/wiki/sdd/specs/<slug>.md`, fill it, and delete the
+italic guidance lines. Every line stays on WHAT and WHY — no framework, table,
+endpoint, library, file path, or algorithm. If you can't phrase it without
+naming the tech, it's a *point to clarify*, not a requirement.
+
+```markdown
+---
+type: spec
+title: Spec — <Feature name>
+description: WHAT and WHY for <feature> — problem, goals, behaviour, acceptance criteria.
+tags: [sdd, spec]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: sdd
+slug: <slug>
+status: draft
+---
+
+# Spec — <Feature name>
+
+> Slug: `<slug>` · Status: draft · Created: <YYYY-MM-DD>
+> Inherits: [constitution](../constitution.md)
+
+## Problem & why
+<The pain, who feels it, and the cost of leaving it unsolved. One short
+paragraph. State the problem, not a pre-chosen solution.>
+
+## Cost of not building it
+<What concretely happens if nobody does this, and what it costs. If the honest
+answer is "not much", that IS the finding — write it down rather than softening
+it. Required for specs dated 2026-09-06 or later.>
+
+## The cheapest alternative
+<What would solve most of this WITHOUT building it, and why that is not enough.
+"Nothing" is not an answer; there is always a manual workaround, a smaller
+version, or doing nothing. Required for specs dated 2026-09-06 or later.>
+
+## Goals
+- <What success delivers, in outcome terms. One bullet per goal.>
+
+## Non-goals / out of scope
+- <What is explicitly NOT done in THIS change — adjacent features, deferred
+  work, things a reader might assume are included. Be explicit, not silent:
+  unsaid scope becomes assumed scope.>
+
+## Users & context
+<Who acts, the situation they're in, and what they're trying to achieve.
+Real users from the constitution/wiki, not invented personas.>
+
+## Behaviour
+- Main path: <what the system does, observably, in the common case>
+- Edge cases: <empty, maximum, boundary, concurrent, repeated…>
+- Error paths: <what the user sees when it goes wrong; what is NOT revealed>
+
+## Acceptance criteria
+<Binary, observable checks. Prefer Given / When / Then. Each must be later
+checkable by `verify` and convertible to a `tasks` done-check.>
+- Given <state>, When <action>, Then <observable outcome>.
+- Given <state>, When <action>, Then <observable outcome>.
+
+## Points to clarify
+<The typed handoff to `clarify`. Every entry declares which of the four it is,
+because each one gets a different action from the next phase. Non-empty is
+normal; untyped is not — an untyped entry is read as `pregunta abierta`, the
+costliest of the four.>
+- **pregunta abierta** — <formulable now, unanswered. clarify asks it.>
+- **suposición tomada** — <what you decided.> *Base:* <why.> *Riesgo:* <what
+  changes if it turns out wrong.> clarify validates it rather than re-asking.
+- **decisión diferida** — <sharp, out of this cycle on purpose. clarify leaves
+  it.>
+- **área no formulable** — <you can tell something is coming and cannot phrase
+  the question yet. clarify notes it; it graduates when it sharpens.>
+```
+
+## Field notes
+
+- **Status** moves `draft` → `clarified` (after the `clarify` phase) → `planned`
+  (once `plan` exists). Don't invent other states. An approval obtained as a
+  blanket "just run it" is recorded as **approved in autopilot**, not flat.
+- **Before you call it written**, run `npm run spec:gate <path>`. It checks that
+  every section here carries content or an explicit open point, and prints the
+  clauses it cannot check (the unmarked assumption is yours).
+- **The two doubt sections are dated, not retroactive.** `Cost of not building
+  it` and `The cheapest alternative` are required only for specs whose
+  frontmatter `timestamp` is `2026-09-06` or later. Specs written before that
+  are exempt — they cannot answer honestly after the fact, and a gate that turns
+  the whole corpus red is a gate that gets switched off. A spec with no readable
+  `timestamp` falls on the exempt side too.
+- **Sharpness, not difficulty**, sorts the last two types from the first: *can
+  you state the question precisely now?* Not *can you answer it?* Anything past
+  what this change is for goes to **Non-goals**, where it never graduates.
+- **Behaviour** is where HOW leaks in most. Audit every verb: "queries",
+  "caches", "calls", "stores in" are implementation. Replace with the observable
+  effect ("shows", "lets the user", "prevents", "remembers across visits").
+- **Acceptance criteria** are the contract `verify` checks at the end of the
+  chain. A criterion a human has to subjectively judge is not done — sharpen it
+  or move the soft part to *Points to clarify*.
+- **Updating an existing spec** (same slug): read it, merge new understanding,
+  keep the history of resolved clarifications visible rather than silently
+  rewriting. Never overwrite blind.

package/skills/shared/speckit-analyze/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: speckit-analyze
+description: Check consistency, coverage and traceability across spec, plan, checklist and tasks before implementation. Use after speckit-tasks.
+license: MIT
+compatibility: Requires the Spec Kit layout under .specify/ and specs/.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Find contradictions before code makes them expensive.
+
+**Input**: `spec.md`, `plan.md`, `checklist.md` and `tasks.md` for the same feature.
+
+**Steps**
+
+1. Build a matrix: requirement → plan component → checklist gate → task.
+2. Report every gap, orphan and contradiction in `analysis.md`:
+   - `## Cobertura` — requirements without a task or test.
+   - `## Contradicciones` — spec vs plan vs checklist.
+   - `## Duplicados` — tasks or components that solve the same thing.
+   - `## Ambigüedades` — language that still admits two implementations.
+   - `## Veredicto` — `PASS` or `NEEDS_FIX` with the exact artifact to edit.
+3. Fix nothing in this phase; return findings to the owning artifact.
+
+**Artifacts**: `specs/<feature>/analysis.md`
+
+**Exit states**
+- `PASS` — full coverage and no contradiction.
+- `NEEDS_FIX` — at least one gap or contradiction; name the artifact.
+
+**Guardrails**
+- Never edit the spec or plan from this skill.
+- A requirement covered only by a "misc" task is not covered.
+- Do not silence a finding because implementation is already underway.

package/skills/shared/speckit-assess-decide/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: speckit-assess-decide
+description: Score the assessment and produce a GO, KILL or NEEDS_CLARIFICATION decision. Use when intake, research, problem and concept are complete.
+license: MIT
+compatibility: Requires the Spec Kit layout under `.specify/assessments/`.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Close the assessment lane with an explicit, auditable decision.
+
+**Input**: `intake.md`, `research.md`, `problem.md` and `concept.md` for the same slug.
+
+**Steps**
+
+1. Score each dimension from 1 to 5 in `decision.md`:
+   - `## Scorecard` — problema, evidencia, impacto, esfuerzo, reversibilidad.
+   - `## Decisión` — `GO`, `KILL` or `NEEDS_CLARIFICATION`.
+   - `## Justificación` — two paragraphs tied to the scorecard.
+   - `## Condiciones` — what must remain true for the decision to hold.
+   - `## Siguiente paso` — the exact change name for the feature lane, or the archive path.
+2. Apply the thresholds: `GO` requires evidence >= 3, impacto >= 3 and reversibilidad >= 3.
+3. If the decision is `KILL`, state what would have to change to reopen it.
+4. Hand off to the feature lane only with a human acknowledgment when the issue is `ai::spec-ready`.
+
+**Artifacts**: `.specify/assessments/<slug>/decision.md`
+
+**Exit states**
+- `GO` — proceed to `/speckit.constitution` and `/speckit.specify`.
+- `KILL` — archive the assessment directory with the decision.
+- `NEEDS_CLARIFICATION` — return to `assess-define` with the open question.
+
+**Guardrails**
+- Never approve your own `ai::spec-ready`; the human gate is mandatory.
+- Do not hide a low score behind optimistic prose.

package/skills/shared/speckit-assess-define/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: speckit-assess-define
+description: Define the problem, users, goals and success metrics of an idea with evidence. Use after assess-research confirmed the assumptions.
+license: MIT
+compatibility: Requires the Spec Kit layout under `.specify/assessments/`.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Write the problem definition that the rest of the assessment will be judged against.
+
+**Input**: `intake.md` and `research.md` for the same slug.
+
+**Steps**
+
+1. Write `problem.md`:
+   - `## Problema` — one paragraph, present tense, no solution.
+   - `## Usuarios` — primary and secondary, with frequency and context.
+   - `## Objetivos` — numbered, each measurable.
+   - `## No objetivos` — what this change deliberately excludes.
+   - `## Métricas` — baseline, target and how each is collected.
+   - `## Restricciones` — technical, legal or operational limits found in research.
+2. Check that every objective maps to at least one metric and one user.
+3. Remove adjectives that cannot be measured ("rápido", "fácil", "robusto").
+
+**Artifacts**: `.specify/assessments/<slug>/problem.md`
+
+**Exit states**
+- `GO` — problem, users, objectives and metrics are complete and consistent.
+- `NEEDS_CLARIFICATION` — an objective has no metric or an affected user is unknown.
+- `KILL` — the problem is real but the cost or constraints make it unviable now.
+
+**Guardrails**
+- Do not write requirements, user stories or acceptance criteria yet; that belongs to `spec.md`.
+- Never set a target without a baseline.

package/skills/shared/speckit-assess-intake/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: speckit-assess-intake
+description: Capture and normalize a raw idea before investing in research. Use when an issue or request arrives without a clear problem statement, owner or success signal.
+license: MIT
+compatibility: Requires the Spec Kit layout under `.specify/assessments/`.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Capture the idea exactly as it arrived, then normalize it without judging it yet.
+
+**Input**: the raw request (issue, message or note) and an optional slug.
+
+**Steps**
+
+1. Read the request and separate facts from assumptions. Do not research solutions yet.
+2. Assign a kebab-case slug and create `.specify/assessments/<slug>/`.
+3. Write `intake.md` with these headings only:
+   - `## Petición original` — verbatim, quoted.
+   - `## Problema observado` — one paragraph, no solution language.
+   - `## Afectados` — who suffers the problem and how often.
+   - `## Señal de éxito` — observable metric or event.
+   - `## Supuestos` — numbered, each falsifiable.
+   - `## Preguntas abiertas` — numbered, each answerable by research.
+4. Reject ideas that cannot name an affected user or a success signal: record why.
+
+**Artifacts**: `.specify/assessments/<slug>/intake.md`
+
+**Exit states**
+- `GO` — problem, users and success signal exist; continue to `assess-research`.
+- `NEEDS_CLARIFICATION` — a question blocks research; ask the human and stop.
+- `KILL` — no affected user or no observable outcome; archive with the reason.
+
+**Guardrails**
+- Never propose architecture, libraries or estimates in this phase.
+- Never invent quotes, metrics or owners.
+- Keep every assumption falsifiable; vague language such as "mejorar" is not a success signal.

package/skills/shared/speckit-assess-research/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: speckit-assess-research
+description: Gather evidence for and against an idea before shaping a solution. Use after assess-intake produced a problem statement with falsifiable assumptions.
+license: MIT
+compatibility: Requires the Spec Kit layout under `.specify/assessments/`.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Turn the intake assumptions into evidence, not opinions.
+
+**Input**: `.specify/assessments/<slug>/intake.md`.
+
+**Steps**
+
+1. For each assumption, search the repository, the GitLab issues and the public documentation.
+2. Record evidence in `research.md`:
+   - `## Evidencia a favor` — claim, source, date and how it was verified.
+   - `## Evidencia en contra` — same shape; do not omit inconvenient findings.
+   - `## Precedentes` — existing modules or issues that already solved part of this.
+   - `## Coste de oportunidad` — what the team stops doing if this proceeds.
+   - `## Supuestos refutados` — the intake assumptions that did not survive.
+3. Prefer primary sources (code, API docs, telemetry) over blog posts.
+4. Mark every unverifiable claim as `NO VERIFICADO`; never present it as fact.
+
+**Artifacts**: `.specify/assessments/<slug>/research.md`
+
+**Exit states**
+- `GO` — at least one assumption confirmed and none refuted fatally.
+- `NEEDS_CLARIFICATION` — the evidence is insufficient and a human can unblock it.
+- `KILL` — the evidence refutes the core problem or a cheaper precedent already exists.
+
+**Guardrails**
+- Cite sources with paths or URLs; an uncited claim is not evidence.
+- Do not design the solution, estimate effort or choose libraries.

package/skills/shared/speckit-assess-shape/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: speckit-assess-shape
+description: Compare solution shapes and choose an appetite before committing to a feature specification. Use after assess-define fixed the problem and metrics.
+license: MIT
+compatibility: Requires the Spec Kit layout under `.specify/assessments/`.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Explore two or three viable shapes, then choose one to carry into the feature lane.
+
+**Input**: `problem.md` and `research.md` for the same slug.
+
+**Steps**
+
+1. Describe at least two options in `concept.md`:
+   - `## Opción A/B/C` — approach, affected modules, data changes, risks.
+   - `## Esfuerzo` — appetite in days, not a detailed estimate.
+   - `## Coste de mantenimiento` — what the team must keep working.
+   - `## Reversibilidad` — how to undo it if the metrics do not move.
+2. Recommend one option and state the trade-off accepted.
+3. Define the smallest version that can validate the main metric.
+4. Record explicitly what is deferred to a later change.
+
+**Artifacts**: `.specify/assessments/<slug>/concept.md`
+
+**Exit states**
+- `GO` — one option fits the appetite and validates the metric.
+- `NEEDS_CLARIFICATION` — the options differ only in cost and a human must choose.
+- `KILL` — no option fits the appetite or every option is irreversible.
+
+**Guardrails**
+- Do not write file-level plans, schemas or code; `design.md` owns that.
+- Never present one option as the only possibility without comparing it.
+- The appetite is a constraint, not a promise: do not expand it silently.

package/skills/shared/speckit-bug-assess/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: speckit-bug-assess
+description: Diagnose a bug without editing code. Use when a defect needs a reproducible root cause before any fix is authorized.
+license: MIT
+compatibility: Requires access to logs, tests and the repository.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Produce a diagnosis that another engineer could reproduce.
+
+**Input**: the failing report, logs, and the affected route or component.
+
+**Steps**
+
+1. Reproduce the defect or record why it cannot be reproduced.
+2. Write `assessment.md`:
+   - `## Síntoma` — observed vs expected, with the exact request or action.
+   - `## Reproducción` — numbered steps and environment.
+   - `## Evidencia` — logs, stack traces, failing test names.
+   - `## Causa raíz` — the smallest code path or data state that explains it.
+   - `## Alcance` — modules affected and modules explicitly not affected.
+   - `## Fix propuesto` — approach only, no patch.
+   - `## Riesgo de regresión` — tests that must stay green.
+3. Point to file and line for the root cause; if unknown, say `NO DETERMINADA`.
+4. Do not edit source, tests or configuration in this phase.
+
+**Artifacts**: `.specify/bugs/<slug>/assessment.md`
+
+**Exit states**
+- `ROOT_CAUSE` — diagnosis complete; continue to `bug-fix`.
+- `NEEDS_DATA` — reproduction or evidence is missing; list exactly what is needed.
+
+**Guardrails**
+- Never guess a root cause from a stack trace alone.
+- Do not propose a fix that changes architecture; that requires a feature change.
+- Never mark a bug fixed from this phase.

package/skills/shared/speckit-bug-fix/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: speckit-bug-fix
+description: Apply a scoped repair for a diagnosed bug and document the change. Use after speckit-bug-assess produced ROOT_CAUSE.
+license: MIT
+compatibility: Requires a workspace with tests.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Fix only what the diagnosis proved, and leave the evidence behind.
+
+**Input**: `.specify/bugs/<slug>/assessment.md` with exit state `ROOT_CAUSE`.
+
+**Steps**
+
+1. Re-read the root cause and the declared scope. If the scope must grow, stop and return to `bug-assess`.
+2. Write the smallest change that removes the cause; do not refactor adjacent code.
+3. Add or update a regression test that fails before the fix and passes after it.
+4. Write `fix.md`:
+   - `## Causa corregida` — one sentence tied to the diagnosis.
+   - `## Archivos` — path and purpose of every touched file.
+   - `## Prueba de regresión` — test name and command.
+   - `## Fuera de alcance` — what was deliberately not touched.
+   - `## Riesgos` — remaining uncertainty.
+5. Run the narrow test suite and the package typecheck.
+
+**Artifacts**: `.specify/bugs/<slug>/fix.md` plus the code and test changes.
+
+**Exit states**
+- `FIXED` — regression test green and typecheck clean; continue to `bug-test`.
+- `BLOCKED` — the fix requires a scope or design change; record why and stop.
+
+**Guardrails**
+- Never weaken an existing test to make the suite pass.
+- Never include unrelated formatting or dependency updates.
+- No `TODO`, `FIXME` or placeholder code.

package/skills/shared/speckit-bug-test/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: speckit-bug-test
+description: Verify a bug fix against reproduction, regression and adjacent behavior, then issue a verdict. Use after speckit-bug-fix produced FIXED.
+license: MIT
+compatibility: Requires the project test commands.
+metadata:
+  author: onna
+  version: "1.0"
+---
+
+Independently verify the repair; do not trust the implementer's summary.
+
+**Input**: `assessment.md`, `fix.md` and the changed files.
+
+**Steps**
+
+1. Reproduce the original defect with the pre-fix revision or a fixture that simulates it.
+2. Run the regression test and confirm it fails without the patch and passes with it.
+3. Run the package suite and record the command, duration and result.
+4. Write `test.md`:
+   - `## Reproducción original` — pass/fail with evidence.
+   - `## Regresión` — test name and result.
+   - `## Suite` — command and totals.
+   - `## Riesgo residual` — areas not covered.
+   - `## Veredicto` — `VERIFIED`, `PARTIAL` or `FAILED`.
+5. If `FAILED`, return to `bug-assess` with the new evidence; do not patch the code here.
+
+**Artifacts**: `.specify/bugs/<slug>/test.md`
+
+**Exit states**
+- `VERIFIED` — original defect gone, regression test proven, suite green.
+- `PARTIAL` — fix works but evidence or environment is incomplete; list the gap.
+- `FAILED` — the defect persists or a new regression appears; reopen the diagnosis.
+
+**Guardrails**
+- Never edit the fix or the tests in this phase.
+- Never issue `VERIFIED` from a skipped or flaky test without saying so.