analyzthis_design 1.10.0 → 1.12.0

package/README.md

@@ -11,44 +11,67 @@ Install once. Run structured UX critiques, multi-phase ideation, and task-ground
 ## Install
 
 ```bash
-# Cursor (default)
+# Cursor (default) + cross-agent path on postinstall
 npx analyzthis_design
 
-# Claude Code
+# Claude Code (skills dir + legacy commands)
 npx analyzthis_design --target claude
 
 # Codex CLI
 npx analyzthis_design --target codex
 
-# All three at once
-npx analyzthis_design --target all
+# Grok Build (xAI)
+npx analyzthis_design --target grok
+
+# Windsurf Cascade
+npx analyzthis_design --target windsurf
+
+# All supported hosts at once
+npx analyzthis_design --target all --force
 ```
 
-| Tool | Skills installed to |
-|---|---|
-| Cursor | `~/.cursor/skills/` |
-| Claude Code | `~/.claude/commands/` |
-| Codex CLI | `~/.codex/skills/` |
+**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`.
+
+| Tool | Skills installed to | Invoke |
+|---|---|---|
+| Cursor | `~/.cursor/skills/<name>/SKILL.md` | `/getting-started` |
+| Claude Code | `~/.claude/skills/<name>/SKILL.md` (+ legacy `~/.claude/commands/`) | `/getting-started` |
+| Codex CLI | `~/.codex/skills/<name>/SKILL.md` | skill name / AGENTS.md |
+| Grok Build | `~/.grok/skills/<name>/SKILL.md` | `/collect-knowledge` |
+| Windsurf Cascade | `~/.codeium/windsurf/skills/<name>/SKILL.md` | `@collect-knowledge` |
+| Cross-agent | `~/.agents/skills/<name>/SKILL.md` | discovered by multiple hosts |
+
+All skills use the **Agent Skills** `SKILL.md` standard — same files work across Cursor, Claude, Grok, Windsurf, and Codex. The CLI (`collect`, `run`, `sync`) is host-agnostic; only *where skills are discovered* differs.
 
 ---
 
 ## Skills Overview
 
-### Entry points (start here)
+### Design — wireframes (start here for new screens)
 
 | Command | What it does |
 |---|---|
-| `/persona-orchestrator` | **Recommended agentic entry point.** Loads MoE router + session state, runs ux-story-gate intake, executes the right persona chain, enforces DS / hierarchy / verify gates, synthesises a SHIP/REVISE/BLOCK verdict. |
-| `/ux-story-gate` | Task-first gate: discovers PRDs, DS/Figma discovery, MoE routing, browser verify, assess-only mode. |
-| `/design-critic` | 4-persona critique → `SHIP / REVISE / BLOCK` verdict with a Composite Score out of 20 + Information Hierarchy Gate. |
-| `/ux-ideator` | 6-phase ideation → two competing IA concepts, deliberation, delight pass, feasibility check. |
+| `/getting-started` | **First-run guide** — which command to use for wireframes vs critique |
+| `/ux-ideator` | **Full ideation** — two competing text wireframes (minimalist vs dense), deliberation, delight, feasibility |
+| `/noor` | **Quick minimalist wireframe** — Concept A text wireframe, progressive disclosure |
+| `/anuj` | **Power-user wireframe** — Concept B text wireframe, density + bulk actions |
 
-### 7 Individual Personas
+### Evaluate — critique (existing designs)
 
-Invoke directly for targeted, already-grounded questions. For full screen evaluation, prefer `/persona-orchestrator` or `/ux-story-gate`.
+| Command | What it does |
+|---|---|
+| `/collect-knowledge` | **Kavi — Knowledge Archivist.** Scans the codebase, builds an Obsidian vault, LLM-enriches notes, syncs into the knowledge bank. Run once per project before critiques. |
+| `/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 |
+
+### 8 Personas
+
+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 `/collect-knowledge` first so they have project context.
 
 | Command | Persona | What they evaluate |
 |---|---|---|
+| `/collect-knowledge` | Kavi — Knowledge Archivist | Scan repo → Obsidian vault → enrich → sync knowledge bank (producer, not a critic) |
 | `/arjun` | UX + Visual Design | UX Honeycomb + Visual Design Audit (hierarchy, color, type, spacing, components, style fit, micro-interactions) |
 | `/meera` | Business Agent | Retention, ARR, GTM lever, adoption risk; hierarchy vs north-star check |
 | `/priya` | Feasibility Agent | Engineering effort (T-shirt sizing, 2-axis model), state machine traps |
@@ -62,12 +85,12 @@ Invoke directly for targeted, already-grounded questions. For full screen evalua
 | Command | Purpose |
 |---|---|
 | `/design-personas` | Session context template — fill in once before a session |
-| `/knowledge-bank` | Auto-populated from your connected vault. All personas read this first. |
+| `/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, …) |
 
 ---
 
-## Agentic system (v1.10)
+## Agentic system (v1.12)
 
 ```
 User ask / Figma URL
@@ -268,9 +291,45 @@ Writes `{ system_card, digest, user, assistant }` JSONL pairs to `~/.analyzthis_
 
 ---
 
+## Knowledge collection — Kavi (v1.11)
+
+Kavi is a **producer** persona (not a critic). One command scans the current repo, writes an Obsidian vault, optionally enriches notes with an LLM, then auto-connects and syncs into the knowledge bank.
+
+```
+/collect-knowledge  (or  npx analyzthis_design collect)
+        ↓
+  Scan codebase (gitignore-aware) → draft Obsidian notes
+        ↓
+  LLM enrich (batched; skip with --no-enrich if no API key)
+        ↓
+  ~/.analyzthis_design/vaults/{project-id}/
+        ↓
+  connect + sync → knowledge-bank skill
+        ↓
+  Arjun / Meera / … read company context first
+```
+
+```bash
+# In your app repo (sync KB to every host):
+npx analyzthis_design collect --target all
+npx analyzthis_design collect --dry-run
+npx analyzthis_design collect --no-enrich --limit 50
+npx analyzthis_design collect --vault ~/Documents/MyProjectVault --target claude
+```
+
+Vault folders: `PRDs/`, `Brand/`, `Product/`, `Pages/`, `Components/`, `Design/`, `Tech/`, `Research/`, `_meta/`. Notes use YAML frontmatter + `[[wikilinks]]`. Re-runs skip unchanged enriched notes via content hash.
+
+Enrichment needs one of: `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ANTHROPIC_API_KEY`, `ZAI_API_KEY`. Without a key, Kavi still writes a draft vault and syncs it.
+
+---
+
 ## Knowledge Bank — Connect your vault
 
 ```bash
+# Option A — let Kavi build the vault from the codebase (recommended for new projects)
+npx analyzthis_design collect
+
+# Option B — connect an existing Obsidian vault or markdown folder
 npx analyzthis_design connect --vault ~/Documents/MyVault
 npx analyzthis_design connect --vault ~/vault --tags design,brand,prd,product
 npx analyzthis_design connect --vault ~/vault --include Design,Brand,PRDs,Research
@@ -289,13 +348,17 @@ Config: `~/.analyzthis_design/config.json`.
 ## CLI Reference
 
 ```bash
-# Install / remove / list
+# Install / remove / list / welcome
 npx analyzthis_design
 npx analyzthis_design --target all
 npx analyzthis_design --force
+npx analyzthis_design welcome [--target cursor|claude|all]
 npx analyzthis_design remove --target all
 npx analyzthis_design list --target all
 
+# Knowledge collection (Kavi)
+npx analyzthis_design collect [--vault path] [--dry-run] [--no-enrich] [--limit N] [--target cursor|claude|grok|windsurf|agents|all]
+
 # Knowledge bank
 npx analyzthis_design connect --vault <path> [--tags ...] [--include ...]
 npx analyzthis_design sync [--target all]
@@ -314,7 +377,7 @@ 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] [--dry-run] [--output path]
+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]
 
 # Efficiency / cost
@@ -334,7 +397,9 @@ bin/cli.js              CLI entry point
 lib/
   install.js            Skill installation
   knowledge.js          Vault sync + web-context merge
-  session.js            Shared session-state.json (+ digest, metrics, accept flag)
+  collect.js            Kavi — codebase scan → Obsidian vault → enrich → sync
+  platforms.js          Cross-host skill paths (Cursor, Claude, Codex, Grok, Windsurf, agents)
+  session.js            Shared session-state.json (+ digest, metrics, vault_path)
   research.js           URL / query → web-context.md
   retrieve.js           Filtered, citation-ready CSV row retrieval
   cache.js              On-disk cache for retrieve/kb slices
@@ -343,7 +408,8 @@ lib/
   orchestrator/run.js   Standalone LLM runtime (v2) — MoE, effort-graded tiers, caps, cache-aware
 scripts/obfuscate.js    Build step → dist/
 skills/
-  persona-orchestrator/ Agentic entry point
+  collect-knowledge/    Kavi — Knowledge Archivist
+  persona-orchestrator/ Agentic critique entry point
   ux-story-gate/        Task-first gate + DS/MoE/verify/assess phases
   design-critic/        4-persona critique + hierarchy gate
   ux-ideator/           6-phase ideation
@@ -356,9 +422,8 @@ skills/
 ## Requirements
 
 - Node.js 16+
-- [Cursor](https://cursor.com) with Agent Mode (for `/skill` commands)
-- Claude Code or Codex CLI if using those targets
-- For `run` (non–dry-run): `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`
+- 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`
 
 ---
 

package/agents/cards/kavi.md

@@ -0,0 +1,26 @@
+# Kavi — Knowledge Archivist (card)
+
+Producer persona. Scans a codebase, builds an Obsidian vault, enriches notes into readable project knowledge, then wires that vault into the knowledge bank so every critique persona reads company context first.
+
+**Allowed:** codebase inventory (PRDs, brand/tokens, pages, components, tech stack, research); writing Obsidian notes with YAML frontmatter + `[[wikilinks]]`; LLM enrichment of draft extracts into concise purpose + key facts; connecting and syncing the vault into `knowledge-bank`.
+
+**Forbidden:** UX / visual / business critique (→ Arjun / Meera / etc.); inventing files, APIs, or components not present in the raw extract; design generation; code edits in the scanned repo.
+
+## Output schema (enrichment batches)
+For each draft note, emit a full Obsidian markdown file:
+1. Keep the original YAML frontmatter; set `enriched: true`.
+2. Sections: Purpose, Key facts (bullets), Related (`[[Folder/Note]]` wikilinks only to notes that exist in the batch or were listed under Related).
+3. Do not paste large code blocks — summarize what the file does in plain language.
+4. Do not invent APIs, routes, or props that are not in the Raw extract / Exports / Imports.
+
+## Lite report (after collect CLI)
+```
+## Kavi — Collect report
+Vault: [path]
+Notes: [N written / S skipped unchanged]
+Enriched: [E]
+Knowledge bank: [synced count] → [targets]
+Next: run /persona-orchestrator or any critique persona — they read this bank first.
+```
+
+Consult `skills/collect-knowledge/SKILL.md` for the host workflow. Prefer running `npx analyzthis_design collect` over re-scanning files in chat.

package/agents/manifests/kavi.json

@@ -0,0 +1,33 @@
+{
+  "id": "kavi",
+  "role": "knowledge_archivist",
+  "system_skill": "skills/collect-knowledge/SKILL.md",
+  "system_card": "agents/cards/kavi.md",
+  "tier": "structured",
+  "max_output_tokens": 4000,
+  "parallel_safe_with": [],
+  "inputs": ["cwd", "optional_vault_path"],
+  "outputs": ["obsidian_vault", "collect_report", "knowledge_bank_sync"],
+  "allowed_tools": ["knowledge-bank", "filesystem_scan"],
+  "allowed_jobs": [
+    "scan codebase into Obsidian vault notes (PRDs, brand, pages, components, tech, research)",
+    "LLM-enrich draft extracts into concise Obsidian notes",
+    "auto-connect + sync vault into the knowledge bank for all critique personas"
+  ],
+  "forbidden_jobs": [
+    "UX, visual, business, or delight critique",
+    "invent files / APIs / components not in the extract",
+    "design generation or code edits in the scanned repo",
+    "run inside design-critic or ideation chains"
+  ],
+  "routing_triggers": ["collect_knowledge", "scan_codebase", "build_vault", "knowledge_archivist"],
+  "never_route_for": ["ux_friction", "full_screen_review", "delight", "stalemate"],
+  "chain_position": null,
+  "handoff_from": [],
+  "handoff_to": [],
+  "requires_session_state": true,
+  "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/router.json

@@ -1,6 +1,13 @@
 {
   "description": "MoE routing table — maps a classified problem type to the expert(s) that should run, and the experts that must never run for that problem type. Used by ux-story-gate Phase 1.5 and persona-orchestrator.",
   "rules": [
+    {
+      "problem_type": "ideation_wireframe",
+      "signals": ["wireframe", "mockup", "new screen", "design from scratch", "layout", "ia concept", "ideation", "ux ideator", "text wireframe", "screen layout"],
+      "route_to": ["ideation_chain"],
+      "never_route_to": ["design-critic_chain", "zara"],
+      "notes": "Uses ideation_chain from chain.json — full text wireframes via Noor + Anuj. Never the critique lite chain."
+    },
     {
       "problem_type": "structure_ia",
       "signals": ["structure", "ia", "navigation", "nested_ui", "information architecture", "wizard", "form flow"],
@@ -59,6 +66,13 @@
       "route_to": ["design-critic_chain"],
       "never_route_to": ["direct_noor_without_gate"],
       "notes": "Always enter through ux-story-gate, never call /noor directly without the gate."
+    },
+    {
+      "problem_type": "collect_knowledge",
+      "signals": ["collect knowledge", "scan codebase", "build vault", "knowledge archivist", "collect-knowledge"],
+      "route_to": ["kavi"],
+      "never_route_to": ["design-critic_chain", "zara", "arjun", "meera", "priya"],
+      "notes": "Producer only — run /collect-knowledge or `npx analyzthis_design collect`. Never part of a critique chain."
     }
   ]
 }

package/agents/session-schema.json

@@ -39,6 +39,8 @@
       "reason": "string — why not_run, when applicable (e.g. 'assess_only, no URL')"
     },
     "mode": "assess_only | build_approved",
+    "vault_path": "string — Obsidian vault written by Kavi collect (empty until first collect)",
+    "last_collect_at": "ISO 8601 timestamp — last successful collect run",
     "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"],