devtronic 1.0.0 → 1.2.0

package/templates/claude-code/.claude/skills/design-audit/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: devtronic:design-audit
+description: UX audit — evaluates designs against Nielsen's 10 heuristics and WCAG 2.1 AA accessibility. Consolidates findings with severity.
+allowed-tools: Task, Read, Glob, Write, Bash
+argument-hint: "[--wireframes|--code|--both]"
+---
+
+# Design:Audit - UX Heuristics & Accessibility
+
+Evaluates design artifacts or implementation against UX heuristics and accessibility standards.
+
+## When to Use
+- After wireframing — audit the spec before building
+- Before a release — audit the implementation
+- When onboarding to a codebase with unknown UX quality
+- Proactively during design review cycles
+
+## Modes
+
+| Flag | Input | What runs |
+|------|-------|----------|
+| `--wireframes` | `thoughts/design/wireframes.md` | Heuristics only (no code) |
+| `--code` | Source files (src/, app/) | Heuristics + accessibility on code |
+| `--both` | Wireframes + code | Full audit |
+| no flag | auto-detect | Checks what exists |
+
+---
+
+## Process
+
+```
+1. LOAD CONTEXT
+   ├── Detect mode from $ARGUMENTS or auto-detect
+   └── Load thoughts/design/wireframes.md and/or source files
+
+2. PARALLEL AUDIT
+   ├── Invoke design-critic (heuristic evaluation)
+   └── Invoke a11y-auditor (accessibility checks)
+
+3. CONSOLIDATE
+   └── Merge findings, deduplicate, sort by severity
+
+4. GENERATE REPORT
+   └── Write thoughts/design/audit.md
+   └── Print summary
+```
+
+## Step 2: What each agent checks
+
+**design-critic** evaluates:
+- Nielsen's 10 heuristics applied to screen flows and interactions
+- Works on text wireframe specs or UI code descriptions
+- Returns severity: blocker / warning / suggestion per heuristic
+
+**a11y-auditor** checks (WCAG 2.1 AA):
+- Color contrast (4.5:1 text, 3:1 large text, 3:1 UI components)
+- Touch targets minimum 44x44px
+- Alt text on images
+- Form labels and associations
+- Keyboard navigation and focus order
+- ARIA roles and landmark regions
+- Reduced motion support
+
+## Output: `thoughts/design/audit.md`
+
+```markdown
+# UX Audit: [Feature/Product]
+
+**Date**: YYYY-MM-DD
+**Mode**: wireframes | code | both
+**Status**: N blockers, M warnings, K suggestions
+
+---
+
+## Heuristic Evaluation
+
+| # | Heuristic | Status | Finding | Recommendation |
+|---|-----------|--------|---------|----------------|
+| 1 | Visibility of system status | pass | - | - |
+| 4 | Consistency and standards | warn | Navigation labels differ between mobile and desktop | Unify labels |
+| 8 | Aesthetic and minimalist design | blocker | Dashboard shows 14 metrics on first load | Prioritize top 5, collapse rest |
+
+## Accessibility
+
+| Check | Status | Finding | Fix |
+|-------|--------|---------|-----|
+| Color contrast | fail | Button text #999 on #FFF = 2.85:1 (need 4.5:1) | Use #767676 minimum |
+| Touch targets | warn | Icon buttons are 32x32px | Increase to 44x44px |
+| Form labels | pass | All inputs have associated labels | - |
+
+---
+
+## Consolidated Findings
+
+### Blockers (must fix before launch)
+1. [Finding with file:line if from code]
+
+### Warnings (should fix)
+1. [Finding]
+
+### Suggestions (nice to have)
+1. [Finding]
+
+---
+
+## Next Steps
+- Fix blockers before proceeding to implementation
+- Warnings can be filed as issues and addressed in parallel
+```
+
+## Tips
+- Run `--wireframes` early — cheaper to fix in spec than in code
+- Run `--code` before PR — catches what code review misses
+- Blockers from accessibility are non-negotiable for public-facing products

package/templates/claude-code/.claude/skills/design-define/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: devtronic:design-define
+description: Synthesis phase — generates personas, user journey maps, and HMW problem statements from research.
+allowed-tools: Task, Read, Write, AskUserQuestion
+argument-hint: "[topic]"
+---
+
+# Design:Define - Personas, Journeys & Problem Framing
+
+## When to Use
+- After `/design:research` (reads thoughts/design/research.md)
+- When you have enough context to model the user
+- Before jumping to wireframes or IA
+
+**Skip for:** B2B internal tools where users are well-known, or when define artifacts already exist.
+
+---
+
+## Process
+```
+1. LOAD CONTEXT
+   └── Read thoughts/design/research.md (required or ask for input)
+   └── Read thoughts/specs/ for functional requirements
+
+2. CLARIFY (if research is thin)
+   └── AskUserQuestion: fill gaps in audience / pain points
+
+3. INVOKE ux-researcher
+   └── Input: research doc + any additional context
+   └── Output: personas, journeys, HMW questions
+
+4. REVIEW & REFINE
+   └── Present output to user for validation
+   └── Adjust persona names, priorities if needed
+
+5. PERSIST
+   └── Write thoughts/design/define.md
+   └── Append status to thoughts/design/design.md
+```
+
+## Step 3: What ux-researcher produces
+
+Ask the `ux-researcher` subagent to generate:
+
+**Personas (2-3 max)**:
+- Name, role, age range
+- Goals (what they want to achieve)
+- Frustrations (pain points)
+- Context of use (device, environment, frequency)
+- Quote that captures their mindset
+
+**User Journey Maps (per primary persona)**:
+- Stages: Discover → Onboard → Use → Return
+- Actions per stage
+- Touchpoints
+- Pain points at each stage
+- Opportunities for improvement
+
+**How Might We questions**:
+- 5-8 HMW questions from the pain points
+- Format: "How might we [solve pain point] for [persona] so that [outcome]?"
+
+**Problem Statement**:
+- One crisp sentence: "[Persona] needs a way to [action] because [insight]"
+
+## Output: `thoughts/design/define.md`
+
+```markdown
+# Design Define: [Feature/Product]
+
+**Date**: YYYY-MM-DD
+**Status**: draft
+
+## Personas
+
+### [Name] — [Role]
+- **Goals**: ...
+- **Frustrations**: ...
+- **Context**: ...
+- **Quote**: "..."
+
+### [Name 2] — [Role]
+...
+
+## User Journey: [Primary Persona]
+
+| Stage | Actions | Touchpoints | Pain Points | Opportunities |
+|-------|---------|-------------|-------------|---------------|
+| Discover | ... | ... | ... | ... |
+| Onboard | ... | ... | ... | ... |
+| Use | ... | ... | ... | ... |
+| Return | ... | ... | ... | ... |
+
+## Problem Statement
+"[Persona] needs a way to [action] because [insight]."
+
+## How Might We...
+1. HMW [question 1]?
+2. HMW [question 2]?
+...
+
+## Next Step
+Run `/design:ia` to define navigation structure and information architecture.
+```
+
+## Tips
+- 2 personas is usually better than 5 — focus over completeness
+- HMW questions should be optimistic but not solution-prescriptive
+- The Problem Statement is the single most important output — get it right

package/templates/claude-code/.claude/skills/design-ia/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: devtronic:design-ia
+description: Information architecture phase — defines navigation structure, sitemap, and user flows from personas and journeys.
+allowed-tools: Task, Read, Write, AskUserQuestion
+argument-hint: "[scope]"
+---
+
+# Design:IA - Information Architecture & Navigation
+
+## When to Use
+- After `/design:define` — reads thoughts/design/define.md
+- Before wireframing — IA is the skeleton that wireframes flesh out
+- When navigation structure is unclear or complex
+
+**Skip for:** Single-screen tools or features with no navigation.
+
+---
+
+## Process
+```
+1. LOAD CONTEXT
+   ├── Read thoughts/design/define.md (personas, journeys)
+   ├── Read thoughts/design/research.md (if exists)
+   └── Read thoughts/specs/ for functional scope
+
+2. CLARIFY SCOPE
+   └── AskUserQuestion: how many screens? any existing navigation to respect?
+
+3. INVOKE ia-architect
+   └── Input: personas + journeys + functional requirements
+   └── Output: sitemap, navigation model, content hierarchy, user flows
+
+4. PRESENT & VALIDATE
+   └── Show sitemap and primary flows to user
+   └── Iterate if needed
+
+5. PERSIST
+   └── Write thoughts/design/ia.md
+   └── Append to thoughts/design/design.md
+```
+
+## Step 3: What ia-architect produces
+
+**Sitemap**: all screens/pages in hierarchical text format
+**Navigation model**: primary nav, secondary nav, entry points
+**Content hierarchy**: per screen — what content/actions appear and in what order
+**User flows**: critical paths from persona journeys as step-by-step flows
+**Dead-end check**: are there screens with no way back? Missing empty states?
+
+## Output: `thoughts/design/ia.md`
+
+```markdown
+# Information Architecture: [Feature/Product]
+
+**Date**: YYYY-MM-DD
+**Status**: draft
+
+## Sitemap
+
+```
+Home
+├── [Section 1]
+│   ├── [Screen 1.1]
+│   └── [Screen 1.2]
+└── [Section 2]
+    └── [Screen 2.1]
+```
+
+## Navigation Model
+
+- **Primary nav**: [items]
+- **Secondary nav**: [items or "none"]
+- **Entry points**: [how users arrive at key screens]
+- **Exit points**: [where users go after completing main task]
+
+## Content Hierarchy
+
+### [Screen Name]
+1. [Most important element]
+2. [Secondary element]
+3. [Supporting content]
+4. [Actions]
+
+## User Flows
+
+### Flow: [Primary Task from Persona Journey]
+```
+[Step 1] → [Step 2] → [Step 3] → [Success State]
+                    ↓
+              [Error State] → [Recovery]
+```
+
+## IA Issues Found
+- [ ] [Any dead-ends, missing states, or inconsistencies]
+
+## Next Step
+Run `/design:wireframe` to specify layout for each screen.
+```
+
+## Tips
+- Sitemap depth beyond 3 levels usually indicates a UX problem
+- Every flow needs an error/empty state
+- Navigation should match users' mental model, not the technical structure

package/templates/claude-code/.claude/skills/design-research/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: devtronic:design-research
+description: Discovery phase — synthesizes competitive analysis, target audience, and business context into a research document.
+allowed-tools: Task, Read, Glob, AskUserQuestion, Write, WebFetch
+argument-hint: "[topic]"
+---
+
+# Design:Research - Discovery & Competitive Analysis
+
+Runs the discovery phase for a new product or feature. Gathers context, analyzes competitors, and produces a structured research document to inform design decisions.
+
+## When to Use
+- Starting a new product or feature with no prior research
+- After `/spec` to enrich requirements with market context
+- When competitive landscape is unknown
+
+**Skip for:** Internal tools with no competition, or when research already exists in `thoughts/design/research.md`.
+
+---
+
+## Process
+```
+1. LOAD CONTEXT
+   └── Read thoughts/specs/ (if exists) for requirements
+   └── Read thoughts/design/design.md (if exists) for prior decisions
+
+2. GATHER INPUT (AskUserQuestion)
+   ├── Who is the target user? (demographics, technical level, context of use)
+   ├── What problem does this solve? (pain point, current workarounds)
+   ├── Competitors or reference products? (URLs or names)
+   └── Business constraints? (timeline, budget, platform, team size)
+
+3. COMPETITIVE ANALYSIS
+   └── Invoke ux-researcher subagent with competitor list
+   └── Analyze: features, UX patterns, strengths, weaknesses, differentiation opportunities
+
+4. SYNTHESIS
+   └── Key insights from research
+   └── Target audience definition
+   └── Differentiation opportunities
+   └── Research questions for user interviews (if applicable)
+
+5. PERSIST
+   └── Write thoughts/design/research.md
+   └── Append status to thoughts/design/design.md
+```
+
+## Step 2: Gather Input
+
+Ask these questions via AskUserQuestion (combine into 2-3 questions max):
+- Target audience and their context
+- Core problem and current workarounds
+- Competitor names or URLs (3-5 max)
+- Any known constraints
+
+## Step 3: Competitive Analysis
+
+For each competitor:
+- Core value proposition
+- Key UX patterns (navigation, onboarding, key flows)
+- Strengths from user perspective
+- Weaknesses / gaps
+
+Invoke the `ux-researcher` subagent with the gathered data.
+
+## Step 4: Synthesis
+
+Produce:
+- **Target Audience**: primary persona sketch (expand in `/design:define`)
+- **Key Insights**: 3-5 bullets from competitive analysis
+- **Differentiation Opportunities**: where the product can win
+- **Open Questions**: what we don't know yet, for user interviews
+
+## Output: `thoughts/design/research.md`
+
+```markdown
+# Design Research: [Feature/Product]
+
+**Date**: YYYY-MM-DD
+**Status**: draft
+
+## Target Audience
+[Who, context of use, technical level]
+
+## Problem Statement
+[Core pain point and current workarounds]
+
+## Competitive Analysis
+
+### [Competitor 1]
+- Value prop: ...
+- UX patterns: ...
+- Strengths: ...
+- Weaknesses: ...
+
+### [Competitor 2]
+...
+
+## Key Insights
+1. ...
+2. ...
+
+## Differentiation Opportunities
+- ...
+
+## Open Questions
+- ...
+
+## Next Step
+Run `/design:define` to build personas and user journeys.
+```
+
+## Tips
+- Keep competitor analysis factual, not opinionated
+- 3 competitors is usually enough — depth over breadth
+- Open Questions become the agenda for user interviews

package/templates/claude-code/.claude/skills/design-review/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: devtronic:design-review
+description: QA visual review — compares implementation against wireframe specs and design system. Surfaces deviations with severity.
+allowed-tools: Task, Read, Glob, Bash, Write
+argument-hint: "[component-name|--all]"
+---
+
+# Design:Review - Implementation vs Design QA
+
+Compares what was built against what was designed. Uses `thoughts/design/wireframes.md` and `thoughts/design/design-system.md` as ground truth.
+
+## When to Use
+- After `/execute-plan` completes UI implementation
+- Before PR — catch design deviations before code review
+- In the post-review step of the workflow
+
+**This is NOT a code quality review** — use `/post-review` for that. This reviews visual/UX fidelity.
+
+---
+
+## Process
+
+```
+1. LOAD GROUND TRUTH
+   ├── Read thoughts/design/wireframes.md (layout, components, states)
+   └── Read thoughts/design/design-system.md (tokens, components)
+
+2. DETERMINE SCOPE
+   └── $ARGUMENTS: specific component name or --all
+   └── If --all: review all screens from wireframes
+
+3. PER COMPONENT/SCREEN:
+   ├── Read implementation file(s)
+   ├── Compare: components present? layout correct? tokens used?
+   ├── Check: all states implemented? (empty/loading/error/success)
+   └── Invoke visual-qa if screenshots are available
+
+4. CONSOLIDATE FINDINGS
+   └── Severity: blocker / warning / suggestion
+
+5. OUTPUT
+   └── Print findings per component
+   └── Overall compliance summary
+```
+
+## Step 3: What Gets Compared
+
+For each screen/component from wireframes.md:
+
+| Aspect | Check |
+|--------|-------|
+| **Components present** | All listed components exist in implementation |
+| **Content hierarchy** | Order of elements matches spec priority |
+| **Interactive elements** | All buttons/inputs present with correct labels |
+| **States** | Empty, loading, error, success all handled |
+| **Token usage** | No hardcoded values that should be tokens |
+| **Responsive** | Does it break at mobile widths? |
+| **Copy** | Placeholder copy replaced with real or meaningful copy |
+
+## Step 3b: visual-qa (when screenshots available)
+
+If the user provides screenshot paths or URLs:
+- Pass design screenshot vs implementation screenshot to visual-qa
+- visual-qa returns a diff table: element | expected | found | severity
+
+## Severity
+
+- **Blocker**: Missing component, broken state, wrong primary action
+- **Warning**: Minor layout deviation, token not used, missing state
+- **Suggestion**: Copy tweak, spacing polish, animation missing
+
+## Output Format
+
+```
+## Design Review: [Component/Screen]
+
+**Spec**: thoughts/design/wireframes.md#[screen]
+**File**: src/components/[File]
+**Status**: N blockers, M warnings
+
+### Blockers
+- [ ] Error state not implemented (spec requires: "Show inline error below field")
+
+### Warnings
+- [ ] Button uses `#3B82F6` instead of `var(--color-primary)`
+- [ ] Card padding is 12px, spec says 16px (space.4)
+
+### Passing
+- ✓ All form fields present
+- ✓ Loading skeleton implemented
+- ✓ Empty state with CTA present
+
+---
+```
+
+## Tips
+- Run immediately after `/execute-plan` — easier to fix before PR
+- Blockers from design review → add to current PR
+- Warnings → file as follow-up issues, don't block the PR

package/templates/claude-code/.claude/skills/design-spec/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: devtronic:design-spec
+description: Generates a developer-ready design specification from design artifacts. Bridges design phase and implementation planning.
+allowed-tools: Task, Read, Write, Glob
+argument-hint: "[screen-name|--all]"
+---
+
+# Design:Spec - Developer Handoff Specification
+
+Generates a structured design specification from `thoughts/design/` artifacts, consumable by `/create-plan` and developers.
+
+## When to Use
+- After design phase is complete (wireframes + design system defined)
+- Before `/create-plan` — spec informs component breakdown
+- When handing off design to a developer unfamiliar with the design decisions
+
+---
+
+## Process
+
+```
+1. LOAD DESIGN ARTIFACTS
+   ├── thoughts/design/wireframes.md (screen layouts, components, states)
+   ├── thoughts/design/design-system.md (tokens, component specs)
+   ├── thoughts/design/define.md (personas, for context)
+   └── thoughts/design/ia.md (navigation, for routing)
+
+2. SCOPE
+   └── $ARGUMENTS: specific screen name, or --all for full spec
+
+3. GENERATE SPEC
+   Per screen:
+   ├── Component breakdown (what to build)
+   ├── Props and variants for each component
+   ├── Token references (which tokens to use, not raw values)
+   ├── Interaction specs (hover, click, keyboard behavior)
+   ├── State specs (all 4 states with expected behavior)
+   └── Edge cases (empty, error, boundary conditions)
+
+4. WRITE
+   └── thoughts/design/spec.md (full handoff document)
+```
+
+## Output: `thoughts/design/spec.md`
+
+```markdown
+# Design Specification: [Feature/Product]
+
+**Date**: YYYY-MM-DD
+**Personas**: [from define.md]
+**Status**: ready-for-implementation
+
+---
+
+## Component Inventory
+
+| Component | Screen(s) | Variants | Priority |
+|-----------|-----------|----------|----------|
+| Button | All | primary, secondary, ghost, destructive | P0 |
+| Card | Dashboard, List | default, selected, loading | P0 |
+| EmptyState | List, Search | with-cta, without-cta | P1 |
+
+---
+
+## Screen: [Name]
+
+**Route**: /[path]
+**Persona**: [primary user]
+
+### Components
+
+#### [ComponentName]
+
+**Purpose**: [what it does in this screen]
+
+**Props**:
+| Prop | Type | Values | Default |
+|------|------|--------|---------|
+| variant | string | 'primary' \| 'secondary' | 'primary' |
+| size | string | 'sm' \| 'md' \| 'lg' | 'md' |
+| disabled | boolean | true \| false | false |
+
+**Tokens**:
+- Background: `color.primary`
+- Text: `color.neutral.50`
+- Padding: `space.4` (vertical) × `space.6` (horizontal)
+- Border radius: `radius.md`
+
+**Interactions**:
+| Trigger | Action |
+|---------|--------|
+| Hover | Background → `color.primary.hover` |
+| Focus | Outline `color.primary` 2px offset |
+| Click | [what happens] |
+| Keyboard Enter/Space | Same as click |
+
+**States**:
+| State | Appearance | Behavior |
+|-------|-----------|----------|
+| Default | [description] | [behavior] |
+| Hover | [description] | [behavior] |
+| Loading | Spinner replaces label | Disabled interactions |
+| Error | [description] | [behavior] |
+| Success | [description] | [behavior] |
+| Disabled | 40% opacity | No interactions |
+
+**Edge Cases**:
+- Long text: truncate with ellipsis at 200px
+- [Other edge cases]
+
+---
+
+## Routing & Navigation
+
+[From ia.md — summarized for implementation]
+
+---
+
+## Implementation Notes
+
+- [Key decisions or constraints developers should know]
+- [Known tradeoffs made in the design]
+- [Anything that deviates from common patterns and why]
+
+---
+
+## Next Step
+
+Run `/create-plan` — this spec file can be passed as context to inform the component breakdown.
+```
+
+## Tips
+- Specs should be implementation-ready — no ambiguity about what to build
+- Token references not raw values — let the token system handle theming
+- Edge cases are the most valuable part — developers often skip them
+- Keep it concise — long specs don't get read