ganbatte-os 0.2.1

package/squads/design-squad/tasks/audit-design.md

@@ -0,0 +1,174 @@
+---
+task: auditDesign()
+responsavel: "@dave-malouf"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: true
+
+Entrada:
+  - campo: organization_context
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+  - campo: current_design_practice
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+
+Saida:
+  - campo: designAudit
+    tipo: string
+    destino: Console
+    persistido: false
+
+Checklist:
+  - "[ ] All three lenses assessed with scores and specific findings"
+  - "[ ] Top 3-5 highest-leverage improvements identified"
+  - "[ ] Phased roadmap created with milestones"
+---
+
+# Task: Design Audit & Maturity Assessment
+
+**Task ID:** DESIGN-002
+**Version:** 1.0.0
+**Command:** `*audit-design`
+**Agent:** Dave Malouf (dave-malouf) + Design Chief (design-chief)
+**Purpose:** Assess design maturity across three lenses and identify gaps with an improvement roadmap.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `organization_context` | Company size, stage, industry | YES |
+| `current_design_practice` | Team, tools, processes | YES |
+| `design_artifacts` | Existing designs, systems, docs | PREFERRED |
+| `stakeholder_concerns` | Pain points from leadership | NO |
+| `product_portfolio` | Products/services using design | NO |
+
+## Preconditions
+
+1. Access to current design practice information
+2. Understanding of organizational structure and design team placement
+3. Willingness to assess honestly (not just validate current approach)
+
+## Execution Phases
+
+### Phase 1: Assess Maturity (3 Lenses)
+
+**Lens 1: How We Work Together (People & Culture)**
+1. Team structure — centralized, embedded, hybrid?
+2. Role clarity — are design roles well-defined?
+3. Career paths — do designers have growth trajectories?
+4. Hiring practices — how is design talent evaluated?
+5. Cross-functional collaboration — how do design, engineering, and product interact?
+6. Design culture — is design valued at the leadership level?
+7. Rate: Ad Hoc (1) → Emerging (2) → Defined (3) → Managed (4) → Optimized (5)
+
+**Lens 2: How We Work (Process & Workflow)**
+1. Design process — is there a consistent methodology?
+2. Research practice — how are user insights gathered and used?
+3. Handoff process — how do designs get to engineers?
+4. Quality assurance — how is design quality verified?
+5. Feedback loops — how do teams learn from shipped products?
+6. Tooling — is the tool stack consistent and efficient?
+7. Rate: Ad Hoc (1) → Emerging (2) → Defined (3) → Managed (4) → Optimized (5)
+
+**Lens 3: What We Work On (Craft & Output)**
+1. Design system — does one exist? Is it used consistently?
+2. Accessibility — is WCAG compliance standard practice?
+3. Visual consistency — are products visually coherent?
+4. UX quality — are products usable and intuitive?
+5. Innovation — is the team pushing design boundaries?
+6. Documentation — are design decisions recorded and shared?
+7. Rate: Ad Hoc (1) → Emerging (2) → Defined (3) → Managed (4) → Optimized (5)
+
+### Phase 2: Identify Gaps
+
+1. Map current maturity scores across all three lenses
+2. Identify the lowest-scoring lens — this is the primary bottleneck
+3. Within each lens, identify specific gaps:
+   - What exists but is broken or inconsistent?
+   - What is entirely missing?
+   - What is working well and should be preserved?
+4. Cross-reference gaps — do people gaps cause process gaps cause craft gaps?
+5. Benchmark against industry standards for the company's stage and size
+6. Identify the 3-5 highest-leverage improvements
+
+### Phase 3: Recommend Improvements
+
+1. For each identified gap, recommend a specific intervention:
+   - **Quick wins** (1-2 weeks) — Low effort, immediate impact
+   - **Short-term** (1-3 months) — Moderate effort, significant improvement
+   - **Long-term** (3-12 months) — Strategic investment for lasting change
+2. Prioritize by impact and feasibility
+3. Identify dependencies — what must happen first?
+4. Estimate resource requirements — people, tools, budget
+5. Define success metrics for each improvement
+
+### Phase 4: Build Roadmap
+
+1. Create a phased improvement roadmap:
+   - **Phase 1 (Month 1-2):** Foundation — Quick wins + critical fixes
+   - **Phase 2 (Month 3-6):** Building — Process standardization + tooling
+   - **Phase 3 (Month 6-12):** Scaling — Culture change + advanced practices
+2. Define milestones and checkpoints
+3. Assign ownership for each initiative
+4. Create a measurement plan — how will progress be tracked?
+5. Plan for communication — how will the organization be informed and engaged?
+6. Define the governance model for ongoing design maturity improvement
+
+## Output Format
+
+```yaml
+design_audit:
+  auditors: [dave-malouf, design-chief]
+  organization: "{company}"
+  maturity_scores:
+    people_culture:
+      score: 0
+      level: "Ad Hoc | Emerging | Defined | Managed | Optimized"
+      strengths: ["{what works}"]
+      gaps: ["{what is missing}"]
+    process_workflow:
+      score: 0
+      level: "Ad Hoc | Emerging | Defined | Managed | Optimized"
+      strengths: ["{what works}"]
+      gaps: ["{what is missing}"]
+    craft_output:
+      score: 0
+      level: "Ad Hoc | Emerging | Defined | Managed | Optimized"
+      strengths: ["{what works}"]
+      gaps: ["{what is missing}"]
+  overall_maturity: 0
+  primary_bottleneck: "{lowest scoring lens}"
+  top_improvements:
+    - improvement: "{description}"
+      impact: "HIGH | MEDIUM | LOW"
+      effort: "HIGH | MEDIUM | LOW"
+      timeline: "quick_win | short_term | long_term"
+  roadmap:
+    phase_1: ["{foundation items}"]
+    phase_2: ["{building items}"]
+    phase_3: ["{scaling items}"]
+  measurement_plan: ["{metrics to track}"]
+```
+
+## Veto Conditions
+
+- **NEVER** assess maturity without considering all three lenses — they are interconnected
+- **NEVER** recommend advanced practices for an organization at Ad Hoc maturity — meet them where they are
+- **NEVER** ignore people and culture — process and tools fail without the right culture
+- **NEVER** create a roadmap without clear ownership and milestones
+- **NEVER** skip the strengths assessment — build on what works, do not only focus on gaps
+
+## Completion Criteria
+
+- [ ] All three lenses assessed with scores and specific findings
+- [ ] Gaps identified and cross-referenced across lenses
+- [ ] Top 3-5 highest-leverage improvements identified
+- [ ] Improvements prioritized by impact and feasibility
+- [ ] Phased roadmap created with milestones
+- [ ] Measurement plan defined for tracking progress
+- [ ] Ownership assigned for each initiative

package/squads/design-squad/tasks/create-component-spec.md

@@ -0,0 +1,185 @@
+---
+task: createComponentSpec()
+responsavel: "@design-system-architect"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: true
+
+Entrada:
+  - campo: component_name
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+  - campo: tech_stack
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+
+Saida:
+  - campo: componentSpec
+    tipo: string
+    destino: Console
+    persistido: false
+
+Checklist:
+  - "[ ] All variants specified (size, intent, state, layout, content)"
+  - "[ ] Design tokens mapped with fallback chain"
+  - "[ ] Accessibility requirements complete (ARIA, keyboard, screen reader)"
+---
+
+# Task: Component Specification
+
+**Task ID:** DESIGN-004
+**Version:** 1.0.0
+**Command:** `*create-component-spec`
+**Agent:** Design System Architect (design-system-architect) + Brad Frost (brad-frost)
+**Purpose:** Create a complete component specification with variants, tokens, accessibility, and API documentation.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `component_name` | User request | YES |
+| `component_purpose` | What problem it solves | YES |
+| `design_system_context` | Existing tokens and patterns | PREFERRED |
+| `tech_stack` | Framework (React, Vue, Svelte, etc.) | YES |
+| `usage_context` | Where it will be used | PREFERRED |
+| `reference_examples` | Existing implementations to reference | NO |
+
+## Preconditions
+
+1. Component purpose is clearly defined
+2. Design token system exists (or will be created alongside)
+3. Tech stack is known for API design
+
+## Execution Phases
+
+### Phase 1: Define Purpose
+
+1. State the component's purpose — what user need does it serve?
+2. Identify where it sits in the atomic hierarchy: atom, molecule, or organism
+3. List use cases — where will this component appear?
+4. Define what this component is NOT (prevent scope creep)
+5. Check existing components — can an existing component be extended instead?
+6. Identify component dependencies — what atoms/molecules does it compose?
+
+### Phase 2: Design Variants
+
+1. **Size variants** — sm, md, lg (where applicable)
+2. **Color/intent variants** — primary, secondary, danger, warning, success, neutral
+3. **State variants:**
+   - Default (resting state)
+   - Hover (mouse over)
+   - Focus (keyboard focus — visible focus ring)
+   - Active (being clicked/pressed)
+   - Disabled (non-interactive)
+   - Loading (async operation in progress)
+   - Error (validation failure)
+   - Selected/Checked (toggle state)
+4. **Layout variants** — inline, block, full-width, responsive behavior
+5. **Content variants** — with/without icon, with/without description, truncation behavior
+6. For each variant, define visual specifications: colors, spacing, typography, borders
+
+### Phase 3: Specify Tokens
+
+1. Map component styles to design tokens (never use raw values):
+   - Background: `{component}-{variant}-bg`
+   - Text: `{component}-{variant}-text`
+   - Border: `{component}-{variant}-border`
+   - Shadow: `{component}-{variant}-shadow`
+   - Spacing: `{component}-padding-{size}`
+   - Typography: `{component}-font-{property}`
+2. Define token fallback chain: component token → alias token → global token
+3. Ensure all color tokens support dark mode theming
+4. Document which tokens are customizable vs locked
+5. Verify contrast ratios meet WCAG AA (4.5:1 text, 3:1 UI elements)
+
+### Phase 4: Document API
+
+1. **Props/Attributes:**
+   - Name, type, default value, description
+   - Required vs optional
+   - Valid values for enums
+2. **Events/Callbacks:**
+   - Event name, payload, when it fires
+3. **Slots/Children:**
+   - Named slots and their expected content
+   - Default slot behavior
+4. **Accessibility:**
+   - ARIA role and attributes
+   - Keyboard interaction pattern (Tab, Enter, Space, Arrow keys, Escape)
+   - Screen reader announcement behavior
+   - Focus management (where focus goes, trap behavior)
+   - Color contrast verification
+5. **Responsive Behavior:**
+   - Breakpoint-specific adaptations
+   - Touch target sizes (minimum 44x44px)
+   - Mobile-specific interactions
+6. **Code Examples:**
+   - Basic usage
+   - Each variant
+   - Composition with other components
+   - Common patterns
+
+## Output Format
+
+```yaml
+component_spec:
+  name: "{component name}"
+  creators: [design-system-architect, brad-frost]
+  atomic_level: "atom | molecule | organism"
+  purpose: "{what it does}"
+  dependencies: ["{required sub-components}"]
+  variants:
+    sizes: ["{size list}"]
+    intents: ["{intent list}"]
+    states: ["{state list}"]
+  tokens:
+    - token: "{token name}"
+      value: "{default value}"
+      customizable: true
+      dark_mode: "{dark value}"
+  props:
+    - name: "{prop name}"
+      type: "{type}"
+      default: "{default}"
+      required: true
+      description: "{what it controls}"
+  events:
+    - name: "{event name}"
+      payload: "{data type}"
+      description: "{when it fires}"
+  accessibility:
+    role: "{ARIA role}"
+    keyboard: ["{interaction pattern}"]
+    announcements: ["{screen reader behavior}"]
+    contrast: "verified AA"
+  responsive:
+    breakpoints: ["{adaptations}"]
+    touch_target: "44x44px minimum"
+  code_examples:
+    basic: "{code}"
+    variants: "{code}"
+    composition: "{code}"
+```
+
+## Veto Conditions
+
+- **NEVER** specify a component without accessibility requirements — they are not optional
+- **NEVER** use raw color/spacing values — always reference design tokens
+- **NEVER** skip interactive states — hover, focus, active, and disabled are mandatory
+- **NEVER** create a component that duplicates an existing component's purpose
+- **NEVER** omit keyboard interaction patterns — not all users use a mouse
+
+## Completion Criteria
+
+- [ ] Component purpose defined with clear scope
+- [ ] All variants specified (size, intent, state, layout, content)
+- [ ] Design tokens mapped with fallback chain
+- [ ] Props/API fully documented with types and defaults
+- [ ] Accessibility requirements complete (ARIA, keyboard, screen reader)
+- [ ] Responsive behavior defined with touch targets
+- [ ] Code examples provided for all major use cases
+- [ ] Dark mode token values defined

package/squads/design-squad/tasks/create-design-system.md

@@ -0,0 +1,179 @@
+---
+task: createDesignSystem()
+responsavel: "@brad-frost"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: true
+
+Entrada:
+  - campo: project_context
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+  - campo: tech_stack
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+
+Saida:
+  - campo: designSystem
+    tipo: string
+    destino: Console
+    persistido: false
+
+Checklist:
+  - "[ ] Interface audit completed with inconsistencies documented"
+  - "[ ] All design tokens defined (colors, typography, spacing, borders, shadows)"
+  - "[ ] Documentation complete with examples and contribution guide"
+---
+
+# Task: Atomic Design System Creation
+
+**Task ID:** DESIGN-001
+**Version:** 1.0.0
+**Command:** `*create-design-system`
+**Agent:** Brad Frost (brad-frost) + Dan Mall (dan-mall)
+**Purpose:** Build a complete atomic design system from audit through atoms, molecules, organisms, and documentation.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `project_context` | Application or product description | YES |
+| `brand_guidelines` | Colors, typography, logos | PREFERRED |
+| `existing_ui` | Current interface screenshots or code | PREFERRED |
+| `tech_stack` | Frontend framework and tools | YES |
+| `team_size` | Design and dev team size | NO |
+| `accessibility_requirements` | WCAG level target | NO (default: AA) |
+
+## Preconditions
+
+1. Project context and tech stack are defined
+2. Brand guidelines exist (even minimal — colors and fonts at minimum)
+3. Understanding of who will consume the design system (designers, developers, both)
+
+## Execution Phases
+
+### Phase 1: Audit Existing (brad-frost)
+
+1. Conduct interface inventory — screenshot every unique component
+2. Categorize existing UI elements by type:
+   - Colors, typography, spacing, icons, borders, shadows
+   - Buttons, inputs, labels, badges, links
+   - Cards, forms, navigation, modals, tables
+   - Page layouts, templates, responsive patterns
+3. Identify inconsistencies — how many variations of the same component exist?
+4. Assess current accessibility — WCAG compliance of existing elements
+5. Document the "component zoo" — everything that exists today
+6. Identify the 20% of components that cover 80% of the interface
+
+### Phase 2: Define Atoms (brad-frost)
+
+1. **Color tokens** — Define global palette, semantic colors, and component-level aliases
+   - Global: brand colors, neutrals, feedback colors (success, warning, error, info)
+   - Semantic: text-primary, text-secondary, bg-surface, bg-canvas, border-default
+   - Component: button-primary-bg, input-border, card-shadow
+2. **Typography tokens** — Font families, sizes, weights, line heights, letter spacing
+   - Scale: xs, sm, base, lg, xl, 2xl, 3xl, 4xl
+   - Semantic: heading-1 through heading-6, body, caption, label, code
+3. **Spacing tokens** — Consistent spacing scale (4px base unit recommended)
+   - Scale: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24
+4. **Border tokens** — Radius scale, border widths, styles
+5. **Shadow tokens** — Elevation levels (sm, md, lg, xl)
+6. **Animation tokens** — Duration, easing, transition properties
+7. **Breakpoint tokens** — Responsive breakpoints
+8. Document each atom with usage guidelines
+
+### Phase 3: Build Molecules & Organisms (brad-frost + dan-mall)
+
+**Molecules (simple component groups):**
+1. Button group (button + icon + label)
+2. Input field (label + input + helper text + error message)
+3. Search bar (input + button + icon)
+4. Media object (image + text block)
+5. Navigation item (icon + label + badge)
+6. Card header (avatar + title + subtitle + action)
+
+**Organisms (complex component groups):**
+1. Navigation bar (logo + nav items + search + user menu)
+2. Form section (heading + description + multiple input fields + actions)
+3. Data table (header + rows + pagination + filters)
+4. Card (header + media + content + footer + actions)
+5. Modal (overlay + header + content + footer actions)
+6. Sidebar (logo + navigation + user info + footer)
+
+For each component:
+- Define variants (size, color, state)
+- Specify interactive states (default, hover, focus, active, disabled, loading)
+- Document props/API
+- Write accessibility requirements (ARIA roles, keyboard nav, screen reader)
+- Create responsive behavior specification
+
+### Phase 4: Document (dan-mall)
+
+1. **Getting Started** — Installation, setup, and first component usage
+2. **Design Principles** — The "why" behind design decisions
+3. **Token Reference** — Complete token catalog with visual examples
+4. **Component Catalog** — Each component with:
+   - Description and purpose
+   - Live examples with all variants
+   - Props/API documentation
+   - Do's and Don'ts with visual examples
+   - Accessibility notes
+   - Code snippets (copy-paste ready)
+5. **Pattern Library** — Common compositions and layouts
+6. **Contribution Guide** — How to add/modify components
+7. **Governance Model** — Who approves changes, versioning, deprecation process
+
+## Output Format
+
+```yaml
+design_system:
+  name: "{system name}"
+  creators: [brad-frost, dan-mall]
+  methodology: "Atomic Design"
+  tech_stack: "{framework}"
+  accessibility_target: "WCAG 2.1 AA"
+  tokens:
+    colors: "{token count}"
+    typography: "{token count}"
+    spacing: "{token count}"
+    borders: "{token count}"
+    shadows: "{token count}"
+  components:
+    atoms: ["{list}"]
+    molecules: ["{list}"]
+    organisms: ["{list}"]
+    templates: ["{list}"]
+  documentation:
+    getting_started: true
+    token_reference: true
+    component_catalog: true
+    pattern_library: true
+    contribution_guide: true
+    governance_model: true
+  governance:
+    versioning: "semver"
+    approval_process: "{description}"
+    deprecation_policy: "{description}"
+```
+
+## Veto Conditions
+
+- **NEVER** skip the audit phase — building without understanding what exists creates duplication
+- **NEVER** define components without accessibility from the start — retrofitting is 10x harder
+- **NEVER** create tokens without a clear naming convention and hierarchy
+- **NEVER** skip documentation — an undocumented design system will not be adopted
+- **NEVER** build organisms before atoms and molecules are solid
+
+## Completion Criteria
+
+- [ ] Interface audit completed with inconsistencies documented
+- [ ] All design tokens defined (colors, typography, spacing, borders, shadows)
+- [ ] Atoms documented with usage guidelines
+- [ ] Molecules and organisms built with variants and states
+- [ ] Accessibility requirements defined for every component
+- [ ] Documentation complete with examples and contribution guide
+- [ ] Governance model established for ongoing maintenance