@skilly-hand/skilly-hand 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -16,6 +16,38 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.8.1] - 2026-04-04
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.8.1)
+
+### Added
+- _None._
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
+## [0.8.0] - 2026-04-04
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.8.0)
+
+### Added
+- Added portable skill `frontend-design` for project-aware UI component design that enforces stack detection before any design work.
+- Added portable skill `life-guard` for multi-perspective code and decision review using a committee + domain expert safety guard pattern.
+- Added portable skill `test-driven-development` for guiding the RED → GREEN → REFACTOR TDD cycle.
+
+### Changed
+- _None._
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.7.0] - 2026-04-04
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.7.0)
 

package/README.md

@@ -33,7 +33,6 @@
 ## Quick Start
 
 ```bash
-npm install
 npx skilly-hand
 ```
 
@@ -58,6 +57,10 @@ npx skilly-hand
 | `--json` | Emit machine-readable output and disable interactive prompts |
 | `--yes`, `-y` | Skip confirmation prompts for mutating commands (`install`, `uninstall`) |
 | `--dry-run` | Preview install plan without writing files |
+| `--agent`, `-a <name>` | Target a specific assistant (repeatable; e.g. `--agent claude --agent cursor`) |
+| `--include <tag>` | Only include skills matching the given tag |
+| `--exclude <tag>` | Exclude skills matching the given tag |
+| `--cwd <path>` | Run as if in a different directory |
 
 ---
 
@@ -69,8 +72,11 @@ The catalog currently includes:
 - `agents-root-orchestrator`
 - `angular-guidelines`
 - `figma-mcp-0to1`
+- `frontend-design`
+- `life-guard`
 - `skill-creator`
 - `spec-driven-development`
+- `test-driven-development`
 - `token-optimizer`
 
 See [catalog/README.md](./catalog/README.md) for generated skill metadata.
@@ -124,10 +130,6 @@ packages/
   core/                 # installation, rendering, and restore logic
   detectors/            # stack auto-detection
   catalog/              # catalog access and validation
-source/legacy/
-  agentic-structure/    # original material preserved as reference
-tests/
-  fixtures/             # simulated repos for integration testing
 ```
 
 ---

package/catalog/README.md

@@ -8,8 +8,11 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `agents-root-orchestrator` | Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | core, workflow, orchestration | all |
 | `angular-guidelines` | Guide Angular code generation and review using latest stable Angular verification and modern framework best practices. | angular, frontend, workflow, best-practices | all |
 | `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |
+| `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Never invents design decisions — reads the project first, confirms with the user, then designs. | frontend, design, workflow, ui | all |
+| `life-guard` | Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict. | core, review, workflow, quality | all |
 | `skill-creator` | Create and standardize AI skills with reusable structure, metadata rules, and templates. | core, workflow, authoring | all |
 | `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. | core, workflow, planning | all |
+| `test-driven-development` | Guide implementation using the RED → GREEN → REFACTOR TDD cycle: write a failing test first, write the minimum code to pass, then refactor while tests stay green. | testing, workflow, quality, core | all |
 | `token-optimizer` | Classify task complexity and right-size reasoning depth, context gathering, and response detail to reduce wasted tokens. | core, workflow, efficiency | all |
 
 Legacy source remains under `source/legacy/agentic-structure` and is excluded from installation.

package/catalog/catalog-index.json

@@ -3,7 +3,10 @@
   "agents-root-orchestrator",
   "angular-guidelines",
   "figma-mcp-0to1",
+  "frontend-design",
+  "life-guard",
   "skill-creator",
   "spec-driven-development",
+  "test-driven-development",
   "token-optimizer"
 ]

package/catalog/skills/frontend-design/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: frontend-design
+description: >
+  Project-aware frontend design skill that detects the existing tech stack, UI libraries,
+  CSS variables, and design tokens before proposing any UI work. Never invents design
+  decisions — reads the project first, confirms with the user, then designs.
+  Trigger: user asks to build, design, style, or update any UI component, page, or visual element in a frontend project.
+metadata:
+  author: skilly-hand
+  last-edit: 2026-04-04
+  license: Apache-2.0
+  version: "1.0.0"
+  changelog: "initial release; prevents AI slop design by enforcing project-aware stack detection before any design work; affects all frontend design and styling tasks"
+  auto-invoke: "design a component, create a UI, style this page, build a frontend, update the layout"
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write
+allowed-modes:
+  - stack-detector      # Scan the project for tech stack, UI libs, CSS vars, and design tokens
+  - component-designer  # Design and implement components following the confirmed project stack
+---
+
+# Frontend Design Guide
+
+## When to Use
+
+Use this skill when:
+
+- You are designing, building, or restyling a UI component, page, or layout in an existing project.
+- You are adding new visual elements that must match the project's existing design language.
+- You are refactoring styling or structure of frontend code to align with established patterns.
+- You need to choose between UI components, tokens, or styles already available in the project.
+
+Do not use this skill for:
+
+- Greenfield design system creation with no existing codebase to read from.
+- Backend, API, or data-layer tasks with no UI surface.
+- Design tool work (Figma, Sketch) unrelated to code implementation.
+- Projects where the user has explicitly opted out of stack detection.
+
+---
+
+## Routing Map
+
+Always run stack detection first. Never skip to design.
+
+| Step | Intent | Sub-agent |
+| --- | --- | --- |
+| 0 (always first) | Detect framework, UI library, CSS approach, tokens, and existing patterns | [agents/stack-detector.md](agents/stack-detector.md) |
+| 1 (only after confirmation) | Design and implement components using confirmed stack | [agents/component-designer.md](agents/component-designer.md) |
+
+---
+
+## Standard Execution Sequence
+
+1. **Run stack detection** — always start with `stack-detector`, no exceptions.
+2. **Present findings to the user** — surface the detected stack clearly and ask for explicit confirmation.
+3. **If anything is unclear or ambiguous, ask** — do not proceed with partial or uncertain information.
+4. **Scan existing tokens and components** — read what already exists before proposing anything.
+5. **Design with confirmed context only** — hand off to `component-designer` only after step 2 is complete.
+
+---
+
+## Critical Patterns
+
+### Pattern 1: Tech Stack Detection is Non-Negotiable
+
+Before writing a single line of UI code or proposing any design, run [agents/stack-detector.md](agents/stack-detector.md).
+
+This means:
+- Reading `package.json` to identify the framework and installed libraries.
+- Detecting CSS approach (Tailwind, CSS Modules, styled-components, Sass, vanilla).
+- Finding existing design tokens (CSS custom properties, theme files, `tokens.json`).
+- Sampling real components from the project to understand naming, structure, and styling conventions.
+
+If `package.json` is missing or the project root is unclear, stop and ask the user where to look.
+
+Never assume a library is present based on file extensions alone — verify it in dependencies.
+
+### Pattern 2: Never Invent Tokens — Read First
+
+Before using any color, spacing, font size, border radius, shadow, or z-index value:
+
+1. Search for CSS custom properties: `grep -r "var(--" src/`
+2. Check for a theme file: `tailwind.config.ts`, `theme.ts`, `tokens.json`, `_variables.scss`
+3. Check for a design system config: `@mui/material`, `chakra-ui/theme`, `shadcn/ui` config
+
+If the token does not exist in the project, do not invent it. Ask the user: "This project doesn't define a token for X. Should I add one, or is there an existing value I missed?"
+
+### Pattern 3: Confirm Before Every Design Decision
+
+At every fork — layout choice, component variant, color, interaction pattern — if the right answer is not derivable from the existing code, ask the user.
+
+Examples of things that require confirmation:
+- Which existing component to base a new one on.
+- Whether to use Tailwind utility classes or a CSS module.
+- Whether to match a specific existing page's spacing rhythm or start fresh.
+- Which breakpoints the project already targets.
+
+Short, specific questions are better than long ambiguous ones. One question at a time if possible.
+
+### Pattern 4: Follow the Project's Visual Language
+
+After stack detection, read 3–5 existing components before proposing any design. Identify:
+- The naming convention (PascalCase components, BEM CSS, camelCase tokens, etc.)
+- The composition pattern (atomic components, compound components, render props, slots)
+- The styling approach (co-located styles, global theme, utility-first classes)
+
+Every new component or style must feel like it was written by the same team that wrote the existing code — not imported from a different design system.
+
+---
+
+## What Not To Do
+
+These are the most critical rules. Violating any of them produces AI slop.
+
+- **Never assume a UI library is present** without verifying it in `package.json`. Shadcn and Radix look similar in JSX — check the deps.
+- **Never pick colors, fonts, or spacing values not already in the project**. If the project has no purple, do not introduce purple.
+- **Never use Inter as a default font** unless it is explicitly declared in the project. Inter is a sign of uncontextualized AI output.
+- **Never generate a component without reading at least one existing component first**. The project's conventions must be the template.
+- **Never apply a generic layout** (hero + cards + CTA, standard nav + footer) without verifying the project already uses or wants that structure.
+- **Never chain design decisions silently**. If one decision implies a downstream choice (e.g. using a grid library implies a layout system), surface it.
+- **Never proceed after ambiguity**. If the detected stack is inconsistent (e.g., Tailwind and styled-components both present), stop and ask which one is canonical.
+- **Never treat a partial stack detection as complete**. If `package.json` was readable but no component files were found, say so and ask for the component directory.
+- **Never ship a "placeholder" or "you can customize this later" design**. Every value must be intentional and project-derived.
+- **Never skip the confirmation step** even if the stack looks obvious. One confirmation prevents ten corrections.
+
+---
+
+## Decision Tree
+
+```text
+User asks for UI work
+  -> Has stack-detector been run and confirmed by user?
+       NO  -> Run stack-detector, present findings, ask for confirmation
+       YES -> Continue
+
+Is the requested component similar to an existing one in the project?
+  YES -> Read the existing component, use it as the structural and styling template
+  NO  -> Ask the user which existing component is closest, or if this is a net-new pattern
+
+Does the design require a token/value (color, spacing, font) not yet found in the project?
+  YES -> Ask the user: add a new token, use an existing one, or clarify?
+  NO  -> Use the existing token
+
+Is the CSS approach Tailwind?
+  YES -> Use only classes declared in tailwind.config; no arbitrary values unless project already uses them
+  NO  -> Continue
+
+Is the CSS approach CSS Modules or Sass?
+  YES -> Follow the naming convention of existing .module.css or .scss files exactly
+  NO  -> Continue
+
+Is the CSS approach styled-components or CSS-in-JS?
+  YES -> Match the theme structure; use theme.colors/spacing/typography from the existing theme provider
+  NO  -> Use whatever CSS approach was detected; if none detected, ask the user
+
+Ready to implement?
+  YES -> Hand off to component-designer with full confirmed context
+```
+
+---
+
+## Code Examples
+
+### Example 1: Detecting CSS custom properties in a project
+
+```bash
+# Find all CSS variables defined at :root
+grep -rn ":root" src/ --include="*.css" --include="*.scss"
+
+# Find all usages of CSS custom properties
+grep -rn "var(--" src/ --include="*.css" --include="*.scss" --include="*.tsx" --include="*.vue"
+```
+
+### Example 2: Identifying a Tailwind project and reading its token config
+
+```bash
+# Check if Tailwind is installed
+cat package.json | grep tailwind
+
+# Read the full color/spacing/font token config
+cat tailwind.config.ts
+```
+
+### Example 3: Sampling existing components to learn the pattern
+
+```bash
+# Find all component files in a React project
+find src/components -name "*.tsx" | head -5
+
+# Read one to understand structure and styling approach
+cat src/components/Button/Button.tsx
+```
+
+### Example 4: Detecting shadcn/ui vs MUI vs Chakra
+
+```bash
+# shadcn/ui (no package — installed as local files)
+ls src/components/ui/
+
+# MUI
+grep '"@mui/material"' package.json
+
+# Chakra UI
+grep '"@chakra-ui/react"' package.json
+
+# Radix Primitives (often underlies shadcn)
+grep '"@radix-ui' package.json
+```
+
+---
+
+## Commands
+
+```bash
+# Read project dependencies
+cat package.json | grep -A 50 '"dependencies"'
+
+# Detect CSS approach from file extensions
+find src -name "*.module.css" | head -3       # CSS Modules
+find src -name "*.module.scss" | head -3      # Sass Modules
+grep -rl "styled-components\|emotion" src/    # CSS-in-JS
+grep -rl "cn(\|clsx\|classnames" src/         # Tailwind class merging
+
+# Find design token files
+find . -name "tokens.json" -o -name "theme.ts" -o -name "_variables.scss" 2>/dev/null
+
+# List existing components
+find src/components -maxdepth 2 -name "*.tsx" -o -name "*.vue" | head -10
+```
+
+---
+
+## Resources
+
+- Stack detection procedure: [agents/stack-detector.md](agents/stack-detector.md)
+- Component design rules: [agents/component-designer.md](agents/component-designer.md)
+- Full scan checklist: [assets/stack-scan-checklist.md](assets/stack-scan-checklist.md)

package/catalog/skills/frontend-design/agents/component-designer.md

@@ -0,0 +1,95 @@
+# Component Designer
+
+## Precondition
+
+**Do not start without a confirmed stack summary from [stack-detector.md](stack-detector.md).**
+
+If the user asks you to design something and no confirmed stack summary exists, respond:
+"Before I design anything, I need to scan the project. Running stack detection first."
+Then invoke stack-detector. Do not skip this, even if the task feels small.
+
+---
+
+## When to Use
+
+Use this agent when:
+
+- Stack detection is complete and the user has confirmed the summary.
+- The user asks to build, style, or refactor a specific UI component or page section.
+- You need to design something new that must fit the project's existing visual language.
+
+Do not use this agent when:
+
+- Stack detection has not been run or confirmed.
+- The request is to redesign the entire application's design system.
+- The user explicitly asks for a greenfield design with no constraints.
+
+---
+
+## Design Rules
+
+These rules are absolute. No exceptions without explicit user confirmation.
+
+1. **Use only confirmed tokens.** Every color, spacing, font, shadow, and border-radius value must come from the confirmed stack summary. If a token does not exist, ask before inventing one.
+
+2. **Follow the sampled component structure.** The typing pattern, import style, prop naming, and composition approach must match what was observed in the sampled components. Do not introduce patterns from other frameworks or design systems.
+
+3. **Match the CSS approach exactly.** If the project uses Tailwind classes, use only classes present in `tailwind.config`. If the project uses CSS Modules, write a co-located `.module.css` file following the existing naming convention. If the project uses a theme object (MUI, Chakra), reference `theme.colors`, `theme.spacing`, etc.
+
+4. **Reference existing components, not external patterns.** When a new component is structurally similar to an existing one, start from that existing component. Do not start from a blank slate or an external design system example.
+
+5. **No placeholder values.** No `#000`, `16px`, `1rem` hardcoded without a corresponding token. No `/* TODO: replace with brand color */` comments. If you don't have the right value, ask.
+
+---
+
+## Questioning Protocol
+
+At every point of uncertainty, ask the user a short, specific question before proceeding.
+
+**Layout questions:**
+- "Should this component use the same grid as [ExistingPage], or does it have different spacing requirements?"
+- "The project breakpoints in tailwind.config are `sm`, `md`, `lg`. Should this component be responsive at all three, or only `md` and above?"
+
+**Style questions:**
+- "I see `--color-primary` and `--color-accent` in globals.css. Which one should this button use for its default state?"
+- "The existing Card uses `rounded-md`. Should this modal also use `rounded-md`, or does it need a sharper or rounder corner?"
+
+**Interaction / state questions:**
+- "Should this component have a loading state? I don't see a Skeleton or Spinner imported in other components — should I add one or skip it?"
+- "The existing Input has a `disabled` prop. Should this new Select also handle `disabled`?"
+
+**Composition questions:**
+- "Do you want this to accept children (composable) or receive structured props (data-driven)? The existing Card uses both — which pattern fits here?"
+
+One question at a time. Do not front-load a list of 8 questions before starting.
+
+---
+
+## Implementation Checklist
+
+Before finalizing any output, verify every item:
+
+- [ ] All color values come from confirmed project tokens, not hardcoded hex or named colors.
+- [ ] All spacing values use confirmed tokens (Tailwind classes, CSS vars, or theme values).
+- [ ] Typography (font family, size, weight, line-height) matches an existing usage in the codebase.
+- [ ] The component's file structure (location, naming, exports) matches the existing pattern.
+- [ ] The prop interface follows the same TypeScript conventions as sampled components.
+- [ ] The styling approach (Tailwind, CSS Module, styled, theme) is consistent with the confirmed stack.
+- [ ] No new dependencies were introduced without asking the user first.
+- [ ] No new design tokens were invented without explicit user approval.
+- [ ] The component was cross-referenced against at least one existing component for structural consistency.
+- [ ] Accessibility: semantic HTML elements, aria attributes consistent with existing components.
+
+---
+
+## What Finished Work Looks Like
+
+A finished component from this agent:
+
+- Reads like it was written by the existing team.
+- Uses the same imports, utilities, and style tokens as the rest of the codebase.
+- Has no values that can't be traced back to a confirmed project resource.
+- Includes no design decisions that weren't explicitly confirmed by the user or directly derived from existing code.
+- Has no "you can customize this" placeholder comments.
+
+If the output doesn't meet this bar, it is not done.

package/catalog/skills/frontend-design/agents/stack-detector.md

@@ -0,0 +1,154 @@
+# Stack Detector
+
+## Goal
+
+Surface a complete, verified picture of the project's frontend stack before any design work begins. This agent produces a **confirmed stack summary** that the component-designer requires as a precondition. Nothing gets designed until this output is validated by the user.
+
+Do not guess. Do not assume. Do not approximate. Every field in the output must come from something you actually read in the project.
+
+---
+
+## When to Use
+
+Run this agent:
+
+- At the very start of every frontend design task, before any other action.
+- When the user changes direction mid-task and a different part of the codebase is now in scope.
+- When the confirmed stack summary from a previous run is no longer current (e.g., user says "we migrated to Tailwind").
+
+Do not skip this agent:
+
+- Not even when the stack "looks obvious" from the file names.
+- Not even when the user describes the stack in plain language — descriptions can be outdated or incomplete.
+
+---
+
+## Scan Procedure
+
+Run these steps in order. Do not skip a step because a previous one seemed sufficient.
+
+### Step 1 — Read package.json
+
+```bash
+cat package.json
+```
+
+Extract:
+- Framework: `react`, `vue`, `@angular/core`, `svelte`, `next`, `nuxt`, `astro`, `remix`, etc.
+- UI component library: `@mui/material`, `@chakra-ui/react`, `@radix-ui/*`, `antd`, `@headlessui/react`, etc.
+- CSS-in-JS library: `styled-components`, `@emotion/react`, `@stitches/react`, `vanilla-extract`, etc.
+- CSS utilities: `tailwindcss`, `unocss`, `windicss`
+- Preprocessor: `sass`, `less`, `postcss`
+- Note the exact version of each — not just presence.
+
+If `package.json` is missing, ask: "I can't find package.json. Where is the project root?"
+
+### Step 2 — Detect CSS Approach
+
+One project may use multiple CSS strategies. Identify all of them.
+
+```bash
+# CSS Modules
+find src -name "*.module.css" -o -name "*.module.scss" | head -5
+
+# Tailwind (class-based utility)
+cat tailwind.config.ts 2>/dev/null || cat tailwind.config.js 2>/dev/null
+
+# styled-components or emotion
+grep -rl "styled\." src/ | head -3
+grep -rl "css\`" src/ | head -3
+
+# Global stylesheets
+find src -name "globals.css" -o -name "global.scss" -o -name "index.css" | head -3
+```
+
+If both Tailwind and styled-components are present, flag it: "I see both Tailwind and styled-components in this project. Which is the canonical styling approach for new components?"
+
+### Step 3 — Find Design Tokens
+
+```bash
+# CSS custom properties
+grep -rn ":root" src/ --include="*.css" --include="*.scss" | head -20
+
+# Tailwind config tokens
+cat tailwind.config.ts 2>/dev/null
+
+# Token files
+find . -name "tokens.json" -o -name "design-tokens.json" -o -name "_variables.scss" -o -name "variables.css" 2>/dev/null
+
+# Theme files (MUI, Chakra, custom)
+find src -name "theme.ts" -o -name "theme.tsx" -o -name "theme.js" | head -3
+```
+
+Extract and list the available tokens by category: colors, spacing, typography, border-radius, shadows.
+
+If no tokens are found, note it explicitly: "No design tokens were found. This project may be using hardcoded values or a library's default theme."
+
+### Step 4 — Detect shadcn/ui (special case)
+
+shadcn/ui is installed as local source files, not as a package. Detect it separately:
+
+```bash
+# shadcn/ui components live here
+ls src/components/ui/ 2>/dev/null
+
+# shadcn config
+cat components.json 2>/dev/null
+```
+
+If `components.json` exists, read it to understand the alias paths, CSS variable naming, and base color.
+
+### Step 5 — Sample Existing Components
+
+Read 3–5 existing component files. Choose a variety: a simple atomic component, a composite one, and if available, a page-level layout.
+
+```bash
+find src/components -maxdepth 2 -name "*.tsx" -o -name "*.vue" | head -10
+```
+
+For each sampled component, note:
+- How it imports and applies styles (classNames, css modules, theme tokens, Tailwind classes).
+- How props are typed and named.
+- Whether it uses composition patterns (children, slots, render props).
+- Any shared utility functions (e.g., `cn()`, `clsx()`, `twMerge()`).
+
+---
+
+## Confirmation Checklist
+
+Before handing off to component-designer, present the following summary to the user and ask for explicit confirmation:
+
+```
+Detected stack:
+  Framework:        [e.g. React 18 (Next.js 14)]
+  UI library:       [e.g. shadcn/ui (Radix + Tailwind) | None detected]
+  CSS approach:     [e.g. Tailwind CSS v3 with CSS Modules for overrides]
+  Design tokens:    [e.g. CSS vars in globals.css: --color-primary, --spacing-md, ...]
+                    OR [None found — using Tailwind config colors/spacing]
+  Component sample: [e.g. Button, Card, Modal — all use cn() + Tailwind classes]
+
+Does this match your project setup? Any corrections before I proceed?
+```
+
+Do not move forward until the user responds. A non-answer ("looks fine", "yes") is acceptable. Silence is not.
+
+---
+
+## Output Format
+
+After user confirmation, produce a structured stack summary to pass to component-designer:
+
+```
+CONFIRMED STACK SUMMARY
+-----------------------
+Framework:         React 18 / Next.js 14 (App Router)
+UI library:        shadcn/ui (components.json present, alias: @/components/ui)
+CSS approach:      Tailwind CSS v3; utility classes primary; no CSS Modules
+Design tokens:     Tailwind config (src/styles/tailwind.config.ts)
+                   CSS vars: --background, --foreground, --primary, --muted (globals.css)
+Style utilities:   cn() from @/lib/utils (clsx + tailwind-merge)
+Component pattern: Functional, TypeScript, props typed via interface, forwardRef on inputs
+Sampled:           Button.tsx, Card.tsx, Input.tsx
+```
+
+This summary is the required input for component-designer. If the summary cannot be completed, do not proceed.

package/catalog/skills/frontend-design/assets/stack-scan-checklist.md

@@ -0,0 +1,58 @@
+# Stack Scan Checklist
+
+Reference table for stack-detector. Use this to ensure no detection category is missed before producing the confirmed stack summary.
+
+---
+
+## Detection Categories
+
+| Category | What to Find | Where to Look | How to Detect | Confirmed? |
+| --- | --- | --- | --- | --- |
+| **Framework** | React, Vue, Angular, Svelte, Solid, Astro, etc. | `package.json` dependencies | `react`, `vue`, `@angular/core`, `svelte`, `astro` in deps | [ ] |
+| **Meta-framework** | Next.js, Nuxt, Remix, SvelteKit, etc. | `package.json`, config files | `next`, `nuxt`, `@remix-run/react` in deps; `next.config.*`, `nuxt.config.*` | [ ] |
+| **UI component library** | MUI, Chakra, shadcn, Radix, Headless, Ant, Mantine | `package.json` + component imports | `@mui/material`, `@chakra-ui/react`, `antd`, `@mantine/core`, `@headlessui/react`, or `components.json` | [ ] |
+| **shadcn/ui (special)** | Local shadcn component files | `src/components/ui/`, `components.json` | `ls src/components/ui/`; `cat components.json` | [ ] |
+| **CSS approach** | Tailwind, CSS Modules, styled-components, Emotion, Sass, vanilla | File extensions + package.json | `.module.css`, `.module.scss`, `styled.`, `css\``, `tailwindcss` in deps | [ ] |
+| **CSS preprocessor** | Sass/SCSS, Less, PostCSS | `package.json`, file extensions | `sass`, `less`, `postcss` in deps; `.scss`, `.less` files | [ ] |
+| **Design tokens (CSS vars)** | Custom properties at `:root` | Global CSS/SCSS files | `grep -rn ":root"` in stylesheets | [ ] |
+| **Design tokens (Tailwind)** | Extended colors, spacing, fonts | `tailwind.config.ts` / `tailwind.config.js` | `theme.extend.colors`, `theme.extend.spacing`, `theme.extend.fontFamily` | [ ] |
+| **Design tokens (theme file)** | MUI theme, Chakra theme, custom theme provider | `src/theme.ts`, `src/styles/theme.ts`, `ThemeProvider` usage | `cat theme.ts`; search for `createTheme`, `extendTheme`, `ThemeProvider` | [ ] |
+| **Design tokens (JSON)** | Figma tokens, Style Dictionary output | `tokens.json`, `design-tokens.json` | `find . -name "tokens.json"` | [ ] |
+| **Style utilities** | cn(), clsx(), classnames, twMerge | Utility files, component imports | `grep -rl "clsx\|cn(\|classnames\|twMerge" src/` | [ ] |
+| **Component location** | Where components live in the project | `src/components/`, `app/components/`, `components/` | `find src -maxdepth 3 -type d -name "components"` | [ ] |
+| **Naming convention** | PascalCase files, kebab-case files, flat vs nested | Sampled component file names | Read 3–5 component files | [ ] |
+| **TypeScript** | Typed props, interfaces, generics in use | File extensions, tsconfig | `.tsx`, `.ts` files; `typescript` in deps | [ ] |
+| **Existing breakpoints** | sm, md, lg, xl values | `tailwind.config`, global CSS, theme file | `theme.screens` in Tailwind; media queries in global CSS | [ ] |
+
+---
+
+## Ambiguity Flags
+
+Stop and ask the user if any of these are true:
+
+| Condition | Question to Ask |
+| --- | --- |
+| Both Tailwind and styled-components present | "Which is the canonical styling approach for new components?" |
+| Multiple UI libraries detected | "Are all of these in active use, or is one being deprecated?" |
+| No tokens found anywhere | "No design tokens were found. Are values hardcoded throughout, or is there a file I missed?" |
+| `components/ui/` exists but no `components.json` | "I see a `ui/` folder but no shadcn config. Is this shadcn, or a custom component library?" |
+| CSS Modules and Tailwind both in use | "Do new components use Tailwind, CSS Modules, or both? Which does the team prefer?" |
+| No component files found in expected locations | "Where does the project keep its UI components?" |
+| `package.json` exists but no lock file | "Is this project actively maintained? No lock file found — dependencies may be inconsistent." |
+
+---
+
+## Minimum Viable Summary
+
+The confirmed stack summary passed to component-designer must include all of the following. Any `[unknown]` field must be resolved with the user before proceeding.
+
+```
+Framework:         [name + version]
+Meta-framework:    [name + version] or [none]
+UI library:        [name + version] or [none]
+CSS approach:      [primary approach] + [secondary if applicable]
+Design tokens:     [source file(s) + list of key token categories available]
+Style utilities:   [e.g. cn() from @/lib/utils] or [none]
+Component pattern: [structural observation from sampled files]
+Sampled files:     [list of 3–5 file paths read]
+```