analyzthis_design 1.7.0 → 1.10.0

package/agents/chain.json

@@ -0,0 +1,55 @@
+{
+  "description": "Default sequential graph for a full multi-persona critique (design-critic). The MoE router in router.json selects a smaller subset of this chain by default; only run this full chain for an explicit full-screen review.",
+  "default_expert_budget": 2,
+  "default_chain": [
+    { "step": 1, "persona": "arjun",  "handoff_from": null,     "handoff_to": "meera",  "parallel_safe_with": [] },
+    { "step": 2, "persona": "meera",  "handoff_from": "arjun",  "handoff_to": "priya",  "parallel_safe_with": ["priya"] },
+    { "step": 3, "persona": "priya",  "handoff_from": "meera",  "handoff_to": "zara",   "parallel_safe_with": ["meera"] },
+    { "step": 4, "persona": "zara",   "handoff_from": "priya",  "handoff_to": null,     "parallel_safe_with": [] }
+  ],
+  "ideation_chain": [
+    { "step": 1, "persona": "meera", "handoff_to": ["noor", "anuj"], "parallel_safe_with": [] },
+    { "step": 2, "persona": "noor",  "handoff_from": "meera", "handoff_to": "arjun", "parallel_safe_with": ["anuj"] },
+    { "step": 2, "persona": "anuj",  "handoff_from": "meera", "handoff_to": "arjun", "parallel_safe_with": ["noor"] },
+    { "step": 3, "persona": "arjun", "handoff_from": ["noor", "anuj"], "handoff_to": "zara", "parallel_safe_with": [] },
+    { "step": 4, "persona": "zara",  "handoff_from": "arjun", "handoff_to": "priya", "parallel_safe_with": [] },
+    { "step": 5, "persona": "priya", "handoff_from": "zara",  "handoff_to": "raj", "parallel_safe_with": [] },
+    { "step": 6, "persona": "raj",   "handoff_from": "priya", "handoff_to": null, "parallel_safe_with": [] }
+  ],
+  "tiers": {
+    "router": null,
+    "extract": { "provider": "openai", "model": "gpt-4o-mini" },
+    "structured": { "provider": "openai", "model": "gpt-4o-mini" },
+    "critique": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" },
+    "arbitrate": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" }
+  },
+  "max_output_tokens": {
+    "structured": 900,
+    "critique": 1800,
+    "arbitrate": 1200
+  },
+  "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  },
+    "standard": { "provider": "google",    "model": "gemini-2.5-flash",    "max_output_tokens": 1200 },
+    "hard":     { "provider": "anthropic", "model": "claude-sonnet-5",     "max_output_tokens": 1800 }
+  },
+  "gate_override": {
+    "description": "Gates are safety nets — never run on a downgraded model. Any step whose gateName is listed here is pinned to use_effort regardless of the classified effort.",
+    "applies_to": ["ds_gate", "information_hierarchy_gate", "verify_gate"],
+    "use_effort": "hard"
+  },
+  "gates": [
+    { "name": "ds_gate", "runs": "before persona chain (ux-story-gate Phase 0.5); on failure, chain stops after arjun_color_system_only" },
+    { "name": "information_hierarchy_gate", "runs": "after persona chain, before re-evaluation/BLOCK escalation" },
+    { "name": "verify_gate", "runs": "after persona chain, before synthesis (ux-story-gate Phase 4.5); skipped (not_run) when assess_only with no URL" }
+  ],
+  "escalation": {
+    "condition": "stalemate or BLOCK verdict from any persona",
+    "route_to": "raj"
+  },
+  "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."
+  }
+}

package/agents/manifests/anuj.json

@@ -0,0 +1,31 @@
+{
+  "id": "anuj",
+  "role": "power_user",
+  "system_skill": "skills/anuj/SKILL.md",
+  "system_card": "agents/cards/anuj.md",
+  "tier": "critique",
+  "max_output_tokens": 1500,
+  "parallel_safe_with": ["noor"],
+  "inputs": ["task_map", "session_context", "information_hierarchy"],
+  "outputs": ["concept_b_wireframe"],
+  "allowed_tools": ["design-reference", "stacks"],
+  "allowed_jobs": [
+    "audit density, bulk actions, keyboard shortcuts for daily-use surfaces",
+    "produce Concept B wireframe",
+    "keep rank #1 of the declared information hierarchy prominent even at full density"
+  ],
+  "forbidden_jobs": [
+    "propose density audits for surfaces with task Frequency != daily/weekly",
+    "implement code without explicit build approval"
+  ],
+  "routing_triggers": ["daily_use", "data_density", "bulk_actions", "keyboard_shortcuts"],
+  "never_route_for": ["one_time_use_surfaces", "learning_products_without_daily_frequency"],
+  "chain_position": 1,
+  "handoff_from": [],
+  "handoff_to": ["arjun"],
+  "requires_session_state": true,
+  "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

@@ -0,0 +1,46 @@
+{
+  "id": "arjun",
+  "role": "ux_visual",
+  "system_skill": "skills/arjun/SKILL.md",
+  "system_card": "agents/cards/arjun.md",
+  "tier": "critique",
+  "max_output_tokens": 1800,
+  "parallel_safe_with": [],
+  "inputs": ["task_map", "session_context", "ds_checklist", "figma_context", "information_hierarchy"],
+  "outputs": ["ux_critique", "visual_audit", "combined_score"],
+  "allowed_tools": ["design-reference", "browser_verify", "figma_mcp"],
+  "allowed_jobs": [
+    "UX Honeycomb critique",
+    "Visual Design Audit (hierarchy, color, typography, spacing, components, style fit, micro-interactions)",
+    "diagnose visual issues against declared information hierarchy and DS tokens"
+  ],
+  "forbidden_jobs": [
+    "brand-system recovery as a primary job (diagnostic only — cite tokens, do not ship !important overrides)",
+    "delight pass (hand off to Zara)",
+    "implement code without explicit build approval"
+  ],
+  "routing_triggers": ["ux", "accessibility", "responsive", "interaction_bug", "visual_quality"],
+  "never_route_for": ["business_priority", "build_effort", "delight_moment"],
+  "chain_position": 2,
+  "handoff_from": ["noor"],
+  "handoff_to": ["meera"],
+  "requires_session_state": true,
+  "hard_gates": ["ds_gate", "information_hierarchy_gate"],
+  "scoped_modes": {
+    "arjun_color_system_only": {
+      "description": "Restricted scope used on DS Gate early-exit: only Color System + Typography contrast dimensions from the Visual Design Audit run, not the full Honeycomb + Visual Audit.",
+      "dimensions": ["color_system", "typography_contrast"],
+      "max_output_tokens": 700
+    }
+  },
+  "effort_overrides": {
+    "trivial": {
+      "when": "scoped_mode == arjun_color_system_only (single-dimension color/contrast diagnostic)",
+      "max_output_tokens": 700
+    },
+    "hard": {
+      "when": "full_chain == true || problem_type == full_screen_review (full Honeycomb + Visual Audit)",
+      "max_output_tokens": 1800
+    }
+  }
+}

package/agents/manifests/design-critic.json

@@ -0,0 +1,21 @@
+{
+  "id": "design-critic",
+  "role": "orchestrator",
+  "system_skill": "skills/design-critic/SKILL.md",
+  "inputs": ["task_map", "session_context", "figma_context", "ds_checklist"],
+  "outputs": ["composite_score", "task_finding_table", "verdict"],
+  "allowed_tools": ["design-reference", "browser_verify", "figma_mcp"],
+  "allowed_jobs": [
+    "run the full persona chain (Arjun -> Meera -> Priya -> Zara) for a full screen review",
+    "enforce the Information Hierarchy Gate",
+    "escalate to Raj on stalemate/BLOCK"
+  ],
+  "forbidden_jobs": [
+    "run without a completed ux-story-gate pass",
+    "implement code without explicit build approval"
+  ],
+  "routing_triggers": ["full_screen_review", "multi_persona_critique"],
+  "chain": ["arjun", "meera", "priya", "zara"],
+  "escalates_to": "raj",
+  "requires_session_state": true
+}

package/agents/manifests/meera.json

@@ -0,0 +1,31 @@
+{
+  "id": "meera",
+  "role": "business",
+  "system_skill": "skills/meera/SKILL.md",
+  "system_card": "agents/cards/meera.md",
+  "tier": "critique",
+  "max_output_tokens": 1200,
+  "parallel_safe_with": ["priya"],
+  "inputs": ["task_map", "session_context", "arjun_output", "information_hierarchy"],
+  "outputs": ["business_impact", "hierarchy_metric_check"],
+  "allowed_tools": ["design-reference"],
+  "allowed_jobs": [
+    "north-star metric impact assessment",
+    "segment / GTM / retention analysis",
+    "check that rank #1 on screen matches the actual business-critical driver"
+  ],
+  "forbidden_jobs": [
+    "visual or UX critique (route to Arjun)",
+    "implement code without explicit build approval"
+  ],
+  "routing_triggers": ["business_priority", "pricing", "access_control", "monetization", "retention"],
+  "never_route_for": ["visual_quality", "ia_structure"],
+  "chain_position": 3,
+  "handoff_from": ["arjun"],
+  "handoff_to": ["priya"],
+  "requires_session_state": true,
+  "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/noor.json

@@ -0,0 +1,32 @@
+{
+  "id": "noor",
+  "role": "information_architect",
+  "system_skill": "skills/noor/SKILL.md",
+  "system_card": "agents/cards/noor.md",
+  "tier": "critique",
+  "max_output_tokens": 1500,
+  "parallel_safe_with": ["anuj"],
+  "inputs": ["task_map", "session_context", "figma_context"],
+  "outputs": ["concept_a_wireframe", "information_hierarchy"],
+  "allowed_tools": ["design-reference"],
+  "allowed_jobs": [
+    "declare ranked information hierarchy",
+    "propose minimalist IA / progressive disclosure structure",
+    "produce Concept A wireframe"
+  ],
+  "forbidden_jobs": [
+    "brand token recovery",
+    "contrast / accessibility fixes (route to Arjun)",
+    "implement code without explicit build approval"
+  ],
+  "routing_triggers": ["structure", "ia", "navigation", "nested_ui", "wizard", "form"],
+  "never_route_for": ["brand", "contrast", "design_system_compliance"],
+  "chain_position": 1,
+  "handoff_from": [],
+  "handoff_to": ["arjun", "anuj"],
+  "requires_session_state": true,
+  "effort_overrides": {
+    "trivial": { "when": "hierarchy-only declaration", "max_output_tokens": 700 },
+    "hard": { "when": "multi-screen IA", "max_output_tokens": 1500 }
+  }
+}

package/agents/manifests/persona-orchestrator.json

@@ -0,0 +1,17 @@
+{
+  "id": "persona-orchestrator",
+  "role": "entry_point",
+  "system_skill": "skills/persona-orchestrator/SKILL.md",
+  "inputs": ["user_ask", "figma_url"],
+  "outputs": ["session_state", "task_finding_table", "verdict"],
+  "allowed_tools": ["design-reference", "figma_mcp", "browser_verify", "knowledge-bank"],
+  "allowed_jobs": [
+    "single entry point for agentic runs: load router + session, run ux-story-gate, execute chain or MoE subset, run gates, synthesize verdict"
+  ],
+  "forbidden_jobs": [
+    "bypass ux-story-gate phases 0-1.5",
+    "implement code without explicit build approval (respect assess-only mode)"
+  ],
+  "reads": ["agents/router.json", "agents/chain.json", "agents/session-schema.json"],
+  "requires_session_state": true
+}

package/agents/manifests/priya.json

@@ -0,0 +1,31 @@
+{
+  "id": "priya",
+  "role": "feasibility",
+  "system_skill": "skills/priya/SKILL.md",
+  "system_card": "agents/cards/priya.md",
+  "tier": "structured",
+  "max_output_tokens": 900,
+  "parallel_safe_with": ["meera"],
+  "inputs": ["task_map", "session_context", "meera_output", "tech_stack"],
+  "outputs": ["feasibility_analysis"],
+  "allowed_tools": ["design-reference", "stacks"],
+  "allowed_jobs": [
+    "T-shirt sizing (two-axis: UI x State)",
+    "risk and blocker identification",
+    "simpler-alternative sizing (modal vs accordion vs wizard, etc.)"
+  ],
+  "forbidden_jobs": [
+    "visual or business critique",
+    "implement code without explicit build approval"
+  ],
+  "routing_triggers": ["build_effort", "implementation_risk", "modal_vs_wizard", "state_machine"],
+  "never_route_for": ["visual_quality", "delight_moment"],
+  "chain_position": 4,
+  "handoff_from": ["meera"],
+  "handoff_to": ["zara"],
+  "requires_session_state": true,
+  "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/raj.json

@@ -0,0 +1,30 @@
+{
+  "id": "raj",
+  "role": "arbitrator",
+  "system_skill": "skills/raj/SKILL.md",
+  "system_card": "agents/cards/raj.md",
+  "tier": "arbitrate",
+  "max_output_tokens": 1200,
+  "parallel_safe_with": [],
+  "inputs": ["session_context", "persona_outputs"],
+  "outputs": ["arbitration_verdict"],
+  "allowed_tools": ["design-reference"],
+  "allowed_jobs": [
+    "resolve stalemates between personas using the 5 product principles",
+    "issue final SHIP / REVISE / BLOCK when personas disagree"
+  ],
+  "forbidden_jobs": [
+    "run when there is no stalemate or BLOCK condition",
+    "implement code without explicit build approval"
+  ],
+  "routing_triggers": ["stalemate", "block", "conflicting_verdicts"],
+  "never_route_for": ["routine_single_persona_critique"],
+  "chain_position": 6,
+  "handoff_from": ["zara", "arjun", "meera", "priya", "noor", "anuj"],
+  "handoff_to": [],
+  "requires_session_state": true,
+  "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/ux-story-gate.json

@@ -0,0 +1,23 @@
+{
+  "id": "ux-story-gate",
+  "role": "orchestrator",
+  "system_skill": "skills/ux-story-gate/SKILL.md",
+  "inputs": ["user_ask", "prd_sources", "figma_context", "knowledge_bank"],
+  "outputs": ["task_map", "ds_checklist", "routing_decision", "session_state"],
+  "allowed_tools": ["design-reference", "figma_mcp", "browser_verify", "knowledge-bank"],
+  "allowed_jobs": [
+    "Phase 0: discover PRDs/user stories, build task map",
+    "Phase 0.5: DS/Figma discovery, DS token checklist",
+    "Phase 1: mental model of user personas",
+    "Phase 1.5: MoE routing decision",
+    "Phase 4.5: browser verify gate",
+    "Phase 5.5: assess-only mode gate"
+  ],
+  "forbidden_jobs": [
+    "skip phases 0-1.5 before handing off to persona chain"
+  ],
+  "routing_triggers": ["any_screen_or_flow_review"],
+  "hands_off_to": "persona-orchestrator",
+  "requires_session_state": true,
+  "mandatory_first_step": true
+}

package/agents/manifests/zara.json

@@ -0,0 +1,32 @@
+{
+  "id": "zara",
+  "role": "delight",
+  "system_skill": "skills/zara/SKILL.md",
+  "system_card": "agents/cards/zara.md",
+  "tier": "critique",
+  "max_output_tokens": 1200,
+  "parallel_safe_with": [],
+  "inputs": ["task_map", "session_context", "priya_output", "ds_checklist"],
+  "outputs": ["delight_pass"],
+  "allowed_tools": ["design-reference"],
+  "allowed_jobs": [
+    "identify exactly ONE structural or surface delight moment",
+    "add delight on top of an already DS-compliant, hierarchy-correct foundation"
+  ],
+  "forbidden_jobs": [
+    "contrast fixes, token drift correction, or any brand/design-system recovery — these are out of scope for Zara; refuse and route to the DS Gate + Arjun",
+    "run before the ds_gate has passed",
+    "implement code without explicit build approval"
+  ],
+  "routing_triggers": ["delight_moment", "onboarding", "empty_state", "first_impression"],
+  "never_route_for": ["contrast", "brand_tokens", "design_system_compliance", "accessibility_fix"],
+  "requires_ds_gate_pass": true,
+  "chain_position": 5,
+  "handoff_from": ["priya"],
+  "handoff_to": [],
+  "requires_session_state": true,
+  "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

@@ -0,0 +1,64 @@
+{
+  "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": "structure_ia",
+      "signals": ["structure", "ia", "navigation", "nested_ui", "information architecture", "wizard", "form flow"],
+      "route_to": ["noor"],
+      "never_route_to": ["zara"]
+    },
+    {
+      "problem_type": "ux_friction",
+      "signals": ["ux friction", "accessibility", "responsive", "interaction bug", "usability"],
+      "route_to": ["arjun"],
+      "never_route_to": ["zara"],
+      "notes": "Zara is never used for contrast fixes."
+    },
+    {
+      "problem_type": "brand_design_system",
+      "signals": ["brand", "tokens", "contrast", "design system", "ds compliance", "hex", "!important"],
+      "route_to": ["ds_gate", "arjun_color_system_only"],
+      "never_route_to": ["zara", "noor_alone"],
+      "notes": "DS Gate runs first; Arjun is scoped to Color System diagnostic only, not a general critique."
+    },
+    {
+      "problem_type": "business_priority",
+      "signals": ["business priority", "metric alignment", "north-star", "monetization", "retention", "pricing"],
+      "route_to": ["meera"],
+      "never_route_to": []
+    },
+    {
+      "problem_type": "build_effort",
+      "signals": ["build size", "modal vs wizard", "feasibility", "effort sizing", "state machine"],
+      "route_to": ["priya"],
+      "never_route_to": []
+    },
+    {
+      "problem_type": "delight",
+      "signals": ["delight", "onboarding", "peak moment", "empty state", "first impression"],
+      "route_to": ["zara"],
+      "never_route_to": [],
+      "notes": "Only after the DS Gate has passed."
+    },
+    {
+      "problem_type": "daily_use_density",
+      "signals": ["daily use", "bulk actions", "density", "keyboard shortcuts", "power user"],
+      "route_to": ["anuj"],
+      "never_route_to": [],
+      "notes": "Not for learning products unless usage frequency is daily/weekly."
+    },
+    {
+      "problem_type": "stalemate",
+      "signals": ["stalemate", "block", "conflicting verdicts"],
+      "route_to": ["raj"],
+      "never_route_to": []
+    },
+    {
+      "problem_type": "full_screen_review",
+      "signals": ["full screen review", "critique this screen", "review this page"],
+      "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."
+    }
+  ]
+}

package/agents/session-schema.json

@@ -0,0 +1,61 @@
+{
+  "description": "Shape of session-state.json, persisted per project so Ask/Agent turns and persona hand-offs never re-derive context that was already gathered.",
+  "path": "~/.analyzthis_design/sessions/{project-id}/session-state.json",
+  "shape": {
+    "project_id": "string — derived from cwd or explicit --project flag",
+    "created_at": "ISO 8601 timestamp",
+    "updated_at": "ISO 8601 timestamp",
+    "task_map": [
+      {
+        "task": "string — primary user task",
+        "frequency": "daily | weekly | monthly | one_time",
+        "priority": "string"
+      }
+    ],
+    "figma_node": { "url": "string", "confirmed": "boolean" },
+    "content_sources": ["string — e.g. ppt, docx, prd, figma"],
+    "ds_checklist": {
+      "no_invented_hex": "boolean | null",
+      "no_important_overrides": "boolean | null",
+      "kit_components_preferred": "boolean | null",
+      "light_dark_from_tokens_only": "boolean | null",
+      "contrast_checked_against_wcag": "boolean | null"
+    },
+    "information_hierarchy": {
+      "declared_by": "noor | undeclared",
+      "ranking": ["string — rank #1 first"]
+    },
+    "routing_decision": {
+      "problem_type": "string — from agents/router.json",
+      "experts": ["string — persona ids"],
+      "reason": "string"
+    },
+    "persona_outputs": {
+      "<persona_id>": "object — structured output block per agents/manifests/<persona_id>.json"
+    },
+    "verify_results": {
+      "primary_task": "pass | fail | not_run",
+      "screenshots": ["string — file paths"],
+      "reason": "string — why not_run, when applicable (e.g. 'assess_only, no URL')"
+    },
+    "mode": "assess_only | build_approved",
+    "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"],
+      "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" },
+      "mode": "assess_only | build_approved"
+    },
+    "metrics": {
+      "llm_calls": "number — persona calls made in the last run",
+      "experts_run": ["string — persona ids actually executed"],
+      "input_tokens_est": "number — estimated input tokens across the last run",
+      "output_tokens_est": "number — estimated output tokens across the last run",
+      "cache_hits": "number — retrieve/cache hits during the last run",
+      "mode": "lite | full",
+      "effort_log": [{ "persona": "string", "effort": "trivial|standard|hard", "model": "string|null", "scoped_mode": "string|null" }],
+      "cost_usd": "number — estimated $ cost of the run from config.pricing (0 when pricing missing)"
+    }
+  }
+}