deliberate-cli 0.2.0-beta.1.1

package/roles/scout/matchup/output-template.md

@@ -0,0 +1,115 @@
+# Matchup — _<Product>_ vs _<Us>_
+
+As of _<Month D, YYYY — the date this read was true>_.
+
+## Bottom line
+
+_2–3 sentences: what this rival is, where it collides with us (and at which layer — platform vs product),
+and the single most important strategic implication. Then the one-line takeaway as a blockquote — the
+sentence a reader keeps if they read nothing else._
+
+> _**The one-line takeaway.**_
+
+## At a glance
+
+_The head-to-head in one scannable table. Pick the 6–10 factors that actually decide this contest. `Edge`
+is an honest call — `us`, `them`, or `even` — never a home-team default._
+
+| Factor | _<Product>_ | _<Us>_ | Edge |
+|---|---|---|---|
+| _factor_ | _their state_ | _our state_ | _us / them / even_ |
+
+## Strengths & weaknesses
+
+_Honest SWOT for both sides. Each side's real weakness is the other's opening — name them plainly._
+
+- **Their strengths (our threats):** _≤3 — what they genuinely do better._
+- **Their weaknesses (our openings):** _≤3 — where they're structurally or currently weak._
+- **Our strengths (their threats):** _≤3._
+- **Our weaknesses (their openings):** _≤3 — be candid; the deck loses in Q&A otherwise._
+
+## Dimension-by-dimension
+
+_One tight block per dimension — 1–3 sentences each. End every block with **Edge: us / them / even —
+because…**. Drop a dimension only if it genuinely doesn't apply (say so)._
+
+### User journey
+_First-run to habitual use for each; where onboarding / activation is smoother. **Edge:** …_
+
+### UX / interaction
+_Interaction model, polish, the moments that delight or grate. **Edge:** …_
+
+### Functional
+_What each has that the other doesn't; parity / WIP on both sides. **Edge:** …_
+
+### Supported scenarios
+_The genres / use-cases each covers; the omission on each side. **Edge:** …_
+
+### Strategic
+_The real threat (commoditization? substitution?) and the real opportunity. **Edge:** …_
+
+### Marketing & positioning
+_How each is sold — audience, message, tone; the risk of a head-to-head we'd lose. **Edge:** …_
+
+### Pricing & business model
+_How each monetizes (free/OSS, PLG, sales, tiers); where the wedge is. **Edge:** …_
+
+### Distribution & GTM motion
+_How each acquires and where that's strong or brittle (stars, community, sales, embeds). **Edge:** …_
+
+### Implementation approach
+_Architecture / stack / runtime and the trade-offs it buys or costs each side. **Edge:** …_
+
+### Ecosystem & interoperability
+_Integrations, standards, partners; whether the two can coexist / migrate between. **Edge:** …_
+
+### Maturity & momentum
+_Version, cadence, adoption, funding, team size, bus factor — who's accelerating. **Edge:** …_
+
+## Jobs-to-be-done coverage
+
+_The core jobs in this space; who gets each done and where the gap is. Keep to the jobs that matter._
+
+| Job (`I want to _[job]_, so I can _[outcome]_`) | _<Product>_ | _<Us>_ | Gap |
+|---|---|---|---|
+| _job_ | _covers / partial / no_ | _covers / partial / no_ | _the opening_ |
+
+## Battlecard
+
+- **Why we win:** _≤3 themes — the durable reasons a buyer chooses us. Each with a proof point._
+- **Why we lose:** _≤3 — the honest reasons a buyer chooses them._
+- **Landmines / traps:** _≤3 — where competing on their terms is a mistake (our do-not-compete), and
+  their claims we must not walk into._
+- **Objection handling:** _≤3 — their strongest pitch line, and our grounded answer to it._
+
+## Positioning against them
+
+_2–4 sentences: the frame that makes their strengths matter less and moves the fight to our ground
+(who-it's-for, the category, the wedge). Then the explicit **do-not-compete**: the arena we deliberately
+cede._
+
+## Opportunities
+
+_Prioritized responses. `Borrow` ranked by value ÷ effort; `Partner` = interop / coexistence angles;
+`Respond` = roadmap / positioning moves. ≤3 per lane, only what's genuinely warranted._
+
+- **Borrow:** _capability worth adopting — why it fits, value ÷ effort. (Learn, don't copy — note their
+  license.)_
+- **Partner / interop:** _a coexistence, migration, or partnership angle._
+- **Respond:** _a feature, spike, positioning, or pricing move — tied to the finding that motivates it._
+
+## Strategy canvas
+
+_The value-curve inputs for a comparison chart. List the competing factors buyers weigh; rate each
+`high / medium / low` for both. Where the two lines diverge is the story._
+
+| Factor | _<Product>_ | _<Us>_ |
+|---|---|---|
+| _factor_ | _high / medium / low_ | _high / medium / low_ |
+
+## Sources
+
+_Every claim above traces here. First-party where possible; date each; mark confidence
+(**fact** first-party ▪ **inferred** ▪ **assumption**)._
+
+- _[Source name](https://…) — <what it grounds> · <date> · fact / inferred / assumption_

package/roles/skills/README.md

@@ -0,0 +1,19 @@
+# Skills — reusable method and craft
+
+These files are shared, product-agnostic methods injected into role prompts alongside the current project's context. They teach roles how to do the craft; they must not describe a specific product. Product-specific grounding is written by the host during `init` under `deliberate/context/` and supplied separately.
+
+| File | Purpose | Used by |
+| --- | --- | --- |
+| `jtbd.md` | Jobs-to-be-Done analysis: situation, motivation, desired progress, alternatives, outcomes, and evidence | Init, Frame, Shape, Launch, Prototype, One-pager, Matchup |
+| `positioning.md` | State the competitive alternative, unique attributes, value, audience, category, positioning statement, and defensible differentiator | Init, Launch, One-pager, Matchup |
+| `metrics.md` | Select outcome measures, leading inputs, and counter-metric guardrails without confusing activity for value | Init, Launch |
+| `product-readout.md` | Produce a defensible periodic read of configured metrics and customer evidence, including comparisons, evidence gaps, causality, and actions | Readout |
+| `ux-principles.md` | Surface-neutral experience principles for clear, accessible, trustworthy product journeys | Shape, Prototype |
+| `win-conditions.md` | Evaluate durable demand, value, fit, adoption, distribution, trust, and compounding advantage as build-toward goals | Score, Shape, Launch, Prototype |
+| `prioritization.md` | Apply gates and a weakest-link rubric to produce an evidence-based 0–10 score and lean verdict, excluding effort | Score, Matchup |
+| `critique.md` | Constructive, bounded criticism that strengthens a decision without creating endless review loops | Score |
+| `landscape-scan.md` | Scan market and competitive evidence with source discipline, breadth, time-window filtering, and change detection | Init, Brief, Matchup |
+| `head-to-head.md` | Research one named rival deeply across evidence, dimensions, SWOT, JTBD, battlecard, positioning, and opportunities | Matchup |
+| `tech-constraints.md` | Keep prototypes, artifacts, and implementation guidance self-contained and integration-ready | Shape, Prototype, Matchup |
+
+`roles/config.yaml` is the source of truth for which role receives each method. The engine re-reads it on every invocation, so changes apply to the next prompt.

package/roles/skills/critique.md

@@ -0,0 +1,64 @@
+# Critique
+
+> How the **Critic** pushes every stage toward greatness **in a single pass**. The engine
+> allows the Critic exactly **one** automatic revise loop, then the pipeline always
+> proceeds (`src/engine/pipeline.mjs`). So this is not a conversation — it is one
+> high-leverage intervention. Make it count; never bank on a second round.
+
+## The economics: one shot, so bundle everything
+There is **no back-and-forth**. You do not get to raise issue A, see it fixed, then raise
+issue B. Therefore:
+- **Front-load every concern in one critique.** If three things are wrong, name all three
+  now — don't hold the second-order issues for a round that will never come.
+- **Make each ask self-contained and checkable.** Request only changes the producer can
+  fully make and you could verify in the *same* artifact — never "explore X and report
+  back," never "let's iterate on Y."
+- **Right-size the ask.** A `revise` must be completable in one pass. If a fix is too big
+  for that, say so plainly (`block`, or note it as a follow-up) rather than triggering a
+  revise you know can't land in one go.
+
+## Two altitudes: floor, then ceiling
+Great criticism does two jobs at once. Do both, in this order:
+
+**1. The floor — must-fix (gates the verdict).** Correctness, grounding, alignment,
+stage-rubric compliance. These are things that make the work *wrong* — fabricated demand,
+drift from strategy/non-goals, a Prototype that doesn't run, a Case scored on solution
+effort. Any of these → `revise` (or `block` if unrecoverable in one pass).
+
+**2. The ceiling — the single biggest lift (elevates).** Beyond "not wrong," name the
+**one** change that would take the work from *fine* to *exceptional* — the sharper insight,
+the more ambitious framing, the missing move a great operator would make. Offer it even
+when the floor is clean (on a `proceed`), as an **optional** lift labelled as such. Exactly
+one — the highest-leverage one — so it's actionable, not a wish-list.
+
+## How to make it constructive (not destructive)
+- **Point to the fix, not just the flaw.** Every concern = *what's wrong* → *why it changes
+  the decision* → *the specific change that resolves it*. A flaw with no direction is noise.
+- **Raise the bar, don't rewrite the work.** You judge and direct; you don't produce the
+  artifact. Give the sharpest possible instruction, then let the producer execute.
+- **Be specific and evidential.** Quote the line, name the missing evidence, cite the rubric
+  or skill it violates. Vague criticism can't be acted on in one pass.
+- **Prioritize ruthlessly.** Lead with what matters most. Cap it: **≤ 3 must-fix + 1
+  elevation.** A long list dilutes the signal and can't be resolved in one revise.
+
+## When to stop (don't manufacture work)
+- If it is grounded, aligned, and meets the rubric, say **`proceed`** — plainly. Do not
+  invent concerns to look rigorous.
+- The bar for `revise` is **"this is materially wrong or changes the decision,"** not "I'd
+  have done it differently." Taste disagreements are at most an optional elevation note.
+- Never withhold a `proceed` to force another lap. One pass is the design, not a failure.
+
+## Verdict discipline
+- **`proceed`** — floor is clean. May carry one optional elevation.
+- **`revise`** — one or more must-fix issues that are *fixable in a single pass*; bundle
+  every fix into this one critique.
+- **`block`** — a fatal, unrecoverable-in-one-pass problem (e.g., the whole artifact is
+  ungrounded, or built for a different product). Reserve for genuine dead-ends; the human
+  gate handles the rest.
+
+## Anti-patterns
+- Nitpicking style, wording, or formatting that doesn't change the decision.
+- Drip-feeding concerns across "rounds" that don't exist — one shot, all issues.
+- Requesting open-ended exploration or anything you can't verify in the same artifact.
+- A wall of low-priority notes; a `revise` with no specific, one-pass fix.
+- Manufacturing concerns on solid work instead of saying `proceed`.

package/roles/skills/head-to-head.md

@@ -0,0 +1,88 @@
+# Head-to-Head — Method
+
+> Use this whenever you produce a **single-competitor matchup** — a full, sourced read of one named
+> product against ours, on demand. It is the sibling of `landscape-scan`: that skill scans the *field*
+> for *change over time* (breadth); this one goes *deep on one named rival* at a point in time (depth).
+> Reuse `landscape-scan` §2 (source discipline) verbatim; everything else here is matchup-specific. The
+> goal is a document a PM can defend in a board review and assemble a competing deck from without
+> re-researching.
+
+## 0. Point-in-time, not a time series
+A matchup is **the current read on one rival**, true as of a stated date — not a log of changes (that's
+`brief`). Stamp the `as_of` date (in the body **and** the frontmatter), ground the read in what's live
+*now*, and **refresh the single canonical doc in place** when the rival moves — don't spawn a new dated
+copy (git holds the history; `brief` owns the change-over-time series and signals when a refresh is due).
+If a claim was true six months ago but isn't now, it doesn't belong.
+
+## 1. Steelman before you strike
+**Argue the rival's case at its strongest first.** Per `AGENTS.md` ("do your stage's job objectively"),
+a flattering matchup is worse than useless — it loses the deck in the Q&A. Establish, honestly, what they
+do genuinely better and why a smart buyer picks them *before* you find the openings. Home-team bias is the
+failure mode; catch it in yourself.
+
+## 2. Ground every claim in a source (from `landscape-scan` §2)
+Each factual claim carries a **working link** to a first-party source — their site, docs, changelog, repo,
+pricing page, a release tag, a filing. Name the source in the link text. Mark each claim's confidence:
+**fact** (first-party, cited) ▪ **inferred** (reasoned from evidence) ▪ **assumption** (stated as such).
+Never present an inference or assumption as a fact. If the project context or the rival's public surface is
+thin, say what you could and couldn't ground — don't invent features, pricing, funding, or adoption.
+
+Grounding sources: `deliberate/context/product.md` (our positioning, personas, JTBD, strategy) +
+`deliberate/context/competitors.md` (if the rival is already tracked, its monitoring sources) + the
+attached sources + your own first-party research of the rival. If the rival isn't tracked yet, **ask the
+user whether to add it** (default yes) to the Competitors roster in `product.md` and its monitoring sources
+in `competitors.md` so `brief` starts watching it — closing the loop between the two commands.
+
+## 3. Read across every dimension — who's ahead, and why
+Work each dimension and end each with an honest **Edge: us / them / even — because…**. Cover, at minimum:
+
+- **User journey** — first-run → habitual use; where activation is smoother.
+- **UX / interaction** — model, polish, the moments that delight or grate.
+- **Functional** — has / doesn't-have on both sides; parity and WIP.
+- **Supported scenarios** — the genres each covers; the omission on each side.
+- **Strategic** — the real threat (commoditization / substitution) and the real opportunity.
+- **Marketing & positioning** — audience, message, tone; the head-to-head we'd lose.
+- **Pricing & business model** — how each monetizes; where the wedge is.
+- **Distribution & GTM** — how each acquires; where that's strong or brittle.
+- **Implementation approach** — architecture / stack / runtime and its trade-offs.
+- **Ecosystem & interoperability** — integrations, standards, partners; can they coexist / migrate?
+- **Maturity & momentum** — version, cadence, adoption, funding, team size, bus factor, trajectory.
+
+"Even" is a valid verdict. Don't manufacture contrast to look thorough.
+
+## 4. Synthesize — SWOT, JTBD, and the value curve
+- **SWOT the pair:** each side's real weakness is the other's opening. Name our weaknesses candidly.
+- **JTBD coverage:** apply the `jtbd` method — the core jobs in this space, who gets each done, and the
+  gap. Jobs, not features.
+- **Strategy canvas:** rate the buyer's decision factors `high / medium / low` for both sides — the
+  value-curve inputs. Where the two lines diverge is the story.
+
+## 5. Turn the read into a decision
+- **Battlecard:** **why we win** / **why we lose** (≤3 each, with proof), **landmines** (where competing on
+  their terms is a trap — our do-not-compete), and **objection handling** (their best pitch line + our
+  grounded answer).
+- **Positioning against them** (apply `positioning`): the frame that moves the fight to our ground, plus
+  the arena we deliberately cede.
+- **Opportunities** (apply `prioritization`): **Borrow** (value ÷ effort; learn, don't copy — respect
+  their license), **Partner / interop**, **Respond** (roadmap / pricing / positioning). Only what's
+  warranted.
+
+## 6. Leave it deck-ready (no separate deck section)
+Don't add a slide outline or "deck kit" — the substance *is* the deck material. A good matchup already
+carries everything a competing deck needs: a one-line thesis (Bottom line), the at-a-glance table, the
+strategy canvas, the win/lose themes with proof, objection handling, and the prioritized bet — each
+grounded and cited. Write those well and a human can assemble slides without re-researching.
+
+## 7. Be concise
+Every bullet **≤ 3 sentences, ideally 1–2**. Hard caps: ≤3 per battlecard lane, ≤3 opportunities per lane,
+one tight block per dimension, 6–10 factors in the at-a-glance and canvas tables. The fewer bullets, the
+better — earn every line.
+
+## Anti-patterns (reject these)
+- A home-team read that never says where we lose, or lists no real weakness of ours.
+- A "fact" with no source link, or an inference/assumption dressed as a fact.
+- Stale claims — anything not true as of the `as_of` date.
+- Manufactured contrast where the honest answer is "even".
+- Copying the rival's code/assets instead of learning from the pattern (mind their license).
+- Padding every dimension to look exhaustive instead of cutting to what decides the contest.
+- Bolting on a slide outline / "deck kit" — the substance already seeds the deck (§6).

package/roles/skills/jtbd.md

@@ -0,0 +1,43 @@
+# Jobs-to-be-Done (JTBD) — Method
+
+> Use this whenever you **frame a problem** (Frame) or **design a surface** (Shape, Prototype).
+> A job is the *progress a user is trying to make in a situation* — never a feature, never a demographic.
+
+## 0. Find the personas & jobs from evidence (don't invent them)
+Before framing anything, **infer who the users are and what jobs they're doing from the evidence**: the attached **sources (code, docs)** and the **content of the case**. Read the repo/docs for the surfaces, roles, and workflows the product already serves; read the case for who is hurting and why. Each persona and job must trace to that material — never conjure a persona, job, or demographic the evidence doesn't support (label genuine inferences as assumptions).
+
+Then **scan for additional affected personas**: who else feels the ripple effects of this problem? Look one step out from the obvious user — the **admin/approver upstream**, the **downstream consumer** of their output, the **teammate or peer** who depends on them. Include the ones whose jobs are **materially** affected (grounded the same way); skip incidental bystanders. For each, name *how* the problem touches their job.
+
+## 1. Job statement — the lean format (what Frame outputs)
+**Group jobs under the persona who has them.** The persona line carries the *who* and the situation; each job is a single bullet, matching the Frame template:
+**"I want to [job to be done], so I can [outcome]."**
+- Keep it **solution-free** — no product or feature names.
+- It's a *job*, not a feature request or a demographic. (Underneath, every job still answers "When [situation], I want to [motivation], so I can [outcome]" — but the situation lives in the persona framing, so the bullet stays lean.)
+- A few **key** jobs per persona — don't bundle unrelated jobs into one line, and don't pad with minor ones.
+
+## Going deeper — for the design stages (Shape & Prototype)
+> Frame stays lean: personas + their key jobs. The tools below are for the design stage (Shape), which must move a *specific* job through a real UX. Don't make Frame produce a full workup.
+
+### The struggling moment (optional)
+When it fits the product/scenario, name the **specific, observable moment of friction** that makes the user start looking for a better way — concrete ("it's 11pm and I have 40 unread feedback items and a roadmap review tomorrow"), not abstract ("they're busy"). Some jobs are ongoing or ambient rather than triggered by a sharp moment; **don't force a struggling moment where there isn't one.**
+
+### Three dimensions
+A job usually has three dimensions — cover the ones that matter for the design:
+- **Functional** — the practical task to accomplish.
+- **Emotional** — how they want to feel, or stop feeling (e.g., in control, not anxious, confident).
+- **Social** — how they want to be *perceived* by others (their team, boss, peers, investors).
+
+### Job map — the steps of getting the job done
+The job has stages even when no product exists. Use the steps that apply:
+**Define → Locate → Prepare → Confirm → Execute → Monitor → Modify → Conclude.**
+For each relevant step, note **today's friction**. Good UX supports the *steps of the job*, not just one button.
+
+### Forces of progress (why they switch — or don't)
+- **Push** (pain of the current situation) + **Pull** (attraction of the new way) drive change.
+- **Habit** (inertia of today) + **Anxiety** (fear of the new) resist it.
+Design must **amplify pull and reduce anxiety** (e.g., show the evidence to build trust).
+
+## Anti-patterns (reject these)
+- A persona is not a job. A feature is not a job. "Be more productive" is too vague to act on.
+- A solution smuggled into the job statement ("I want a dashboard…").
+- A persona or job invented without support in the sources or the case.

package/roles/skills/landscape-scan.md

@@ -0,0 +1,77 @@
+# Landscape Scan — Method
+
+> Use this whenever you work the competitive + market landscape: **setting up a project's context**
+> (`init` — map the *current* field of named competitors and their monitoring sources, the ecosystem
+> players and theirs, and the market/space) or producing a periodic **Brief** (the *changes* within a
+> time window). The competition + market **lenses** (§1) and the **source discipline** (§2) are shared;
+> the **timeframe** (§0), the filtering to executive-worthy *change* (§3), and the decision framing (§4)
+> apply to the **Brief**. For `init` you are cataloguing the field, not reporting change — skip §0 and use
+> §1–§2 to find and record the real competitors, the ecosystem players, their first-party sources, and the
+> market signals worth watching.
+
+## 0. Timeframe — the whole game (Brief only)
+A brief reports **only what changed inside the window** you are given (`period_start → period_end`).
+- The window is *since the last brief*, capped at **3 months**. If a change shipped, was announced, or
+  was reported **before `period_start`, it does not belong in this brief** — a prior brief already owned
+  it (or it is too old to be news).
+- Date every finding against the window before you keep it. If you cannot establish that a change
+  happened inside the window, **drop it** — do not pad the brief with undated evergreen facts.
+- "No change" is a valid, valuable answer. An honest empty section beats invented motion.
+
+## 1. Two lenses
+**Competition** — the *named* competitors from the project context (`product.md` → Competitors, with
+their monitoring sources in `competitors.md`). For each, scan the **first-party** signals in
+`competitors.md` within the window:
+- announcements / product blog, release notes / changelog, **roadmap** changes,
+- **codebase activity** (public repos: notable commits, merged PRs, new modules, deprecations),
+- pricing / packaging changes, docs for newly-shipped capabilities.
+
+**Market & ecosystem** — the *space and players around the project*, one step wider than the named
+competitors, grounded in `product.md` → **Ecosystem** (the named players — dependencies, complements,
+channels, movers — each `current`/`potential`, with their monitoring sources in `ecosystem.md`) and
+`product.md` → **Market** (the category, the standards & protocols the product participates in or depends on,
+and the technologies/trends to watch). For each ecosystem player, scan its **first-party** signals in
+`ecosystem.md` within the window (a dependency's releases / breaking changes / security advisories, a
+complement's product & integration updates, a channel's marketplace or policy changes, a mover's spec /
+roadmap / governance shifts); for the market, watch:
+- new or upcoming **protocol / standard / spec** releases and version bumps,
+- **new entrants** or adjacent players (including potential partners),
+- **M&A, funding, partnerships, pivots, shutdowns**, and newly-relevant **technologies** or platform shifts.
+Market events (funding, M&A) may cite a reputable secondary source when no first-party one exists;
+competitor and ecosystem-player product claims should trace to their own channel wherever possible. If the
+project context's Competitors, Ecosystem, or Market is thin, say what you could and could not ground — don't
+invent players or standards to fill it.
+
+## 2. Ground every finding in a source
+Each highlight carries a **working link** to where you saw it — a changelog entry, a blog post, a commit,
+a release tag, a filing. No link, no highlight. Prefer official / first-party sources; name the source in
+the link text so the reader knows what they're clicking (`[Changelog](…)`, `[GitHub PR](…)`).
+
+## 3. Filter hard — earn the executive's attention
+The fewer bullets, the better. A finding only survives if it is **important, relevant to this project, and
+potentially actionable**. Ruthlessly cut:
+- routine dot-releases, dependency bumps, copy tweaks, minor bug fixes,
+- vanity metrics and undirected "they posted a blog" noise,
+- anything a manager would skim past.
+Caps (hard limits, aim lower): **≤ 3 highlights per competitor**, **≤ 3 market highlights**, **≤ 3 Key
+highlights** overall, and only the action items that are genuinely warranted. If a competitor had no
+meaningful change, say **"No meaningful updates."** — don't manufacture one.
+
+## 4. From findings to a decision
+- **Key highlights** = the top (≤3) changes across *both* lenses — what the reader must know if they read
+  nothing else. Draw them from the per-section findings; don't introduce new facts here.
+- **Action items** = the *so-what* for THIS project, reasoned from the highlights: should a feature,
+  research spike, or investment be started? A partnership explored? A new technology or standard adopted?
+  A positioning or pricing response considered? Tie each action to the finding that motivates it. Only
+  include actions that are warranted — an empty action list is fine when the window was quiet.
+
+## 5. Be concise
+Every bullet is **≤ 3 sentences, ideally 1–2** — straight to the point, no preamble, no hedging. The
+brief is scanned in a minute; write it that way.
+
+## Anti-patterns (reject these)
+- A finding with no date, or dated outside the window.
+- A highlight with no source link, or a link to a non-authoritative source presented as first-party.
+- Padding a quiet window with minor releases to look thorough.
+- Repeating a change a previous brief already reported.
+- Editorializing / speculation dressed as fact; inventing funding, partnerships, or competitors.

package/roles/skills/metrics.md

@@ -0,0 +1,58 @@
+# Metrics — Method
+
+> Use this whenever you must state **how a product's success is measured**: the Metrics & traction of a
+> project's context (`init`) and the telemetry-grounded metrics of a go-to-market (`market`). A good metric
+> is one number that, if it moves, tells you the product is delivering more value — and that a team can
+> actually influence. Ground every metric in real evidence. Project context records durable definitions and
+> comparison semantics, never time-sensitive values or targets copied during init.
+
+## The north-star — pick the one that matters
+The **north-star metric (NSM)** is the single measure that best captures the value customers get (and that
+the business captures in turn). Test a candidate against three checks:
+- **Value:** does it go up only when customers get more of what they came for? (Not vanity — registrations,
+  raw pageviews, and "total users" usually fail this.)
+- **Leading, not lagging:** does it move *before* revenue, predicting it? (Revenue itself is the lagging
+  result; the NSM is the input that drives it.)
+- **Actionable:** can the team move it through the product? (Not a market-wide number nobody controls.)
+Prefer a metric of *delivered value per unit time* (e.g. "weekly active teams that complete the core job")
+over a stock ("total signups").
+
+## The metric tree — inputs beneath the NSM
+Decompose the NSM into the **input metrics** that drive it, so the context shows *what to pull*:
+- **Acquisition → Activation → Engagement → Retention → Revenue → Referral** (the AARRR spine) — keep the
+  stages that matter for this product.
+- For each, name the **one** metric that best captures it (activation rate, D30/W4 retention, weekly active,
+  expansion, referral rate, …).
+- Distinguish **leading vs lagging** (activation & retention lead; revenue & churn lag) so the reader knows
+  which are early signals.
+
+## Guardrails — what must NOT get worse
+Name a **counter-metric** for the NSM (the thing a naive push on the NSM would break — quality, latency,
+trust, unit cost, support load). A metric without a guardrail invites gaming.
+
+## The readout contract — make every read comparable
+
+First record one project-level reporting contract:
+
+- cadence and calendar alignment, defaulting to a completed Monday–Sunday calendar week;
+- the project's named timezone;
+- comparison with the immediately preceding equivalent completed period.
+
+Then, for every metric, record the durable semantics needed to calculate it consistently over that shared period: exact definition, aggregation, source or query, unit, desired direction, and important segments. A user may override one readout with another completed calendar period or explicit date range; every metric and evidence source follows the override for that run, and the comparison becomes the immediately preceding equivalent period. The previous readout artifact is never the metric baseline.
+
+## Craft rules
+- **One north-star, a handful of inputs.** A dashboard of 30 metrics is not a strategy.
+- **Keep context durable.** Never copy a current value, dated baseline, target, or mutable numeric boundary
+  into init context. Link the live source that owns those values.
+- **Compare like with like.** Preserve the report-level period, aggregation, alignment, timezone, and segment.
+- **Tie metrics to the job.** The NSM should measure the persona's job-to-be-done getting done, not
+  activity for its own sake.
+- **Per-value, not per-vanity.** Reach/impressions/registrations are vanity unless they map to value.
+
+## Anti-patterns (reject these)
+- A vanity NSM (total users, pageviews, downloads) that rises without more value delivered.
+- Revenue as the north-star (it's the lagging result; find the input that predicts it).
+- A pile of metrics with no single north-star and no guardrail.
+- A snapshot value or target copied into one-time init context where it will silently become stale.
+- A metric calculated over a different period from the rest of the readout.
+- A metric no one on the team can actually move.

package/roles/skills/positioning.md

@@ -0,0 +1,44 @@
+# Positioning — Method
+
+> Use this whenever you must state **what a product is, who it's for, and why it wins**: the
+> Value proposition & positioning of a project's context (`init`), and the pitch of a go-to-market
+> (`launch`). Positioning is a deliberate choice of the *context* in which a product is understood — not a
+> tagline. Done well it makes the value obvious to the right buyer; done badly it makes a good product
+> look irrelevant. Ground every element in real evidence — never borrow another product's story.
+
+## The five inputs (derive these first — April Dunford's frame)
+Work them in order; each constrains the next:
+1. **Competitive alternatives** — what the customer would *actually* use if this didn't exist (a rival, a
+   spreadsheet, a manual process, "do nothing"). This sets the reference point the value is judged against.
+2. **Unique attributes** — the capabilities / assets this has that the alternatives **lack** (features,
+   data, integrations, model, distribution, license). Only real, verifiable ones.
+3. **Value** — the outcome those attributes enable that the customer cares about ("so they can __"). Map
+   each attribute → the concrete value; drop attributes that map to no value the buyer wants.
+4. **Target segment** — the customers who care **most** about that value (the ones for whom it's urgent,
+   frequent, or high-stakes). Positioning is sharpened by *who you exclude*, not just who you include.
+5. **Market category** — the frame of reference that makes the value obvious to that segment ("it's a
+   \_\_"). The category sets expectations; pick the one where the unique value reads as important, not the
+   biggest-sounding one.
+
+## The output — a positioning statement
+Compose the inputs into one crisp line, then the sharpest differentiator:
+- **"For [target segment] who [need/situation], [product] is a [market category] that [key value], unlike
+  [competitive alternative], because [unique attribute]."**
+- **Differentiation / moat:** the single defensible reason this stays ahead — or, honestly, "table-stakes:
+  the alternatives already offer this" when there's no durable edge. Never inflate a parity feature into a moat.
+
+## Craft rules
+- **Anchor on the alternative, not the feature.** Value is relative; "10× faster" means nothing without the
+  baseline the buyer compares against.
+- **One segment, one category, one core value.** A statement that fits everyone positions for no one.
+- **Attributes → value, always.** A list of features is not positioning; the value they unlock is.
+- **Be specific and grounded.** Name the real segment, the real alternative, the real attribute — no
+  invented demand, no aspirational moat the evidence doesn't support (label an assumption if you must).
+- **Keep it tight.** The statement is one sentence; the differentiator one or two bullets.
+
+## Anti-patterns (reject these)
+- A feature list or a mission statement dressed up as positioning.
+- "For everyone" / "the leading platform for X" (category-inflation with no chosen segment).
+- A moat claim that's really table-stakes; or unique attributes that map to no buyer value.
+- Positioning against a category ("we're not like legacy tools") instead of the concrete alternative the
+  customer would actually choose.

package/roles/skills/prioritization.md

@@ -0,0 +1,101 @@
+# Prioritization
+
+> How **Score** turns the AI-era **win-conditions** (defined in the `win-conditions` skill)
+> into a single go / no-go score. The win-conditions say what makes a **product** win over
+> time; Score scores a single **Case** — so the test is whether the Case **advances or
+> unblocks** those win-conditions, **not** whether one Case embodies all of them. Score
+> **project-relative** (against *this* project's strategy/objective from the derived context),
+> grounded in the Frame artifact (the problem + competitive landscape), on a **0–10** scale.
+>
+> **Reason fully, then explain clearly.** Work through the factors internally, then publish a
+> short, **human-legible** brief (see "Output") — not the raw factor table or math.
+
+## The one rule: score the problem, not the solution
+Score runs **before** anything is designed or built, so ignore every solution-side variable
+— **effort, size, feasibility, build cost, and "how hard is it to build" are out of scope.**
+When building is nearly free, that a thing *can* be built tells you nothing. Judge only the
+**opportunity**.
+
+## What gates, and what only lifts
+Not every good Case is a moat. Some **drive** a win-condition (build the flywheel, own a new
+channel); many **enable** one (remove a limitation, reach parity, unblock or **broaden the
+audience**). Both can be high-value — so separate the *necessary* conditions from the *value
+multipliers*.
+
+**Kill-gates — the case-level necessities (a Case must clear all three):**
+- **Durable, AI-proof demand** — a real, important need that ubiquitous AI makes *more*
+  valuable, not obsolete. No real demand → dead.
+- **Reachable audience** — the people who need it can actually get and adopt it (AI-era
+  distribution at the Case level). A Case that **broadens** the audience scores *well* here —
+  it is not penalised for it.
+- **On-strategy & trust-safe** — it advances (or at least doesn't contradict) this project's
+  strategy, and it doesn't erode trust or violate a non-goal. A non-goal / hard-constraint
+  violation is an automatic **reject**.
+
+**Value multipliers — raise a passing Case, never gate it:**
+- **Compounding flywheel / moat** — how much durable, proprietary advantage it builds (data,
+  network, switching costs). Strong = big upside; **weak is fine for an enabler.**
+- **Differentiation, taste & delight, agent-readiness, personalization, openness, "why now."**
+  (Full definitions in `win-conditions`.)
+
+## Credit enablers and table-stakes (don't punish parity)
+A Case that removes a key limitation, reaches competitive parity, or **broadens the target
+audience** is legitimately valuable **even with no standalone moat**. Score it on the demand
+it unlocks and the audience it opens, and recognise it **raises the ceiling** for future
+flywheel and differentiation. **Never reject or dock an enabler merely for "not being a moat
+by itself"** — that is the wrong test for enabling work. Where useful, name the moat-builder
+it sets up next, but do not hold its absence against the enabler.
+
+## Confidence is a modifier, not a factor
+**Cap** any factor whose score rests on thin or second-hand evidence, and state the biggest
+uncertainty. Strong scores need independent, grounded evidence — else the Evaluator will (rightly)
+flag fabricated demand, reach, or advantage.
+
+## How to aggregate — gates, then weakest-link + multipliers (NOT a weighted average)
+**Do not average the factors.** A weighted mean lets a strong factor paper over a fatal flaw
+and rewards bland, well-rounded Cases over the spiky ones that matter. Instead:
+
+**Step 1 — Kill-gates.** If any of the three necessities (demand · reachable audience ·
+on-strategy/trust-safe) is essentially absent (≤ 3/10), or a non-goal / hard constraint is
+violated → **reject**; the score is that low necessity's value. No multiplier buys it back.
+
+**Step 2 — Floor by the weakest necessity, then lift with multipliers.** For a Case that
+clears the gates, the floor is set by the weakest of the three necessities (a chain is only as
+strong as its weakest link). From there the **multipliers raise the score** — a strong
+moat/flywheel or sharp differentiation pushes toward the top; their **absence does not pull an
+enabler down**. An enabler with strong demand + audience and a weak moat is a **good** Case,
+not a weak one.
+
+**Step 3 — Verdict.** Map to the bands. Prefer a defensible whole or half number — the gate
+logic is the point, not the decimal.
+
+## Verdict bands (0–10)
+Advisory input to the human's go/no-go decision:
+- **≥ 7.0** → **advance** — real durable demand, a reachable (often broadened) audience,
+  on-strategy; either a genuine driver *or* a strong enabler that unlocks a lot.
+- **5.0 – 6.9** → **shelve** — clears the gates but limited; name the single thing that would
+  move it (more demand evidence, a wider audience, or the moat it should set up).
+- **< 5.0** → **reject** — fails a kill-gate: no real demand, no reachable audience, or
+  off-strategy / trust-eroding.
+
+## Output — a short, legible brief
+Reason through everything internally, then emit a **structured, human-readable** summary
+following the output template: a **Score + verdict**, a one-line "what this is," then **only the
+1–3 factors that actually drive the score** (the binding constraint and the biggest lift) —
+**not** a roll-call of kill-gates that merely clear (a passing gate is a pass, not a reason), and
+**no "Net" / synthesis line**. Then **at most two concrete, checkable risks** (the specific thing
+that could be wrong and how you'd know — not an abstract caveat), kept separate from the strengths,
+and the single thing that would change the call. Fewer, sharper points beat completeness; keep each
+one a clear sentence. Do **not** dump the raw factor table, the per-factor numbers, or the math.
+
+## Anti-patterns
+- **Punishing an enabler / table-stakes Case for lacking a standalone moat or flywheel** —
+  removing a limitation and broadening the audience *is* the value; score it on that.
+- **Citing kill-gates that merely clear as justification for the score** — a passing gate is a
+  pass, not a driver; name only the factors that actually move the number.
+- **A "Net" / synthesis line, more than three drivers, or abstract non-actionable risks** — cut them.
+- **Computing a weighted average / summing the factors** — use gates + weakest-link + multipliers.
+- Letting a strong multiplier (moat, taste) paper over **no real demand or no reachable audience**.
+- Scoring how easy/cheap the solution is to build (effort — out of scope).
+- Importing another product's metric or strategy — score against **this** project's.
+- A verdict with no score; a dense, self-conflicting paragraph instead of the structured brief.