@imolko/ultra-agent 0.1.0-beta

package/skills/code-review/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: code-review
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's ADRs and standards?) and Spec (does the code match the originating spec?). Use when the user wants to review a branch, a merge request, work-in-progress changes, or asks to "review since X".
+---
+
+# Code Review
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented standards (the ADR registry and commit-message standard)?
+- **Spec** — does the code faithfully implement the originating spec?
+
+Run both axes (in parallel sub-agents if your runtime supports them; otherwise sequentially), then aggregate the findings.
+
+Read `docs/agents/repo-config.md` for the repo pointers (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`) — use them instead of hardcoded paths.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`. If they didn't specify one, ask.
+
+Capture the diff once: `git diff <fixed-point>...HEAD` (three-dot, against the merge-base), plus `git log <fixed-point>..HEAD --oneline`. Confirm the ref resolves (`git rev-parse <fixed-point>`) and the diff is non-empty before going further.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`) — fetch via `glab issue view <id>`.
+2. A path the user passed as an argument.
+3. A spec under `docs/` or an issue matching the branch name or feature.
+4. Nothing found — ask the user. If there is no spec, the **Spec** axis skips and reports "no spec available".
+
+### 3. Identify the standards sources
+
+The ADR registry (`adr_dir`) is the primary standard: A-001 (clean architecture layers), T-015 (method placement), A-005 (Either returns), A-025 (ports/adapters/drivers), A-029 (intention verbs), A-031 (ubiquitous language — the domain READMEs, `domain_dir`), A-032 (artifact README format), A-033 (commit messages). Read the tier indexes and the ADRs relevant to the diff.
+
+On top of the registry, the Standards axis always carries the **smell baseline** below — Fowler code smells that apply even where no ADR speaks. Two rules bind it:
+
+- **The repo overrides.** A documented ADR standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic, never a hard violation — and skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*:
+
+- **Mysterious Name** — a name that doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape in more than one hunk or file. → extract the shared shape.
+- **Feature Envy** — a method reaching into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields keep travelling together. → bundle them into one type.
+- **Primitive Obsession** — a primitive standing in for a domain concept that deserves its own type. → give it a small type (A-031's value-objects).
+- **Repeated Switches** — the same switch/if-cascade recurs. → polymorphism, or one shared map.
+- **Shotgun Surgery** — one logical change scattered across many files. → gather what changes together.
+- **Divergent Change** — one module edited for several unrelated reasons. → split it.
+- **Speculative Generality** — abstraction added for needs the spec doesn't have. → delete it.
+- **Message Chains** — long `a.b().c().d()` navigation. → hide the walk behind one method.
+- **Middle Man** — a class that mostly delegates onward. → cut it.
+- **Refused Bequest** — an implementer ignoring most of what it inherits. → drop the inheritance.
+
+### 4. Run both axes
+
+**Standards axis** — check every changed file against the relevant ADRs and the smell baseline. Report: file, the standard or smell violated, the evidence, and the suggested fix.
+
+**Spec axis** — diff the changes against the originating spec. Report: each spec requirement as met / unmet / unclear, and any code that does work the spec doesn't ask for (gold-plating).
+
+### 5. Aggregate and report
+
+Report the two axes side by side — Standards findings, then Spec findings, each with severity (blocking / advisory). End with a one-line verdict.

package/skills/codebase-design/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: codebase-design
+description: Vocabulary and principles for designing deep modules and placing seams. Use when designing or improving a module's interface, deciding where a seam goes, making code more testable or agent-navigable, or when another skill (tdd, code-review, implement) needs the depth/leverage/locality terms.
+---
+
+# Codebase Design
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. The architectural container these terms live in is the four-layer Clean Architecture with ports, adapters, and drivers (A-001, A-025); this glossary decides *where a seam goes inside* that container and how deep the module behind it is.
+
+## Glossary
+
+Use these terms exactly — consistent language is the whole point.
+
+**Module** — anything with an interface and an implementation: a function, class, package, or a port. Scale-agnostic on purpose. _Avoid_: unit, component, service.
+
+**Interface** — everything a caller must know to use the module correctly: the type signature plus invariants, ordering constraints, error modes, required configuration, performance. _Avoid_: API, signature (too narrow). The feature-level interface is the **domain port** (A-025).
+
+**Implementation** — what's inside a module, behind its interface. A small interface over a large implementation is deep; a large interface over a small implementation is shallow.
+
+**Depth** — leverage at the interface: behaviour a caller or test exercises per unit of interface learned. **Deep** = a lot of behaviour behind a small interface; **shallow** = the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; where a module's interface lives. Where the seam goes is a design decision, distinct from what goes behind it. At the feature level the seams are the **ports** (A-025): the domain port (use case ↔ adapter) and the driver port (adapter ↔ driver) — swapping a driver without touching the use case is the seam's payoff. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter** (A-025) — the bridge that implements a **domain port** and delegates to a **driver port**; the one place the typed domain↔tech translation happens. In this repo "adapter" means that bridge specifically. For "the concrete thing satisfying an interface at a seam", say **driver**.
+
+**Leverage** — what callers get from depth: more capability per unit of interface learned. One implementation pays back across N call sites and M tests.
+
+**Locality** — what maintainers get from depth: change, bugs, knowledge and verification concentrate in one place. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+A deep module is a small interface + a lot of implementation; a shallow module is a large interface + little implementation (pass-through). When designing an interface, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+## Principles
+
+- **Push complexity down.** Hide the hard part behind the interface; the caller shouldn't see it.
+- **Design for the caller, not the implementation.**
+- **The seam is the leverage decision.** The right seam makes the module testable and replaceable without editing (swapping a driver without touching the use case or adapter, A-025).
+- **Method placement follows T-015**: domain behaviour lives on the definition, not the facade.
+- **Which layer a thing belongs to** is A-001 / A-026's question, not this glossary's.
+
+For the DDD instantiation (value-objects, aggregates, `of()`), see `tdd`'s deep-modules and interface-design references.

package/skills/configure-repo/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: configure-repo
+description: Configure the repo pointer hub (docs/agents/repo-config.md) by running the package CLI. Use once per repo, or after a folder rename.
+disable-model-invocation: true
+---
+
+# Configure Repo
+
+The pointer hub lives in `docs/agents/repo-config.md` and is written by the package CLI, not by hand (A-052). This skill is a thin wrapper: it runs the CLI and reports any values that diverge from the Imolko defaults.
+
+## Process
+
+1. Run the installer — it materializes the pointer hub with the Imolko defaults:
+
+```bash
+npx @imolko/ultra-agent install
+```
+
+The CLI writes `docs/agents/repo-config.md` with these pointers:
+
+| Puntero | Default | Qué resuelve |
+|---------|---------|--------------|
+| `adr_dir` | `docs/adr/` | registro ADR (índice: `<adr_dir>/index.md`) |
+| `domain_dir` | `domain/` | capa de dominio y lenguaje ubicuo (A-031, A-032) |
+| `issue_language` | `es` | idioma de los issues publicados |
+| `tracker_cli` | `glab` | CLI del issue tracker |
+| `ship_cmd` | `npx @imolko/ultra-agent ship` | comando que dispara el pipeline ship (A-039) |
+
+2. If the repo diverges from a default, edit that value in place — keep the pointer keys (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`, `ship_cmd`) unchanged.
+
+3. Verify the pointers resolve — `npx @imolko/ultra-agent status` must exit 0.
+
+4. Tell the human which values differ from the Imolko defaults, if any.

package/skills/diagnose-bug/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: diagnose-bug
+description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
+---
+
+# Diagnosing Bugs
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+Read `docs/agents/repo-config.md` for the repo pointers (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`) — use them instead of hardcoded paths.
+
+When exploring, read the relevant domain READMEs (`domain_dir`; A-031) for a mental model of the modules, and check the ADRs in the area you're touching.
+
+## Redact
+
+This skill has you show commands, outputs and captured artifacts. **Redact every secret first** — write `<REDACTED>` in its place. Build loops against env vars so the credential stays in the environment. Captured artifacts carry auth headers: quote only the lines that carry the signal.
+
+If the redacted output isn't enough to diagnose, say so and ask the user.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on *this* bug — you will find the cause; bisection, hypothesis-testing and instrumentation all just consume it. Without one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — roughly in order
+
+1. **Failing test** at the tightest test layer that exercises the bug — unit or integration (A-003) — placed at the seam (port, A-025) closest to the cause.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace** — save a real payload/event log to disk and replay it through the code path.
+6. **Throwaway harness** — a minimal subset of the system (one service, mocked deps) that exercises the bug path with one call.
+7. **Property / fuzz loop** — 1000 random inputs looking for the failure mode.
+8. **Bisection harness** — automate "boot at state X, check" so you can `git bisect run` it.
+9. **Differential loop** — same input through old vs new version, diff outputs.
+10. **HITL script** — last resort; drive the human through a structured loop so captured output feeds back to you.
+
+Build the right loop and the bug is 90% fixed.
+
+### Tighten the loop
+
+Once you have *a* loop, **tighten** it: faster? sharper signal (assert the specific symptom, not "didn't crash")? more deterministic (pin time, seed RNG, isolate filesystem, freeze network)? A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is a superpower.
+
+### Non-deterministic bugs
+
+The goal isn't a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. 50%-flake is debuggable; 1% isn't — keep raising the rate.
+
+### When you genuinely cannot build a loop
+
+Stop and say so. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR, log dump, core dump, screen recording), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+### Completion criterion — a tight loop that goes red
+
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** you have **already run at least once** (show the invocation and output, redacted), and it goes red on the bug.
+
+## Phase 2 — Bisect to the cause
+
+Run the loop, form a hypothesis, test it, repeat. Prefer the cheapest discriminating experiment each time. When you find the cause, name it precisely (file, line, mechanism) and confirm by removing the suspected cause and watching the loop go green.
+
+## Phase 3 — Fix and verify
+
+Hand the cause to `/skill:tdd` (red-green, A-003): the Phase 1 loop is the red signal. Fix until it's green, run the surrounding tests, and commit the loop as the regression test — it must go red without the fix.

package/skills/domain-modeling/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: domain-modeling
+description: Build and sharpen the system's domain model and record the decisions that change it. Use when a domain term is resolved, changed, or needs classifying (value object, entity, aggregate), a bounded context shifts, a decision crystallizes that deserves a project-tier ADR, or another skill (grill-me, implement, code-review) reaches it to record one.
+---
+
+# Domain Modeling
+
+Actively build and sharpen the domain model as work happens: challenge terms, stress-test boundaries, and record a decision the moment it crystallizes. This is the *active* discipline, not merely reading the glossary.
+
+Read `docs/agents/repo-config.md` for the repo pointers (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`) — use them instead of hardcoded paths.
+
+The glossary is the **ubiquitous language** (A-031): it lives in the domain layer (`domain_dir`), one `README.md` per artifact, in the A-032 format. There is no separate glossary file, and the domain layer is the authority for every term.
+
+## During the session
+
+### Challenge against the glossary
+
+When a term conflicts with the language already in the domain layer, call it out: "Your domain README defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+### Sharpen fuzzy language
+
+When a term is vague or overloaded, propose the precise canonical term: "'account' — do you mean the Customer or the User? Those are different artifacts."
+
+### Classify the term
+
+The model is DDD (A-031). Name each term's artifact type from the taxonomy (A-032): value object, entity, aggregate, domain service, domain event, or enum. A term you can't classify is either missing from the model or is really two artifacts.
+
+### Stress-test with concrete scenarios
+
+Invent scenarios that probe the boundaries between concepts and force the user to be precise.
+
+### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If it doesn't, surface the contradiction: "Your code cancels whole Orders, but you just said partial cancellation is possible — which is right?"
+
+## Writing
+
+Two artifacts are writable — domain READMEs and project-tier ADRs. Both are proposed first and written only after you confirm.
+
+### Domain READMEs (glossary)
+
+When a term is resolved or changed, edit the owning artifact's `README.md` following A-032. A term that belongs to no existing artifact is a bounded-context boundary question (A-008) — raise it before writing anything.
+
+### Project-tier ADRs
+
+Offer to write an ADR only when all three hold:
+
+1. **Hard to reverse** — changing the decision later costs something.
+2. **Surprising without context** — a future reader will wonder why.
+3. **The result of a real trade-off** — there were genuine alternatives and one was chosen.
+
+When they do, write a project-tier ADR following ADR-0000 — the consistency gate must exit 0.
+
+## Write boundary
+
+`ADR-0000` and the A, T, and P tiers are read-only; only the project tier and the domain READMEs are writable (A-034).

package/skills/grill-me/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: grill-me
+description: Relentless one-question-at-a-time interview to sharpen a plan, design, or the skill set itself, grounded in the ADR registry.
+disable-model-invocation: true
+---
+
+# Grill Me
+
+Interview the user relentlessly about a plan, a design, or the structure of the skill set itself, until you reach a shared understanding. Model it as a **design tree**: every decision branches into the decisions that hang off it. Ask **one question at a time**, each with your recommended answer, and let each answer reshape the tree.
+
+Read `docs/agents/repo-config.md` for the repo pointers (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`) — use them instead of hardcoded paths.
+
+## The frontier
+
+Track the **frontier** — the decisions whose prerequisites are already settled, the questions you can ask now without guessing at answers you haven't heard. Pick the next question from the frontier; a question whose answer depends on another still-open question waits until that one is answered. The session is done when the frontier is empty and the user confirms you share an understanding. Do not act on the plan before that confirmation.
+
+## Facts are your job
+
+Never ask the user for a fact you can look up yourself. Explore the codebase and the registry instead: files, the ADR registry (`adr_dir`), the domain READMEs (`domain_dir`), `package.json`, git history.
+
+## Grounding in the ADR registry
+
+Read the ADR index (`<adr_dir>/index.md`) for the tier map, then the index of the tiers relevant to the topic:
+
+- **A** — always: the methodology governs every plan.
+- **T** — when the topic touches TypeScript artifacts.
+- **P** — when the topic touches Python.
+- **project tier** — when the topic touches this project's domain decisions.
+
+When the user asserts something a governing ADR constrains or contradicts, surface it: "A-029 says business-side methods use intention verbs — your plan says `getData`; which wins?" The ADRs are the authority; the plan bends, they don't.
+
+## Writing: reach domain-modeling
+
+`grill-me` never edits files. When a term or decision crystallizes during the interview, reach `/skill:domain-modeling` to record it — propose the write, wait for confirmation, then delegate.

package/skills/i-have-an-idea/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: i-have-an-idea
+description: Turn a raw idea into a grab-able worker-issue — a five-probe interview, a domain-vocabulary pass, a duplicate check, and a route by candy to the right sharpener.
+disable-model-invocation: true
+---
+
+# I Have An Idea
+
+Capture a raw idea — loose, pre-spec — and publish it on the issue tracker as a worker-issue a developer can grab. The interview is light but forcing: five probes, each extracting a piece the idea can't survive without; then a pass that maps the idea's words to the domain vocabulary; then a duplicate check against open and closed issues; then publish. The published issue carries the route to the sharpener that fits its size.
+
+Reference: A-035 (the concept), A-042 (idea structure), A-037 (labels), A-038 (skill-first issues), A-031 (domain vocabulary).
+
+Read `docs/agents/repo-config.md` for the repo pointers (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`) — use them instead of hardcoded paths.
+
+## Process
+
+### 1. Take the idea
+
+Ask for the raw idea in one or two sentences. Do not shape it yet.
+
+### 2. Five probes — one question at a time
+
+Ask them in order. Do not skip any, and do not accept an empty answer.
+
+1. **What's the idea?** — the change, stated plainly.
+2. **What's the current situation?** — where it lives, what's true today, what's the friction. This becomes `# Contexto` (reuse the wording of `to-specs`' `# Contexto`).
+3. **Why does it matter?** — then drill once: "and why does *that* matter?"
+4. **What would done look like?** — what is true when it ships.
+5. **Can you put a candy on it?** — `1`, `2`, `4`, or `8`; `?` if it can't be estimated yet; or `16`/bigger ("too big for one idea"). The human self-estimates; the skill records, never suggests.
+
+If the answer to probe 5 is `?`, ask one more: **what is the one question whose answer would make this idea estimable?** That becomes `# Pregunta`. It must be one sharp question a decision or investigation can resolve — not a compound question, not a restatement of the idea. `# Pregunta` deliberately matches wayfinder's ticket section name, so the question lifts verbatim into the first decision ticket when the idea routes to `/skill:wayfinder`.
+
+### 3. Map the wording to the domain vocabulary
+
+Read the domain READMEs (`domain_dir`; A-031, A-032). For each non-glossary term in the idea and context:
+
+- **A canonical term exists** → propose the substitution and ask: "you said X — the domain calls this Y. Replace?"
+- **No canonical term** → ask: "is X a new domain concept, or just informal wording?"
+
+Outcome per term:
+
+- **Replace** → use the canonical term in the title, `# Contexto`, and `# Idea` (everywhere the term appears in the issue). The proponent's raw wording lives in the conversation, not the issue.
+- **New concept** → keep the proponent's wording (title, `# Contexto`, `# Idea`) and add one line to `# Contexto` per new term: `Nuevo concepto: <term> — candidato a /skill:domain-modeling`.
+- **Informal wording** → keep the proponent's wording as-is; no flag, no `/skill:domain-modeling` candidate.
+
+Only propose when a real glossary term exists — do not lecture.
+
+### 4. Duplicate check
+
+Search issues — open **and** closed — for near-matches using terms from the sharpened idea (now domain-mapped):
+
+```bash
+<tracker_cli> issue list --search "<keywords>" --all
+```
+
+- **Candidates found** → present them and let the human judge:
+  - **abandon** — it's a duplicate; drop the idea.
+  - **link** — attach this idea to the existing issue as a comment; publish nothing new. The note carries the title, the one-line idea, and the route:
+    ```bash
+    <tracker_cli> issue note <IID_DEL_ISSUE_EXISTENTE> -m "<título> — <idea, una línea> — <ruta>"
+    ```
+  - **publish anyway** — it's distinct; continue to publish.
+- **No candidates** → skip the question; go straight to publish (preview + confirm).
+
+The human decides duplication — never the skill.
+
+### 5. Publish
+
+Show a preview, ask for confirmation, then publish. The preview shows the **title, the labels that will be applied, and the full body**, with the route line called out — confirm the route (`/skill:grill-me` or `/skill:wayfinder`) before it is committed. Write all issue text in `issue_language` (default Spanish).
+
+The idea's structure is owned by A-042 (idea pre-spec) — the templates below are its operational copy.
+
+**Estimable (1–4 or 8):** labels `type::idea` + `candy::N`.
+
+```markdown
+# Skill recomendado
+
+<route line>
+
+# Contexto
+
+<probe 2>
+
+Nuevo concepto: <término> — candidato a /skill:domain-modeling
+
+# Idea
+
+<probe 1>
+
+# Por qué importa
+
+<probe 3>
+
+# Hecho se ve como
+
+<probe 4>
+```
+
+`# Skill recomendado` is deliberately not `# Alcance`: the idea is pre-spec and has no scope yet, so it carries A-038's first-instruction-by-name rule (`/skill:<name>` as the first thing read) in a section named for the recommended skill. Do not rename it to `# Alcance` — that name is reserved for post-spec issues (`to-specs`/`to-tasks`).
+
+The `# Skill recomendado` line by candy:
+
+- **1–4:** `Para comenzar, usa /skill:grill-me (→ /skill:to-specs → /skill:to-tasks → /skill:ship).`
+- **8:** `Para comenzar, usa /skill:wayfinder.`
+
+**Unestimable (`?`):** label `type::idea` only (no candy).
+
+```markdown
+# Skill recomendado
+
+Para comenzar, usa /skill:wayfinder.
+
+# Contexto
+
+<probe 2>
+
+Nuevo concepto: <término> — candidato a /skill:domain-modeling
+
+# Idea
+
+<probe 1>
+
+# Por qué importa
+
+<probe 3>
+
+# Hecho se ve como
+
+<probe 4>
+
+# Pregunta
+
+<la única pregunta cuya respuesta hace estimable la idea>
+
+Cuando el camino quede claro, continúa con /skill:to-specs → /skill:to-tasks → /skill:ship.
+```
+
+**16/bigger:** publish **nothing**. It is not one idea — it is a multi-session effort. There is no preview; state the routing decision and confirm it, then tell the human to run `/skill:wayfinder` to chart the map.
+
+Create with `tracker_cli` (default `glab`):
+
+```bash
+cat > /tmp/issue-body.md << 'ISSUE_EOF'
+<CUERPO>
+ISSUE_EOF
+
+<tracker_cli> issue create \
+  --title "<TITULO>" \
+  --description "$(cat /tmp/issue-body.md)" \
+  --label "type::idea,candy::<N>"
+```
+
+For `?`, omit `,candy::<N>`. The title is the idea — concise, in `issue_language`, in domain vocabulary (from step 3).
+
+### 6. Confirm
+
+Close with a one-line summary for whichever ending occurred:
+
+- **Published** → the issue URL, number, and the route (`/skill:grill-me` or `/skill:wayfinder`).
+- **Linked** → the note URL on the existing issue; nothing new published.
+- **Abandoned** → "idea descartada, nada publicado".
+- **16/bigger** → "sin issue publicado — traza el mapa con /skill:wayfinder".
+
+## Rules
+
+The idea's formatting rules are owned by A-042 — read and apply them from there, not restated here.

package/skills/implement/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: implement
+description: Implement a piece of work from a spec or set of tasks, using TDD at pre-agreed seams, and finish with a code review.
+disable-model-invocation: true
+---
+
+# Implement
+
+Implement the work described in the spec or tasks the user supplies.
+
+Read `docs/agents/repo-config.md` for the repo pointers (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`) — use them instead of hardcoded paths.
+
+**Precondition:** a spec or tasks must exist and be sharp enough to build against. No artifact → `/skill:i-have-an-idea` (raw idea) or `/skill:wayfinder` (fog / too big); a conversation to synthesize → `/skill:to-specs`; an artifact too vague to build against → back to `/skill:to-specs` / `/skill:to-tasks`. A seam question stays here — `/skill:codebase-design` (step 2).
+
+## Process
+
+1. **Read the work.** From the spec (produced by `/skill:to-specs`) or the tasks (produced by `/skill:to-tasks`), plus their blocking edges. If a domain artifact is needed and doesn't exist, scaffold it first with `/skill:ultra-generator`.
+2. **Agree the seams.** Confirm the seams (public boundaries) you'll implement and test at — use `/skill:codebase-design` for the vocabulary when the seam is a design question.
+3. **Implement with `/skill:tdd`.**
+4. **Keep it green.** Run typechecking regularly, single test files regularly, and the full test suite once at the end.
+5. **Review.** Once done, run `/skill:code-review` against the work.
+6. **Commit.** Commit to the current branch following the commit-message standard (A-033).

package/skills/research/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: research
+description: Investigate a question against high-trust primary sources and capture the findings as a cited Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated.
+---
+
+# Research
+
+Investigate the question against **primary sources** — official docs, source code, specs, first-party APIs — not a secondary write-up of them. Follow every claim back to the source that owns it.
+
+## Process
+
+1. **Frame the question.** One precise question, not a topic. If the user's request is vague, ask for the question first.
+2. **Hunt primary sources.** For each claim you make, find the source that owns it and cite it. Prefer official docs and first-party code over blogs and summaries.
+3. **Write the findings** to a single Markdown file, each claim carrying its source (a link or a `file:line` reference).
+4. **Save it where the repo keeps such notes.** Match the existing convention; if there is none, put it somewhere sensible (e.g. `docs/` or a notes directory) and say where.
+
+Keep the note tight: the question, the findings, the citations, and the open questions — not a literature review.

package/skills/ship/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: ship
+description: Fire the deterministic ship pipeline over a parent spec — implement its child issues, review, fix, and open one MR — in one action.
+disable-model-invocation: true
+---
+
+# Ship
+
+Fire the ship pipeline over a parent spec. The orchestrator (the `ship` subcommand of `@imolko/ultra-agent`) is deterministic and owns the whole run; you only fire it and stay out of its way.
+
+Read `docs/agents/repo-config.md` for the repo pointer `ship_cmd` — use it instead of hardcoding the command.
+
+Reference: A-039 (ship pipeline), A-037 (labels), A-033 (commits).
+
+## Invocation
+
+```bash
+npx @imolko/ultra-agent ship --parent-iid <PARENT_IID>
+```
+
+Run `npx @imolko/ultra-agent ship --help` for what it does and its flags. If you come from `to-tasks`, the parent's IID is already known; pass it as-is.
+
+## Rules
+
+- Do not edit the tracker while it runs — the `ship` subcommand owns the labels, assignees, and comments (A-039).
+- If it stops on a blocked child or a failure, report the exact state and wait for instructions.

package/skills/spike/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: spike
+description: Build a spike to answer a design question — a state/logic model, a UI variation, or an API shape. Use when the user wants to sanity-check whether logic or a flow feels right, explore what an interface should look like, or try out an API shape and see if it reads.
+---
+
+# Spike
+
+A **spike** is throwaway code that answers a question. The question decides the shape.
+
+## Pick a branch
+
+Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → **logic**: a single shareable HTML file — free-play buttons plus guided walkthroughs — that pushes the state machine through cases hard to reason about on paper, drivable by a non-developer.
+- **"What should this look like?"** → **UI**: several radically different UI variations on one route, switchable via a URL param and a floating bar, landed in the app's web interface.
+- **"What should this API look like?"** → **API**: a minimal endpoint exposing one candidate shape, called by a stub client written the way a real consumer would — if the client reads awkwardly, the shape is wrong.
+
+The branches produce different artifacts — getting this wrong wastes the whole spike. If the question is ambiguous and the user isn't reachable, default to whichever matches the surrounding code and state the assumption at the top.
+
+## Rules that apply to every branch
+
+1. **Throwaway from day one, clearly marked.** Locate it next to where it will be used; name it so a casual reader sees it's a spike, not production.
+2. **Trivial to run.** One command in the task runner, or a single HTML file the user double-clicks. No thinking to start it.
+3. **No persistence by default.** State lives in memory. If the question involves a database, hit a scratch DB or local file with a "SPIKE — wipe me" name.
+4. **Skip the polish.** No tests, no error handling beyond what makes it runnable, no abstractions.
+5. **Surface the state.** After every action, print or render the full relevant state so the user sees what changed.
+6. **Capture it when done.** Fold any validated decision into the real code, and capture the verdict — the answer the spike settled — on the implementation task.

package/skills/tdd/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: tdd
+description: Test-driven development with the red-green-refactor loop, applied to everything the repo builds — domain artifacts, features, apps, and shared-infra (representations, services). Use when building features or fixing bugs with TDD, mentions "red-green-refactor", wants to write tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+Read `docs/agents/repo-config.md` for the repo pointers (`adr_dir`, `domain_dir`, `issue_language`, `tracker_cli`) — use them instead of hardcoded paths.
+
+## Principles
+
+The methodology is owned by A-003 (`<adr_dir>/foundational/A-003-tdd.md`): the red-green-refactor loop, vertical slices, public-API testing, semantic assertions, and the tracer bullet. Read it for the rules; this skill keeps the workflow, and the language-specific patterns live in the references.
+
+## Workflow
+
+### 1. Planning
+
+Before writing any code:
+
+- [ ] Confirm what you're testing and its shape (domain artifact, feature/use-case, app, shared-infra)
+- [ ] Identify which domain rules need testing (valid input, empty input, max length, invalid type, etc.)
+- [ ] List the behaviors to test in priority order
+- [ ] Determine which error cases each rule triggers
+- [ ] If the seam/interface design is in question, consult `/skill:codebase-design`
+- [ ] Get user approval on the test plan
+
+Ask: "Which domain rules should we test? What are the critical boundaries?"
+
+### 2. Ensure the Artifact Exists
+
+If the artifact doesn't exist, scaffold it first with the language's generator (see [Language mechanics](#language-mechanics)).
+
+### 3. Tracer Bullet
+
+The first test is the valid-creation tracer bullet (A-003). A freshly scaffolded artifact usually already passes it, so this step lands GREEN immediately — it proves the test setup and the public factory, not new behavior.
+
+### 4. Incremental Loop
+
+For each domain rule, follow the red-green-refactor cycle: write the test (RED) → add the minimal code to pass (GREEN) → clean up (REFACTOR).
+
+### 5. Refactor
+
+After all tests pass:
+
+- [ ] Extract duplicate test setup into helper functions or `beforeEach`
+- [ ] Simplify validation rules expressed in multiple ways
+- [ ] Consider if the error messages are clear and descriptive
+- [ ] Run the full test suite after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Language mechanics
+
+The concrete test mechanics live in the language tiers, not in this skill:
+
+- **TypeScript**: file naming and JSDoc → T-002; the domain tooling stack → T-010; Zod validation errors → T-001. Test patterns and examples: [tests.md](references/tests.md), [mocking.md](references/mocking.md), [refactoring.md](references/refactoring.md), [deep-modules.md](references/deep-modules.md), [interface-design.md](references/interface-design.md).
+- **Python**: pytest conventions → P-006.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes domain behavior, not implementation
+[ ] Test uses the artifact's public API, not its internals
+[ ] Test uses semantic assertions (A-003)
+[ ] Test would survive a refactor of the internals
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```