aios-core 2.1.6 → 2.2.0

package/.aios-core/development/tasks/setup-design-system.md

@@ -1,462 +1,462 @@
-# Setup Design System Structure
-
-> Task ID: atlas-setup-design-system
-> Agent: Atlas (Design System Builder)
-> Version: 1.0.0
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: setupDesignSystem()
-responsável: Uma (Empathizer)
-responsavel_type: Agente
-atomic_layer: Config
-
-**Entrada:**
-- campo: project_path
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Valid directory path
-
-- campo: options
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Initialization options
-
-**Saída:**
-- campo: initialized_project
-  tipo: string
-  destino: File system
-  persistido: true
-
-- campo: config_created
-  tipo: boolean
-  destino: Return value
-  persistido: false
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Directory is empty or force flag set; config valid
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check directory is empty or force flag set; config valid
-    error_message: "Pre-condition failed: Directory is empty or force flag set; config valid"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Project initialized; config files created; structure valid
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify project initialized; config files created; structure valid
-    error_message: "Post-condition failed: Project initialized; config files created; structure valid"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Project structure correct; all config files valid
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert project structure correct; all config files valid
-    error_message: "Acceptance criterion not met: Project structure correct; all config files valid"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** project-scaffolder
-  - **Purpose:** Generate project structure and config
-  - **Source:** .aios-core/scripts/project-scaffolder.js
-
-- **Tool:** config-manager
-  - **Purpose:** Initialize configuration files
-  - **Source:** .aios-core/utils/config-manager.js
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** init-project.js
-  - **Purpose:** Project initialization workflow
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/init-project.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Directory Not Empty
-   - **Cause:** Target directory already contains files
-   - **Resolution:** Use force flag or choose empty directory
-   - **Recovery:** Prompt for confirmation, merge or abort
-
-2. **Error:** Initialization Failed
-   - **Cause:** Error creating project structure
-   - **Resolution:** Check permissions and disk space
-   - **Recovery:** Cleanup partial initialization, log error
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 2-10 min (estimated)
-cost_estimated: $0.001-0.008
-token_usage: ~800-2,500 tokens
-```
-
-**Optimization Notes:**
-- Validate configuration early; use atomic writes; implement rollback checkpoints
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - automation
-  - workflow
-updated_at: 2025-11-17
-```
-
----
-
-
-## Description
-
-Initialize design system structure for greenfield or brownfield projects. Load tokens from Brad's .state.yaml or manual input, configure Tailwind v4 (`@theme`), bootstrap Shadcn utilities, and prepare Atlas for component generation.
-
-## Prerequisites
-
-- Node.js and npm installed (for React/TypeScript components)
-- Either: Brad's .state.yaml with tokens OR manual token files
-- Project has package.json (or Atlas will create one)
-
-## Workflow
-
-### Interactive Elicitation
-
-This task uses interactive elicitation to configure setup.
-
-1. **Detect Starting Point**
-   - Check for Brad's .state.yaml (brownfield from audit)
-   - If not found, ask for greenfield setup
-   - Confirm which approach to use
-
-2. **Load or Create Tokens**
-   - Brownfield: Load tokens from Brad's state
-   - Greenfield: Ask for tokens.yaml location or create template
-   - Validate token schema
-
-3. **Configure Project Structure**
-   - Ask for component output directory (default: `src/components/ui`)
-   - Confirm Tailwind v4 entry file (`app.css`) and token sources
-   - Decide on Radix/Slot usage, Shadcn component seeding
-   - Test framework (Jest/Vitest) + Storybook (yes/no)
-
-### Steps
-
-1. **Detect Brad's State**
-   - Search for .state.yaml in outputs/design-system/
-   - If found, validate tokenization phase completed
-   - If not found, prepare greenfield setup
-   - Validation: Starting point identified
-
-2. **Load Token Data**
-   - Brownfield: Read token locations from .state.yaml
-   - Greenfield: Prompt for tokens.yaml location
-   - Parse and validate token schema
-   - Check for required token categories (color, spacing, typography)
-   - Validation: Tokens loaded and valid
-
-3. **Create Directory Structure**
-   - Create `components/ui/` (atoms/molecules), `components/composite/`, `components/layout/`
-   - Create `lib/` for utilities (`utils.ts`, `cn`, helpers)
-   - Create `tokens/` directory (YAML, JSON, DTCG, platform exports)
-   - Create `docs/` (component docs, design guidelines)
-   - Create `__tests__/` for shared testing utilities
-   - Validation: Directory structure aligns with Atomic Design + Shadcn conventions
-
-4. **Copy Token Files**
-   - Copy tokens.yaml + tokens.dtcg.json + companion exports into `tokens/`
-   - Generate tokens/index.ts for centralized imports
-   - Ensure dark mode + semantic aliases available
-   - Validation: Tokens accessible in project (TS + runtime)
-
-5. **Initialize Package Dependencies**
-   - Check for React, TypeScript, and Tailwind packages
-   - Install `class-variance-authority`, `tailwind-merge`, `@radix-ui/react-slot`, `lucide-react`
-   - Add testing (`@testing-library/react`, `@testing-library/jest-dom`, `jest-axe`)
-   - Install Storybook 8 (if requested)
-   - Validation: `npm install` (or pnpm) completes without errors
-
-6. **Create Configuration Files**
-   - Generate/merge `tsconfig.json`, `jest.config.js`, `.storybook/` configs
-   - Create `app.css` (or `globals.css`) with `@import "tailwindcss";` and `@theme` definitions
-   - Add `.cursorrules`, ESLint, Prettier configs aligned with Tailwind v4
-   - Create `design-system.config.yaml` for Atlas settings
-   - Validation: Configuration files valid and documented
-
-7. **Generate Token Index**
-   - Create tokens/index.ts exporting typed getters (core/semantic/component)
-   - Provide helper functions for CSS variable access, `theme` helper for Tailwind
-   - Validation: `import { tokens } from '@/tokens'` works across components
-
-8. **Create Base Styles**
-   - Populate `app.css` with `@theme`, `@layer base/components/utilities`
-   - Add reset (modern-normalize), focus-visible, typography defaults
-   - Implement `[data-theme="dark"]` overrides and container queries
-   - Validation: Running Tailwind build yields expected utilities without warnings
-
-9. **Initialize State Tracking**
-   - Create or update `.state.yaml` for Atlas
-   - Record setup configuration (directories, tooling, dependencies)
-   - Capture Tailwind version, token coverage, shadcn components installed
-   - Set phase to "setup_complete"
-   - Validation: State file created
-
-10. **Generate Setup Report**
-    - Create setup-summary.md
-    - List all created files and directories
-    - Document next steps (build components)
-    - Validation: Setup documented
-
-## Output
-
-- **components/** directory structure (ui/, composite/, layout/)
-- **tokens/** with YAML + JSON + DTCG exports
-- **app.css** (or globals.css) with Tailwind `@theme` and base styles
-- **lib/utils.ts** with `cn` helper + shared utilities
-- **setup-summary.md** with configuration details
-- **.state.yaml** updated with Atlas setup data (tailwind/shadcn metadata)
-
-### Output Format
-
-```yaml
-# .state.yaml Atlas setup section
-atlas_setup:
-  completed_at: "2025-10-27T15:00:00Z"
-  starting_point: "brownfield"  # or "greenfield"
-
-  configuration:
-    component_directory: "src/components/ui"
-    css_approach: "tailwind_v4"
-    test_framework: "jest"
-    storybook_enabled: true
-    shadcn_enabled: true
-
-  tokens_loaded:
-    source: "Brad tokenization"
-    categories:
-      - color (12 tokens)
-      - spacing (7 tokens)
-      - typography (10 tokens)
-      - radius (4 tokens)
-      - shadow (3 tokens)
-    total_tokens: 36
-    validation: "passed"
-
-  directory_structure:
-    - components/ui/
-    - components/composite/
-    - components/layout/
-    - tokens/
-    - lib/
-    - docs/
-    - __tests__/
-
-  dependencies_added:
-    - "@testing-library/react"
-    - "@testing-library/jest-dom"
-    - "@storybook/react"
-    - "class-variance-authority"
-    - "tailwind-merge"
-    - "@radix-ui/react-slot"
-
-  phase: "setup_complete"
-  ready_for: "component_building"
-```
-
-## Success Criteria
-
-- [ ] Directory structure follows Atomic Design principles
-- [ ] Tokens (YAML + DTCG) loaded and validated successfully
-- [ ] Tailwind v4 `@theme` + layers configured and build succeeds
-- [ ] Package dependencies installed (React, Tailwind, cva, tailwind-merge, Radix)
-- [ ] Configuration files valid (tsconfig, jest, Storybook, .cursorrules)
-- [ ] Base styles created with tokens + dark mode parity
-- [ ] State tracking initialized (tooling, benchmarks, component paths)
-- [ ] Setup documented clearly (setup-summary.md)
-
-## Error Handling
-
-- **No tokens found**: Offer to create token template or prompt for manual input
-- **Invalid token schema**: Report specific errors, suggest fixes
-- **Missing dependencies**: Auto-install with npm or prompt user
-- **Directory exists**: Ask to overwrite or use different location
-- **Invalid project structure**: Warn user, continue with compatible setup
-
-## Security Considerations
-
-- Validate token file paths (no directory traversal)
-- Sanitize directory names
-- Don't execute code during setup
-- Validate package.json before modifying
-
-## Examples
-
-### Example 1: Brownfield Setup (From Brad)
-
-```bash
-*setup
-```
-
-Output:
-```
-🏗️ Atlas: Setting up design system structure...
-
-✓ Detected Brad's state: outputs/design-system/my-app/.state.yaml
-✓ Loading tokens from Brad's tokenization...
-  - 12 color tokens (OKLCH)
-  - 7 spacing tokens
-  - 10 typography tokens
-  - 6 component mappings
-  - Total: 36 tokens validated
-
-📁 Creating directory structure...
-  ✓ src/components/ui/
-  ✓ src/components/composite/
-  ✓ src/lib/utils.ts
-  ✓ tokens/ (yaml/json/dtcg)
-
-📦 Installing dependencies...
-  ✓ class-variance-authority
-  ✓ tailwind-merge
-  ✓ @radix-ui/react-slot
-  ✓ @testing-library/react + jest-axe
-  ✓ @storybook/react (optional)
-
-⚙️ Generating configuration...
-  ✓ tokens/index.ts (typed exports)
-  ✓ app.css with @theme + dark mode
-  ✓ jest.config.js / storybook-main.ts
-  ✓ .cursorrules (Tailwind v4 + Shadcn patterns)
-
-✅ Setup complete!
-
-Next steps:
-  1. Bootstrap Shadcn library: *bootstrap-shadcn
-  2. Build components: *build button
-  3. Generate docs: *document
-Atlas says: "Foundation is solid. Ready to build."
-```
-
-### Example 2: Greenfield Setup
-
-```bash
-*setup
-```
-
-Output:
-```
-🏗️ Atlas: No Brad state found. Starting greenfield setup...
-
-? Token source:
-  1. I have tokens.yaml
-  2. Create token template
-  3. Manual input
-
-User selects 1
-
-? Path to tokens.yaml: ./tokens/tokens.yaml
-
-✓ Tokens loaded and validated (24 tokens)
-
-? Component directory: src/components/ui
-? Tailwind entry file: src/app/app.css
-? Bootstrap Shadcn starter kit? Yes
-? Enable Storybook? Yes
-
-[...setup continues...]
-```
-
-## Notes
-
-- Brownfield setup is faster (tokens from Brad)
-- Greenfield requires manual token creation or import
-- Atomic Design + Shadcn structure (ui/, composite/, layout/)
-- All styling must use tokens/Tailwind utilities (no CSS modules)
-- Storybook 8 recommended for visual QA
-- `class-variance-authority`, `tailwind-merge`, Radix Slot installed by default
-- Atlas automatically creates TypeScript types for tokens
-- Base styles include CSS reset and token variables
-- Setup can be re-run safely (asks before overwriting)
-- Next step after setup: *build {pattern} to generate components
+# Setup Design System Structure
+
+> Task ID: atlas-setup-design-system
+> Agent: Atlas (Design System Builder)
+> Version: 1.0.0
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: setupDesignSystem()
+responsável: Uma (Empathizer)
+responsavel_type: Agente
+atomic_layer: Config
+
+**Entrada:**
+- campo: project_path
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid directory path
+
+- campo: options
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Initialization options
+
+**Saída:**
+- campo: initialized_project
+  tipo: string
+  destino: File system
+  persistido: true
+
+- campo: config_created
+  tipo: boolean
+  destino: Return value
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Directory is empty or force flag set; config valid
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check directory is empty or force flag set; config valid
+    error_message: "Pre-condition failed: Directory is empty or force flag set; config valid"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Project initialized; config files created; structure valid
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify project initialized; config files created; structure valid
+    error_message: "Post-condition failed: Project initialized; config files created; structure valid"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Project structure correct; all config files valid
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert project structure correct; all config files valid
+    error_message: "Acceptance criterion not met: Project structure correct; all config files valid"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** project-scaffolder
+  - **Purpose:** Generate project structure and config
+  - **Source:** .aios-core/scripts/project-scaffolder.js
+
+- **Tool:** config-manager
+  - **Purpose:** Initialize configuration files
+  - **Source:** .aios-core/utils/config-manager.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** init-project.js
+  - **Purpose:** Project initialization workflow
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/init-project.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Directory Not Empty
+   - **Cause:** Target directory already contains files
+   - **Resolution:** Use force flag or choose empty directory
+   - **Recovery:** Prompt for confirmation, merge or abort
+
+2. **Error:** Initialization Failed
+   - **Cause:** Error creating project structure
+   - **Resolution:** Check permissions and disk space
+   - **Recovery:** Cleanup partial initialization, log error
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 2-10 min (estimated)
+cost_estimated: $0.001-0.008
+token_usage: ~800-2,500 tokens
+```
+
+**Optimization Notes:**
+- Validate configuration early; use atomic writes; implement rollback checkpoints
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Description
+
+Initialize design system structure for greenfield or brownfield projects. Load tokens from Brad's .state.yaml or manual input, configure Tailwind v4 (`@theme`), bootstrap Shadcn utilities, and prepare Atlas for component generation.
+
+## Prerequisites
+
+- Node.js and npm installed (for React/TypeScript components)
+- Either: Brad's .state.yaml with tokens OR manual token files
+- Project has package.json (or Atlas will create one)
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to configure setup.
+
+1. **Detect Starting Point**
+   - Check for Brad's .state.yaml (brownfield from audit)
+   - If not found, ask for greenfield setup
+   - Confirm which approach to use
+
+2. **Load or Create Tokens**
+   - Brownfield: Load tokens from Brad's state
+   - Greenfield: Ask for tokens.yaml location or create template
+   - Validate token schema
+
+3. **Configure Project Structure**
+   - Ask for component output directory (default: `src/components/ui`)
+   - Confirm Tailwind v4 entry file (`app.css`) and token sources
+   - Decide on Radix/Slot usage, Shadcn component seeding
+   - Test framework (Jest/Vitest) + Storybook (yes/no)
+
+### Steps
+
+1. **Detect Brad's State**
+   - Search for .state.yaml in outputs/design-system/
+   - If found, validate tokenization phase completed
+   - If not found, prepare greenfield setup
+   - Validation: Starting point identified
+
+2. **Load Token Data**
+   - Brownfield: Read token locations from .state.yaml
+   - Greenfield: Prompt for tokens.yaml location
+   - Parse and validate token schema
+   - Check for required token categories (color, spacing, typography)
+   - Validation: Tokens loaded and valid
+
+3. **Create Directory Structure**
+   - Create `components/ui/` (atoms/molecules), `components/composite/`, `components/layout/`
+   - Create `lib/` for utilities (`utils.ts`, `cn`, helpers)
+   - Create `tokens/` directory (YAML, JSON, DTCG, platform exports)
+   - Create `docs/` (component docs, design guidelines)
+   - Create `__tests__/` for shared testing utilities
+   - Validation: Directory structure aligns with Atomic Design + Shadcn conventions
+
+4. **Copy Token Files**
+   - Copy tokens.yaml + tokens.dtcg.json + companion exports into `tokens/`
+   - Generate tokens/index.ts for centralized imports
+   - Ensure dark mode + semantic aliases available
+   - Validation: Tokens accessible in project (TS + runtime)
+
+5. **Initialize Package Dependencies**
+   - Check for React, TypeScript, and Tailwind packages
+   - Install `class-variance-authority`, `tailwind-merge`, `@radix-ui/react-slot`, `lucide-react`
+   - Add testing (`@testing-library/react`, `@testing-library/jest-dom`, `jest-axe`)
+   - Install Storybook 8 (if requested)
+   - Validation: `npm install` (or pnpm) completes without errors
+
+6. **Create Configuration Files**
+   - Generate/merge `tsconfig.json`, `jest.config.js`, `.storybook/` configs
+   - Create `app.css` (or `globals.css`) with `@import "tailwindcss";` and `@theme` definitions
+   - Add `.cursorrules`, ESLint, Prettier configs aligned with Tailwind v4
+   - Create `design-system.config.yaml` for Atlas settings
+   - Validation: Configuration files valid and documented
+
+7. **Generate Token Index**
+   - Create tokens/index.ts exporting typed getters (core/semantic/component)
+   - Provide helper functions for CSS variable access, `theme` helper for Tailwind
+   - Validation: `import { tokens } from '@/tokens'` works across components
+
+8. **Create Base Styles**
+   - Populate `app.css` with `@theme`, `@layer base/components/utilities`
+   - Add reset (modern-normalize), focus-visible, typography defaults
+   - Implement `[data-theme="dark"]` overrides and container queries
+   - Validation: Running Tailwind build yields expected utilities without warnings
+
+9. **Initialize State Tracking**
+   - Create or update `.state.yaml` for Atlas
+   - Record setup configuration (directories, tooling, dependencies)
+   - Capture Tailwind version, token coverage, shadcn components installed
+   - Set phase to "setup_complete"
+   - Validation: State file created
+
+10. **Generate Setup Report**
+    - Create setup-summary.md
+    - List all created files and directories
+    - Document next steps (build components)
+    - Validation: Setup documented
+
+## Output
+
+- **components/** directory structure (ui/, composite/, layout/)
+- **tokens/** with YAML + JSON + DTCG exports
+- **app.css** (or globals.css) with Tailwind `@theme` and base styles
+- **lib/utils.ts** with `cn` helper + shared utilities
+- **setup-summary.md** with configuration details
+- **.state.yaml** updated with Atlas setup data (tailwind/shadcn metadata)
+
+### Output Format
+
+```yaml
+# .state.yaml Atlas setup section
+atlas_setup:
+  completed_at: "2025-10-27T15:00:00Z"
+  starting_point: "brownfield"  # or "greenfield"
+
+  configuration:
+    component_directory: "src/components/ui"
+    css_approach: "tailwind_v4"
+    test_framework: "jest"
+    storybook_enabled: true
+    shadcn_enabled: true
+
+  tokens_loaded:
+    source: "Brad tokenization"
+    categories:
+      - color (12 tokens)
+      - spacing (7 tokens)
+      - typography (10 tokens)
+      - radius (4 tokens)
+      - shadow (3 tokens)
+    total_tokens: 36
+    validation: "passed"
+
+  directory_structure:
+    - components/ui/
+    - components/composite/
+    - components/layout/
+    - tokens/
+    - lib/
+    - docs/
+    - __tests__/
+
+  dependencies_added:
+    - "@testing-library/react"
+    - "@testing-library/jest-dom"
+    - "@storybook/react"
+    - "class-variance-authority"
+    - "tailwind-merge"
+    - "@radix-ui/react-slot"
+
+  phase: "setup_complete"
+  ready_for: "component_building"
+```
+
+## Success Criteria
+
+- [ ] Directory structure follows Atomic Design principles
+- [ ] Tokens (YAML + DTCG) loaded and validated successfully
+- [ ] Tailwind v4 `@theme` + layers configured and build succeeds
+- [ ] Package dependencies installed (React, Tailwind, cva, tailwind-merge, Radix)
+- [ ] Configuration files valid (tsconfig, jest, Storybook, .cursorrules)
+- [ ] Base styles created with tokens + dark mode parity
+- [ ] State tracking initialized (tooling, benchmarks, component paths)
+- [ ] Setup documented clearly (setup-summary.md)
+
+## Error Handling
+
+- **No tokens found**: Offer to create token template or prompt for manual input
+- **Invalid token schema**: Report specific errors, suggest fixes
+- **Missing dependencies**: Auto-install with npm or prompt user
+- **Directory exists**: Ask to overwrite or use different location
+- **Invalid project structure**: Warn user, continue with compatible setup
+
+## Security Considerations
+
+- Validate token file paths (no directory traversal)
+- Sanitize directory names
+- Don't execute code during setup
+- Validate package.json before modifying
+
+## Examples
+
+### Example 1: Brownfield Setup (From Brad)
+
+```bash
+*setup
+```
+
+Output:
+```
+🏗️ Atlas: Setting up design system structure...
+
+✓ Detected Brad's state: outputs/design-system/my-app/.state.yaml
+✓ Loading tokens from Brad's tokenization...
+  - 12 color tokens (OKLCH)
+  - 7 spacing tokens
+  - 10 typography tokens
+  - 6 component mappings
+  - Total: 36 tokens validated
+
+📁 Creating directory structure...
+  ✓ src/components/ui/
+  ✓ src/components/composite/
+  ✓ src/lib/utils.ts
+  ✓ tokens/ (yaml/json/dtcg)
+
+📦 Installing dependencies...
+  ✓ class-variance-authority
+  ✓ tailwind-merge
+  ✓ @radix-ui/react-slot
+  ✓ @testing-library/react + jest-axe
+  ✓ @storybook/react (optional)
+
+⚙️ Generating configuration...
+  ✓ tokens/index.ts (typed exports)
+  ✓ app.css with @theme + dark mode
+  ✓ jest.config.js / storybook-main.ts
+  ✓ .cursorrules (Tailwind v4 + Shadcn patterns)
+
+✅ Setup complete!
+
+Next steps:
+  1. Bootstrap Shadcn library: *bootstrap-shadcn
+  2. Build components: *build button
+  3. Generate docs: *document
+Atlas says: "Foundation is solid. Ready to build."
+```
+
+### Example 2: Greenfield Setup
+
+```bash
+*setup
+```
+
+Output:
+```
+🏗️ Atlas: No Brad state found. Starting greenfield setup...
+
+? Token source:
+  1. I have tokens.yaml
+  2. Create token template
+  3. Manual input
+
+User selects 1
+
+? Path to tokens.yaml: ./tokens/tokens.yaml
+
+✓ Tokens loaded and validated (24 tokens)
+
+? Component directory: src/components/ui
+? Tailwind entry file: src/app/app.css
+? Bootstrap Shadcn starter kit? Yes
+? Enable Storybook? Yes
+
+[...setup continues...]
+```
+
+## Notes
+
+- Brownfield setup is faster (tokens from Brad)
+- Greenfield requires manual token creation or import
+- Atomic Design + Shadcn structure (ui/, composite/, layout/)
+- All styling must use tokens/Tailwind utilities (no CSS modules)
+- Storybook 8 recommended for visual QA
+- `class-variance-authority`, `tailwind-merge`, Radix Slot installed by default
+- Atlas automatically creates TypeScript types for tokens
+- Base styles include CSS reset and token variables
+- Setup can be re-run safely (asks before overwriting)
+- Next step after setup: *build {pattern} to generate components