analyzthis_design 1.11.0 → 1.15.0

package/README.md

@@ -30,10 +30,12 @@ npx analyzthis_design --target windsurf
 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`.
+
 | Tool | Skills installed to | Invoke |
 |---|---|---|
-| Cursor | `~/.cursor/skills/<name>/SKILL.md` | `/collect-knowledge` |
-| Claude Code | `~/.claude/skills/<name>/SKILL.md` (+ legacy `~/.claude/commands/`) | `/collect-knowledge` |
+| 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` |
@@ -45,19 +47,29 @@ All skills use the **Agent Skills** `SKILL.md` standard — same files work acro
 
 ## Skills Overview
 
-### Entry points (start here)
+### Design — wireframes (start here for new screens)
+
+| Command | What it does |
+|---|---|
+| `/getting-started` | **First-run guide** — which command to use for wireframes vs critique |
+| `/design-director` | **Full producer path** — ideation → DesignSpec (tokens + components) → spec gates → implement when approved |
+| `/ux-ideator` | **Full ideation** — two competing text wireframes (minimalist vs dense), deliberation, delight, feasibility, DesignSpec |
+| `/design-spec` | **DesignSpec contract** — layout, tokens, component mapping, states (use with design-director) |
+| `/noor` | **Quick minimalist wireframe** — Concept A text wireframe, progressive disclosure |
+| `/anuj` | **Power-user wireframe** — Concept B text wireframe, density + bulk actions |
+
+### Evaluate — critique (existing designs)
 
 | Command | What it does |
 |---|---|
-| `/collect-knowledge` | **Kavi — Knowledge Archivist.** Scans the codebase, builds an Obsidian vault, LLM-enriches notes, syncs into the knowledge bank so every critique persona reads company context first. Run this once per project before critiques. |
-| `/persona-orchestrator` | **Recommended agentic critique 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. |
+| `/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 full screen evaluation, prefer `/persona-orchestrator` or `/ux-story-gate`. Run `/collect-knowledge` first so they have project context.
+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 |
 |---|---|---|
@@ -80,7 +92,7 @@ Invoke critique personas for targeted, already-grounded questions. For full scre
 
 ---
 
-## Agentic system (v1.11)
+## Agentic system (v1.15)
 
 ```
 User ask / Figma URL
@@ -150,20 +162,36 @@ Provider defaults live in `~/.analyzthis_design/config.json`:
     "claude-sonnet-5":   { "input_per_m": 2,    "output_per_m": 10 },
     "gpt-4o":            { "input_per_m": 2.50, "output_per_m": 10 }
   },
-  "research": { "provider": "https://example.com/search?q={query}" }
+  "research": { "provider": "https://example.com/search?q={query}" },
+  "collect": {
+    "web_urls": ["https://your-company.com/brand-guidelines"],
+    "web_queries": ["competitor onboarding patterns"],
+    "web_limit": 10,
+    "web_from_repo": true
+  }
 }
 ```
 
 The `effort_matrix` and `gate_override` live in `agents/chain.json` (not the user config) so they ship with the package and stay in sync with the agent graph. `pricing` is user-configured so you control your own $-cost reporting.
 
-**Web research:**
+**Web research (automatic in collect):**
+
+Kavi fetches URLs during `collect` — from config and from links in README/PRD markdown — and merges them into the knowledge bank. You usually do **not** need a separate `research` step.
+
+```bash
+npx analyzthis_design collect                    # repo + web URLs in one pass
+npx analyzthis_design collect --dry-run          # preview URLs Kavi will fetch
+npx analyzthis_design collect --no-web           # repo only
+```
+
+Manual research (optional, when you want one-off fetches without a full collect):
 
 ```bash
 npx analyzthis_design research --url https://example.com/design-tokens
 npx analyzthis_design research --query "EY design system tokens"
 ```
 
-Writes to `~/.analyzthis_design/sessions/{id}/web-context.md` and merges into the knowledge bank on `sync`.
+Writes to `~/.analyzthis_design/sessions/{id}/web-context.md` and merges into the knowledge bank on `sync` / `collect`.
 
 ---
 
@@ -262,6 +290,37 @@ Writes `{ system_card, digest, user, assistant }` JSONL pairs to `~/.analyzthis_
 
 ---
 
+## DesignSpec — Designer-grade handoff (v1.15)
+
+Personas can now guide **what** and **how** to design — not just critique.
+
+```
+/ux-ideator or /design-director
+        ↓
+  Text wireframe + information hierarchy
+        ↓
+  DesignSpec JSON (layout, tokens, components, states)
+        ↓
+  Spec gates: DS + hierarchy + Arjun visual
+        ↓
+  status: ship → implement (if build_approved)
+        ↓
+  Browser verify + delta critique
+```
+
+**DesignSpec** fields: `intent`, `information_hierarchy`, `layout.regions`, `tokens` (from your DS), `components[]` (real import paths), `states` (empty/loading/error/success), `do`/`dont`.
+
+```bash
+npx analyzthis_design spec template    # empty copy-paste block
+npx analyzthis_design spec validate --file design-spec.json
+npx analyzthis_design spec save --file design-spec.json
+npx analyzthis_design spec show
+```
+
+Schema: `agents/design-spec-schema.json`. Producer orchestration: `/design-director`.
+
+---
+
 ## UX Story Gate — How it works
 
 `/ux-story-gate` is the task-first gate for any screen evaluation:
@@ -281,32 +340,53 @@ Writes `{ system_card, digest, user, assistant }` JSONL pairs to `~/.analyzthis_
 
 ---
 
-## Knowledge collection — Kavi (v1.11)
+## Knowledge collection — Kavi (v1.14)
 
-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.
+Kavi is a **producer** persona (not a critic). One command scans the current repo, **discovers Obsidian vaults and knowledge graphs**, **fetches external URLs**, writes an Obsidian vault with dynamic `Sources/*.md` manifests, optionally enriches notes, then auto-connects and syncs everything into the knowledge bank.
 
 ```
 /collect-knowledge  (or  npx analyzthis_design collect)
         ↓
-  Scan codebase (gitignore-aware) → draft Obsidian notes
+  Scan codebase → draft Obsidian notes
+        ↓
+  Discover knowledge sources (.obsidian vaults, wikis, refs in README/docs)
         ↓
-  LLM enrich (batched; skip with --no-enrich if no API key)
+  Write Sources/*.md manifest notes + _meta/knowledge-sources.md
         ↓
-  ~/.analyzthis_design/vaults/{project-id}/
+  Auto-connect discovered vaults + fetch web URLs → web-context.md
         ↓
-  connect + sync → knowledge-bank skill
+  LLM enrich (optional)
         ↓
-  Arjun / Meera / … read company context first
+  connect + sync → knowledge bank (repo + vaults + web)
+        ↓
+  Personas read unified 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 --dry-run          # preview notes + URLs
+npx analyzthis_design collect --no-web           # skip external fetch
 npx analyzthis_design collect --no-enrich --limit 50
 npx analyzthis_design collect --vault ~/Documents/MyProjectVault --target claude
 ```
 
+Add external sources and vault paths in `~/.analyzthis_design/config.json`:
+
+```json
+{
+  "collect": {
+    "source_paths": ["~/Documents/MyCompanyVault"],
+    "scan_home_vaults": false,
+    "auto_connect_discovered": true,
+    "web_urls": ["https://your-company.com/brand-guidelines"],
+    "web_limit": 10
+  }
+}
+```
+
+Kavi auto-discovers: `.obsidian/` vaults in the repo, markdown wikis, knowledge-graph mentions, and vault paths referenced in README / AGENTS.md / docs. Each discovery gets a `Sources/*.md` manifest note fed into the knowledge bank.
+
 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.
@@ -338,15 +418,22 @@ 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
 
+# Design spec
+npx analyzthis_design spec template
+npx analyzthis_design spec validate --file design-spec.json
+npx analyzthis_design spec save --file design-spec.json
+npx analyzthis_design spec show
+
 # Knowledge collection (Kavi)
-npx analyzthis_design collect [--vault path] [--dry-run] [--no-enrich] [--limit N] [--target cursor|claude|grok|windsurf|agents|all]
+npx analyzthis_design collect [--vault path] [--dry-run] [--no-enrich] [--no-web] [--no-discover] [--web-limit N] [--target ...]
 
 # Knowledge bank
 npx analyzthis_design connect --vault <path> [--tags ...] [--include ...]
@@ -386,7 +473,8 @@ bin/cli.js              CLI entry point
 lib/
   install.js            Skill installation
   knowledge.js          Vault sync + web-context merge
-  collect.js            Kavi — codebase scan → Obsidian vault → enrich → sync
+  collect.js            Kavi — codebase scan → vault → source discovery → enrich → sync
+  source-discovery.js   Obsidian vault / wiki / knowledge-graph discovery + manifest MD
   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

package/agents/cards/design-director.md

@@ -0,0 +1,19 @@
+# Design Director (card)
+
+Producer orchestrator — ideation → **DesignSpec** → spec gates → implementation when `build_approved`.
+
+**Allowed:** run ux-ideator wireframes; synthesize DesignSpec; DS + hierarchy + Arjun spec validation; hand off SHIPped spec to host for TSX build; post-build verify.
+
+**Forbidden:** implement on `assess_only`; skip spec gates; code without `status: ship`.
+
+## Lite summary (for routing only)
+Use full `skills/design-director/SKILL.md` for any producer run — never lite for spec synthesis.
+
+## Spec gate checklist
+- DS: tokens from project, no invented hex
+- Hierarchy: rank #1 → `hierarchy_rank: 1` component
+- Arjun: type/spacing/contrast classes on spec
+- All pass → `status: ship` → build if approved
+
+## CLI
+`npx analyzthis_design spec show | validate | template`

package/agents/design-spec-schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "DesignSpec",
+  "description": "Machine-readable design contract produced after ideation. Guides WHAT to design and HOW (tokens, components, layout, states). Personas and the host LLM must not drift from a SHIPped spec.",
+  "type": "object",
+  "required": ["version", "screen_name", "status", "intent", "information_hierarchy", "layout", "tokens", "components", "states"],
+  "properties": {
+    "version": { "type": "string", "const": "1.0" },
+    "screen_name": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["draft", "spec_review", "ship", "revise"] },
+    "intent": {
+      "type": "object",
+      "required": ["primary_user_task", "primary_action"],
+      "properties": {
+        "primary_user_task": { "type": "string" },
+        "north_star_metric": { "type": "string" },
+        "primary_action": { "type": "string" },
+        "business_framing": { "type": "string" }
+      }
+    },
+    "information_hierarchy": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "layout": {
+      "type": "object",
+      "required": ["grid", "regions"],
+      "properties": {
+        "grid": { "type": "string", "description": "e.g. 12-col, single-column" },
+        "max_width": { "type": "string", "description": "Tailwind or token, e.g. max-w-7xl" },
+        "breakpoints": { "type": "array", "items": { "type": "string" } },
+        "nav_level": { "type": "string", "enum": ["L1", "L2", "L3"] },
+        "regions": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["name", "content"],
+            "properties": {
+              "name": { "type": "string" },
+              "span": { "type": "string" },
+              "content": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "tokens": {
+      "type": "object",
+      "required": ["colors", "typography", "spacing"],
+      "properties": {
+        "colors": { "type": "object", "additionalProperties": { "type": "string" } },
+        "typography": { "type": "object", "additionalProperties": { "type": "string" } },
+        "spacing": { "type": "object", "additionalProperties": { "type": "string" } },
+        "source": { "type": "string", "description": "tailwind.config | css-vars | figma | knowledge-bank" }
+      }
+    },
+    "components": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["region", "component"],
+        "properties": {
+          "region": { "type": "string" },
+          "component": { "type": "string" },
+          "import_path": { "type": "string" },
+          "variant": { "type": "string" },
+          "props": { "type": "object" },
+          "hierarchy_rank": { "type": "number", "minimum": 1 }
+        }
+      }
+    },
+    "states": {
+      "type": "object",
+      "required": ["empty", "loading", "error", "success"],
+      "properties": {
+        "empty": { "type": "string" },
+        "loading": { "type": "string" },
+        "error": { "type": "string" },
+        "success": { "type": "string" }
+      }
+    },
+    "motion": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "notes": { "type": "string" }
+      }
+    },
+    "do": { "type": "array", "items": { "type": "string" } },
+    "dont": { "type": "array", "items": { "type": "string" } },
+    "wireframe_ref": { "type": "string" },
+    "delight_moment": { "type": "string" },
+    "effort_estimate": { "type": "string" },
+    "citations": {
+      "type": "array",
+      "items": { "type": "string", "description": "[filename, row N: \"value\"] format" }
+    },
+    "spec_verdict": {
+      "type": "object",
+      "properties": {
+        "arjun_visual": { "enum": ["pass", "revise", "pending"] },
+        "ds_gate": { "enum": ["pass", "fail", "pending"] },
+        "hierarchy_gate": { "enum": ["pass", "fail", "pending"] },
+        "notes": { "type": "string" }
+      }
+    }
+  }
+}

package/agents/manifests/design-director.json

@@ -0,0 +1,26 @@
+{
+  "id": "design-director",
+  "role": "design_producer",
+  "system_skill": "skills/design-director/SKILL.md",
+  "system_card": "agents/cards/design-director.md",
+  "tier": "critique",
+  "max_output_tokens": 4000,
+  "parallel_safe_with": [],
+  "inputs": ["task_map", "ds_checklist", "design_spec", "knowledge_bank"],
+  "outputs": ["design_spec", "implementation_handoff", "verify_results"],
+  "allowed_tools": ["design-reference", "design-spec", "browser_verify", "figma_mcp"],
+  "allowed_jobs": [
+    "orchestrate ideation → DesignSpec → spec gates → implementation handoff",
+    "validate spec against DS and information hierarchy",
+    "guide host LLM implementation from SHIPped spec"
+  ],
+  "forbidden_jobs": [
+    "skip spec gates and jump to code",
+    "implement when mode is assess_only",
+    "invent components not in design_spec.components"
+  ],
+  "routing_triggers": ["design-director", "design spec", "guide how to design", "build this design", "implement spec"],
+  "never_route_for": ["full_screen_review_only"],
+  "chain_position": null,
+  "requires_session_state": true
+}

package/agents/router.json

@@ -1,6 +1,20 @@
 {
   "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": "design_director",
+      "signals": ["design-director", "design director", "guide how to design", "design and build", "implement the spec", "design spec build", "producer path"],
+      "route_to": ["design-director"],
+      "never_route_to": ["design-critic_chain"],
+      "notes": "Producer path — ideation → DesignSpec → spec gates → build. Use /design-director skill, not critique chain."
+    },
+    {
+      "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"],

package/agents/session-schema.json

@@ -39,6 +39,19 @@
       "reason": "string — why not_run, when applicable (e.g. 'assess_only, no URL')"
     },
     "mode": "assess_only | build_approved",
+    "design_spec": {
+      "version": "1.0",
+      "screen_name": "string",
+      "status": "draft | spec_review | ship | revise",
+      "intent": "object — primary_user_task, primary_action, north_star_metric",
+      "information_hierarchy": ["string — rank #1 first"],
+      "layout": "object — grid, regions, nav_level",
+      "tokens": "object — colors, typography, spacing, source",
+      "components": "array — region, component, import_path, hierarchy_rank",
+      "states": "object — empty, loading, error, success",
+      "spec_verdict": "object — arjun_visual, ds_gate, hierarchy_gate, notes",
+      "updated_at": "ISO 8601"
+    },
     "vault_path": "string — Obsidian vault written by Kavi collect (empty until first collect)",
     "last_collect_at": "ISO 8601 timestamp — last successful collect run",
     "digest": {
@@ -47,6 +60,7 @@
       "ds_at_risk": ["string — ds_checklist keys currently at risk"],
       "experts": ["string — persona ids selected for this run"],
       "prior_scores": { "<persona_id>": "number | string — last known score for delta re-evaluation" },
+      "design_spec_status": "draft | spec_review | ship | revise — shortcut from design_spec.status",
       "mode": "assess_only | build_approved"
     },
     "metrics": {