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

package/skills/shared/open-weights/references/sizing-and-quant.md

@@ -0,0 +1,89 @@
+# Size ↔ VRAM and quant formats — selection-time depth
+
+This is the **"will it fit before I pick it"** estimate. The **operational** per-request KV-cache
+sizing and runtime flags live in `ollama` (single box) and `vllm` (serving) — do not duplicate them
+here. These numbers are rules of thumb for *choosing a size class*, not a per-model spec sheet;
+confirm the real footprint with `ollama show` or the model card.
+
+## The weights formula
+
+```text
+weights_GB ≈ params(B) × bytes_per_param
+  fp16 / bf16 → 2.0     (2 GB per 1B params)
+  int8 / 8-bit → ~1.0   (1 GB per 1B params)
+  4-bit        → ~0.5–0.6 (≈ 0.6 GB per 1B params, conservative)
+
+total_VRAM ≈ weights_GB + KV_cache + runtime_overhead
+```
+
+The 4-bit rate is a round number: measured k-quant rates land near ~4.9 bits/weight for Q4_K_M
+(~0.6 byte/param). Round **up** when budgeting so you don't OOM. **KV cache and overhead are extra**
+and grow with context length — always leave a margin above the weights figure.
+
+### Worked examples (weights only, fp16 unless noted)
+
+| Model | Params | fp16 | 8-bit | 4-bit |
+|---|---|---|---|---|
+| Small | 3B | ~6 GB | ~3 GB | ~2 GB |
+| Mid | 8B | ~16 GB | ~8 GB | ~5 GB |
+| Large-consumer | 32B | ~64 GB | ~32 GB | ~20 GB |
+| Big | 70B | **~140 GB** | ~70 GB | ~40 GB |
+
+**The 70B lesson:** fp16 ~140 GB does not fit any single GPU on the market for most teams. Options:
+(a) **quantize** to 4-bit (~40 GB → fits one 80 GB card), accepting some quality/throughput cost; or
+(b) **tensor-parallel** across multiple GPUs (e.g. 2×80 GB) to keep full precision — a `vllm` job.
+
+## What fits which hardware class
+
+| Hardware | fp16 ceiling (weights) | Practical pick |
+|---|---|---|
+| 8 GB consumer GPU | ~3B | 7–8B @ 4-bit (~5 GB) + small context |
+| 12 GB | ~5B | up to ~14B @ 4-bit |
+| 16 GB | ~7B | 13–14B @ 4-bit; 7–8B @ 8-bit |
+| 24 GB (3090/4090) | ~10B | ~32B @ 4-bit (~20 GB) |
+| 48 GB (or 2×24) | ~22B | 70B @ 4-bit is tight; better on 80 GB |
+| 80 GB (A100/H100) | ~34B | 70B @ 4-bit (~40 GB), or a big MoE (gpt-oss-120b) |
+| 2×80 GB+ | 70B fp16 (~140 GB) via TP | full-precision large models |
+| Apple unified (e.g. 64 GB) | shares with the whole OS | budget vs **total** unified memory, not a GPU number |
+| CPU / edge | — | small GGUF (≤3B) at 4-bit; slow but runs |
+
+## MoE: total vs active params
+
+Mixture-of-experts models (Mixtral, gpt-oss, Llama 4, big Qwen/DeepSeek) route each token through a
+**subset** of experts. So a "120B" MoE might activate only ~5B params per token (fast inference) —
+**but you still need VRAM to hold all experts.** Budget against **total** params for memory and
+against **active** params for the speed intuition. Don't size a 120B MoE as if it were a 5B dense.
+
+## Quant formats — pick by runtime
+
+| Format | Runtime | Notes |
+|---|---|---|
+| **GGUF** | llama.cpp, Ollama, LM Studio | The local default. CPU + Apple Silicon + single GPU. Self-contained files with quant in the name. |
+| **AWQ** | vLLM, TGI, transformers | Activation-aware weight quant; strong 4-bit quality for GPU serving. |
+| **GPTQ** | vLLM, TGI, transformers | Older post-training quant; very widely available 4-bit. |
+| **bitsandbytes (NF4/int8)** | transformers | Load-time quantization — quick for experiments and QLoRA fine-tuning. |
+| **EXL2** | ExLlamaV2 | Variable bit-rate; good on consumer GPUs, flexible size/quality. |
+
+Rule: **local/Mac/CPU → GGUF**; **GPU serving → AWQ or GPTQ**; **fine-tuning experiments → bnb NF4**.
+Getting or converting to a format is a `huggingface` (convert) / `ollama` / `vllm` job.
+
+## Decoding a GGUF quant tag
+
+`Q4_K_M`:
+- **`Q4`** — nominal ~4-bit weights.
+- **`_K`** — a **k-quant**: mixed precision that keeps the more error-sensitive tensors (attention,
+  some feed-forward) at higher bit-depth than the bulk. Better quality than the old flat `Q4_0`.
+- **`_M`** — size/quality **tier**: `_S` (small, lower), `_M` (medium — the balanced default),
+  `_L` (large, higher). There are also non-K legacy tags (`Q4_0`, `Q4_1`, `Q5_0`…).
+
+Quality ladder (rough): `fp16` ≥ `Q8_0` (near-lossless, ~1 byte/param) > `Q6_K` > `Q5_K_M` >
+**`Q4_K_M`** (standard default, ~half of fp16 for a few % loss) > `Q3_K` > `Q2_K` (noticeable
+degradation). **Do not drop below Q4 to cram a too-big model onto a too-small GPU** — the quality
+falls off fast and you'll often still OOM at real context. Pick a smaller model instead.
+
+## Selection heuristic
+
+1. Estimate weights_GB at 4-bit for the sizes you're considering.
+2. Keep it **comfortably under** your VRAM (leave ~20–30% for KV cache + overhead + context).
+3. If nothing that fits passes your eval, the honest options are: a better-tuned smaller model, a
+   bigger box (route to `runpod`/`modal`), or `vllm` tensor-parallel — **not** sub-Q4 desperation.

package/skills/shared/orient/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: orient
+description: "Always-on. How the harness talks to the person: STE-style short sentences, every answer understandable on its own, technical or with analogies by the profile, and a ladder (text → diagram → HTML page → video on request) when the person does not follow. Closes every turn with the brújula. Fires on 'no entiendo', 'explícamelo', 'enséñame', 'dibújamelo', 'explain it from zero', '¿dónde estamos?'. NOT the missing-skill installer (that is `suggest`), NOT a text the user sends to others (that is `unslop`)."
+tags: [orient, voice, ste, explain, diagram, eli5, show-me, compass, always-on]
+recommends: []
+profiles: [minimal, core, full]
+origin: ai-hub
+---
+
+# orient — talk so the person understands, then show them where they are
+
+You own how the harness speaks to the person. Four rules, a register, a ladder, and the brújula.
+
+## The four rules
+
+1. **Their language.** Reply in the language the person writes in, this turn. If they switch, you
+   switch. `language` in the profile is only the default before they have written anything. Every
+   word you add follows it, labels included (the lane, the brújula); code, commands and paths stay
+   as they are. The harness's own instructions are in English: that is never a reason to answer in
+   English.
+2. **Speak STE, in their language.** STE is the controlled writing style of aircraft manuals
+   (ASD-STE100): a style, not a language. Short sentences. One idea per sentence. Simple words.
+   Active voice. The instruction before the reason.
+3. **Every answer stands alone.** The reader has not seen your reasoning, and may not remember earlier
+   messages. Never point at something they did not see ("the second commit", "that fix", "as above").
+   Name it, in one sentence.
+4. **Short.** Say what the reader needs, then stop. No walls of paragraphs. Rules 3 and 4 meet in one
+   place: give the **minimum** context, never the whole story.
+
+Three habits make those rules hold (adapted from the `i-have-adhd` skill, ayghri, MIT):
+
+- **The answer goes first.** The first line is the answer, the verdict or the action. Context comes
+  after, and only if it is needed. A reader who stops after one line must still know the answer.
+- **Five visible items at most.** Group a longer list and show the five that matter now. Keep the
+  rest and give it when asked or when it becomes next. Never drop an item that matters.
+- **Check before you send.** Delete a first sentence that only announces what follows. Delete
+  closing filler ("hope this helps"); the brújula is the close. Delete a "perhaps" that adds
+  nothing, and keep one that carries real doubt.
+
+Full rules and examples → `references/orientation-contract.md`.
+
+## The register
+
+Read `technical_level` in `02-DOCS/wiki/harness/user-profile.md`.
+
+| technical_level | Register |
+|---|---|
+| `technical` | Technical terms, used directly. No 101s. |
+| `non-technical`, `mixed` | Plain words. One everyday analogy for each new idea. |
+| no profile | Analogies. Ask once: "¿Te hablo en lenguaje técnico o con analogías?" and save the answer. |
+
+The person can change it by saying so ("háblame más técnico", "con analogías"). Update
+`technical_level` (`technical` or `non-technical`), confirm in one line, apply it from this turn.
+Old profiles may carry `accompaniment_level:` or `accompaniment:` (the retired L0–L3 dial): ignore both.
+
+## The ladder — when the person does not follow
+
+Climb **one** step per sign. Signs: they repeat the question, say "no entiendo" / "¿qué?" /
+"explícamelo", answer short and annoyed, or ask about a term you just used. Weak signs are not signs:
+guessing their mood reads as condescending.
+
+| Step | What | Detail |
+|---|---|---|
+| 1 | Text, in the three rules | always |
+| 2 | One diagram in the chat | the smallest form that carries the point |
+| 3 | One self-contained HTML page | big pictures, few words; open it |
+| 4 | Animated video | only offered, never made unasked |
+
+The person can also ask for any step directly ("dibújamelo", "hazme una página", "explícamelo desde
+cero"). Forms, the from-zero page and the video step → `references/explain-ladder.md`.
+
+## The brújula — close every turn
+
+No turn ends in seco. One block, at the end, never mid-work.
+
+```text
+📍 Dónde estás — the state, in one sentence that stands alone
+✅ Qué has hecho — only when something was done
+🧭 Por qué — only when a decision was made; one sentence
+➡️ Siguiente — 1-3 concrete options, ending in a question
+```
+
+📍 and ➡️ always. ✅ and 🧭 only when they carry something. Situate from what is **actually** built;
+an invented state is worse than a shorter block. At a real fork, ask: the fork is where the person's
+judgment is worth more than yours.
+
+## Where this ends
+
+- "Install the missing skill?" belongs to `suggest`.
+- A text the person sends to others (email, post, README) belongs to `unslop`.
+- Visual identity is `design`; a deck someone presents from is `presentations`; a course with
+  exercises is `course-builder`.

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

@@ -0,0 +1,18 @@
+# Evals — orient
+
+How the harness talks to the person. These cases check the voice (STE-style, short, every answer
+stands alone), the register from `technical_level`, the explain ladder (text → diagram → HTML →
+video on request), and the brújula at the end of a turn. Install prompts stay with `suggest`; text
+for others stays with `unslop`.
+
+| Prompt | Expected |
+|---|---|
+| "ya está instalado, ¿y ahora qué?" | short stand-alone state + next step as a question |
+| "no entiendo nada" | one step up the ladder: a small diagram |
+| "explícame Docker desde cero" | from-zero explanation with analogies |
+| "háblame más técnico" | set technical_level, confirm, apply |
+| "renombra esta variable" | no full brújula block (trivial mid-flow) |
+| "haz que este correo suene humano" | defer to `unslop` |
+
+A pass = short sentences, nothing that needs earlier context, the right register, one ladder step
+per sign, and no turn ending in seco.

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

@@ -0,0 +1,67 @@
+skill: orient
+
+# How the harness talks to the person: STE-style short sentences, every answer stands alone,
+# register (technical or with analogies) from the register, a ladder (text → diagram → HTML →
+# video on request) when the person does not follow, and the brújula at the end of a turn.
+# It defers "install a missing skill?" to suggest and text for others to unslop.
+
+should_trigger:
+  - prompt: "Ya está instalado el postgresdb. ¿Y ahora qué?"
+    why: "An action just finished and the user is unsure what to do next — orient situates them and proposes the next step."
+
+  - prompt: "No sé por dónde seguir con mi proyecto."
+    why: "The user is lost — the core trigger: situate on the map and propose 1-3 next steps."
+
+  - prompt: "No entiendo nada de lo que me has dicho."
+    why: "A clear sign the person does not follow — orient climbs one step of the ladder (a diagram)."
+
+  - prompt: "Dibújame cómo funciona el flujo de login."
+    why: "A direct request for step 2 of the ladder — the smallest diagram that carries the point."
+
+  - prompt: "Explícame qué es Docker desde cero, que no sé nada."
+    why: "Zero background — a from-zero explanation with everyday analogies (the old eli5 job, now step 3 of the ladder)."
+
+  - prompt: "Háblame más técnico, que esto ya lo controlo."
+    why: "A spoken register change — orient sets the register to technical, confirms in one line, applies it."
+
+  - prompt: "¿En qué punto del proyecto vamos?"
+    why: "A 'where am I?' question — orient renders the state in sentences that stand alone."
+
+should_not_trigger:
+  - prompt: "Renombra esta variable a `userCount`."
+    route_to: "none"
+    why: "A trivial mechanical edit mid-flow — no full brújula block over a one-line change."
+
+  - prompt: "Necesito una base de datos para guardar pedidos."
+    route_to: "suggest"
+    why: "An install gap — suggest owns it. orient must not duplicate the 'install it?' prompt."
+
+  - prompt: "Haz que este correo al cliente suene más humano."
+    route_to: "unslop"
+    why: "A text the user sends to others — unslop owns the human-register rewrite."
+
+  - prompt: "Arregla el test que falla."
+    route_to: "debug"
+    why: "Root-cause work owned by debug; orient only closes the turn."
+
+capability:
+  - scenario: "The user just ran `ai-hub add skill postgresdb` and says 'ya está, ¿y ahora qué?'. The profile records `technical_level: non-technical`. Show how orient closes the turn."
+    must_include:
+      - "Short sentences, one idea each; no paragraph walls"
+      - "Every line understandable without earlier messages (names the database, does not say 'eso' or 'lo de antes')"
+      - "Plain words with an everyday analogy for any new idea (non-technical register)"
+      - "Closes with 📍 and ➡️, the next step ending in a question"
+      - "Does NOT re-prompt to install a skill (defers that to suggest)"
+
+  - scenario: "Orient explained a caching bug in text. The user replies: '¿qué? no entiendo'. The profile shows the register technical. Show the next answer."
+    must_include:
+      - "Climbs exactly one step: a single small diagram (pseudocode, call tree or flow), not an HTML page or a video"
+      - "Uses real names from the code, not placeholders"
+      - "Keeps the technical register (no 101s)"
+      - "At most two lines of prose beside the diagram"
+
+  - scenario: "The profile carries `the register: mixed` and an old `accompaniment_level: L0`. The user asks what a migration is. Show how orient answers."
+    must_include:
+      - "Ignores accompaniment_level (retired)"
+      - "Uses the analogies register (mixed → analogies)"
+      - "Short, stand-alone answer that ends with the brújula"

package/skills/shared/orient/references/explain-ladder.md

@@ -0,0 +1,93 @@
+# The explain ladder
+
+Text → diagram → HTML page → video. Climb one step per clear sign that the person does not follow,
+or go straight to the step they ask for. Each step replaces the last one; it does not add to it.
+
+## Step 1 — text
+
+The four rules of `../SKILL.md`: their language, STE, stands alone, short. Most answers stop here.
+
+## Step 2 — one diagram in the chat
+
+Pick the **smallest** form that carries the point. One form per answer. Two lines of prose beside it,
+then stop.
+
+| The question is about | Draw |
+|---|---|
+| Logic, an algorithm, a decision | pseudocode |
+| What calls what at runtime | call tree |
+| UI structure | component tree, with state and module boundaries |
+| Which file does what | shallow file tree, one comment per entry |
+| Flow between pieces over time | Mermaid sequence or flow diagram |
+| Steps that branch | ASCII flow with boxes and arrows |
+| What changes in a shape that exists | `diff`, in the shape of the topic |
+| Nothing with a shape | prose — say so, no decorative diagram |
+
+Rules:
+
+- **Only the parts that answer the question.** Drop the rest of the system.
+- **Real names.** Real paths, functions, state values. `ServiceA → ServiceB` explains nothing.
+- **A diff in the shape of the topic.** A layout change is a file-tree diff; a control-flow change is
+  a pseudocode diff. Show the whole block instead when most of it is new.
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+```diff
+ src/
+ ├── commands/
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+## Step 3 — one HTML page
+
+For layout, visual state, a dense comparison, or someone who knows **nothing** about the topic.
+
+- One self-contained file. Big pictures first, words second. Inline SVG or plain HTML boxes; no chart
+  library. Readable on a phone.
+- The picture carries the idea; the words label it. If the page still makes sense with the text
+  removed, it works. A caption per picture, not a paragraph.
+- From zero: everyday objects only, no term before it is shown, and one line at the end on what the
+  simplification left out.
+- Inside a product, borrow its colours, type and spacing. Never invent an identity.
+
+Shape of a from-zero page:
+
+```text
+one sentence  : what this thing is, in words a stranger would use
+big picture 1 : the thing, drawn
+big picture 2 : the thing doing its job, step by step
+one line      : the part people get wrong
+one line      : what this left out (only if it left something out)
+```
+
+Write it, then open it (`open path/to/explain-<topic>.html`).
+
+## Step 4 — video, only on request
+
+An animated explainer (3Blue1Brown style) for something that moves: a process over time, a
+transformation, an algorithm running. It costs time and often an API key (narration, e.g.
+ElevenLabs) or local compute. So:
+
+- Offer it in one line. Never build it unasked.
+- On yes, use the catalog's video skill (`remotion-video`). If it is not installed, `suggest` offers it.
+
+## Anti-patterns
+
+| Anti-pattern | Do this instead |
+|---|---|
+| Four forms because each adds a little | One form, the smallest that answers |
+| The whole system when asked about one path | Draw the path, drop the rest |
+| A diagram to look thorough | Answer in prose, say there is nothing to draw |
+| Defining a term with two more terms | Show the thing, then name it |
+| Simplifying until it is wrong | Keep it true; name what you dropped |
+| Jumping to the HTML page on the first question | Climb one step per sign |

package/skills/shared/orient/references/orientation-contract.md

@@ -0,0 +1,86 @@
+# Orientation contract
+
+The one definition of how the harness talks to the person. The `orient` skill owns it. Other skills
+point here from a short footer instead of copying it.
+
+## Voice: STE, adapted
+
+STE (Simplified Technical English, ASD-STE100) is the controlled language of aircraft maintenance
+manuals. Its rules are measurable. Apply them about 80%: in the user's language, without the
+900-word dictionary.
+
+| Rule | Limit | Example |
+|---|---|---|
+| One idea per sentence | 1 | "Instalé la skill. Ahora reinicia la sesión." |
+| Sentence length | ≤ 20 words for an instruction, ≤ 25 to describe | — |
+| Paragraph length | ≤ 6 sentences, one topic | — |
+| Active voice | always in instructions | "El test comprueba X", not "X es comprobado" |
+| Instruction first, then the reason | — | "Haz backup. Si no, pierdes los datos." |
+| One word, one meaning | — | Do not call the same thing "skill", "módulo" and "plugin" |
+| Noun stacks | ≤ 3 words | "fichero de perfil", not "fichero de configuración de perfil de usuario" |
+| Warnings | the order first, the risk next | "No borres `.ai-hub/`. Los hooks dejan de funcionar." |
+| Lists | vertical, for anything with steps or more than 3 items | — |
+
+Not STE: soften it when a rule would cost meaning. Precision beats the limit.
+
+## Stand-alone answers
+
+The reader did not see your reasoning, your tool output, or your plan. They may have skipped earlier
+messages. So:
+
+- Name things. "El arreglo de las rutas con espacio", not "ese arreglo".
+- No back-references the reader cannot resolve: "el segundo commit", "lo de antes", "como dije".
+- A term you introduced three turns ago gets a short gloss again if it matters now.
+- One sentence of context is enough. Never retell the session.
+
+Test: could someone read only this message and act on it? If not, add the missing sentence.
+
+## Short
+
+- Lead with the answer. Then what the person must do or decide.
+- Cut preambles, recaps of what they said, and summaries of what you just wrote.
+- A table or a list beats a paragraph when there are parallel items.
+- If it does not change what the reader understands or does, delete it.
+
+## Register
+
+`technical_level` in `02-DOCS/wiki/harness/user-profile.md` sets the vocabulary:
+
+- `technical` — use the precise term directly. No 101 explanations.
+- `non-technical` or `mixed` — plain words. One everyday analogy per new idea: things a person has
+  held (keys, boxes, a queue at a counter, a light switch). Never explain an unknown with another
+  unknown. When a technical word is unavoidable (a command, a file), say what it does in the same
+  sentence.
+- No profile — analogies, and ask once: "¿Te hablo en lenguaje técnico o con analogías?".
+
+Simple is never false. If an analogy leaves something important out, say what in one line.
+Simple is never childish: adult tone, no baby talk, no exclamation marks.
+
+`accompaniment_level:` and `accompaniment:` (the L0–L3 dial) are retired keys from older profiles. Ignore them.
+
+## The brújula block
+
+```text
+📍 Dónde estás — the state, one sentence that stands alone
+✅ Qué has hecho — one line, only when something was done
+🧭 Por qué — one sentence, only when a decision was made
+➡️ Siguiente — 1-3 concrete options, ending in a question
+```
+
+- 📍 and ➡️ every time. ✅ and 🧭 only when they carry something.
+- Each line follows the voice above: one sentence, stands alone.
+- No turn ends in seco: a turn that finishes an action, reaches a fork, or could leave the person
+  unsure ends with the block.
+- Outside any artifact. A text meant to be copied (email, post) is separated from the block.
+
+## The ladder
+
+Text first. One step up per clear sign that the person does not follow, or when they ask for a step.
+Detail → `explain-ladder.md`.
+
+## Division of labor
+
+- `orient` guides the **person** (this contract).
+- `suggest` equips the **session** ("install the missing skill?"). Defer install prompts to it.
+- `unslop` cleans **text that leaves the session** (emails, posts, READMEs): AI tells out, human
+  register in.

package/skills/shared/parallel/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: parallel
+description: "Use when two or more pieces of work are genuinely independent — disjoint files, no shared state, no ordering edge — and should fan out across subagents, then be gathered and reconciled under a combined test suite. Decides WHAT can run concurrently; NOT the isolation it runs in (that is `worktrees`), NOT the per-unit TDD loop (that is `implement`)."
+tags: [parallel, subagents, fanout]
+recommends: []
+profiles: [core, full]
+origin: ai-hub
+---
+
+# parallel — fan out independent work, then reconcile
+
+*Parallelism is a property of the work, not a wish. Prove the pieces are disjoint, dispatch one subagent per piece with a self-contained brief, then gather and reconcile before anyone calls it done.*
+
+This is an **on-demand process skill** in the SDD chain. You reach it from `implement` (or any phase) when the work in front of you splits into pieces that could each be handed to a different person who never talks to the others. It owns one discipline: **partition → dispatch → gather → reconcile**. It does *not* own the work inside each piece — a subagent building a module still runs its own red → green → refactor loop from `implement`; this skill only orchestrates the fan-out. It also does not own the *place* the work runs: a clean branch or checkout to work in is `worktrees`. `parallel` decides **what can run at the same time**; `worktrees` provides **the isolation it runs in**.
+
+The whole value is in the gate at the front. Run work in parallel only when it is *actually* independent. Forcing parallelism onto coupled work does not make it faster — it makes it a merge disaster, and the time you save dispatching you lose tenfold reconciling. Most of this skill is about earning the right to parallelize.
+
+## The independence test (run this before dispatching anything)
+
+A set of tasks is safe to parallelize only when **every** answer below is yes. One no means serialize that pair.
+
+```text
+INDEPENDENCE TEST — for every PAIR of candidate tasks
+- [ ] Disjoint files       — they never write the same file (and don't both edit a shared barrel/index/registry)
+- [ ] No shared state       — no shared in-memory object, DB row, migration, global config, or env they both mutate
+- [ ] No ordering edge      — neither needs the other's OUTPUT to start or to assert against
+- [ ] No hidden coupling     — not the same schema/contract/type that must agree, not the same external resource
+- [ ] Self-containable brief — each can be described fully on its own, with its own done-check, without "see the other task"
+```
+
+If a pair fails any line, they are one serial unit — run them in order in the same agent, or sequence them as a dependency. If a *group* passes for every internal pair, that group is a parallel batch. It is normal to end up with a mix: a few disjoint clusters you fan out, and a serial spine that holds them together.
+
+```text
+Good fan-out  — "add the users repository" ‖ "add the invoices repository" ‖ "write the README"
+                (separate modules, separate files, no task reads another's output)
+Bad fan-out   — "define the User type" ‖ "write the endpoint that returns a User"
+                (the second needs the first's output — serialize: type, THEN endpoint)
+Bad fan-out   — "add field to the orders migration" ‖ "add another field to the orders migration"
+                (same file, same migration — one serial unit, not two)
+```
+
+## The four phases
+
+```text
+PARTITION → DISPATCH → GATHER → RECONCILE
+```
+
+Never skip RECONCILE. Green-in-isolation is not green-together — the point of failure in parallel work is always the seam, and the seam only shows up after you merge.
+
+### 1. PARTITION — carve the work into disjoint units
+
+Take the task list (from `tasks`, or the implicit list in front of you) and group it. For each candidate group, run the independence test above. Produce an explicit partition: the parallel batches and the serial spine between them. Write the partition down — even one line per batch — so the gather step has something to check against. Decide the **degree of parallelism**: one subagent per unit, but cap it where the units would contend on the same scarce resource (a single test database, a rate-limited API, your own review bandwidth). More subagents than you can reconcile is not faster.
+
+### 2. DISPATCH — one subagent per unit, with a self-contained brief
+
+Each subagent gets a brief it can execute **without reading the others**. A brief that says "do the auth part, coordinate with the other agent on the token shape" has already failed the independence test — go back and fix the partition. A complete brief carries:
+
+```text
+SUBAGENT BRIEF (one per unit)
+- Scope        — exactly which files/dirs this unit owns, and the explicit boundary it must NOT cross
+- Goal         — what to build, in its own words, no "see the other task"
+- Done-check   — the verifiable condition that means this unit is finished (from the tasks phase)
+- Constraints  — the constitution rules + stack skill it must honor (e.g. ../fastapi/SKILL.md testing)
+- Selected skills — ids + paths resolved from .ai-hub/skill-registry.json
+- Compact rules — 4-5 actionable rules digested from those skills for THIS unit
+- Skill fallback — what to do if a referenced skill is unavailable
+- Interface    — any contract it must conform to, FROZEN before dispatch (see the rule below)
+- Model tier   — the tier this unit runs on, by the KIND of work it does (only when routing is enabled — see below)
+- Report-back  — what to return: the diff, the test output, decisions worth logging, skill_resolution
+```
+
+**Freeze shared contracts before you dispatch, never during.** If two units both touch the same API shape, type, or schema, that interface is a *dependency*, not something to negotiate in flight. Define it in the serial spine first, hand the frozen version to every unit, and only then fan out. Cross-talk between live subagents is the smell that the partition was wrong.
+
+Each subagent still owns its own discipline inside its scope — TDD via `implement`, the stack skill's test mechanics, decision logging. This skill does not relax any of that; it just runs several of them at once.
+
+**Per-unit model tier (when routing is enabled).** `parallel` has *no fixed tier* — this is the most concrete place per-phase model routing pays off. When `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`, give each unit the tier of the *kind of work it does*, not one tier for the whole fan-out: an implement-type unit → `balanced`, a scan/research/boilerplate unit → `light`, a unit doing genuine design or root-cause reasoning → `heavy`. Resolve the tier to a concrete model via `models.tiers` and **dispatch that subagent on that model** (e.g. Claude Code's `model` field on the Task/subagent) — real routing, independent of the session model. If routing is off or no profile exists, dispatch on the session model and say nothing. Full protocol: `../sdd/references/model-routing.md`.
+
+**Set the model on every dispatch — an omitted model silently inherits the session's, usually the most expensive one, and that is how a fan-out's cost quietly explodes.** ai-hub installs a `developer` subagent pinned to the **balanced** tier (Sonnet by default; the user's onboarding choice in `.ai-hub/developer.json`, never `light`). For implement-type units, **dispatch to the `developer` agent** (e.g. Claude Code `subagent_type: developer`) — that's the deliberate cost cap the user asked for. Only escalate a genuinely heavy unit (real design / root-cause) to a heavy model, and only when routing is enabled; otherwise balanced is the floor and the ceiling. If you dispatch a raw subagent instead, name its tier explicitly.
+
+### The unit report contract (statuses & escalation)
+
+Each unit reports **one of four statuses** — it does not guess or hack around a wall when unsure:
+
+- `DONE` — done-check green, the unit's frozen interface honored.
+- `DONE_WITH_CONCERNS` — green, but a flagged risk/assumption for the orchestrator to adjudicate.
+- `BLOCKED` — cannot proceed (failing dependency, a contract that doesn't hold, missing access).
+- `NEEDS_CONTEXT` — something it needed (an interface, a constraint) was not in its brief.
+
+On `BLOCKED`/`NEEDS_CONTEXT`, **never re-dispatch the same brief to the same model unchanged** —
+change something first: add the missing interface/constraint, fix the dependency, or escalate the
+tier for a genuinely hard unit. An identical re-run burns budget without progress. A `BLOCKED` unit
+is a partition signal too: if it blocked on another unit, the two were not independent — re-partition.
+
+Every subagent result must also report:
+
+```yaml
+skill_resolution:
+  used: []
+  missing: []
+  fallback: []
+  compact_rules: []
+```
+
+The orchestrator folds these into the final parallel result. If a unit claims it used a skill that was not available in the registry or not included in the brief, treat that as a review risk and inspect the work before merging.
+
+### 3. GATHER — collect every result, hold the merge
+
+Wait for **all** units to report. Collect each one's diff, test output, and any decisions. Do not start merging the fast ones while slow ones are still running — partial merges create the exact shared-state races you partitioned to avoid. Check each result against its brief's done-check *before* it touches the integration branch: a unit that came back not-actually-done gets sent back, not merged hopefully.
+
+**Per-unit review gate (before merge).** For each non-trivial unit, run the same fresh-eyes review `implement` runs per task, over *that unit's diff alone* — package it with `../implement/scripts/review-package <BASE> <HEAD>` and dispatch a reviewer that is **not** the unit's own implementer, given the diff path, the unit's done-check, and its frozen interface; never pre-rate severity or tell it what to skip. Fold `Critical`/`Important` findings back before merging. Full protocol: `../implement/references/per-task-review.md`. This is the cheap per-unit pass; the *combined* adversarial review over the whole merged diff is still `review`'s job at the end (RECONCILE only proves the seam compiles and tests green).
+
+### 4. RECONCILE — merge, then prove the seam holds
+
+This is where parallel work is actually finished. In order:
+
+1. **Merge the units** onto the integration branch (or working tree). Resolve any conflict by hand — a conflict here means the partition leaked (two units touched the same line); note it so the next partition is cleaner.
+2. **Run the *combined* suite.** Each unit was green alone; that proves nothing about together. Run the whole test suite (the stack skill's `scripts/verify.sh`) across the merged result.
+3. **If the combined suite is red**, the failure lives in the seam between units. Switch to `debug` — reproduce → isolate → fix — instead of guessing which unit to blame.
+4. **Reconcile the decision logs.** Fold each unit's decisions into `02-DOCS/wiki/sdd/decisions.md` (append-only), and if two units made a choice that now disagrees, resolve it explicitly and log the resolution.
+
+Only after the combined suite is green is the parallel batch done. Hand the merged, green result back to the phase that called you (usually `implement`, heading for `verify`).
+
+**What to say.** In chat, say only what the reader needs, in the `orient` voice: the partition, any frozen contract, and each reconcile conflict with its fix — one line each. The register (technical or with analogies) comes from `technical_level` in `02-DOCS/wiki/harness/user-profile.md`. However short the report, you still run the independence test and the combined-suite gate in full.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality |
+| --- | --- |
+| "These two touch the same file but I'll parallelize and merge later." | Same file = shared state. That's a merge race and lost work. One serial unit. |
+| "I'll let the subagents coordinate the token shape between themselves." | Live cross-talk means the partition failed. Freeze the contract in the spine first, then dispatch. |
+| "Both units are green on their own, so the feature is done." | Green-alone proves nothing about together. Run the combined suite before any done-claim. |
+| "Fan out everything — more subagents is always faster." | Past the point you can reconcile, it's slower and riskier. Cap parallelism at what one serial spine can absorb. |
+| "I'll merge the fast unit now and the slow one when it lands." | Partial merges reintroduce the races you partitioned away. Gather all, then reconcile once. |
+| "It's only two small tasks, but parallel sounds efficient." | Orchestration overhead > the work. Just do them in a row. |
+| "The brief says 'see the other agent's output' — close enough." | That's a dependency, not independence. Serialize, or freeze the output first. |
+| "Combined suite is red, probably the slower unit — I'll tweak it." | Don't guess at the seam. Reproduce and isolate with `debug`. |
+| "I just want an isolated branch, so I'll use parallel." | That's isolation, not concurrency. Use `worktrees`. |
+| "Routing's on, so I'll run the whole fan-out on one tier." | `parallel` has no fixed tier — give each unit the tier of its own work (scan→light, build→balanced, design→heavy). |
+
+## Result envelope
+
+End with:
+
+```json result-envelope
+{
+  "status": "complete",
+  "executive_summary": "Parallel units gathered, reconciled, and combined suite checked.",
+  "artifact": "02-DOCS/wiki/sdd/progress/<slug>.md",
+  "next_recommended": "implement",
+  "risk": "low|medium|high",
+  "model": { "per_unit": [{ "unit": "users-repo", "tier": "balanced", "resolved": "model-id" }], "routing": "on|off" },
+  "skill_resolution": {
+    "used": ["parallel"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Freeze shared contracts before dispatch.", "Run combined suite after merge."]
+  },
+  "evidence": ["partition", "unit reports", "combined suite output"]
+}
+```
+
+## Where you are in the chain
+
+`parallel` is on-demand, callable from any phase but most often from `implement`:
+
+`constitution` → `specify` → `clarify` → `plan` → `tasks` → `analyze` → **implement** → `verify` → `review` → `ship`, with `debug` · `worktrees` · **parallel** callable on demand.
+
+**Next:** when the fan-out is reconciled and the combined suite is green, return to the phase that called you — usually `../implement/SKILL.md`, continuing the task list toward `../verify/SKILL.md`. If the seam is red, go to `debug` first. If the ordered task list with done-checks does not exist yet, that is `tasks`, not this. If what you actually needed was an isolated branch rather than concurrency, that's `worktrees`.