@phuc1403/musketeer 0.9.0 → 0.10.0

package/template/.claude/skills/hallmark-loop/references/loop-control.md

@@ -1,79 +1,79 @@
-# Loop control — state, stop condition, dry detection
-
-The MAIN session owns the loop control. It is **deterministic**: read the structured `state` the
-auditor returned and decide — no re-judging in MAIN (that would re-introduce self-review).
-
-## State carried between rounds
-
-Keep this small object in MAIN (and nothing else from the round — no screenshots):
-
-```
-state = {
-  scores: { P, H, E, S, R, V },          // last auditor verdict, each 1–5
-  findings: [ {gate, tell, source, verdict, evidence, severity, fix} ],
-}
-prevFindings = <previous round's findings, or null>
-dryRounds    = <consecutive rounds with no net-new findings>
-round        = <0-based round counter>
-```
-
-## Stop condition (check after each audit, before redesign)
-
-Stop the loop when **ANY** of the three fires:
-
-1. **Converged** — all six axes `≥ 4` **AND** zero `critical` findings. Do **not** maintain a
-   separate "hard-gate" list here — `slop-test.md` is the source of truth for which gates are
-   auto-fail, and the auditor already surfaces those as `severity: critical` when it reads the
-   rubric. So "zero critical findings" *is* the hard-gate check; nothing to duplicate. A
-   `cant-tell` does **not** count as a failure — but log it.
-2. **Max rounds** — `round >= 4`. Hallmark's six-axis critique almost always finds a sub-5;
-   four rounds is the practical ceiling. Report what's still open rather than looping forever.
-3. **Dry** — `dryRounds >= 2` (two consecutive rounds produced **no net-new findings**). The loop
-   has stopped making progress; further rounds will churn, not improve.
-
-## Net-new / dry detection
-
-After each audit, compute net-new findings vs the previous round:
-
-```
-key(f)   = `${f.gate}:${f.severity}`          // a finding's identity
-newKeys  = state.findings.map(key)
-oldKeys  = (prevFindings ?? []).map(key)
-netNew   = newKeys.filter(k => !oldKeys.includes(k))
-
-if (netNew.length === 0) dryRounds += 1
-else                     dryRounds  = 0
-```
-
-Compare against **`prevFindings`** (last round only), not against all-time findings — otherwise a
-finding the redesign legitimately could not fix would reset the counter every round and the loop
-would never go dry. Conversely, a finding that *reappears after being fixed* (a regression the
-redesign introduced) is correctly counted as net-new, which is what you want.
-
-## Redesign targeting
-
-Pass the redesign step the **actionable** findings only: `verdict === "fail"`, sorted
-`critical → major → minor`. Skip `cant-tell` (instead, next round's capture should surface more
-evidence for those — e.g. capture an extra viewport or add the missing element to the
-`computed.json` selector list). Hand `/hallmark redesign` each finding's `gate`, `evidence`, and
-`fix` so it edits precisely rather than re-designing wholesale.
-
-## Round log
-
-If `frontend/.hallmark/log.json` exists, append one record per round so future runs (and the
-diversification gates) can see the history:
-
-```json
-{ "loop": true, "round": 2, "scores": {"P":5,"H":4,"E":5,"S":4,"R":5,"V":5},
-  "counts": {"critical":0,"major":1,"minor":2,"cant_tell":1}, "stopped": null }
-```
-
-Set `"stopped"` to `"converged" | "max-rounds" | "dry"` on the final record.
-
-## Final report (Step 6)
-
-Tell the user, concisely:
-- the **final six-axis scores**,
-- **which** stop condition fired (and at which round),
-- **residual findings** still open at stop, by gate number + severity, and any `cant-tell`s,
-- where the artifacts live (`frontend/.hallmark/loop/round-<N>/`).
+# Loop control — state, stop condition, dry detection
+
+The MAIN session owns the loop control. It is **deterministic**: read the structured `state` the
+auditor returned and decide — no re-judging in MAIN (that would re-introduce self-review).
+
+## State carried between rounds
+
+Keep this small object in MAIN (and nothing else from the round — no screenshots):
+
+```
+state = {
+  scores: { P, H, E, S, R, V },          // last auditor verdict, each 1–5
+  findings: [ {gate, tell, source, verdict, evidence, severity, fix} ],
+}
+prevFindings = <previous round's findings, or null>
+dryRounds    = <consecutive rounds with no net-new findings>
+round        = <0-based round counter>
+```
+
+## Stop condition (check after each audit, before redesign)
+
+Stop the loop when **ANY** of the three fires:
+
+1. **Converged** — all six axes `≥ 4` **AND** zero `critical` findings. Do **not** maintain a
+   separate "hard-gate" list here — `slop-test.md` is the source of truth for which gates are
+   auto-fail, and the auditor already surfaces those as `severity: critical` when it reads the
+   rubric. So "zero critical findings" *is* the hard-gate check; nothing to duplicate. A
+   `cant-tell` does **not** count as a failure — but log it.
+2. **Max rounds** — `round >= 4`. Hallmark's six-axis critique almost always finds a sub-5;
+   four rounds is the practical ceiling. Report what's still open rather than looping forever.
+3. **Dry** — `dryRounds >= 2` (two consecutive rounds produced **no net-new findings**). The loop
+   has stopped making progress; further rounds will churn, not improve.
+
+## Net-new / dry detection
+
+After each audit, compute net-new findings vs the previous round:
+
+```
+key(f)   = `${f.gate}:${f.severity}`          // a finding's identity
+newKeys  = state.findings.map(key)
+oldKeys  = (prevFindings ?? []).map(key)
+netNew   = newKeys.filter(k => !oldKeys.includes(k))
+
+if (netNew.length === 0) dryRounds += 1
+else                     dryRounds  = 0
+```
+
+Compare against **`prevFindings`** (last round only), not against all-time findings — otherwise a
+finding the redesign legitimately could not fix would reset the counter every round and the loop
+would never go dry. Conversely, a finding that *reappears after being fixed* (a regression the
+redesign introduced) is correctly counted as net-new, which is what you want.
+
+## Redesign targeting
+
+Pass the redesign step the **actionable** findings only: `verdict === "fail"`, sorted
+`critical → major → minor`. Skip `cant-tell` (instead, next round's capture should surface more
+evidence for those — e.g. capture an extra viewport or add the missing element to the
+`computed.json` selector list). Hand `/hallmark redesign` each finding's `gate`, `evidence`, and
+`fix` so it edits precisely rather than re-designing wholesale.
+
+## Round log
+
+If `frontend/.hallmark/log.json` exists, append one record per round so future runs (and the
+diversification gates) can see the history:
+
+```json
+{ "loop": true, "round": 2, "scores": {"P":5,"H":4,"E":5,"S":4,"R":5,"V":5},
+  "counts": {"critical":0,"major":1,"minor":2,"cant_tell":1}, "stopped": null }
+```
+
+Set `"stopped"` to `"converged" | "max-rounds" | "dry"` on the final record.
+
+## Final report (Step 6)
+
+Tell the user, concisely:
+- the **final six-axis scores**,
+- **which** stop condition fired (and at which round),
+- **residual findings** still open at stop, by gate number + severity, and any `cant-tell`s,
+- where the artifacts live (`frontend/.hallmark/loop/round-<N>/`).

package/template/.claude/skills/handoff/SKILL.md

@@ -1,15 +1,15 @@
----
-name: handoff
-description: Compact the current conversation into a handoff document for another agent to pick up.
-argument-hint: "What will the next session be used for?"
----
-
-Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
-
-Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
-
-Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
-
-Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
-
-If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/template/.claude/skills/knowledge-crunching/SKILL.md

@@ -1,94 +1,94 @@
----
-name: knowledge-crunching
-description: >-
-  Crunch domain knowledge with the user as domain expert into test-driven domain-layer code and a ubiquitous language (DDD). Use when the user invokes /knowledge-crunching, describes a domain flow or feature to model, wants to discover a domain model, distill a ubiquitous language, or reconcile experts' terminology.
----
-
-# Knowledge Crunching
-
-You are the developer/architect on a DDD team; the user is the **domain expert** (the client). You crunch their knowledge into a model through a tight modeling dialogue, with one commitment: **the emerging model is test-driven domain-layer code, not diagrams.**
-
-**This skill handles:** the collaborative modeling *dialogue* and the domain-layer model it produces — types, behavior, unit tests, and the language in `docs/ubiquitous-language.md` — for a module that already exists, whether its domain layer is a bare scaffold or a live model. **Does NOT handle:** persistence, repositories, UI, API/transport, deployment, strategic context-mapping, or standing up a new module scaffold (a prerequisite, done first). Stay in the domain layer; if the user asks for the rest, note it's out of scope and offer to hand off afterward.
-
-## The five stances (hold these the whole session)
-
-1. **Model in code, not diagrams.** Every model fragment is a small type or method — in the bounded context's own language — you can show on screen. The running test, not a picture, is what makes the model concrete to the expert.
-2. **Verify before you build.** Never write code for an unconfirmed concept — propose, ask, and **WAIT** for the answer.
-3. **Speak the expert's words.** Use their nouns and verbs verbatim. Reconcile synonyms and contradictions out loud ("customer and account holder — same thing?"). Code names == language names.
-4. **Distill, don't transcribe.** Exclude every fact the current problem doesn't need — the model is a distillation, not a transcription. Bring a concept back only when a feature actually pulls it in.
-5. **Don't accept the solution as stated.** A request usually arrives already framed as a mechanism ("export the table, sort it, email a summary"). That framing is not the domain. Dig past it for the concepts underneath — that is where the model is.
-
-## Workflow
-
-### Step 1 — Read what already exists
-**First read any prior crunching output for that context** — `docs/ubiquitous-language.md` and the domain's code; in DDD, document = code. If the module is a bare scaffold with no language chosen yet, ask the user which language and test framework the context should be modeled in before proposing any code.
-
-If a model is already there, read it against the language and let each mismatch become a Step 4 loop turn — surface it, verify with the user, then change code and `docs/ubiquitous-language.md` together:
-
-- **Synonym drift** — code says `Learner`, experts now say `Student`. Reconcile and pick one, in both.
-- **Conflated concept** — one type doing two jobs the experts name separately → candidate split.
-- **Leaked invariant** — a rule enforced in a service/controller that an aggregate should own.
-- **Dead concept** — a type no scenario exercises anymore → remove it from the code and drop its entry.
-
-### Step 2 — Find the first model elements
-The opening description is usually a mechanism, not a model (stance 5). Listen past it for the **domain nouns and verbs that keep recurring**, and name 2–4 of them back as candidate concepts.
-
-For each, ask whether it is something the business actually names and treats as a distinct thing — as opposed to a word used in passing, or one you invented. You are testing your own guesses, so expect to be corrected. This is *not* "which word do you prefer?" — choosing between two words for one thing is stance 3, and it only arises once you have two.
-
-> **You:** I'm hearing `Car`, `Inspection`, and something like `Listing` for a car on the lot for sale. Is `Listing` a real thing you'd name, or just "the car is on the lot"?
->
-> **Expert:** It's real, but we call it a `Unit`, and only once it's passed inspection. A car we haven't inspected isn't a unit.
-
-One answer, and you have a concept, its actual name, and the rule that brings it into existence. Do not scaffold types yet.
-
-### Step 3 — Focus on ONE scenario
-Narrow to a single concrete scenario to make progress. Ask the user to pick or confirm the one you'll model first; everything else waits. If their explanation runs ahead of you, say so and pull back here.
-
-### Step 4 — The per-concept tight loop (the heart of the skill)
-For each concept the chosen scenario pulls in, run this loop — **one concept at a time**:
-
-1. **Propose** one model fragment as minimal code in the project's language (a type, a method, a relationship) + a one-line plain gloss of what it means.
-2. **Ask one sharp verifying question** that would expose a misunderstanding if your guess is wrong. Pick the type that fits the fragment you just proposed — a good question is falsifiable, concrete, and answerable in a sentence, never "does this look right?":
-
-   | Type | What it pins down | Template |
-   |---|---|---|
-   | **Cardinality** | how many relate to how many | "Does one X belong to exactly one Y, or many?" |
-   | **Synonym** | two words, one concept | "Are X and Y the same thing?" |
-   | **Ownership of behavior** | which object does the work | "What pushes the signal — X or Y?" |
-   | **Exclusion / relevance** | is this concept needed *now* | "Does X matter for this scenario?" |
-   | **Simplification** | how little can we model | "Is a simplified Z enough instead of full X?" |
-   | **Computation goal** | what the output must be | "What exactly do you need from this?" |
-   | **Definition of a unit** | what one increment is | "What counts as one X?" |
-   | **Lifetime / sameness** | shared vs per-instance data | "Is this the same for every instance, or per instance?" |
-
-   If you can't think of a question, you don't understand the fragment well enough to code it — go smaller. Prefer a question that could get a "no"; one that can only be answered "yes" teaches nothing. After a "no," restate the corrected understanding before moving on.
-3. **WAIT** for the answer. Do not write code, tests, or the next fragment until the user responds.
-4. **Fold in** the correction (rename, re-shape, drop, or add), then record the term (Step 6).
-
-Example of the loop's rhythm (compressed):
-
-> **You:** Here's my first guess — an `Order` groups the `LineItem`s a customer buys in one go, so `Order` holds many `LineItem`s. Does a `LineItem` belong to exactly one `Order`, or can the same one sit on several?
->
-> **Expert:** One line item, one order. Always.
->
-> **You:** Good — I'll make that a hard invariant. *(folds in, records the term, then moves to the next concept)*
-
-A loop turn is complete only when **all three** agree: the **expert** has answered the verifying question, the **code** reflects that answer, and **`docs/ubiquitous-language.md`** records the term. If any of the three lags, close the gap before proposing the next concept.
-
-### Step 5 — TDD the confirmed behavior (one test at a time)
-Make the confirmed fragment real with the red-green loop in the `tdd` skill (`.claude/skills/tdd/SKILL.md`) — its rules on one-test-at-a-time, minimal green, testing observable behavior through the public surface, and never refactoring while red all apply here unchanged.
-
-Two amendments for a crunching session:
-
-- **Domain layer only.** No persistence, no application handlers, no UI. Ignore that skill's full-vertical-slice default — here the slice stops at the domain, and what comes next is the expert's next concept, not the next layer.
-- **The Step 4 sketch is a drawing in the chat, not a file.** Do not create the production type ahead of its first failing test. A compile error because the type does not exist yet is a legitimate red, and that failing run is the point.
-
-### Step 6 — Record the language immediately
-The ubiquitous language lives in **one** place: `docs/ubiquitous-language.md`. There is no separate glossary file. The moment a term is confirmed, add one line — `Term: ` then what it means in the expert's words. Nothing else: no rejected-synonym list, no deferred section, no grouping. The term is already the type's name (stance 3), so don't restate it. Rename in code, rename here in the same turn.
-
-Write a dictionary entry, not prose. One line. No lead-in, no narrative, no "this is the concept that…". Keep implementation and vendor words out — they name the mechanism, not the concept (stance 5). Keep invariants out — rules live in the code and its tests (Step 5).
-
-If the doc does not exist yet, copy `assets/ubiquitous-language.template.md` from this skill to `docs/ubiquitous-language.md`. If it already exists, edit it — never overwrite it, and never start a second one. It is canonical, and is also your seed (Step 1).
-
-### Step 7 — Distill, then loop
-Drop concepts the current scenario doesn't need and say so ("I'll leave scheduling out for now; we'll bring it back when a feature needs it"). When a new scenario arrives and the model can't express it, brainstorm a new concept or refactor an existing one toward deeper insight — that is crunching the knowledge further. Return to Step 3 for the next scenario.
+---
+name: knowledge-crunching
+description: >-
+  Crunch domain knowledge with the user as domain expert into test-driven domain-layer code and a ubiquitous language (DDD). Use when the user invokes /knowledge-crunching, describes a domain flow or feature to model, wants to discover a domain model, distill a ubiquitous language, or reconcile experts' terminology.
+---
+
+# Knowledge Crunching
+
+You are the developer/architect on a DDD team; the user is the **domain expert** (the client). You crunch their knowledge into a model through a tight modeling dialogue, with one commitment: **the emerging model is test-driven domain-layer code, not diagrams.**
+
+**This skill handles:** the collaborative modeling *dialogue* and the domain-layer model it produces — types, behavior, unit tests, and the language in `docs/ubiquitous-language.md` — for a module that already exists, whether its domain layer is a bare scaffold or a live model. **Does NOT handle:** persistence, repositories, UI, API/transport, deployment, strategic context-mapping, or standing up a new module scaffold (a prerequisite, done first). Stay in the domain layer; if the user asks for the rest, note it's out of scope and offer to hand off afterward.
+
+## The five stances (hold these the whole session)
+
+1. **Model in code, not diagrams.** Every model fragment is a small type or method — in the bounded context's own language — you can show on screen. The running test, not a picture, is what makes the model concrete to the expert.
+2. **Verify before you build.** Never write code for an unconfirmed concept — propose, ask, and **WAIT** for the answer.
+3. **Speak the expert's words.** Use their nouns and verbs verbatim. Reconcile synonyms and contradictions out loud ("customer and account holder — same thing?"). Code names == language names.
+4. **Distill, don't transcribe.** Exclude every fact the current problem doesn't need — the model is a distillation, not a transcription. Bring a concept back only when a feature actually pulls it in.
+5. **Don't accept the solution as stated.** A request usually arrives already framed as a mechanism ("export the table, sort it, email a summary"). That framing is not the domain. Dig past it for the concepts underneath — that is where the model is.
+
+## Workflow
+
+### Step 1 — Read what already exists
+**First read any prior crunching output for that context** — `docs/ubiquitous-language.md` and the domain's code; in DDD, document = code. If the module is a bare scaffold with no language chosen yet, ask the user which language and test framework the context should be modeled in before proposing any code.
+
+If a model is already there, read it against the language and let each mismatch become a Step 4 loop turn — surface it, verify with the user, then change code and `docs/ubiquitous-language.md` together:
+
+- **Synonym drift** — code says `Learner`, experts now say `Student`. Reconcile and pick one, in both.
+- **Conflated concept** — one type doing two jobs the experts name separately → candidate split.
+- **Leaked invariant** — a rule enforced in a service/controller that an aggregate should own.
+- **Dead concept** — a type no scenario exercises anymore → remove it from the code and drop its entry.
+
+### Step 2 — Find the first model elements
+The opening description is usually a mechanism, not a model (stance 5). Listen past it for the **domain nouns and verbs that keep recurring**, and name 2–4 of them back as candidate concepts.
+
+For each, ask whether it is something the business actually names and treats as a distinct thing — as opposed to a word used in passing, or one you invented. You are testing your own guesses, so expect to be corrected. This is *not* "which word do you prefer?" — choosing between two words for one thing is stance 3, and it only arises once you have two.
+
+> **You:** I'm hearing `Car`, `Inspection`, and something like `Listing` for a car on the lot for sale. Is `Listing` a real thing you'd name, or just "the car is on the lot"?
+>
+> **Expert:** It's real, but we call it a `Unit`, and only once it's passed inspection. A car we haven't inspected isn't a unit.
+
+One answer, and you have a concept, its actual name, and the rule that brings it into existence. Do not scaffold types yet.
+
+### Step 3 — Focus on ONE scenario
+Narrow to a single concrete scenario to make progress. Ask the user to pick or confirm the one you'll model first; everything else waits. If their explanation runs ahead of you, say so and pull back here.
+
+### Step 4 — The per-concept tight loop (the heart of the skill)
+For each concept the chosen scenario pulls in, run this loop — **one concept at a time**:
+
+1. **Propose** one model fragment as minimal code in the project's language (a type, a method, a relationship) + a one-line plain gloss of what it means.
+2. **Ask one sharp verifying question** that would expose a misunderstanding if your guess is wrong. Pick the type that fits the fragment you just proposed — a good question is falsifiable, concrete, and answerable in a sentence, never "does this look right?":
+
+   | Type | What it pins down | Template |
+   |---|---|---|
+   | **Cardinality** | how many relate to how many | "Does one X belong to exactly one Y, or many?" |
+   | **Synonym** | two words, one concept | "Are X and Y the same thing?" |
+   | **Ownership of behavior** | which object does the work | "What pushes the signal — X or Y?" |
+   | **Exclusion / relevance** | is this concept needed *now* | "Does X matter for this scenario?" |
+   | **Simplification** | how little can we model | "Is a simplified Z enough instead of full X?" |
+   | **Computation goal** | what the output must be | "What exactly do you need from this?" |
+   | **Definition of a unit** | what one increment is | "What counts as one X?" |
+   | **Lifetime / sameness** | shared vs per-instance data | "Is this the same for every instance, or per instance?" |
+
+   If you can't think of a question, you don't understand the fragment well enough to code it — go smaller. Prefer a question that could get a "no"; one that can only be answered "yes" teaches nothing. After a "no," restate the corrected understanding before moving on.
+3. **WAIT** for the answer. Do not write code, tests, or the next fragment until the user responds.
+4. **Fold in** the correction (rename, re-shape, drop, or add), then record the term (Step 6).
+
+Example of the loop's rhythm (compressed):
+
+> **You:** Here's my first guess — an `Order` groups the `LineItem`s a customer buys in one go, so `Order` holds many `LineItem`s. Does a `LineItem` belong to exactly one `Order`, or can the same one sit on several?
+>
+> **Expert:** One line item, one order. Always.
+>
+> **You:** Good — I'll make that a hard invariant. *(folds in, records the term, then moves to the next concept)*
+
+A loop turn is complete only when **all three** agree: the **expert** has answered the verifying question, the **code** reflects that answer, and **`docs/ubiquitous-language.md`** records the term. If any of the three lags, close the gap before proposing the next concept.
+
+### Step 5 — TDD the confirmed behavior (one test at a time)
+Make the confirmed fragment real with the red-green loop in the `tdd` skill (`.claude/skills/tdd/SKILL.md`) — its rules on one-test-at-a-time, minimal green, testing observable behavior through the public surface, and never refactoring while red all apply here unchanged.
+
+Two amendments for a crunching session:
+
+- **Domain layer only.** No persistence, no application handlers, no UI. Ignore that skill's full-vertical-slice default — here the slice stops at the domain, and what comes next is the expert's next concept, not the next layer.
+- **The Step 4 sketch is a drawing in the chat, not a file.** Do not create the production type ahead of its first failing test. A compile error because the type does not exist yet is a legitimate red, and that failing run is the point.
+
+### Step 6 — Record the language immediately
+The ubiquitous language lives in **one** place: `docs/ubiquitous-language.md`. There is no separate glossary file. The moment a term is confirmed, add one line — `Term: ` then what it means in the expert's words. Nothing else: no rejected-synonym list, no deferred section, no grouping. The term is already the type's name (stance 3), so don't restate it. Rename in code, rename here in the same turn.
+
+Write a dictionary entry, not prose. One line. No lead-in, no narrative, no "this is the concept that…". Keep implementation and vendor words out — they name the mechanism, not the concept (stance 5). Keep invariants out — rules live in the code and its tests (Step 5).
+
+If the doc does not exist yet, copy `assets/ubiquitous-language.template.md` from this skill to `docs/ubiquitous-language.md`. If it already exists, edit it — never overwrite it, and never start a second one. It is canonical, and is also your seed (Step 1).
+
+### Step 7 — Distill, then loop
+Drop concepts the current scenario doesn't need and say so ("I'll leave scheduling out for now; we'll bring it back when a feature needs it"). When a new scenario arrives and the model can't express it, brainstorm a new concept or refactor an existing one toward deeper insight — that is crunching the knowledge further. Return to Step 3 for the next scenario.

package/template/.claude/skills/research/SKILL.md

@@ -1,69 +1,69 @@
----
-name: research
-description: "Research technical solutions and analyze architectures by spawning parallel researcher agents that search the web and cross-reference findings. Use for technology evaluation, best-practices research, solution design, and scalability/security/maintainability analysis."
-license: MIT
-argument-hint: "[topic]"
-metadata:
-  author: Phuc Pham
-  version: "2.1.1"
----
-
-# Research
-
-## 1. Decompose
-
-Break the topic into independent sub-questions. Note recency requirements (how current
-the information must be) and any specific angles the user cares about (security, perf,
-cost, migration path) — these shape both the queries and the final sections.
-
-## 2. Gather (parallel agents)
-
-For each independent sub-question, dispatch a `researcher` agent via the Agent tool
-(`subagent_type: "researcher"`). Run independent agents in a single message so they execute
-concurrently. Scale the count to the topic's breadth; don't spawn overlapping agents.
-
-Give each agent **one** sub-question plus any recency/angle constraints from step 1. The
-agent handles query crafting, source prioritization, and returning findings with URLs.
-Keep synthesis (steps 3–4) in the main agent.
-
-## 3. Cross-reference
-
-Before synthesizing:
-- **Verify** each significant claim across multiple independent sources.
-- **Check dates** — flag stale information.
-- **Surface conflicts** explicitly rather than silently picking a side.
-- **Flag single-source claims** as unverified; discard or downgrade what fails.
-
-## 4. Report
-
-Save to the output path if the main agent provided one; otherwise return inline. Cite
-sources throughout. Sacrifice grammar for concision.
-
-Adapt the structure to the topic — don't pad with empty sections. A typical shape:
-
-```markdown
-# Research: [Topic]
-
-## Summary
-[Key findings + recommendation, 1-3 paragraphs]
-
-## Findings
-[Organized by sub-question. Add security / performance / cost subsections
- only where they're relevant to this topic.]
-
-## Conflicts & Caveats
-[Conflicting or single-source claims, stale info]
-
-## Recommendations
-[Actionable: what to do, code examples, pitfalls. Include a comparison if evaluating options.]
-
-## References
-[Linked sources]
-
-## Open Questions
-[Unresolved items — always include, even if empty.]
-```
-
-**Standards:** accuracy (cross-referenced), currency (prefer last 12 months unless history
-matters), always cite with links. Deliver strategic intelligence that enables a decision,
-not a pile of links.
+---
+name: research
+description: "Research technical solutions and analyze architectures by spawning parallel researcher agents that search the web and cross-reference findings. Use for technology evaluation, best-practices research, solution design, and scalability/security/maintainability analysis."
+license: MIT
+argument-hint: "[topic]"
+metadata:
+  author: Phuc Pham
+  version: "2.1.1"
+---
+
+# Research
+
+## 1. Decompose
+
+Break the topic into independent sub-questions. Note recency requirements (how current
+the information must be) and any specific angles the user cares about (security, perf,
+cost, migration path) — these shape both the queries and the final sections.
+
+## 2. Gather (parallel agents)
+
+For each independent sub-question, dispatch a `researcher` agent via the Agent tool
+(`subagent_type: "researcher"`). Run independent agents in a single message so they execute
+concurrently. Scale the count to the topic's breadth; don't spawn overlapping agents.
+
+Give each agent **one** sub-question plus any recency/angle constraints from step 1. The
+agent handles query crafting, source prioritization, and returning findings with URLs.
+Keep synthesis (steps 3–4) in the main agent.
+
+## 3. Cross-reference
+
+Before synthesizing:
+- **Verify** each significant claim across multiple independent sources.
+- **Check dates** — flag stale information.
+- **Surface conflicts** explicitly rather than silently picking a side.
+- **Flag single-source claims** as unverified; discard or downgrade what fails.
+
+## 4. Report
+
+Save to the output path if the main agent provided one; otherwise return inline. Cite
+sources throughout. Sacrifice grammar for concision.
+
+Adapt the structure to the topic — don't pad with empty sections. A typical shape:
+
+```markdown
+# Research: [Topic]
+
+## Summary
+[Key findings + recommendation, 1-3 paragraphs]
+
+## Findings
+[Organized by sub-question. Add security / performance / cost subsections
+ only where they're relevant to this topic.]
+
+## Conflicts & Caveats
+[Conflicting or single-source claims, stale info]
+
+## Recommendations
+[Actionable: what to do, code examples, pitfalls. Include a comparison if evaluating options.]
+
+## References
+[Linked sources]
+
+## Open Questions
+[Unresolved items — always include, even if empty.]
+```
+
+**Standards:** accuracy (cross-referenced), currency (prefer last 12 months unless history
+matters), always cite with links. Deliver strategic intelligence that enables a decision,
+not a pile of links.