analyzthis_design 1.20.1 → 2.0.1

package/README.md

@@ -4,33 +4,45 @@ A set of AI design personas and a task-first evaluation framework that plugs int
 
 Install once. Run structured UX critiques, multi-phase ideation, and task-grounded screen reviews — directly inside your AI chat. **No external LLM API keys required** for CLI orchestrator runs: **`/devi`** voices each persona from your host IDE (Cursor, Claude, etc.).
 
-**npm:** [analyzthis_design](https://www.npmjs.com/package/analyzthis_design) · **Current version:** 1.20.1
+## v2.0 — chunked execution by default
+
+`npx analyzthis_design run --task "..."` now uses a **frontier planner + cheap chunk models**:
+
+1. Frontier/strong model plans the task into small chunks.
+2. Each chunk runs on the cheapest capable model: local Ollama, free cloud APIs (Groq, Gemini, OpenRouter), or cheap cloud APIs with your keys.
+3. Outputs are merged into a final verdict.
+4. Telemetry learns which models work best for each chunk type.
+
+Use `npx analyzthis_design run-unchunked` for the legacy single-pass orchestrator.
+
+**npm:** [analyzthis_design](https://www.npmjs.com/package/analyzthis_design) · **Current version:** 2.0.1 · **Step-by-step guide:** [HOW-TO-USE.md](./HOW-TO-USE.md)
 
 ---
 
-## Install
+## Quick start
 
 ```bash
-# Cursor (default) + cross-agent path on postinstall
+# 1. Install slash commands (Cursor/Claude/Codex/Grok/Windsurf)
 npx analyzthis_design
 
-# Claude Code (skills dir + legacy commands)
-npx analyzthis_design --target claude
+# 2. Run a task in v2.0 chunked mode (free/cheap models)
+npx analyzthis_design run --task "Review invoice approval screen"
 
-# Codex CLI
-npx analyzthis_design --target codex
+# 3. Or use legacy single-pass orchestrator
+npx analyzthis_design run-unchunked --task "Review invoice approval screen" --provider host
+```
 
-# Grok Build (xAI)
-npx analyzthis_design --target grok
+### Install by target IDE
 
-# Windsurf Cascade
+```bash
+npx analyzthis_design --target claude
+npx analyzthis_design --target codex
+npx analyzthis_design --target grok
 npx analyzthis_design --target windsurf
-
-# All supported hosts at once
 npx analyzthis_design --target all --force
 ```
 
-**After install:** type `/getting-started` in Cursor or Claude Code (or `@getting-started` in Windsurf). Re-print CLI help anytime with `npx analyzthis_design welcome`.
+**After install:** type `/getting-started` in Cursor or Claude Code (or `@getting-started` in Windsurf). For a complete walkthrough, see [HOW-TO-USE.md](./HOW-TO-USE.md). Re-print CLI help anytime with `npx analyzthis_design welcome`.
 
 | Tool | Skills installed to | Invoke |
 |---|---|---|
@@ -205,9 +217,14 @@ Key fields after a run:
 | Field | Contents |
 |---|---|
 | `persona_outputs` | Each persona's text + parsed deliberation JSON |
+| `full_prompts` | Exact `{ system, user }` prompts sent to the LLM (for training / auditing) |
+| `structured_outputs` | Parsed grades, score, top fixes per persona |
+| `covered_points` | Deduplicated findings across personas (redundancy suppression) |
+| `task_type` | Canonical problem type from the router |
 | `deliberation` | `round_log`, `open_objections`, `consensus_reached`, `raj_escalated` |
 | `synthesis` | Composite scores, verdict, top 3, hierarchy gate |
 | `synthesis_markdown` | Phase 5 block for display / export |
+| `outcome` | `inferred` + `confirmed` outcome per persona (for the evolution loop) |
 | `host_run` | Host-mode checkpoint when paused for Devi (`run_dir`, `checkpoint`) |
 | `metrics` | `llm_calls`, `deliberation_rounds`, `objections_raised`, token estimates |
 
@@ -227,31 +244,36 @@ agents/
   session-schema.json
 ```
 
-**Standalone runtime (v2):**
+**v2.0 chunked runtime (default for `run`):**
 
 ```bash
-# Print routing + deliberation groups (no LLM calls)
-npx analyzthis_design run --task "Fix contrast on landing page" --dry-run
+# Default: frontier planner + sequential chunk execution on free/cheap models
+npx analyzthis_design run --task "Review invoice approval screen"
 
-# Host mode (default when no API keys) — Devi voices personas
-npx analyzthis_design run --task "Review invoice screen" --full
-npx analyzthis_design devi status
-npx analyzthis_design run --continue --task "Review invoice screen" --full
+# Auto-detect local Ollama, otherwise use free cloud models
+npx analyzthis_design run --task "Review invoice approval screen" --budget free
 
-# External API providers (optional)
-export ANTHROPIC_API_KEY=sk-...
-npx analyzthis_design run --task "Review this screen" --figma https://figma.com/... --provider anthropic
+# Use your paid keys for cheap cloud models
+npx analyzthis_design run --task "..." --budget cheap --provider together
+
+# Limit parallelism / chunk count (sequential is default)
+npx analyzthis_design run --task "..." --sequential --max-chunks 4
+npx analyzthis_design run --task "..." --parallel --max-chunks 6
 
-# Force full chain, bypass router, tune deliberation
-npx analyzthis_design run --task "Full critique of onboarding" --full
-npx analyzthis_design run --task "Just check spacing" --experts arjun
-npx analyzthis_design run --task "..." --max-rounds 2 --satisfaction 0.5
-npx analyzthis_design run --task "..." --no-deliberate   # legacy sequential handoff
+# Legacy single-pass orchestrator (unchunked)
+npx analyzthis_design run-unchunked --task "Review invoice approval screen" --full
+
+# Host mode (no API keys) — Devi voices personas via prompt queue
+npx analyzthis_design run-unchunked --task "Review invoice screen" --full
+npx analyzthis_design devi status
+npx analyzthis_design run-unchunked --continue --task "Review invoice screen" --full
 ```
 
-**Provider resolution order:** explicit `--provider` → config → first available API key → **`host`** (Devi).
+**Chunk model selection:** Ollama auto-discovered → free cloud (Groq/Gemini/OpenRouter free endpoints) → cheap cloud with user keys. The **planner always runs on a frontier/strong model** and never on a cheap model; if no frontier provider is available, it falls back to the host model with a warning.
 
-Supported providers: `host` | `anthropic` | `openai` | `google` | `zai`
+**Provider resolution order:** explicit `--provider` → config → first available API key → **`host`** (Devi) for unchunked; chunked mode also considers Ollama and free endpoints before paid.
+
+Supported providers: `host` | `anthropic` | `openai` | `google` | `zai` | `ollama` | `groq` | `together` | `openrouter` | `deepseek`
 
 Provider defaults live in `~/.analyzthis_design/config.json`:
 
@@ -357,6 +379,9 @@ Ask → session digest → MoE router (1–2 experts, not 4) → persona cards (
 | **Persona cards** | `agents/cards/<persona>.md` (~500 tokens) are the default system prompt; the full `skills/<persona>/SKILL.md` is only opened for a C-or-below rubric lookup or an explicit deep/full request. |
 | **Lite output schema** | Grades + Top 2 fixes + score, by default. Deep/full schema is opt-in. |
 | **Retrieve-on-demand** | `npx analyzthis_design retrieve --file colors.csv --column "Product Type" --keywords saas` returns only matching rows, pre-formatted for citation — never the whole CSV. |
+| **Multi-file reference packs** | Each persona retrieves from 3-5 CSV files (not 1), pooled into a single ranker call. Arjun gets styles + ux-guidelines + ui-reasoning + charts; Zara gets colors + typography + styles + landing + icons. Same LLM cost as single-file, 3-5x coverage. |
+| **Best For Tags** | `styles.csv` and `typography.csv` have a `Best For Tags` column (semicolon-delimited product-type tokens) for reliable keyword filtering. Previously `Best For` was free-text and 31/84 styles were unfilterable. |
+| **CSV schema + validation** | `skills/design-reference/schema.json` defines all 28 CSV files' headers, filter columns, and cross-file joins. `npm run validate` checks integrity before publish. |
 | **Model tiers** | `structured` steps can run on a cheaper model (e.g. `gpt-4o-mini`); `critique`/`arbitrate` steps use a stronger model. Configurable per tier in `~/.analyzthis_design/config.json`. |
 | **Caching** | `lib/cache.js` caches retrieve results (invalidated automatically when the source CSV changes) and knowledge-bank slices (invalidated on `sync` / `session reset`). |
 | **Cost metrics** | Every `run` records `metrics` (llm_calls, experts_run, estimated tokens, cache_hits) into session state. |
@@ -412,7 +437,7 @@ npx analyzthis_design feedback list
 npx analyzthis_design feedback export --persona arjun --all
 ```
 
-Writes `{ system_card, digest, user, assistant }` JSONL pairs to `~/.analyzthis_design/training/<persona>.jsonl` from every session where that persona's output was explicitly accepted.
+`export-training` now emits richer training pairs: `{ system_card, system_prompt_full, user_prompt_full, digest, user, assistant, structured_output, outcome, task_type }`. The full prompts are captured automatically on every `run`, so fine-tuning datasets include the exact context the persona saw.
 
 **Correction export** writes `{ assistant_rejected, assistant_preferred, user_comment, tags }` to `~/.analyzthis_design/feedback/<persona>-corrections.jsonl` — useful when users were unhappy or had to rewrite persona output. Every entry is also appended to a global `corrections.jsonl` across projects.
 
@@ -420,6 +445,62 @@ Once a persona accumulates ~100–300 accepted pairs (and optionally correction
 
 ---
 
+## Self-evolving persona team (v1.21)
+
+The system now captures every run, learns from accepted outputs + confirmed outcomes, and proposes improvements to its own prompts, reference data, and routing — **dry-run by default**, human review before any apply.
+
+```
+Run → full prompts + structured output + outcome captured
+        ↓
+Lessons extracted (accepted outputs) → ~/.analyzthis_design/lessons/<persona>.jsonl
+        ↓
+Outcome confirmed (shipped / revised / blocked / missed)
+        ↓
+evolve --extract → proposes:
+  - prompt patches (new canonical failure patterns per persona)
+  - reference-data rows (new product-type patterns)
+  - router patches (task_type → best-performing expert)
+        ↓
+  evolve --apply <patchId> (human review) → skill/CSV/router updated
+         ↓
+Next run retrieves:
+  - per-persona knowledge slices (priority + fallback)
+  - past lessons for similar tasks
+  - query-expanded + ranked reference rows from 3-5 CSV files per persona
+```
+
+### Retrieval stack
+
+| Layer | What it does | Files |
+|---|---|---|
+| **Query expansion** | One cheap LLM call per run expands the task into search terms (product type, design domain, component, persona lens) | `lib/query-expander.js`, `agents/cards/query-expander.md` |
+| **Per-persona ranking** | A second cheap LLM call per persona ranks the top 5 reference rows + knowledge notes for that persona's lens | `lib/ranker.js`, `agents/cards/ranker.md` |
+| **Lessons retrieval** | Top-3 lessons from past accepted sessions, keyword-matched to the current task | `lib/lessons.js` |
+| **Redundancy suppression** | Before each persona produces, it sees what prior personas already covered and is told to only add NEW insights | `lib/dedup.js`, `lib/deliberation.js` |
+| **Per-persona KB slices** | `sync` now builds a filtered slice per persona (priority categories first, small fallback context at the end) | `lib/knowledge.js` |
+
+### Commands
+
+```bash
+# Extract lessons + infer outcomes + propose patches (dry-run by default)
+npx analyzthis_design evolve --extract [--window N] [--dry-run]
+
+# Review a patch before applying
+npx analyzthis_design evolve --apply <patchId> --dry-run
+
+# Apply a patch after review (prompt / reference rows only; router patches need manual edit)
+npx analyzthis_design evolve --apply <patchId>
+
+# Outcome tracking
+npx analyzthis_design outcome --infer [--window N]      # auto-infer from next session
+npx analyzthis_design outcome --pending                  # list inferred outcomes awaiting confirmation
+npx analyzthis_design outcome --confirm --persona arjun --result shipped
+```
+
+Config in `agents/chain.json` → `evolution` block: `extraction_window_days`, `min_lessons_for_patch`, `min_outcomes_for_router_patch`.
+
+---
+
 ## Persona feedback — corrections & unhappiness (v1.16)
 
 When a persona gets it wrong, you can record **what was wrong** and **how you fixed it**. This feeds future fine-tuning (negative / DPO pairs) alongside the existing positive `export-training` path.
@@ -631,12 +712,27 @@ npx analyzthis_design research --query <text>
 # Reference data (retrieve-on-demand)
 npx analyzthis_design retrieve --file <csv> --column <col> --keywords a,b [--limit N]
 
-# Standalone orchestrator
-npx analyzthis_design run --task "..." [--figma URL] [--provider host|anthropic|openai|google|zai] [--dry-run] [--output path]
-npx analyzthis_design run --task "..." [--lite | --full] [--experts a,b]
-npx analyzthis_design run --task "..." [--deliberate | --no-deliberate] [--max-rounds N] [--satisfaction 0.4]
+# Standalone orchestrator (v2.0 chunked by default)
+npx analyzthis_design run --task "..." [--budget free|cheap|auto] [--sequential|--parallel] [--max-chunks N] [--dry-run]
+npx analyzthis_design run-unchunked --task "..." [--lite|--full] [--experts a,b] [--dry-run] [--deliberate|--no-deliberate]
 npx analyzthis_design run --continue --task "..."   # resume host-mode run after /devi
 
+# CSV validation
+npx analyzthis_design validate    # validate all 28 CSV files against schema.json
+
+# Self-evolving team (v1.21)
+npx analyzthis_design evolve --extract [--window N] [--dry-run]
+npx analyzthis_design evolve --apply <patchId> [--dry-run]
+npx analyzthis_design outcome --infer [--window N]
+npx analyzthis_design outcome --pending
+npx analyzthis_design outcome --confirm --persona <id> --result shipped|revised|blocked|missed
+
+# Mood board (v1.22)
+npx analyzthis_design moodboard create --task "..." [--auto] [--url <url> ...]
+npx analyzthis_design moodboard critique --board <id>
+npx analyzthis_design moodboard add --board <id> --url <url> --title "..." --tags a,b
+npx analyzthis_design moodboard list
+
 # Devi — host LLM queue (v1.20)
 npx analyzthis_design devi status [--run path]
 npx analyzthis_design devi respond --run <run-dir> --step 001-arjun --file response.md
@@ -666,6 +762,21 @@ lib/
   research.js           URL / query → web-context.md
   retrieve.js           Filtered, citation-ready CSV row retrieval
   cache.js              On-disk cache for retrieve/kb slices
+  chunk-models.js       Curated free/cheap model pool + Ollama auto-discovery
+  chunk-planner.js      Frontier/strong model chunk planner
+  chunk-router.js       Cheapest capable model per chunk
+  chunk-executor.js     Chunk execution with retry + fallback
+  chunk-synthesis.js    Merge chunk outputs into final verdict
+  chunk-telemetry.js    Per-chunk model quality tracking
+  chunk-run.js          Top-level chunked execution coordinator
+  reference-pack.js     Shared multi-file CSV + vault retrieval (buildReferencePack)
+  moodboard.js          Mood-board engine: collect web/DS references, tag, deliberate
+  dedup.js              Cross-persona redundancy detection
+  lessons.js            Self-evolving lessons store (extract/retrieve/inject)
+  outcome.js            Infer + confirm persona outcome labels
+  query-expander.js     LLM task → search terms for retrieval
+  ranker.js             LLM per-persona ranking of reference/knowledge candidates
+  evolve.js             Evolution engine: prompt/reference/router patch proposals
   export.js             LoRA training-pair export hook
   feedback.js           Persona unhappiness + correction logging (session + global JSONL)
   feedback-submit.js    Opt-in anonymized submit to Supabase (community feedback)
@@ -680,6 +791,7 @@ scripts/
   quality-check.js      Validate persona outputs vs skill + deliberation protocol
   demo-fictional-deliberation.js  Dry-run walkthrough for FlowPay scenario
 scripts/obfuscate.js    Build step → dist/
+scripts/validate-csvs.js  CSV integrity validation against schema.json
 skills/
   devi/                 Host LLM runtime — voices personas from pending prompts
   kavi/                 Kavi — Knowledge Archivist (/kavi)
@@ -699,11 +811,46 @@ skills/
 
 - Node.js 16+
 - Any Agent Skills–compatible host: [Cursor](https://cursor.com), [Claude Code](https://code.claude.com), Codex CLI, [Grok Build](https://x.ai), or Windsurf Cascade
-- **CLI `run`:** works without API keys via **`/devi`** host mode (default). Optional keys for automated API runs: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`
+- **CLI `run`:** works without API keys via **`/devi`** host mode (default). Optional keys for automated API runs: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ZAI_API_KEY`, `GROQ_API_KEY`, `TOGETHER_API_KEY`, `OPENROUTER_API_KEY`, `DEEPSEEK_API_KEY`. Local Ollama auto-detected at `localhost:11434`.
 - **Kavi `collect` enrichment:** optional — same keys as above; without keys, draft vault + sync still run
 
 ---
 
+## What's new in v2.0
+
+| Feature | Description |
+|---------|-------------|
+| **Chunked execution by default** | Frontier planner → cheap chunk models (Ollama, free/cheap cloud) → synthesis |
+| **Model router** | Auto-discovers Ollama + uses curated free/cheap cloud model pool |
+| **Chunk telemetry** | Tracks per-model success rate so router improves over time |
+| **Legacy mode preserved** | `npx analyzthis_design run-unchunked` for the original single-pass orchestrator |
+| **Planner never cheap** | Planner always uses frontier/host; chunk models are cost-optimized |
+| **Multi-file reference retrieval** | Each persona retrieves from 3-5 CSV files (not 1) via a shared ranker — same LLM cost, 3-5x coverage |
+| **All 16 stacks detected** | `detectStack()` covers all 16 stack CSVs (flutter, swiftui, laravel, threejs, etc.) — was 8 |
+| **CSV schema + validation** | `npm run validate` checks all 28 CSV files against `schema.json` before publish |
+| **Best For Tags** | styles.csv + typography.csv have normalized tag columns for reliable keyword filtering |
+
+## What's new in v1.22
+
+| Feature | Description |
+|---------|-------------|
+| **Mood boards** | `/mood-board` collects web references + design-system patterns, tags them, and runs team deliberation |
+| **User-contributed references** | User can add URLs/notes to a board and rerun the critique loop |
+| **Visual direction setting** | Arjun, Meera, Priya, Zara, Noor score references via the UX Honeycomb rigor matrix |
+| **Workspace artifacts** | `moodboard/{boardId}.json` is written into the project for the user to inspect |
+
+## What's new in v1.21
+
+| Feature | Description |
+|---------|-------------|
+| **Self-evolving team** | `evolve --extract` harvests lessons + outcomes; proposes prompt/CSV/router patches |
+| **Per-persona knowledge slices** | `sync` builds filtered context per persona (priority categories + fallback) |
+| **Query expansion + ranking** | Cheap LLM calls broaden retrieval and rank references per persona lens |
+| **Lessons store** | Past accepted fixes are retrieved for similar future tasks |
+| **Outcome tracking** | `outcome --confirm` / `--infer` labels whether a persona's output actually shipped |
+| **Full-prompt training export** | `export-training` now emits the exact `{ system, user }` prompts + structured output |
+| **Redundancy suppression** | Personas see what prior personas already covered and add only new insights |
+
 ## What's new in v1.20
 
 | Feature | Description |

package/agents/cards/chunk-planner.md

@@ -0,0 +1,5 @@
+You are the `/chunk-planner` explainer. You describe how the v2.0 chunked execution planner works.
+
+You do not execute chunks or replace routing decisions. You help the user inspect and understand chunk plans.
+
+When asked about a specific plan, read `session-state.json` and look under `chunk_run.plan`.

package/agents/cards/mood-board.md

@@ -0,0 +1,13 @@
+You are the Mood Board conductor. You do not have a design opinion of your own.
+
+Your job is to:
+1. Collect visual/textual references for a design direction.
+2. Tag references with style, mood, surface, and relevant keywords.
+3. Pull matching design-system tokens, styles, and patterns from the reference CSVs.
+4. Run Arjun, Meera, Priya, Zara, and Noor through adversarial deliberation over the board.
+5. Write `board.json` to the session and a workspace copy the user can open.
+6. Accept user-contributed references and rerun the loop.
+
+Always assess-only: never write code or final wireframes. Produce the structured board artifact and a synthesis of the team's direction.
+
+Cite design-system rows using the format: `[filename, row N: "exact quoted value"]`.

package/agents/cards/query-expander.md

@@ -0,0 +1,17 @@
+# Query Expander (card)
+
+You expand a design task into search terms for reference-data retrieval.
+
+**Allowed:** Read the task + persona lens; output a JSON array of 5-10 search terms.
+**Forbidden:** Output anything other than the JSON array. No prose, no explanation.
+
+**Output format:**
+```json
+["term1", "term2", "term3", "term4", "term5"]
+```
+
+Terms should be:
+- Product-type keywords (saas, fintech, e-commerce, dashboard, etc.)
+- Design-domain keywords (contrast, hierarchy, spacing, accessibility, etc.)
+- Component/pattern keywords (modal, table, onboarding, empty state, etc.)
+- Persona-specific lens keywords (e.g. for Arjun: color, typography, gestalt; for Priya: state, API, performance)

package/agents/cards/ranker.md

@@ -0,0 +1,16 @@
+# Ranker (card)
+
+You rank reference candidates for a specific design persona's lens.
+
+**Allowed:** Read the task, persona lens, and candidate list; output a JSON array of candidate numbers in priority order (most relevant first).
+**Forbidden:** Output anything other than the JSON array. No prose.
+
+**Output format:**
+```json
+[3, 7, 1, 5, 2]
+```
+
+Rank by:
+- Relevance to the persona's lens (UX, business, feasibility, delight, IA, etc.)
+- Relevance to the specific task
+- Specificity (more specific = higher rank than generic)

package/agents/cards/run-unchunked.md

@@ -0,0 +1,7 @@
+You are the `/run-unchunked` skill. You invoke the legacy non-chunked orchestrator.
+
+Use this only when the user explicitly asks for unchunked mode or a quick single-expert run.
+
+Do not replace the default chunked orchestrator. Do not run the chunk planner.
+
+Assess-only: do not implement code unless mode is build_approved.

package/agents/chain.json

@@ -57,5 +57,20 @@
   "re_evaluation": {
     "mode": "delta_only",
     "description": "On any follow-up after REVISE, re-run only the persona(s) assigned to the prior Top 3 actionable changes — never the full chain. See design-critic Re-evaluation Protocol."
+  },
+  "evolution": {
+    "lessons_dir": "~/.analyzthis_design/lessons",
+    "extraction_window_days": 7,
+    "min_lessons_for_patch": 5,
+    "min_outcomes_for_router_patch": 10,
+    "dry_run_default": true
+  },
+  "chunk_models": {
+    "description": "v2.0 chunked execution model pool. Planner is always frontier/strong; chunk models are auto-discovered (Ollama) plus curated cloud free/cheap models.",
+    "planner": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" },
+    "max_chunks": 6,
+    "default_budget": "auto",
+    "default_mode": "sequential",
+    "allow_cheap_paid": true
   }
 }

package/agents/manifests/anuj.json

@@ -24,6 +24,7 @@
   "handoff_from": [],
   "handoff_to": ["arjun"],
   "requires_session_state": true,
+  "knowledge_categories": ["design", "tech"],
   "effort_overrides": {
     "trivial": { "when": "shortcuts-only audit", "max_output_tokens": 700 },
     "hard": { "when": "bulk-action state design", "max_output_tokens": 1500 }

package/agents/manifests/arjun.json

@@ -25,6 +25,7 @@
   "handoff_from": ["noor"],
   "handoff_to": ["meera"],
   "requires_session_state": true,
+  "knowledge_categories": ["brand", "design", "research"],
   "hard_gates": ["ds_gate", "information_hierarchy_gate"],
   "scoped_modes": {
     "arjun_color_system_only": {

package/agents/manifests/chunk-planner.json

@@ -0,0 +1,18 @@
+{
+  "id": "chunk-planner",
+  "name": "Chunk Planner",
+  "tier": "router",
+  "max_output_tokens": 2500,
+  "system_card": "agents/cards/chunk-planner.md",
+  "system_skill": "skills/chunk-planner/SKILL.md",
+  "allowed_jobs": [
+    "Explain the chunked execution planner",
+    "Inspect chunk plans from session state"
+  ],
+  "forbidden_jobs": [
+    "Replace the router or chain",
+    "Execute chunks directly"
+  ],
+  "hard_gates": [],
+  "parallel_safe_with": []
+}

package/agents/manifests/kavi.json

@@ -26,6 +26,7 @@
   "handoff_from": [],
   "handoff_to": [],
   "requires_session_state": true,
+  "knowledge_categories": ["prd", "brand", "product", "design", "research", "tech", "web"],
   "effort_overrides": {
     "standard": { "when": "enrichment batch (default)", "max_output_tokens": 4000 },
     "trivial": { "when": "draft-only / --no-enrich (no LLM)", "max_output_tokens": 500 }

package/agents/manifests/meera.json

@@ -24,6 +24,7 @@
   "handoff_from": ["arjun"],
   "handoff_to": ["priya"],
   "requires_session_state": true,
+  "knowledge_categories": ["product", "research"],
   "effort_overrides": {
     "trivial": { "when": "single GTM lever / retention check", "max_output_tokens": 500 },
     "hard": { "when": "north-star tradeoff or cross-metric conflict", "max_output_tokens": 1200 }

package/agents/manifests/mood-board.json

@@ -0,0 +1,23 @@
+{
+  "id": "mood-board",
+  "name": "Mood Board",
+  "tier": "structured",
+  "max_output_tokens": 1800,
+  "system_card": "agents/cards/mood-board.md",
+  "system_skill": "skills/mood-board/SKILL.md",
+  "allowed_jobs": [
+    "collect web references for visual direction",
+    "tag references with style, mood, surface",
+    "retrieve design-system patterns for the task",
+    "orchestrate team deliberation over references",
+    "write board.json artifacts",
+    "accept user-contributed references and rerun"
+  ],
+  "forbidden_jobs": [
+    "produce final wireframes or code",
+    "replace the design-critic chain for screen review",
+    "auto-apply design system changes"
+  ],
+  "hard_gates": [],
+  "parallel_safe_with": []
+}

package/agents/manifests/noor.json

@@ -25,6 +25,7 @@
   "handoff_from": [],
   "handoff_to": ["arjun", "anuj"],
   "requires_session_state": true,
+  "knowledge_categories": ["design", "product"],
   "effort_overrides": {
     "trivial": { "when": "hierarchy-only declaration", "max_output_tokens": 700 },
     "hard": { "when": "multi-screen IA", "max_output_tokens": 1500 }

package/agents/manifests/priya.json

@@ -24,6 +24,7 @@
   "handoff_from": ["meera"],
   "handoff_to": ["zara"],
   "requires_session_state": true,
+  "knowledge_categories": ["tech"],
   "effort_overrides": {
     "trivial": { "when": "single feature T-shirt sizing (structured extract)", "max_output_tokens": 500 },
     "hard": { "when": "architecture / state-machine risk", "max_output_tokens": 900 }

package/agents/manifests/query-expander.json

@@ -0,0 +1,13 @@
+{
+  "id": "query-expander",
+  "role": "retrieval_assistant",
+  "system_card": "agents/cards/query-expander.md",
+  "tier": "structured",
+  "max_output_tokens": 200,
+  "parallel_safe_with": [],
+  "allowed_jobs": ["query expansion for reference retrieval"],
+  "forbidden_jobs": ["critique", "wireframe", "design generation"],
+  "effort_overrides": {
+    "trivial": { "when": "always", "max_output_tokens": 200 }
+  }
+}

package/agents/manifests/raj.json

@@ -23,6 +23,7 @@
   "handoff_from": ["zara", "arjun", "meera", "priya", "noor", "anuj"],
   "handoff_to": [],
   "requires_session_state": true,
+  "knowledge_categories": ["prd", "product", "design"],
   "effort_overrides": {
     "standard": { "when": "principle ranking (one verdict, never first)", "max_output_tokens": 1200 },
     "hard": { "when": "cross-persona stalemate", "max_output_tokens": 1200 }

package/agents/manifests/ranker.json

@@ -0,0 +1,13 @@
+{
+  "id": "ranker",
+  "role": "retrieval_assistant",
+  "system_card": "agents/cards/ranker.md",
+  "tier": "structured",
+  "max_output_tokens": 200,
+  "parallel_safe_with": [],
+  "allowed_jobs": ["rank reference candidates for persona relevance"],
+  "forbidden_jobs": ["critique", "wireframe", "design generation"],
+  "effort_overrides": {
+    "trivial": { "when": "always", "max_output_tokens": 200 }
+  }
+}

package/agents/manifests/run-unchunked.json

@@ -0,0 +1,19 @@
+{
+  "id": "run-unchunked",
+  "name": "Run Unchunked",
+  "tier": "structured",
+  "max_output_tokens": 900,
+  "system_card": "agents/cards/run-unchunked.md",
+  "system_skill": "skills/run-unchunked/SKILL.md",
+  "allowed_jobs": [
+    "Run the legacy non-chunked orchestrator",
+    "Execute a single-pass persona chain",
+    "Compare against chunked output"
+  ],
+  "forbidden_jobs": [
+    "Replace the default chunked orchestrator",
+    "Run the chunk planner"
+  ],
+  "hard_gates": [],
+  "parallel_safe_with": []
+}

package/agents/manifests/zara.json

@@ -25,6 +25,7 @@
   "handoff_from": ["priya"],
   "handoff_to": [],
   "requires_session_state": true,
+  "knowledge_categories": ["brand", "design"],
   "effort_overrides": {
     "standard": { "when": "delight pass (one peak moment)", "max_output_tokens": 1200 },
     "hard": { "when": "novel interaction design", "max_output_tokens": 1200 }

package/agents/router.json

@@ -67,6 +67,13 @@
       "route_to": ["raj"],
       "never_route_to": []
     },
+    {
+      "problem_type": "chunked_run",
+      "signals": ["chunked", "chunk planner", "run-chunked", "cheap models", "free models", "ollama"],
+      "route_to": ["chunk-planner"],
+      "never_route_to": ["design-critic_chain"],
+      "notes": "Explain or inspect the v2.0 chunked execution planner."
+    },
     {
       "problem_type": "full_screen_review",
       "signals": ["full screen review", "critique this screen", "review this page"],
@@ -80,6 +87,13 @@
       "route_to": ["kavi"],
       "never_route_to": ["design-critic_chain", "zara", "arjun", "meera", "priya"],
       "notes": "Producer only — run /kavi or `npx analyzthis_design collect`. Never part of a critique chain."
+    },
+    {
+      "problem_type": "mood_board",
+      "signals": ["mood board", "mood-board", "/mood-board", "visual direction", "references", "inspiration", "style direction", "design direction"],
+      "route_to": ["mood-board"],
+      "never_route_to": ["design-critic_chain", "zara", "noor_alone"],
+      "notes": "Visual direction setting — collect references, tag them, pull DS patterns, run team deliberation. Not a screen critique."
     }
   ]
 }