analyzthis_design 1.19.0 → 1.20.0

package/README.md

@@ -2,9 +2,9 @@
 
 A set of AI design personas and a task-first evaluation framework that plugs into Cursor, Claude Code, and Codex CLI as slash commands — plus an agentic MoE router with shared session state so you can call the same graph from any IDE or from the CLI.
 
-Install once. Run structured UX critiques, multi-phase ideation, and task-grounded screen reviews — directly inside your AI chat.
+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)
+**npm:** [analyzthis_design](https://www.npmjs.com/package/analyzthis_design) · **Current version:** 1.20.0
 
 ---
 
@@ -66,8 +66,9 @@ All skills use the **Agent Skills** `SKILL.md` standard — same files work acro
 | `/persona-orchestrator` | **Agentic critique entry point** (not for wireframes). MoE router + session state, ux-story-gate intake, persona chain, DS / hierarchy / verify gates → SHIP/REVISE/BLOCK |
 | `/ux-story-gate` | Task-first gate: PRDs, DS/Figma discovery, MoE routing, browser verify, assess-only mode |
 | `/design-critic` | 4-persona critique → Composite Score + Information Hierarchy Gate |
+| `/deliberation-protocol` | Adversarial review rules — grounding, objection JSON, parallel pairs, Raj escalation |
 
-### 8 Personas
+### 9 Personas (+ host runtime)
 
 Invoke critique personas for targeted, already-grounded questions. For **wireframes**, use `/ux-ideator`, `/noor`, or `/anuj`. For full screen **critique**, prefer `/persona-orchestrator` or `/ux-story-gate`. Run **`/kavi`** first so they have project context.
 
@@ -81,6 +82,7 @@ Invoke critique personas for targeted, already-grounded questions. For **wirefra
 | `/noor` | IA Architect | Minimalist Concept A + declared ranked information hierarchy |
 | `/anuj` | Power-User Advocate | Dense Concept B — bulk actions, keyboard shortcuts, hierarchy kept prominent |
 | `/raj` | Arbitrator | Resolves persona stalemates using 5 ranked product principles. Never speaks first. |
+| `/devi` | Host LLM runtime | Voices other personas when CLI `run` uses host mode (no API keys). Reads pending prompts → writes responses → `--continue` resumes |
 
 ### Supporting skills
 
@@ -89,10 +91,11 @@ Invoke critique personas for targeted, already-grounded questions. For **wirefra
 | `/design-personas` | Session context template — fill in once before a session |
 | `/knowledge-bank` | Auto-populated from your connected vault (or from Kavi collect). All personas read this first. |
 | `/design-reference` | CSV reference data (colors, typography, UX guidelines, stacks, …) |
+| `/collect-knowledge` | Alias for `/kavi` |
 
 ---
 
-## Agentic system (v1.19)
+## Agentic system (v1.20)
 
 ```
 User ask / Figma URL
@@ -105,14 +108,70 @@ User ask / Figma URL
         ↓
   MoE subset (default) OR full chain (explicit "full")
         ↓
-  Raj on stalemate (2+ blocking objections)
+  Zara (delight) → Raj on stalemate (after all groups — never before Zara)
+        ↓
+  Phase 5 synthesis (composite score + hierarchy gate + top 3)
         ↓
   Hard gates: DS → Hierarchy → Verify
         ↓
   SHIP / REVISE / BLOCK
 ```
 
-### Adversarial deliberation (v1.19)
+### Devi — host LLM (no API keys) · v1.20
+
+When no `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / `ZAI_API_KEY` is set, **`run` defaults to `provider: host`**. The orchestrator writes each persona step as a prompt file; **`/devi`** (or your host IDE agent) embodies that persona and writes the response back. No paid API calls.
+
+```bash
+# 1. Start run — pauses at first persona with prompt path
+npx analyzthis_design run --task "Review invoice approval screen" --full
+
+# 2. In Cursor / Claude: invoke /devi
+#    (reads pending/*.json, writes responses/*.md in persona voice)
+
+# 3. Check queue + continue
+npx analyzthis_design devi status
+npx analyzthis_design run --continue --task "Review invoice approval screen" --full
+```
+
+**Prompt queue layout:**
+
+```
+~/.analyzthis_design/runs/{project-id}/{run-id}/
+  pending/001-arjun.json    ← orchestrator writes
+  responses/001-arjun.md    ← Devi / host IDE writes
+  manifest.json
+```
+
+**Submit a response manually:**
+
+```bash
+npx analyzthis_design devi respond \
+  --run ~/.analyzthis_design/runs/{project-id}/{run-id} \
+  --step 001-arjun \
+  --file my-arjun-response.md
+```
+
+**Override host mode** when you have API keys:
+
+```bash
+export ANTHROPIC_API_KEY=sk-...
+npx analyzthis_design run --task "..." --provider anthropic
+```
+
+Skill: `/devi` · Implementation: `lib/host-llm.js`, `lib/provider.js`
+
+### Phase 5 synthesis · v1.20
+
+After deliberation closes, the orchestrator builds a **composite synthesis** automatically:
+
+- Per-persona scores (Arjun, Meera, Priya, Zara)
+- **Verdict:** SHIP / REVISE / BLOCK
+- **Top 3 actionable changes** (ranked)
+- **Information Hierarchy Gate** (Arjun visual hierarchy + Meera hierarchy check)
+
+Stored in session as `synthesis` (JSON) and `synthesis_markdown` (display block). Printed at end of every completed `run`.
+
+### Adversarial deliberation (v1.19+)
 
 Personas **debate** grounded in real task_map, PRD, and UI context — they do not pass generic handoff documents.
 
@@ -133,11 +192,24 @@ Config: `~/.analyzthis_design/config.json` → `deliberation` block (see `supaba
 
 Skill: `/deliberation-protocol` | Schema: `agents/deliberation-schema.json`
 
-**Low satisfaction ≠ unlimited tokens.** Objection rounds use lite schema + 600-token cap; synthesis and Raj use full models.
+**Low satisfaction ≠ unlimited tokens.** Objection rounds use lite schema + 600-token cap; synthesis and Raj use full produce mode.
+
+**Raj order (v1.20):** Raj escalates **after all deliberation groups** complete — Zara always runs before Raj in the critique chain.
 
 ---
 
-**Shared session state** lives at `~/.analyzthis_design/sessions/{project-id}/session-state.json` (includes `deliberation.round_log` after adversarial runs).
+**Shared session state** lives at `~/.analyzthis_design/sessions/{project-id}/session-state.json`.
+
+Key fields after a run:
+
+| Field | Contents |
+|---|---|
+| `persona_outputs` | Each persona's text + parsed deliberation JSON |
+| `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 |
+| `host_run` | Host-mode checkpoint when paused for Devi (`run_dir`, `checkpoint`) |
+| `metrics` | `llm_calls`, `deliberation_rounds`, `objections_raised`, token estimates |
 
 ```bash
 npx analyzthis_design session init
@@ -158,19 +230,29 @@ agents/
 **Standalone runtime (v2):**
 
 ```bash
-# Print routing only (no API calls)
+# Print routing + deliberation groups (no LLM calls)
 npx analyzthis_design run --task "Fix contrast on landing page" --dry-run
 
-# Call Anthropic / OpenAI per persona step (MoE subset, lite schema — the default)
+# 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
+
+# External API providers (optional)
 export ANTHROPIC_API_KEY=sk-...
 npx analyzthis_design run --task "Review this screen" --figma https://figma.com/... --provider anthropic
 
-# Force the full design-critic chain, or bypass the router entirely
+# 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 --no-deliberate
+npx analyzthis_design run --task "..." --max-rounds 2 --satisfaction 0.5
+npx analyzthis_design run --task "..." --no-deliberate   # legacy sequential handoff
 ```
 
+**Provider resolution order:** explicit `--provider` → config → first available API key → **`host`** (Devi).
+
+Supported providers: `host` | `anthropic` | `openai` | `google` | `zai`
+
 Provider defaults live in `~/.analyzthis_design/config.json`:
 
 ```json
@@ -239,7 +321,7 @@ flowchart TB
     Router -->|effort| Resolve[resolveModel persona effort]
     Resolve -->|gate? hard override| Matrix[effort_matrix in chain.json]
     Resolve -->|persona| Overrides[manifest.effort_overrides]
-    Matrix --> Call[callLlm provider model maxTokens]
+    Matrix --> Call[callLlm host or API provider]
     Overrides --> Call
     Call --> Metrics[metrics.effort_log + cost_usd]
     Metrics --> CostCmd[npx analyzthis_design cost]
@@ -256,9 +338,9 @@ Classifier rules (first match wins, safety rules before savings rules):
 **Gates never downgrade.** `ds_gate`, `information_hierarchy_gate`, and `verify_gate` are pinned to `hard` via `chain.gate_override` regardless of the classified effort — they're the safety net that makes downgrading persona work safe.
 
 Default effort matrix (in `agents/chain.json`):
-- trivial → `glm-4.5-flash` (free) or Gemini Flash-Lite, ~500-token cap
-- standard → `gemini-2.5-flash` or `gpt-4o-mini`, ~1200-token cap
-- hard → `claude-sonnet-5` or `gpt-5`, ~1800-token cap
+- **trivial** → `host` / Devi (~600-token cap for objection rounds) — or API model when keys set
+- **standard** → `gemini-2.5-flash` or `gpt-4o-mini`, ~1200-token cap
+- **hard** → `claude-sonnet-5` or `gpt-5`, ~1800-token cap
 
 Per-persona `effort_overrides` in each manifest refine this (e.g. Arjun's `trivial` is the color-system-only scoped mode at 700 tokens; his `hard` is the full Honeycomb + Visual Audit at 1800).
 
@@ -550,8 +632,14 @@ npx analyzthis_design research --query <text>
 npx analyzthis_design retrieve --file <csv> --column <col> --keywords a,b [--limit N]
 
 # Standalone orchestrator
-npx analyzthis_design run --task "..." [--figma URL] [--provider anthropic|openai|google|zai] [--dry-run] [--output path]
-npx analyzthis_design run --task "..." [--lite | --full] [--experts a,b] [--deliberate | --no-deliberate] [--max-rounds N] [--satisfaction 0.4]
+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]
+npx analyzthis_design run --continue --task "..."   # resume host-mode run after /devi
+
+# 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
 
 # Efficiency / cost
 npx analyzthis_design metrics [--project id] [--all]
@@ -582,14 +670,22 @@ lib/
   feedback.js           Persona unhappiness + correction logging (session + global JSONL)
   feedback-submit.js    Opt-in anonymized submit to Supabase (community feedback)
   deliberation.js       Adversarial satisfaction loops, context pack, Raj escalation
+  host-llm.js           Devi bridge — pending/response queue, checkpoint on pause
+  provider.js           Auto-detect API keys or default to host
+  synthesis.js          Phase 5 composite score + hierarchy gate + top 3
   cost.js               $-cost report from metrics × config.pricing
-  orchestrator/run.js   Standalone LLM runtime (v2) — MoE, effort-graded tiers, caps, cache-aware
+  orchestrator/run.js   Standalone runtime (v2) — MoE, host/API providers, synthesis
+scripts/
+  run-live-quality.js   Host-mode quality test (fixtures through real engine)
+  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/
 skills/
+  devi/                 Host LLM runtime — voices personas from pending prompts
   kavi/                 Kavi — Knowledge Archivist (/kavi)
   collect-knowledge/    Alias for Kavi (backward compatible)
   persona-orchestrator/ Agentic critique entry point
-  deliberation-protocol/ Adversarial review rules (v1.19)
+  deliberation-protocol/ Adversarial review rules (v1.19+)
   ux-story-gate/        Task-first gate + DS/MoE/verify/assess phases
   design-critic/        4-persona critique + hierarchy gate
   ux-ideator/           6-phase ideation
@@ -603,7 +699,21 @@ 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
-- For `run` / `collect` enrichment: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, or `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`
+- **Kavi `collect` enrichment:** optional — same keys as above; without keys, draft vault + sync still run
+
+---
+
+## What's new in v1.20
+
+| Feature | Description |
+|---------|-------------|
+| **`/devi` host LLM** | No API keys needed — orchestrator writes prompts, host IDE voices personas |
+| **`run --continue`** | Resume after Devi fills `responses/*.md` |
+| **Phase 5 synthesis** | Auto composite score, verdict, top 3, hierarchy gate in session |
+| **Raj ordering fix** | Zara always runs before Raj; Raj escalates after all groups |
+| **Rebuttal rounds** | Prompts require new evidence — no verbatim repeat on objection re-runs |
+| **`devi status` / `devi respond`** | CLI helpers for the prompt queue |
 
 ---
 

package/agents/cards/devi.md

@@ -0,0 +1,15 @@
+# Devi — Host LLM runtime (card)
+
+Meta-agent that **voices** other personas when the orchestrator runs in `host` mode (no external API keys).
+
+**Allowed:** read pending orchestrator prompts; embody any persona skill/card; write response files; batch-process a run directory; resume orchestrator via `--continue`.
+
+**Forbidden:** produce final code edits; skip deliberation JSON; speak as Devi in persona output (always write as the target persona).
+
+## Quick flow
+
+```
+run --task "..."  →  pending/001-arjun.json  →  /devi  →  responses/001-arjun.md  →  run --continue
+```
+
+See `skills/devi/SKILL.md` for the full protocol.

package/agents/chain.json

@@ -36,7 +36,7 @@
   },
   "effort_matrix": {
     "description": "Effort-graded model selection (v1.10). Each persona call is classified trivial|standard|hard and resolved against this matrix. Falls back to the legacy tiers map above when a persona manifest has no effort_overrides for the chosen effort.",
-    "trivial":  { "provider": "zai",      "model": "glm-4.5-flash",        "max_output_tokens": 500  },
+    "trivial":  { "provider": "host",   "model": "devi",                 "max_output_tokens": 600  },
     "standard": { "provider": "google",    "model": "gemini-2.5-flash",    "max_output_tokens": 1200 },
     "hard":     { "provider": "anthropic", "model": "claude-sonnet-5",     "max_output_tokens": 1800 }
   },

package/agents/manifests/devi.json

@@ -0,0 +1,31 @@
+{
+  "id": "devi",
+  "role": "host_llm",
+  "system_skill": "skills/devi/SKILL.md",
+  "system_card": "agents/cards/devi.md",
+  "tier": "structured",
+  "max_output_tokens": 900,
+  "parallel_safe_with": [],
+  "inputs": ["pending_prompts", "persona_skills", "session_state"],
+  "outputs": ["persona_responses"],
+  "allowed_tools": [],
+  "allowed_jobs": [
+    "read orchestrator pending prompts and embody target personas",
+    "write response files for host-mode orchestrator runs",
+    "batch-process all pending steps in a run directory"
+  ],
+  "forbidden_jobs": [
+    "replace persona critique content with meta-commentary",
+    "call external LLM APIs (Devi IS the host LLM)",
+    "implement code without explicit build approval"
+  ],
+  "routing_triggers": ["host_llm", "devi", "pending", "continue run"],
+  "never_route_for": ["design_critique", "wireframe"],
+  "chain_position": 0,
+  "handoff_from": [],
+  "handoff_to": ["arjun", "meera", "priya", "zara", "noor", "anuj", "raj"],
+  "requires_session_state": true,
+  "effort_overrides": {
+    "trivial": { "provider": "host", "max_output_tokens": 900 }
+  }
+}

package/agents/session-schema.json

@@ -79,6 +79,25 @@
       "raj_escalated": "boolean",
       "mode": "adversarial | legacy"
     },
+    "host_run": {
+      "run_id": "string — host LLM run directory id",
+      "run_dir": "string — absolute path to pending/responses queue",
+      "task": "string — task text for --continue",
+      "status": "in_progress | pending_devi | complete",
+      "last_pending": { "step_id": "string", "persona": "string" },
+      "checkpoint": "object | null — deliberation resume state",
+      "started_at": "ISO 8601",
+      "completed_at": "ISO 8601 | omitted"
+    },
+    "synthesis": {
+      "scores": "object — per-persona scores",
+      "total": "number",
+      "max_total": "number",
+      "verdict": "SHIP | REVISE | BLOCK",
+      "top3": ["object — ranked actionable changes"],
+      "hierarchy_gate": "object — gate status"
+    },
+    "synthesis_markdown": "string — Phase 5 composite block for display/export",
     "digest": {
       "task_map_summary": "string — short summary passed to persona calls instead of the full task_map/persona_outputs history",
       "hierarchy_top3": ["string — top 3 ranked hierarchy items, if declared"],