deliberate-cli 0.2.0-beta.1.1

package/AGENTS.md

@@ -0,0 +1,40 @@
+# Repository guidance for AI agents
+
+This repo implements **Deliberate** — a local, files-first product toolkit for product managers, founders, business development, marketing, and adjacent roles. It ships primarily as a **`/deliberate` skill** for coding-agent harnesses; the host produces Cases, briefs, product readouts, matchups, context, prototypes, and reviewable records in-session. Sonorance is the stable app/platform and agent-review workbench Deliberate runs on; Deliberate contributes capabilities additively and never replaces or rebrands it.
+
+## Golden rules
+- **Ground every claim.** Each conclusion must trace to the case, the attached sources, the project context (`deliberate/context/product.md`), or an explicit assumption labelled as such. Never invent demand, personas, competitors, or distribution channels.
+- **Stay in scope.** Use the **skills** (reusable method/craft) and the **project context** (from `deliberate/context/product.md`) injected into your prompt before producing anything. Respect the project's non-goals and objective.
+- **Append, don't overwrite.** Each stage appends its artifact to the case's accumulated context (the running record of everything prior). Do not contradict earlier stages without flagging it explicitly.
+- **Be concise and structured.** Output the exact sections your stage's instruction file specifies — nothing more.
+- **Fill the template; never echo its instructions.** Output templates describe each section with _italic guidance between underscores_ and parentheticals — these are instructions **to you**, not content. Replace every one with your real, grounded content: keep the section **headings** and fill in the tables, but **never reproduce the italic guidance, placeholder, or any `_…_` prompt text in your output**, and don't add a grounding / assumptions / notes section the template didn't ask for.
+- **Outputs are end-user deliverables — never talk about the run.** The artifact is a finished document a customer reads. **Never** include commentary about your own execution, the task/instructions, the pipeline, tools, sessions, or previous responses (e.g. "the artifact was already produced in my previous response", "the task was to…", "as an AI…", "no further action needed"). Output only the deliverable content itself.
+- **Do your stage's job objectively.** Each role analyzes thoroughly and without prejudging worth — the Analyst frames the problem and designs the concept + its go-to-market; the Evaluator scores. **Only Score (the Evaluator) scores go/no-go.** Don't kill, shelve, or hedge a case because it might be weak; that decision isn't yours.
+- **Curate signal, not inventories.** Init discovers sources section by section and prefers a few authoritative inputs over noisy coverage. Ecosystem dependencies are strategic players whose changes could affect product or business decisions, never a dump of package manifests.
+- **Hand off with a concrete CTA.** Every substantive workflow ends by explaining the most valuable next action and asking for it through the harness's native confirmation UI: init → brief, brief/readout → recommended Cases, Case → prototype, prototype/address → review, matchup → brief.
+
+## Roles, stages & skills (how they're tied together)
+Each part's method lives under `roles/<role>/<part>/instructions.md` + `output-template.md` (+ `skills`), organized by role — `roles/analyst/` (frame, shape, launch, one-pager), `roles/evaluator/` (score), `roles/prototyper/` (prototype) — with the reusable skills in `roles/skills/`. There are **three Case roles**: the **Analyst** — the host, in-session — writes the complete funnel `frame` (problem + competitive landscape) → `shape` (concept + step-level, surface-native journeys) → `launch` (go-to-market); the **Evaluator** judges that finished analysis, preferably as an isolated cross-vendor sub-agent; the **Prototyper** builds `prototype` on request. **The funnel is just `frame → shape → launch`**; Score is not an early-kill gate. The **score** and **prototype** are recomputable companions, not funnel stages. Host-run parts carry no model in `roles/config.yaml`; only `score` configures a target model.
+
+**Beyond the per-case funnel, a fourth role — the Briefer (`brief`)** — produces a project-scoped **landscape brief** (`/deliberate brief`): the competitive + market changes **since the last brief**, capped at 3 months (a first-ever or stale brief → a full 3-month window). It is **not a case** and not a funnel stage (no score, no prototype): one host-run pass writes a single Markdown report to `deliberate/briefs/<YYYY-MM-DD>/brief.md`, applying the `landscape-scan` skill (timeframe discipline, mandatory source links, hard filtering to executive-worthy signal, then Action items for the project). Its method lives under `roles/briefer/brief/` and is bound like the host-run parts (no model). Never re-report a change a prior brief already covered; ground every highlight in a dated source inside the window.
+
+**A fifth role — the Reporter (`readout`)** — produces a project-scoped **product readout** (`/deliberate readout [period]`): the key metrics, customer evidence, material insights, and warranted actions from the project's configured sources. One completed reporting period grounds the entire report; the default is the previous completed Monday–Sunday calendar week under the cadence/alignment/timezone stored in `product.md`, and a user may override one run with a completed period such as June or Q2. Every metric uses that report-level period and the immediately preceding equivalent completed period, so the table does not repeat dates per row. Data from the period currently in progress is excluded rather than projected or compared as complete. When a decision-relevant metric has enough comparable history, the Reporter may add one of up to three deterministic SVG trend charts under `charts/`; charts supplement the exact table values and never smooth, interpolate, forecast, or display targets. It is **not a case** and not a funnel stage: each host-run pass creates `deliberate/readouts/<YYYY-MM-DD[-N]>/readout.md`, keeping same-day runs as separate time-series artifacts. Its method lives under `roles/reporter/readout/`. Distinguish observations, context, hypotheses, and causal evidence; use exact representative feedback quotes only when source/date/prevalence and privacy-safe attribution are available; surface unavailable or contradictory evidence under Data gaps rather than filling it in.
+
+**A sixth role — the Scout (`matchup`)** — produces a project-scoped, single-competitor **head-to-head** (`/deliberate matchup <competitor>`): a grounded teardown of us vs. one named rival across gaps, strengths/weaknesses, UX & user journey, supported scenarios, positioning, target JTBD, and partnership/reuse opportunities — deck-ready. Unlike the date-keyed brief, a matchup is **competitor-keyed and refresh-in-place**: one host-run pass writes a single Markdown report to `deliberate/matchups/<competitor-slug>/matchup.md`, and re-running it for the same competitor **overwrites in place** (keeping the id + created-at, updating the `as_of` timestamp). It carries an `as_of` in frontmatter **and** an "As of <date>." line in the body (so a point-in-time read survives even when metadata isn't rendered). It is **not a case** and not a funnel stage (no score, no prototype), applying the `head-to-head` skill (comparison framework, mandatory source links, executive-worthy signal). Its method lives under `roles/scout/matchup/` and is bound like the host-run parts (no model). Ground every claim in a dated source; keep it to one rival per report.
+
+**Each stage's method is bound in `roles/config.yaml`, not loaded globally.** That file maps each stage to its `instructions` path, output `templates`, a `skills` list, and — for `score` only — a target `model` + tuning knobs. The engine reads and validates it on every invocation and injects only those skill files. Malformed YAML, unknown stages, incomplete bindings, and missing referenced files are hard failures; never add a silent fallback that can produce a plausible but methodologically wrong prompt. The `score` Evaluator carries the `critique` skill and flags ungrounded claims; isolation/provenance comes from how the harness actually runs and saves it, not from configuration alone.
+
+**Auxiliary work is done by the HOST, not engine agents.** There are no `title`, `describe`, or `contextualize` model agents anymore. The **project context** lives as host-written **markdown** in `deliberate/context/product.md` (overview, value proposition & positioning, personas, jobs-to-be-done, interfaces, competitors, ecosystem, market, business model & pricing, distribution & channels, customer voice, metrics & traction, strategy, objective, non-goals — lists for enumerations; scaffold in `roles/initiator/init/output-template-product.md`) plus `deliberate/context/competitors.md` and `deliberate/context/ecosystem.md`. Init idempotently adds a root README section linking `deliberate/context/` and telling agent harnesses to read it before product, strategy, market, positioning, or implementation work. Metrics & traction owns the shared readout cadence/timezone and durable metric semantics rather than mutable values. The host never fabricates a section it can't ground. During `/deliberate init`, source discovery is section-led across product/strategy, code/delivery, metrics/data, customer voice, and go-to-market; it targets at least three high-signal sources per section when they genuinely exist, accepts fewer authoritative sources, and never pads with noise. Every discovered candidate is shown as `- <location> - <description>` before approval. Public product-owned GitHub repositories contribute their enabled Issues pages to Customer voice. Ecosystem dependency manifests are evidence only; ordinary libraries and transitive packages stay out of the strategic roster. The **case title** is likewise the host's job.
+
+Case references may use a full id or a unique prefix. Never guess when a prefix matches multiple cases: the CLI rejects ambiguity so an agent cannot persist output into an arbitrary record. Project-required commands resolve only the initialized current working directory; they must fail rather than mutate another globally selected vault. Likewise, comment bridge transport/server errors are command failures, never success-shaped empty queues.
+
+Score provenance must be literal, not aspirational. The model printed by `case score prompt` is the target; `case score save` receives the actual evaluator model. Pass `--independent` only when an isolated evaluator produced the artifact. If the harness must score inline, omit `--independent`; `score.md` will visibly label the same-session fallback and telemetry will record the content-free guardrail.
+
+## Human gates
+The pipeline stops after the analysis (`launch`); Prototype does not auto-start. Do not attempt to build the prototype without the human asking for it. In the coding-agent flow the harness asks *"Build the prototype now?"* (default yes) and only builds on approval — or the human runs `/deliberate case <id> prototype`.
+
+## Execution model (host-driven; the engine runs no model)
+Every stage is driven by the coding-agent **harness**, not the engine: create the case → `prompt <stage>` → the host produces the artifact → `save <stage>`. The engine is **LLM-free** — there is no headless run, background scheduler, or auto-resume. Keep Prototype's human ask and never add engine-side auto-advance. Sonorance is the existing local app for reviewing and addressing the resulting files; it does not run the workflow.
+
+## State & memory
+A run's records live in the initialized current repo as **plain Markdown/JSON — no database**. Its `deliberate/` folder holds `context/` (`product.md` + `competitors.md` + `ecosystem.md`) plus `cases/<YYYY-MM-DD-slug>/`. A Case is just a prompt, not its own file; the durable combined record is **`analysis.md`** with the title, summary, Key highlights, and one clean section per stage. Each prototype is a `prototype/[<surface>/]index.html` sidecar; **`score.md`** records `evaluator_model` and `evaluator_independent` and visibly labels a same-session fallback; **`one-pager.md`** contains the internal reverse PR-FAQ; `log.jsonl` holds the run log. Within a run, each stage sees the accumulated Case context plus the read-only project context.

package/LICENSE

@@ -0,0 +1,174 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do not
+          modify the License. You may add Your own attribution notices
+          within Derivative Works, alongside or as an addendum to the NOTICE
+          text from the Work, provided that such additional attribution
+          notices cannot be construed as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or for
+      any such Derivative Works as a whole, provided Your use, reproduction,
+      and distribution of the Work otherwise complies with the conditions
+      stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer, and
+      charge a fee for, acceptance of support, warranty, indemnity, or
+      other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,89 @@
+# Deliberate
+
+Deliberate is a files-first toolkit for creating reviewable Markdown records in the current repository. The CLI builds prompts, validates role configuration, and persists artifacts; the host coding agent performs the reasoning.
+
+## Install and run
+
+Node.js 22.5 or newer is required.
+
+```bash
+npx deliberate-cli install
+```
+
+Use `/deliberate` in a compatible coding-agent harness. A typical first journey establishes the product and market baseline before creating a Case:
+
+```text
+/deliberate init
+/deliberate brief
+
+# Turn a grounded opportunity from the Brief into a Case.
+/deliberate case "Opportunity surfaced by the landscape brief"
+
+# Review the decision, then make it tangible and monitor product health.
+/deliberate case prototype
+/deliberate readout
+```
+
+Run `deliberate serve --open` to review the generated Markdown, inspect diffs, and leave anchored comments in Sonorance. Project-required commands operate only in an initialized current working directory.
+
+## Commands
+
+```text
+deliberate help [--skill]
+deliberate init
+deliberate serve [--open] [--port <n>]
+deliberate install [--here|--project <dir>]
+deliberate case "<idea>"
+deliberate case list
+deliberate case analysis prompt|save [id] [--file <path> | --note <text>]
+deliberate case score prompt [id]
+deliberate case score save [id] --model <id> [--independent] [--file <path>]
+deliberate case one-pager prompt|save [id] [--file <path>]
+deliberate case prototype prompt|save|list [id] [--surface <slug>] [--file <path>]
+deliberate brief prompt|save|list
+deliberate readout prompt|save|list
+deliberate readout chart --spec <json> --output <svg>
+deliberate matchup prompt|save|list [competitor]
+deliberate source [list | add <location> ["<description>"] [--section <section>] | remove <location>]
+deliberate feedback ["<message>"] [--category <category>] [--rating <rating>] [--file <json>]
+deliberate comment list
+deliberate comment <commentId> resolve [--note "<text>"] [--revised]
+```
+
+Run `deliberate help --skill` for generated, current command guidance.
+
+## Files
+
+```text
+.sonorance/
+  config.json
+  plugins.json
+  sources.md
+  local/
+deliberate/
+  context/
+    product.md
+    competitors.md
+    ecosystem.md
+  cases/<YYYY-MM-DD-slug>/
+    analysis.md
+    score.md
+    one-pager.md
+    prototype/[<surface>/]index.html
+    log.jsonl
+  briefs/<YYYY-MM-DD>/brief.md
+  readouts/<YYYY-MM-DD[-N]>/
+    readout.md
+    charts/<metric>.svg
+  matchups/<competitor-slug>/matchup.md
+```
+
+## Repository map
+
+```text
+src/engine/   prompt builders, persistence, role configuration, and commands
+src/cli/      the deliberate binary
+roles/        generic instructions, templates, and methods
+skill/        the shipped /deliberate skill and launcher
+test/         offline engine, CLI, contract, and skill tests
+```

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "deliberate-cli",
+  "version": "0.2.0-beta.1.1",
+  "type": "module",
+  "description": "Deliberate — a files-first product toolkit for coding agents that creates grounded, reviewable Markdown cases, briefs, readouts, matchups, and prototypes.",
+  "author": {
+    "name": "Deliberate"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sonorance/deliberate.git"
+  },
+  "homepage": "https://deliberate.md",
+  "bugs": {
+    "url": "https://github.com/Sonorance/deliberate/issues"
+  },
+  "bin": {
+    "deliberate-cli": "src/cli/deliberate.mjs",
+    "deliberate": "src/cli/deliberate.mjs",
+    "dlb": "src/cli/deliberate.mjs"
+  },
+  "scripts": {
+    "deliberate": "node src/cli/deliberate.mjs",
+    "app": "node src/cli/deliberate.mjs serve --open",
+    "test": "node --test --test-force-exit --import ./test-setup.mjs"
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "dependencies": {
+    "sonorance": "^0.1.0",
+    "vega": "^6.2.0",
+    "vega-lite": "^6.4.3"
+  },
+  "files": [
+    "src/engine",
+    "src/cli",
+    "roles",
+    "skill",
+    "AGENTS.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "js-yaml": "^4.1.0"
+  }
+}

package/roles/analyst/frame/instructions.md

@@ -0,0 +1,88 @@
+---
+agent: frame
+role: Analyst pass 1 — frames the case into a solution-free problem (personas + jobs-to-be-done) and the competitive landscape for the specific change it proposes.
+---
+# Agent — Frame
+
+You are the **Analyst**, on your **first pass**. In one coherent artifact you (a) turn the case into a
+crisp, **solution-free problem definition** grounded in who the product actually serves, and (b) judge
+whether today's alternatives already offer **exactly the change this case proposes**. This is the
+problem-space groundwork the Evaluator will score next — so be honest and evidence-led, and **do not
+design a solution yet** (that's the `shape` stage).
+
+## Inputs
+- The **case** — the incoming problem, especially the `## Case` section. It is the subject of your
+  analysis; keep it central to every persona, job, and competitor row.
+- The **attached project sources** (the read-only repo, code, docs) and the auto-derived **project
+  context** (personas, jobs-to-be-done, interfaces, strategy, competitors) — your evidence base for who
+  the product serves and what the alternatives are.
+- **`jtbd`** (the method you must apply).
+
+## Task
+
+### Part A — the problem
+**Infer the key personas and their jobs-to-be-done from the evidence** (the sources + the content of the
+case) — ground each; never invent a persona or job the material doesn't support. Turn the case into a
+crisp, **solution-free problem definition**: who is struggling, the jobs they're trying to get done, and
+the outcomes they want. Use `jtbd` — group jobs under their persona and phrase each as a job ("I want to
+_[job]_, so I can _[outcome]_"), with the persona line carrying the *who* and situation. Keep it tight:
+concise personas with their key jobs, not an exhaustive JTBD workup.
+
+Then include any **additional key personas / jobs materially affected** — secondary or adjacent users who
+feel the ripple effects (an admin, an approver, a downstream consumer, a teammate) — grounded the same
+way, with a note of *how* the problem touches them. Only those whose jobs are genuinely impacted.
+
+### Part A.5 — validate the problem
+**Show the problems above are real, not assumed.** In **~3 concise bullets (5 max)**, back the pain with
+evidence — **quantitative** (telemetry, usage data, survey results) or **qualitative** (verbatim field /
+sales / customer / partner quotes, each **attributed to the real person or company by name**). Every figure
+and quote must be real and traceable to the attached sources or the project context — **never invent a
+number, a quote, a company, or a source.** Where a problem has no real supporting evidence, say so plainly
+(mark it an assumption) rather than fabricating one.
+
+### Part B — the competitive landscape
+For each competing solution a customer could reach for **to get this specific change done — as Part A
+frames it** — answer precisely: **does it offer what the case proposes, and how?**, then its honest
+strengths and weaknesses, **scoped to this change only**.
+
+1. **Choose the competing solutions that matter for THIS change** — the real, named products a user could
+   actually use *instead*; **at most five, ideally fewer**. Assume the reader already knows them — don't
+   describe or pre-list them. **No "status quo / do nothing" row.** Never map broad product categories.
+2. **Analyze them in one single table** (not per persona, not per job). Each row: does it offer what the
+   case proposes **as Part A frames it** (yes / partly / no), **how**, then strengths and weaknesses —
+   **assessing only the scope of this case's change**, never unrelated capabilities or the product's
+   overall positioning.
+3. **Differentiation — crisp.** The defensible gap **on this specific change** in **one strong bullet
+   (two at most)**. If there is no real differentiation — it's **table-stakes** everyone already offers —
+   **say so explicitly**; that is a fine, honest answer.
+
+## Output
+Fill in your stage's **output template** (`roles/analyst/frame/output-template.md`), provided at runtime: the
+**Problem** section (personas + jobs), the **Validation** section (real quant / qual evidence), and the
+**Competitive landscape** (one Analysis table + Differentiation). Keep it tight and scoped strictly to the
+case's change.
+
+- **Keep persona descriptions short** — a phrase or a single crisp sentence; no biography or demographics
+  padding. The jobs carry the substance.
+- **Grounding is internal, not a deliverable.** Do the grounding discipline in your reasoning, but **do
+  not emit a "Grounding", "Sources", "Assumptions", or "Notes" section** — the **Validation** section is
+  the one place real evidence belongs; everywhere else, surface an
+  assumption only inline, in the one place it matters, if a claim genuinely rests on one.
+
+Produce the full version now, following every heading of the template.
+
+## Grounding rules
+- Every claim traces to the case or the attached sources — or is labelled an assumption **inline** (never
+  a separate notes/grounding section). **Never invent personas, jobs, competitors, features, or pricing.**
+- **Validation must be real.** Quantitative figures cite their source; qualitative quotes are verbatim and
+  attributed to the real person / company by name. **Never fabricate a quote, a number, a company, or a
+  source** — an honest "no direct evidence yet" beats an invented one.
+- Each job must be **solution-free** and phrased as a job (not a feature request), tied to a concrete
+  persona. **Do not propose a solution — that's `shape`. Stay on the problem.**
+- Stay anchored to what **this case** actually proposes; assess each alternative only on *that* change —
+  not the whole product, not unrelated capabilities.
+- Use **real, named products** as rows (at most five, ideally fewer, only those genuinely relevant); the
+  reader already knows them, so don't describe them. **No status-quo / do-nothing row. One single
+  Analysis table** — never per persona or per job.
+- Don't score go/no-go — that's the Evaluator (`score`). Don't drift into solutioning or channels —
+  that's `shape`.

package/roles/analyst/frame/output-template.md

@@ -0,0 +1,52 @@
+# Frame
+
+## Problem
+
+_Who is struggling and the jobs they're trying to get done — solution-free. One block per distinct
+persona; keep persona lines short._
+
+### _Persona 1_
+
+_Who they are and their situation, in a short phrase or one crisp sentence — no biography._
+
+* I want to _[job to be done]_, so I can _[outcome]_.
+* I want to _[job to be done]_, so I can _[outcome]_.
+
+_(Repeat the persona block for each distinct persona, including any adjacent persona materially affected —
+noting how the problem touches them. No grounding, evidence, sources, or assumptions block.)_
+
+## Validation
+
+_Evidence that the problems above are **real**, not assumed — **quantitative** (telemetry, usage data,
+survey results) or **qualitative** (verbatim field / sales / customer / partner quotes, each attributed to
+the real person or company by name). **~3 concise bullets, 5 max.** Every figure and quote must be real and
+traceable to the sources — **never invent a number, quote, company, or source**. If a problem can't be
+grounded in real evidence, say so plainly (e.g. "no direct evidence yet — assumption") rather than
+fabricating one._
+
+* _a quantitative signal with its source (e.g. "38% of onboarding sessions drop at step 3 — product telemetry, Q2"), **or** a real attributed quote (e.g. "'We rebuild this by hand every release.' — Platform lead, Acme Corp") — grounded, never invented._
+
+## Competitive landscape
+
+_Whether today's alternatives already offer **what this case proposes — exactly as the Problem above
+frames it** — and where the product can credibly differentiate on that specific change._
+
+### Analysis
+
+_A single table with **at most five rows (ideally fewer)** — the real, named products genuinely relevant
+to **this specific change**. For each: does it offer what the case proposes, the way the Problem frames
+it? How? Then its strengths and weaknesses — scoped to this change only, not the whole product. Assume
+the reader already knows these products; don't describe them. No status-quo / do-nothing row._
+
+| Competitor | Offers what the case proposes, as framed? | How | Strengths | Weaknesses / limitations |
+|---|---|---|---|---|
+| _…_ | _yes / partly / no_ | _…_ | _…_ | _…_ |
+
+### Differentiation
+
+_The defensible gap on **this specific change** in **one strong bullet — two at most**. If there is no
+real differentiation because it's **table-stakes** everyone already offers, **say so explicitly** — that
+is a fine, honest answer._
+
+* _the single defensible gap on this change — or "No differentiation: this is table-stakes; the
+  alternatives already offer it."_

package/roles/analyst/launch/instructions.md

@@ -0,0 +1,63 @@
+---
+agent: launch
+role: Analyst pass 3 — plans how the shaped concept reaches its first users, ships in phases, and compounds (positioning, first users, phased launch, growth, telemetry-grounded metrics).
+---
+# Agent — Launch
+
+You are the **Analyst**, on your **third pass** — after you've shaped the concept and its journeys. Design
+**how this concept reaches its first users, launches in phases, earns their trust, and compounds** —
+grounded only in the concept you designed in `## shape` and the problem + competitive landscape in
+`## frame`. **You do not re-judge whether the case should advance** — the Evaluator already scored it.
+
+## Inputs
+- The accumulated context — **anchor on the `## shape` concept + user journeys** and the `## frame`
+  personas, jobs-to-be-done, and competitive landscape. Respect the `## score` read.
+- `jtbd`, **`win-conditions`**. The product's strategy, surface, and **non-goals** come from the project
+  context.
+
+## Task
+Keep it as plain and tight as the Frame and Shape — five short parts:
+
+1. **Pitch.** The sharp value proposition — who it's for, the problem, the payoff. (Timing / "why now" is
+   **not** here — the Evaluator owns it in `## score`; don't restate it.)
+2. **First users.** Two lines plus a follow-on: **Who** — the single, specific first customer to win (name
+   the persona) in one sentence; **Why** — their acute pain and why they're reachable / reference-able, in
+   one sentence; **Who comes next** — one sentence on whether this broadens the product's current audience
+   (and how), or, if not meaningfully, say so plainly.
+3. **Launch plan.** Sequence the shaped concept into phases — **each grounded in a persona + job and the
+   hero journey from `## shape`** (invent no new capabilities; only phase what the concept already implies):
+   - **Phase 1 — Hero MVP:** the core shape plus the minimum capabilities that carry the **hero user
+     journey** end-to-end for the first user — enough to **validate the customer need and ship fast**. Say
+     what's in and the exact need it validates.
+   - **Phase 2 — Fast follow:** the next **necessary** capabilities that complete the experience and cover
+     the adjacent scenarios these users hit — what makes the product whole, not merely viable.
+   - **Phase 3+ — Later:** the **non-necessities** — breadth, nice-to-haves, and polish deferred until the
+     core need is validated.
+4. **Growth.** Considering **only the functionality this case and the concept deliver** (invent no
+   new capabilities): can it strengthen a **product-led** loop — network effects, virality, referrals,
+   content, agent-of-mouth? If no/unlikely, say so in one sentence and stop. If yes, name the single most
+   likely loop: **What** — the loop and how *this feature* drives it; **How** — how to leverage it.
+5. **Key metrics.** Every metric must be **derivable from the telemetry of the capabilities the concept
+   designed** — never an abstract win-condition.
+   - **North Star:** one metric, from the shipped feature's telemetry, that measures this case's success.
+   - **Guardrail:** one telemetry guardrail against over-optimizing the North Star.
+   - **Early signals:** at most **two** leading / proxy telemetry metrics that project where the North Star
+     is heading, each with a scale-vs-pull-back read.
+
+## Output
+Fill in your stage's **output template** (`roles/analyst/launch/output-template.md`), provided at runtime —
+every section, grounded, concise. Prefer **compounding loops** and trust over one-shot reach.
+
+Produce the full version now, following every heading of the template.
+
+## Grounding rules
+- **Build only on the shaped concept — invent no new capabilities.** Scope the launch phases and the
+  growth-loop section to only what the case and concept deliver; phasing is about **sequencing** that scope,
+  not adding to it.
+- **Every phase traces to a persona + job and the hero journey** — Phase 1 is whatever carries that hero
+  journey and validates the need; later phases are ordered by necessity, not wishlist.
+- **Do not mention win-conditions or any internal framework in the output.**
+- Name **real, reachable** segments and channels — cite why that segment is present. Unsupported channel =
+  drop it. **Every metric must be readable from the telemetry of the capabilities the concept designs** —
+  not an abstract win-condition.
+- Every claim traces to the context or is labelled an assumption inline (no separate notes section).

package/roles/analyst/launch/output-template.md

@@ -0,0 +1,50 @@
+# Launch
+
+## Pitch
+
+* **Value proposition:** _one sharp line — who it's for, the problem, the payoff._
+
+## First users
+
+* **Who:** _the single, specific first customer to win (name the persona) — one concise sentence._
+* **Why:** _their acute pain and why they're reachable / reference-able — one concise sentence._
+* **Who comes next:** _one concise sentence — does this broaden the product's current audience (and how),
+  or, if not meaningfully, say so plainly._
+
+## Launch plan
+
+_Sequence the shaped concept into phases — each grounded in a persona + job and the hero journey from
+`## shape` (invent no new capabilities; phase only what the concept already implies)._
+
+* **Phase 1 — Hero MVP:** _the core shape + the minimum capabilities that carry the hero user journey
+  end-to-end for the first user — enough to validate the customer need and ship fast. What's in, and the
+  exact need it validates._
+* **Phase 2 — Fast follow:** _the next necessary capabilities that complete the experience and cover the
+  adjacent scenarios these users hit — what makes it whole, not merely viable._
+* **Phase 3+ — Later:** _the non-necessities — breadth, nice-to-haves, and polish deferred until the core
+  need is validated._
+
+## Growth
+
+_Using **only the functionality this case and the concept deliver** (invent no new capabilities): can it
+strengthen a **product-led** growth loop? If no/unlikely, say so in one sentence. If yes, name the single
+most likely one:_
+
+* **What:** _the loop and how *this feature* drives it._
+* **How:** _how to leverage it for growth._
+
+## Key metrics
+
+_All derived from the **telemetry of the capabilities the concept designs** — not abstract
+win-conditions. If a growth loop was specified, tie these to it._
+
+* **North Star:** _one key metric that best measures the success of this case after release, readable
+  from the shipped feature's telemetry._
+* **Guardrail:** _one telemetry guardrail against over-optimizing the North Star._
+
+**Early signals** — at most **two** leading / proxy telemetry metrics that project where the North Star
+is heading:
+
+| Signal (leading indicator of the North Star) | Scale if… | Pull back if… |
+| --- | --- | --- |
+| _…_ | _…_ | _…_ |