althing 1.7.0__py3-none-any.whl

althing/agent_assets/__init__.py

@@ -0,0 +1,3 @@
+"""Bundled Claude Code slash commands and skills shipped with althing."""
+
+from __future__ import annotations

althing/agent_assets/commands/althing-poll.md

@@ -0,0 +1,75 @@
+---
+description: Run a one-question synthetic poll across AI personas and synthesize the themes
+allowed-tools:
+  - mcp__althing__run_quick_poll
+  - mcp__althing__list_persona_packs
+  - mcp__althing__get_persona_pack
+argument-hint: <question to ask the panel>
+---
+
+Run a quick synthetic poll using the Althing MCP server. One question, a
+handful of AI personas, one synthesized writeup.
+
+Question: $ARGUMENTS
+
+## What to do
+
+1. **Resolve the question.** If `$ARGUMENTS` is empty, ask the user for the
+   question before continuing. Do not invent one.
+
+2. **Pick personas.** Default to the built-in zero-config persona set by
+   omitting the `personas` argument. Only build a custom list when the user
+   names a specific audience (e.g. "three enterprise SRE personas"). In that
+   case, either:
+   - Call `mcp__althing__list_persona_packs` and `get_persona_pack` to
+     pull an installed pack, or
+   - Hand-author 3–5 dicts with `name`, `age`, `occupation`, `background`,
+     and `personality_traits`.
+
+   Keep panels small — `run_quick_poll` caps at 3 personas when running in
+   sampling mode (no API key).
+
+3. **Run the poll.** Call `mcp__althing__run_quick_poll` with:
+   - `question`: the user's question
+   - `personas`: omit for the default set, or pass your custom list
+   - `synthesis`: leave as `true` (default) — the synthesis pass is the
+     point of this command
+
+   Do not pass `model` unless the user explicitly asked for a specific one.
+   The MCP server picks a sensible default (haiku in BYOK mode, or the
+   host's own model in sampling mode).
+
+4. **Report the result.** Present the output in this shape:
+
+   ```
+   Question: <the question>
+   Panel: <n> personas (<mode: BYOK model-name | sampling>)
+
+   ## Themes
+   <bulleted list from the synthesis>
+
+   ## Per-persona responses
+   - <persona name>: <one-line summary of their response>
+   - ...
+
+   ## Notable divergences
+   <any disagreements the synthesis flagged>
+
+   Cost: <$X.XX from the response's `cost` field, or "n/a" in sampling mode>
+   ```
+
+   Keep each persona summary to one line. The full transcripts are in the
+   raw tool output — don't re-print them.
+
+## Guardrails
+
+- **Synthetic panels are exploratory, not validating.** End the report with
+  a single-line caveat: "Synthetic panel — directional signal only, not a
+  substitute for real user research."
+- **Don't loop.** If the user wants a second question, that's another
+  `/althing-poll` invocation, not a follow-up inside this one. For
+  multi-question structured studies, suggest the `/focus-group` skill
+  instead.
+- **Report errors honestly.** If the tool returns an `error` field
+  (missing API key, persona cap exceeded, etc.), show it verbatim and
+  suggest the fix — don't silently fall back.

althing/agent_assets/skills/concept-test/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: concept-test
+description: Validate a product concept or value proposition with a target audience — surfaces whether the problem is real, whether the solution lands, and what would prevent adoption.
+allowed-tools:
+  - mcp__althing__run_panel
+  - mcp__althing__run_quick_poll
+  - mcp__althing__list_persona_packs
+  - mcp__althing__get_persona_pack
+  - mcp__althing__save_persona_pack
+  - mcp__althing__list_instrument_packs
+---
+
+You are running a **concept test** using the althing MCP tools.
+
+## What You Do
+
+You help the user pressure-test an early-stage product concept, value prop, or feature idea against a specific target audience before they build or ship it. The goal is to surface whether the problem is real and whether the proposed solution actually addresses it — not to validate a decision that's already been made.
+
+1. **Clarify the concept and the audience.**
+2. **Design concept-oriented personas** drawn from (or biased toward) the target audience.
+3. **Run the panel** with questions that probe pain, fit, willingness-to-adopt, and objections.
+4. **Synthesize** — is the problem real, does the concept resonate, and what blocks adoption?
+
+## Available MCP Tools
+
+- **`mcp__althing__run_panel`** — Primary tool. Run a multi-question panel with target-audience personas.
+- **`mcp__althing__run_quick_poll`** — Use for a single "would you try this?" temperature check.
+- **`mcp__althing__list_persona_packs`** / **`mcp__althing__get_persona_pack`** — Reuse saved target-audience packs.
+- **`mcp__althing__save_persona_pack`** — Save a new audience pack if the user is likely to re-test.
+- **`mcp__althing__list_instrument_packs`** — Check for bundled packs that fit (e.g. `product-feedback`, `market-research`).
+
+## Workflow
+
+### Step 1: Frame the Concept
+
+Ask the user for:
+- A 2-3 sentence description of the concept (what it is, who it's for, what problem it solves).
+- The target audience (role, demographic, or psychographic).
+- What decision this test is meant to inform ("should we keep exploring?" vs. "which direction?").
+
+### Step 2: Build or Load Personas
+
+- 4-8 personas, biased toward the target audience but with **at least one skeptic** and **at least one adjacent non-target** to stress-test the boundaries.
+- Each persona should have a plausible reason the problem may or may not apply to them.
+
+### Step 3: Design the Instrument
+
+Include questions in this order:
+1. **Problem probe** — "Does this describe something you've actually experienced?" (don't lead with the solution)
+2. **Concept reveal** — present the concept, ask for gut reaction.
+3. **Fit** — "Who do you know this would be for?" (reveals whether they see themselves in it)
+4. **Adoption blockers** — "What would stop you from trying this?"
+5. **Willingness** — rough price sensitivity or alternative-they'd-pick.
+
+Add 1-2 follow-ups on the concept reveal for depth.
+
+### Step 4: Run and Synthesize
+
+After results return, report:
+- **Problem validity** — did panelists actually experience the problem, or did you have to convince them?
+- **Concept resonance** — who lit up, who shrugged, who pushed back.
+- **Top 2-3 adoption blockers** across panelists.
+- **Surprising insights** — anything you didn't expect.
+- **Recommended next step** — iterate the concept, test with real users, or drop it.
+- **Total cost**.
+
+## Guidelines
+
+- **Don't sell the concept to the panel.** Describe it neutrally. Leading questions produce leading answers.
+- **Respect dissent.** If 2 of 6 panelists hate it, that's signal — don't average it away.
+- **Distinguish "I'd use this" from "This is a good idea."** Only the first predicts adoption.
+- **Concept tests are exploration, not validation.** Say so when the user asks "should we build this?" — the honest answer is "this is one data point; go talk to real users."

althing/agent_assets/skills/focus-group/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: focus-group
+description: Run a synthetic focus group — define personas, craft questions, and collect structured qualitative feedback from AI panelists.
+allowed-tools:
+  - mcp__althing__run_prompt
+  - mcp__althing__run_panel
+  - mcp__althing__list_persona_packs
+  - mcp__althing__list_instrument_packs
+---
+
+You are orchestrating a **synthetic focus group** using the althing MCP tools.
+
+## What You Do
+
+You help the user design and run synthetic focus groups — structured qualitative research using AI-powered personas. You handle the full workflow:
+
+1. **Understand the research question** — What does the user want to learn?
+2. **Define personas** — Assemble a list of realistic, diverse participants.
+3. **Design the instrument** — Write targeted questions and follow-ups.
+4. **Run the panel** — Execute the focus group via MCP tools.
+5. **Synthesize results** — Summarize findings, identify patterns, and highlight insights.
+
+## Available MCP Tools
+
+- **`mcp__althing__run_prompt`** — Send a single prompt to an LLM (no personas). Use for a quick smoke test before building a panel.
+- **`mcp__althing__run_panel`** — Run a full panel: pass `personas` (an inline list of persona dicts) plus one question source — inline `questions`, an inline `instrument` dict, or an `instrument_pack` name.
+- **`mcp__althing__list_persona_packs`** — List saved persona packs you can reuse via `run_panel`'s `pack_id`.
+- **`mcp__althing__list_instrument_packs`** — List installed instrument packs you can reference via `run_panel`'s `instrument_pack`.
+
+> These MCP tools take **inline data or pack names, not file paths.** Personas are a JSON list; instruments are an inline dict or an installed pack name. There is no "load this YAML path" argument — read any file yourself and pass its contents inline.
+
+## Workflow
+
+### Step 1: Clarify the Research Goal
+
+Ask the user what they want to test. Examples:
+- "What do people think of the name 'Traitprint' for a career app?"
+- "How would different demographics react to this pricing page?"
+- "Pre-screen this survey before we send it to real participants."
+
+### Step 2: Assemble Personas
+
+Build a list of 3-6 diverse personas. Each persona is a dict with:
+- `name` (required), `age`, `occupation`
+- `background` — 2-3 sentences of life context
+- `personality_traits` — 3-5 traits that shape their perspective
+
+Ensure demographic and psychographic diversity relevant to the research question. Pass the list inline as `run_panel`'s `personas` argument, or reuse a saved pack by `pack_id` (discover names via `list_persona_packs`).
+
+### Step 3: Design the Instrument
+
+Write 2-5 focused questions. Each question can have:
+- `text` — The question itself
+- `response_schema` — Usually `{type: text}`
+- `follow_ups` — Probing questions for depth
+
+Pass them inline as `run_panel`'s `questions` list (single round) or as an `instrument` dict (for v2/v3 multi-round). To use a bundled pack, pass its name as `instrument_pack` (discover names via `list_instrument_packs`).
+
+### Step 4: Run the Panel
+
+Call `mcp__althing__run_panel` with the `personas` list and one question source (`questions`, `instrument`, or `instrument_pack`).
+
+### Step 5: Synthesize
+
+After results return:
+- Summarize each persona's perspective in 1-2 sentences
+- Identify consensus vs. divergence across personas
+- Flag surprising or non-obvious insights
+- Recommend next steps (iterate instrument, test with real users, etc.)
+
+## Guidelines
+
+- **Don't over-engineer personas** — 3-5 well-chosen personas beat 10 generic ones.
+- **Ask pointed questions** — Vague questions get vague answers.
+- **Use follow-ups** — They surface depth that initial responses miss.
+- **Report costs** — Always mention the total cost of the panel run (surfaced as `total_cost`).
+- **Be honest about limitations** — Synthetic panels are for exploration, not validation.

althing/agent_assets/skills/name-test/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: name-test
+description: Quickly test 1-3 candidate product or feature names with a synthetic panel — surfaces confusion, pronounceability, and memorability concerns in one pass.
+allowed-tools:
+  - mcp__althing__run_quick_poll
+  - mcp__althing__run_panel
+  - mcp__althing__list_persona_packs
+  - mcp__althing__get_persona_pack
+  - mcp__althing__list_instrument_packs
+  - mcp__althing__get_instrument_pack
+---
+
+You are running a **quick name test** using the althing MCP tools.
+
+## What You Do
+
+You help the user decide between candidate names for a product, feature, or brand. The workflow is deliberately short — a name test should take minutes, not hours.
+
+1. **Collect candidates** — 1 to 3 names, plus a one-line description of what the thing actually is.
+2. **Pick a lens** — quick single-question poll, or the branching `name-test` instrument pack for deeper probing.
+3. **Run the panel** — small, diverse personas; keep it cheap.
+4. **Report the verdict** — winner, loser, and the specific concern that tipped each (confusion, pronunciation, memorability).
+
+## Available MCP Tools
+
+- **`mcp__althing__run_quick_poll`** — Single-question poll across personas (fastest, cheapest).
+- **`mcp__althing__run_panel`** — Full panel run using the bundled `name-test` branching instrument that probes meaning, pronounceability, or memorability based on first reactions. Its opening question has a `{candidates}` placeholder; fill it with the `vars` argument (see Step 2).
+- **`mcp__althing__list_persona_packs`** / **`mcp__althing__get_persona_pack`** — Reuse saved personas instead of inventing new ones.
+- **`mcp__althing__list_instrument_packs`** — Confirm the `name-test` pack is available.
+
+## Workflow
+
+### Step 1: Gather Inputs
+
+Ask for:
+- The candidate names (comma-separated).
+- A one-sentence description of what the product/feature does.
+- Target audience (so personas are relevant).
+
+### Step 2: Choose Depth
+
+- **Quick gut check** → `run_quick_poll` with a question that has the description and candidate names written directly into the `question` string, e.g. *"Which of these names best fits a budget travel app — Wander, Roamly, Tr9? Why?"*
+- **Full branching evaluation** → `run_panel` with `instrument_pack="name-test"` and `vars={"candidates": "Name A, Name B"}` — the comma-separated candidate names are substituted into the opening question's `{candidates}` placeholder before the panel runs. (CLI equivalent: `althing panel run --instrument name-test --var 'candidates=Name A, Name B'`.) If you omit `vars`, the call fails fast with a typed `INVALID_TOOL_ARG` error naming the missing placeholder. The instrument branches into meaning-probe, pronounce-probe, or memorability-probe based on what surfaces first.
+
+### Step 3: Run
+
+Default to 4-6 personas. If the user hasn't supplied them, generate a small diverse set tuned to the target audience, or pick a saved pack via `get_persona_pack`.
+
+### Step 4: Report
+
+Produce a tight summary:
+- **Winner** and why (quote 1-2 panelists).
+- **Loser** and the specific failure mode (misread, hard to say, forgettable).
+- **Risks for the winner** — concerns that still showed up even for the preferred name.
+- **Total cost** of the run.
+
+## Guidelines
+
+- Keep it small — 4-6 personas is plenty for a name test.
+- Don't over-interpret a single panel — flag when reactions were genuinely mixed rather than forcing a winner.
+- If all names scored poorly, say so and suggest the user brainstorm a new set instead of picking the least-bad.
+- Name tests are exploratory signal, not validation. Say this when the user asks "should we ship this?"

althing/agent_assets/skills/pricing-probe/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: pricing-probe
+description: Probe pricing sensitivity with a target audience using the bundled 'pricing-discovery' branching instrument — surfaces pain, price anchoring, or competitor alternatives based on what the panel volunteers first.
+allowed-tools:
+  - mcp__althing__run_panel
+  - mcp__althing__get_instrument_pack
+  - mcp__althing__list_instrument_packs
+  - mcp__althing__list_persona_packs
+  - mcp__althing__get_persona_pack
+  - mcp__althing__run_quick_poll
+---
+
+You are running a **pricing sensitivity probe** using the althing MCP tools and the bundled `pricing-discovery` v3 branching instrument.
+
+## What You Do
+
+You help the user understand how a target audience reasons about price for a product or service. The `pricing-discovery` instrument is adaptive: it lets each panelist's discovery round drive the probe path — into pain, pricing, or alternatives — so you get signal on whichever dimension actually matters to them.
+
+1. **Frame the problem** — what are we pricing, for whom, and against what alternatives?
+2. **Assemble a target-audience panel.**
+3. **Run the `pricing-discovery` pack** via `run_panel` — with the `{problem}` placeholder filled in via `vars` (see below).
+4. **Interpret the branch** — the panel that routed through `probe_pain` is telling you something different than one that routed through `probe_pricing` or `probe_alternatives`.
+
+## Available MCP Tools
+
+- **`mcp__althing__run_panel`** — Primary tool. The `pricing-discovery` instrument's opening question contains a `{problem}` placeholder. Fill it with the `vars` argument: pass `instrument_pack="pricing-discovery"` together with `vars={"problem": "..."}`. (CLI equivalent: `althing panel run --instrument pricing-discovery --var problem='...'`.) If you omit `vars`, the call fails fast with a typed `INVALID_TOOL_ARG` error naming the missing placeholder — it never sends literal `{problem}` to panelists.
+- **`mcp__althing__get_instrument_pack`** / **`mcp__althing__list_instrument_packs`** — Inspect the bundled pricing-discovery pack (e.g. to see which placeholders it declares).
+- **`mcp__althing__list_persona_packs`** / **`mcp__althing__get_persona_pack`** — Load a saved target-audience pack.
+- **`mcp__althing__run_quick_poll`** — Use for a narrow follow-up question after the main run (e.g. "Would $X/month feel fair?").
+
+## Workflow
+
+### Step 1: Clarify the Pricing Context
+
+Ask:
+- **What problem does the product solve?** (The `pricing-discovery` instrument substitutes this into its opening question.)
+- **Who is it for?** (shapes personas)
+- **Are there competitors or alternatives?** (panelists will volunteer these if real)
+- **What price range is the user considering?** (optional — don't reveal it to the panel until after discovery)
+
+### Step 2: Build or Load the Panel
+
+- 5-8 personas matching the target audience.
+- Include **at least one price-sensitive** persona and **one value-driven** persona — pricing intuition varies more across that axis than demographics.
+- Pull saved packs via `get_persona_pack` when re-running against the same audience.
+
+### Step 3: Run the Instrument
+
+Call `run_panel` with:
+- the persona set (inline `personas`, or a saved pack via `pack_id`)
+- `instrument_pack="pricing-discovery"`
+- `vars={"problem": "<the user's problem statement>"}` — `run_panel` substitutes it into the instrument's `{problem}` placeholder before any panelist sees the question
+
+Note: the instrument branches via theme tags (`pain`, `price`, `alternative`). Routing is **panel-level** — the router makes one decision per round for the whole panel based on the round's aggregate synthesis themes, not one decision per panelist. The executed route lives in the result's top-level `path` (a list of `{round, branch, next}` entries) and `terminal_round` — inspect these; they are the primary signal.
+
+### Step 4: Interpret the Branch
+
+Report, for the panel:
+- **Which branch did the panel take?** (pain / price / alternatives / else)
+- That branch *is* the insight: a panel that routed to `probe_alternatives` is telling you price is benchmarked against an incumbent, not derived from value.
+
+Then overall:
+- **Where the route landed** — if the panel went to `probe_alternatives`, your pricing problem is really a positioning problem.
+- **Price anchors** that surfaced organically (vs. ones you asked about).
+- **Willingness-to-pay range** — cluster the numbers panelists volunteered.
+- **Deal-breakers** — what would stop them from paying anything.
+- **Suggested price test** — one specific follow-up (e.g. a `run_quick_poll` at a target price point).
+- **Total cost**.
+
+## Guidelines
+
+- **Don't anchor the panel with your target price** until after discovery — price sensitivity is contaminated by any number you drop first.
+- **Trust the branch.** The router is how this instrument earns its keep; interpreting which branch fired (panel-level, once per round) matters more than individual answers.
+- **Synthetic WTP is directional, not predictive.** Real people are stingier than personas. Discount synthetic price points before fielding.
+- **Watch for `else` fall-through.** If the panel bypasses the routed branches and lands on `else`, the synthesizer isn't emitting the canonical theme tags — say so and suggest re-running or editing the instrument's theme-tag guidance.

althing/agent_assets/skills/survey-prescreen/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: survey-prescreen
+description: Pre-screen a survey instrument with synthetic respondents before sending to real participants — catches ambiguous wording, leading questions, and dead-end branches cheaply.
+allowed-tools:
+  - mcp__althing__run_panel
+  - mcp__althing__get_instrument_pack
+  - mcp__althing__list_instrument_packs
+  - mcp__althing__save_instrument_pack
+  - mcp__althing__list_persona_packs
+  - mcp__althing__get_persona_pack
+---
+
+You are pre-screening a **user-authored survey instrument** using the althing MCP tools.
+
+## What You Do
+
+You help the user catch problems in a survey before they spend real budget fielding it. Synthetic respondents are cheap — use them to find ambiguous wording, leading questions, unanswerable items, and dead-end branches *before* real participants see the instrument.
+
+1. **Load the user's instrument** (YAML file they provide, or `save_instrument_pack` first if it's inline).
+2. **Assemble stress-test personas** — a mix that should reveal wording problems across demographics.
+3. **Run the instrument** as a full panel.
+4. **Critique** — report specific failure modes per question, not just a thumbs up/down.
+
+## Available MCP Tools
+
+- **`mcp__althing__run_panel`** — Run the user's instrument against the stress-test personas. Pass either `instrument` (inline YAML dict) or `instrument_pack` (name, after saving).
+- **`mcp__althing__get_instrument_pack`** / **`mcp__althing__list_instrument_packs`** — Load an installed instrument for review.
+- **`mcp__althing__save_instrument_pack`** — Save the user's instrument temporarily if they'd rather reference it by name.
+- **`mcp__althing__list_persona_packs`** / **`mcp__althing__get_persona_pack`** — Load a realistic audience pack for the survey's intended population.
+
+## Workflow
+
+### Step 1: Load the Instrument
+
+Read the user's YAML. Before running, do a quick structural review:
+- Are questions clear and scoped to one thing each?
+- Any double-barreled questions ("How satisfied and how often do you...")?
+- Any leading wording ("How much do you *love*...")?
+- For v3 instruments: do `route_when` branches cover plausible respondent paths, or do cases silently fall to `else`?
+- Are follow-ups specific enough to produce depth?
+
+Call out structural issues first — sometimes the instrument doesn't need a panel run at all, just a rewrite.
+
+### Step 2: Assemble Stress-Test Personas
+
+5-8 personas that specifically stress the instrument:
+- **Representative of the intended audience** (2-3).
+- **Adjacent-but-different** — slightly outside the target, to reveal questions that assume audience knowledge (1-2).
+- **A literal responder** who answers exactly what's asked (catches ambiguity).
+- **A confused/distracted responder** (catches comprehension failures).
+- **An opinionated outlier** (catches leading questions — they'll push back).
+
+### Step 3: Run the Panel
+
+Use `run_panel`. If the instrument is v3 branching, note which rounds each persona was routed into — `path` in the result tells you whether branches fired or fell through to `else`.
+
+### Step 4: Critique (Report Format)
+
+For each question, report:
+- **Did everyone understand it?** Quote a confused answer verbatim if so.
+- **Did answers cluster or scatter?** Scattering often means the question is too open or ambiguous.
+- **Were follow-ups productive** or did they produce filler?
+
+Then overall:
+- **Top 3 problems** with the instrument, in priority order.
+- **Specific rewrites** for the worst offenders.
+- **Branch coverage** (v3 only) — which `route_when` clauses never fired, and whether that's a coverage gap or just this persona sample.
+- **Go/no-go** — is this instrument ready to field, or does it need another pass?
+- **Total cost**.
+
+## Guidelines
+
+- **Diagnose, don't just score.** "Question 3 is unclear" is useless; "Question 3 was interpreted three different ways; here are the three readings" is actionable.
+- **Preserve the user's intent.** When suggesting rewrites, match what they were trying to ask — don't silently redesign the survey.
+- **A prescreen isn't a pilot.** Synthetic respondents won't catch fatigue, incentive gaming, or platform-specific dropout. Say so.
+- **If the instrument is broken at the structural level, stop and say so** before burning tokens on a panel run.