ganbatte-os 0.2.1

package/squads/design-squad/tasks/design-ux-flow.md

@@ -0,0 +1,184 @@
+---
+task: designUxFlow()
+responsavel: "@ux-designer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: true
+
+Entrada:
+  - campo: feature_or_product
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+  - campo: target_users
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+
+Saida:
+  - campo: uxFlow
+    tipo: string
+    destino: Console
+    persistido: false
+
+Checklist:
+  - "[ ] User research conducted with documented insights"
+  - "[ ] 2-3 personas created with goals and pain points"
+  - "[ ] Wireframes created for all key screens and flows"
+---
+
+# Task: UX Research & Flow Design
+
+**Task ID:** DESIGN-005
+**Version:** 1.0.0
+**Command:** `*design-ux-flow`
+**Agent:** UX Designer (ux-designer)
+**Purpose:** Conduct user research and design user experience flows from personas through wireframes.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `feature_or_product` | What is being designed | YES |
+| `target_users` | Who will use this | YES |
+| `business_goals` | What the business wants to achieve | YES |
+| `existing_research` | Prior user research, analytics | NO |
+| `constraints` | Technical, time, budget limitations | NO |
+| `competitive_context` | How competitors solve this | NO |
+
+## Preconditions
+
+1. Feature or product scope is defined
+2. Target user group is at least loosely identified
+3. Business goals are articulated
+
+## Execution Phases
+
+### Phase 1: User Research
+
+1. **Define research questions** — What do we need to learn to design well?
+2. **Identify research methods** based on project needs:
+   - User interviews (qualitative — understanding motivations and pain)
+   - Surveys (quantitative — validating hypotheses at scale)
+   - Contextual inquiry (observe users in their natural environment)
+   - Card sorting (understand mental models for information architecture)
+   - Competitive analysis (how do others solve this problem?)
+   - Analytics review (what does existing data tell us?)
+3. **Conduct research** — Execute selected methods
+4. **Synthesize findings** — Identify patterns, themes, and insights
+5. **Create insight statements** — "Users need [X] because [Y], but currently [Z]"
+6. Document all findings in a research repository
+
+### Phase 2: Persona & Journey Mapping
+
+1. **Create user personas** (2-3 primary personas):
+   - Demographics, role, and context
+   - Goals and motivations
+   - Pain points and frustrations
+   - Behaviors and habits
+   - Quote that captures their essence
+   - Technical proficiency level
+2. **Map current journey** (As-Is):
+   - Stages the user goes through today
+   - Actions at each stage
+   - Thoughts and feelings at each stage
+   - Pain points and opportunities
+   - Touchpoints (where they interact with the product/service)
+3. **Map desired journey** (To-Be):
+   - Improved stages with pain points resolved
+   - New touchpoints and interactions
+   - Emotional uplift at key moments
+   - Moments of delight
+
+### Phase 3: Information Architecture
+
+1. **Content inventory** — What content/features must be organized?
+2. **Card sorting results** — How do users naturally group information?
+3. **Site map / App map** — Hierarchical structure of pages/screens
+4. **Navigation model** — Primary, secondary, contextual navigation
+5. **Naming conventions** — Labels that match user mental models (not internal jargon)
+6. **Search and filtering** — How users find content within the structure
+7. Validate IA with tree testing (can users find what they need?)
+
+### Phase 4: Wireframes
+
+1. **Low-fidelity sketches** — Rapid exploration of layout options (3-5 alternatives per key screen)
+2. **Mid-fidelity wireframes** — Selected approach refined with:
+   - Layout grid and spacing
+   - Component placement and hierarchy
+   - Content priority (what is most important on each screen)
+   - Interaction patterns (how users move between states)
+   - Error states and empty states
+   - Loading states
+3. **User flows** — Step-by-step paths for key tasks:
+   - Happy path (everything goes right)
+   - Error path (what happens when things go wrong)
+   - Edge cases (unusual but valid scenarios)
+4. **Annotation** — Document interaction behaviors, validation rules, conditional logic
+5. **Responsive considerations** — How wireframes adapt across breakpoints
+
+### Phase 5: Validation & Testing
+
+1. **Usability testing** — Test wireframes with 5+ representative users
+2. **Task success rate** — Can users complete key tasks?
+3. **Time on task** — How long does each task take?
+4. **Error rate** — Where do users make mistakes?
+5. **Satisfaction** — How do users feel about the experience?
+6. Document findings and iterate on wireframes
+7. Handoff validated wireframes to visual design and development
+
+## Output Format
+
+```yaml
+ux_flow:
+  designer: "ux-designer"
+  feature: "{feature/product name}"
+  research:
+    methods_used: ["{methods}"]
+    key_insights: ["{insight statements}"]
+    participants: 0
+  personas:
+    - name: "{persona name}"
+      role: "{role}"
+      goals: ["{goals}"]
+      pain_points: ["{pains}"]
+      quote: "{representative quote}"
+  journey_map:
+    stages: ["{stage list}"]
+    pain_points: ["{key pains}"]
+    opportunities: ["{design opportunities}"]
+  information_architecture:
+    site_map: "{structure description}"
+    navigation_model: "{nav pattern}"
+    key_labels: ["{naming}"]
+  wireframes:
+    screens: ["{screen list}"]
+    user_flows: ["{flow list}"]
+    interaction_notes: ["{key behaviors}"]
+  validation:
+    method: "{testing method}"
+    task_success_rate: "{percentage}"
+    key_findings: ["{what we learned}"]
+    iterations: ["{changes made}"]
+```
+
+## Veto Conditions
+
+- **NEVER** skip user research and jump straight to wireframes — assumptions lead to wasted design
+- **NEVER** design for a single persona — consider the range of users
+- **NEVER** use internal jargon in navigation or labels — use the user's language
+- **NEVER** design only the happy path — error states and edge cases are part of the experience
+- **NEVER** skip usability testing — untested designs are assumptions, not solutions
+
+## Completion Criteria
+
+- [ ] User research conducted with documented insights
+- [ ] 2-3 personas created with goals and pain points
+- [ ] Journey map created showing current and desired states
+- [ ] Information architecture defined and validated
+- [ ] Wireframes created for all key screens and flows
+- [ ] Error states, empty states, and loading states designed
+- [ ] Usability testing completed with findings documented
+- [ ] Wireframes iterated based on test results

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

@@ -0,0 +1,138 @@
+---
+task: diagnoseDesignChallenge()
+responsavel: "@design-chief"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: true
+
+Entrada:
+  - campo: user_message
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+  - campo: routing_catalog
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+
+Saida:
+  - campo: diagnosis
+    tipo: string
+    destino: Console
+    persistido: false
+
+Checklist:
+  - "[ ] User intent parsed and categorized"
+  - "[ ] Cross-cutting answer delivered to user"
+  - "[ ] Confidence level assessed"
+---
+
+# Task: Diagnose & Route — Design Squad
+
+## Metadata
+
+| Field         | Value                                            |
+|---------------|--------------------------------------------------|
+| Task ID       | `design-squad:diagnose`                          |
+| Command       | `@design-squad` or `@design-squad:design-chief`  |
+| Orchestrator  | `design-chief`                                   |
+| Version       | 1.0.0                                            |
+| Created       | 2026-03-05                                       |
+
+## Purpose
+
+Analyze the user's design question, provide an immediate cross-cutting answer,
+and determine whether specialist routing is needed. The chief NEVER loads a specialist
+agent file during diagnosis — it only identifies the best route.
+
+## Inputs
+
+| Input            | Source              | Required |
+|------------------|---------------------|----------|
+| `user_message`   | User prompt         | YES      |
+| `routing_catalog` | `data/routing-catalog.yaml` | YES |
+| `config`         | `config/config.yaml` | YES     |
+| `conversation_history` | Session context | NO       |
+
+## Preconditions
+
+1. User message is not empty
+2. Routing catalog is loaded and accessible
+
+## Execution Phases
+
+### Phase 1: Parse Request
+
+1. Extract the core question or intent from the user message
+2. Identify keywords, design domains, and technical context
+3. Determine the design domain: systems, operations, experience, or production
+4. Determine the collaboration pattern if applicable:
+   - Design system creation flow
+   - New feature design flow
+   - Design ops setup flow
+
+### Phase 2: Match Routing Catalog
+
+1. Load `data/routing-catalog.yaml`
+2. Match extracted keywords against domain keyword lists
+3. Score each domain by keyword overlap and contextual relevance
+4. Identify `primary_agent` and `secondary_agent` for the top-scoring domain
+5. If multiple domains score equally, consider the design domain to break ties:
+   - Systems questions: prefer brad-frost
+   - Operations questions: prefer dave-malouf
+   - Experience questions: prefer ux-designer
+   - Production questions: prefer design-system-architect or ui-engineer
+
+### Phase 3: Cross-Cutting Answer
+
+**MANDATORY — Always execute this phase before any routing.**
+
+1. Provide an immediate, useful answer to the user's question
+2. The answer should be actionable and demonstrate design domain competence
+3. Include relevant context: methodologies, patterns, or design principles applicable
+4. Reference the applicable design framework or methodology by name
+5. This answer must stand alone — even if the user never follows the routing suggestion
+
+### Phase 4: Confidence Assessment
+
+Assess routing confidence:
+
+| Level  | Criteria                                      | Action                        |
+|--------|-----------------------------------------------|-------------------------------|
+| HIGH   | Clear keyword match, single domain, unambiguous | Route to primary specialist  |
+| MEDIUM | Multiple domains match, slight ambiguity       | Suggest primary + secondary   |
+| LOW    | No clear match, vague request, cross-domain    | Stay with chief, ask clarifying questions |
+
+## Output Format
+
+```yaml
+diagnosis:
+  intent: "{parsed user intent}"
+  design_domain: "systems | operations | experience | production"
+  matched_domain: "{domain from routing catalog}"
+  confidence: "HIGH | MEDIUM | LOW"
+  primary_agent: "{agent-id}"
+  secondary_agent: "{agent-id}"
+  cross_cutting_answer: |
+    {The immediate answer provided to the user}
+  routing_suggestion: |
+    {Why this specialist was chosen and what they can add}
+```
+
+## Veto Conditions
+
+- **NEVER** route without providing a cross-cutting answer first
+- **NEVER** route when confidence is LOW — stay with chief and ask clarifying questions
+- **NEVER** load a specialist agent file during diagnosis — only identify the route
+- **NEVER** trigger a multi-specialist collaboration flow during diagnosis — one specialist at a time
+- **NEVER** default to brad-frost for every question — match the actual design domain
+
+## Completion Criteria
+
+- [x] User intent parsed and categorized
+- [x] Design domain identified
+- [x] Routing catalog consulted and domain matched
+- [x] Cross-cutting answer delivered to user
+- [x] Confidence level assessed
+- [x] Routing suggestion provided (if confidence >= MEDIUM)
+- [x] No specialist agent files loaded during diagnosis

package/squads/design-squad/tasks/generate-handoff.md

@@ -0,0 +1,186 @@
+---
+task: generateHandoff()
+responsavel: "@ui-engineer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: true
+
+Entrada:
+  - campo: design_files
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+  - campo: tech_stack
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+
+Saida:
+  - campo: handoffDocumentation
+    tipo: string
+    destino: Console
+    persistido: false
+
+Checklist:
+  - "[ ] All components inventoried and mapped to design system"
+  - "[ ] Every visual value mapped to a design token"
+  - "[ ] Dev review completed with tradeoffs documented"
+---
+
+# Task: Developer Handoff Documentation
+
+**Task ID:** DESIGN-006
+**Version:** 1.0.0
+**Command:** `*generate-handoff`
+**Agent:** UI Engineer (ui-engineer) + Dan Mall (dan-mall)
+**Purpose:** Generate comprehensive developer handoff documentation for design-to-code translation.
+
+---
+
+## Inputs
+
+| Input | Source | Required |
+|-------|--------|----------|
+| `design_files` | Figma/Sketch files or screenshots | YES |
+| `design_system` | Existing design system reference | PREFERRED |
+| `tech_stack` | Frontend framework and CSS approach | YES |
+| `component_list` | Components used in the design | PREFERRED |
+| `interaction_specs` | Animations, transitions, hover states | PREFERRED |
+| `responsive_requirements` | Breakpoints and adaptation behavior | NO |
+
+## Preconditions
+
+1. Designs are finalized and approved
+2. Design system exists (or token values are specified)
+3. Tech stack is known for code-specific guidance
+4. Interactive behaviors are documented or demonstrable
+
+## Execution Phases
+
+### Phase 1: Inventory Components
+
+1. Map every unique component used in the designs
+2. For each component, determine:
+   - Does it exist in the design system already? (Reference existing)
+   - Is it a variant of an existing component? (Document the variant)
+   - Is it entirely new? (Flag for design system addition)
+3. Create a component dependency tree — which components compose others?
+4. Identify shared patterns — reusable layouts, spacing patterns, interaction patterns
+5. List all icons, illustrations, and media assets needed
+6. Document third-party components or libraries required
+
+### Phase 2: Specify Tokens
+
+1. **Color Mapping** — Map every color in the design to a design token
+   - If no token exists, propose a new semantic token
+   - Document both light and dark mode values
+   - Verify contrast ratios (AA compliance: 4.5:1 text, 3:1 UI)
+2. **Typography Mapping** — Map all text styles to typography tokens
+   - Font family, size, weight, line height, letter spacing
+   - Responsive type scale adjustments
+3. **Spacing Mapping** — Map all padding, margins, and gaps to spacing tokens
+   - Component internal spacing
+   - Between-component spacing
+   - Section and page-level spacing
+4. **Border and Shadow Mapping** — Map decorative styles to tokens
+5. **Motion Mapping** — Map animations to motion tokens (duration, easing, properties)
+6. Export a complete token-to-design mapping table
+
+### Phase 3: Document Interactions
+
+1. **State Transitions** — For each interactive element:
+   - Default → Hover: What changes? (color, shadow, scale, cursor)
+   - Default → Focus: What changes? (outline, ring, background)
+   - Default → Active: What changes? (transform, color)
+   - Default → Disabled: What changes? (opacity, cursor, pointer-events)
+2. **Micro-interactions** — Animations triggered by user actions:
+   - Button press feedback
+   - Form validation appearance
+   - Toast/notification entry and exit
+   - Loading indicators and skeleton screens
+   - Page transitions
+3. **Gesture Support** — Mobile-specific interactions:
+   - Swipe actions
+   - Pull to refresh
+   - Long press
+   - Pinch to zoom
+4. **Keyboard Navigation** — Tab order, shortcut keys, focus management
+5. **Conditional Logic** — Show/hide rules, validation rules, progressive disclosure
+
+### Phase 4: Review with Dev
+
+1. Walk through the handoff with the development team
+2. Clarify ambiguities — address every "what happens when...?" question
+3. Identify technical constraints — what is hard or impossible to implement?
+4. Negotiate tradeoffs — where can design flex for technical feasibility?
+5. Agree on implementation priority — which components/screens first?
+6. Establish the QA process — how will design verify the implementation?
+7. Document all decisions and tradeoffs from the review
+
+## Output Format
+
+```yaml
+handoff:
+  creators: [ui-engineer, dan-mall]
+  tech_stack: "{framework}"
+  design_system: "{system name}"
+  components:
+    existing: ["{components from design system}"]
+    variants_needed: ["{new variants of existing}"]
+    new_required: ["{entirely new components}"]
+  token_map:
+    colors:
+      - design_value: "{hex or rgba}"
+        token: "{token name}"
+        usage: "{where used}"
+    typography:
+      - design_style: "{style name}"
+        token: "{token name}"
+    spacing:
+      - design_value: "{px value}"
+        token: "{token name}"
+  interactions:
+    state_transitions:
+      - element: "{component}"
+        states: "{default → hover → focus → active → disabled}"
+        animation: "{duration, easing}"
+    micro_interactions:
+      - trigger: "{user action}"
+        animation: "{description}"
+        duration: "{ms}"
+        easing: "{function}"
+    keyboard:
+      tab_order: ["{element sequence}"]
+      shortcuts: ["{key: action}"]
+  responsive:
+    breakpoints: ["{px values}"]
+    adaptations:
+      - breakpoint: "{px}"
+        changes: ["{layout changes}"]
+  assets:
+    icons: ["{icon list with format}"]
+    images: ["{image list with sizes}"]
+    fonts: ["{font files}"]
+  dev_review_notes: ["{decisions and tradeoffs}"]
+  qa_checklist: ["{verification items}"]
+```
+
+## Veto Conditions
+
+- **NEVER** hand off designs without token mapping — developers should never guess at values
+- **NEVER** skip interaction documentation — static mockups are incomplete specifications
+- **NEVER** omit responsive behavior — if it is not specified, it will be implemented inconsistently
+- **NEVER** skip the dev review — one conversation prevents days of rework
+- **NEVER** hand off without accessibility specifications — they must be part of the spec, not an afterthought
+
+## Completion Criteria
+
+- [ ] All components inventoried and mapped to design system
+- [ ] Every visual value mapped to a design token
+- [ ] State transitions documented for all interactive elements
+- [ ] Micro-interactions specified with timing and easing
+- [ ] Keyboard navigation and accessibility documented
+- [ ] Responsive behavior specified for all breakpoints
+- [ ] Assets exported in required formats
+- [ ] Dev review completed with tradeoffs documented
+- [ ] QA checklist created for implementation verification

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

@@ -0,0 +1,133 @@
+---
+task: reviewDesignOutput()
+responsavel: "@design-chief"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: true
+
+Entrada:
+  - campo: specialist_output
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+  - campo: original_request
+    tipo: string
+    origem: User Input
+    obrigatorio: true
+
+Saida:
+  - campo: reviewReport
+    tipo: string
+    destino: Console
+    persistido: false
+
+Checklist:
+  - "[ ] All checklist items evaluated"
+  - "[ ] Verdict rendered (APPROVE/REVISE/REJECT)"
+  - "[ ] Accessibility, consistency, and responsiveness individually assessed"
+---
+
+# Task: Review Design Systems/UX Output
+
+**Task ID:** DESIGN-CHIEF-002
+**Version:** 1.0.0
+**Command:** `*review`
+**Orchestrator:** Design Chief (design-chief)
+**Purpose:** Review specialist output against quality checklist, score, and approve or request revision.
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| specialist_output | string | Specialist agent | Yes | Non-empty deliverable |
+| original_request | string | User prompt | Yes | The original request that triggered the work |
+| specialist_id | string | Routing | Yes | Agent ID that produced the output |
+
+---
+
+## Preconditions
+
+- Specialist has completed their task and produced output
+- Output quality checklist is available at checklists/output-quality.md
+
+---
+
+## Execution Phases
+
+### Phase 1: Understand Context
+
+1. Re-read the original user request
+2. Identify what was asked vs what was delivered
+3. Note the specialist who produced the output
+4. Identify the deliverable type: component, layout, design system, UX flow, wireframe, prototype spec
+5. Determine the platform: web, mobile, responsive, cross-platform
+
+### Phase 2: Apply Quality Checklist
+
+1. Load checklists/output-quality.md
+2. Evaluate each item against the specialist output
+3. Mark each item: [x] Pass, [ ] Fail, [N/A] Not Applicable
+4. Count CRITICAL failures and total failures
+5. Pay special attention to: accessibility compliance, design system consistency, responsiveness, and token usage
+
+### Phase 3: Score and Decide
+
+| Score | Verdict | Action |
+|-------|---------|--------|
+| All CRITICAL pass, < 2 non-critical fail | APPROVE | Deliver to user |
+| All CRITICAL pass, 2+ non-critical fail | REVISE | Return to specialist with specific feedback |
+| Any CRITICAL fail | REJECT | Return to specialist, block delivery |
+
+### Phase 4: Output
+
+Produce review report with verdict, score, and feedback.
+
+---
+
+## Output Format
+
+```markdown
+## Review Report
+
+**Specialist:** {name} ({id})
+**Verdict:** {APPROVE | REVISE | REJECT}
+**Score:** {X}/{total} items passed
+
+### Passed
+- {items that passed}
+
+### Issues Found
+- [{CRITICAL|WARN}] {description} — {recommendation}
+
+### Design-Specific Notes
+- Accessibility compliance: {assessment}
+- System consistency: {assessment}
+- Responsive behavior: {assessment}
+
+### Recommendation
+{Next step: deliver / revise specific items / redo}
+```
+
+---
+
+## Veto Conditions
+
+- NEVER approve output with CRITICAL failures
+- NEVER reject without providing specific, actionable feedback
+- NEVER modify the specialist's output — only review and provide feedback
+- NEVER approve designs that fail WCAG 2.1 AA contrast or interaction requirements
+- NEVER approve components that break design system conventions without documented rationale
+
+---
+
+## Completion Criteria
+
+- [ ] Original request re-read and understood
+- [ ] Deliverable type and platform identified
+- [ ] All checklist items evaluated
+- [ ] Score calculated
+- [ ] Verdict rendered (APPROVE/REVISE/REJECT)
+- [ ] Specific feedback provided for any failures
+- [ ] Accessibility, consistency, and responsiveness individually assessed