devtronic 1.0.0 → 1.2.0

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

@@ -0,0 +1,39 @@
+---
+name: devtronic:design-system
+description: Design system router — delegates to define, audit, or sync based on flag. Manages design tokens, components, and style guide lifecycle.
+allowed-tools: Task, AskUserQuestion
+argument-hint: "[--define|--audit|--sync]"
+---
+
+# Design:System - Design System Router
+
+Routes to the right design system sub-skill based on the flag provided.
+
+## When to Use
+- `--define`: Creating or extracting a design system for the first time
+- `--audit`: Checking if the codebase drifts from the design system
+- `--sync`: Updating project config files when tokens change
+
+---
+
+## Routing
+
+| Flag | Delegates to | Purpose |
+|------|-------------|---------|
+| `--define` | `/design:system-define` | Create or extract design tokens and components |
+| `--audit` | `/design:system-audit` | Find drift, unused tokens, hardcoded values |
+| `--sync` | `/design:system-sync` | Sync design-system.md → tailwind/CSS vars/tokens.json |
+| no flag | ask | Prompt user to choose |
+
+## No Flag Behavior
+
+When invoked without a flag, ask:
+- Do you want to define a new design system or extract from existing code? → `--define`
+- Do you want to audit for drift or inconsistencies? → `--audit`
+- Do you want to sync tokens from the design system to project config? → `--sync`
+
+## Source of Truth
+
+All three sub-skills share `thoughts/design/design-system.md` as the canonical design system document.
+
+The sync direction is always: `thoughts/design/design-system.md` → project config files (never the reverse).

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

@@ -0,0 +1,106 @@
+---
+name: devtronic:design-system-audit
+description: Audits the codebase for design system drift — finds hardcoded values, unused tokens, and components that bypass the system.
+allowed-tools: Task, Read, Glob, Grep, Write, Bash
+argument-hint: "[--files path/to/dir]"
+---
+
+# Design:System-Audit - Design System Drift Detection
+
+Scans the codebase against `thoughts/design/design-system.md` to detect drift: hardcoded values, unused tokens, and components that bypass the design system.
+
+## When to Use
+- Before a PR or release — catch drift before it merges
+- After onboarding new developers — check for style habits that bypass the system
+- Periodically on growing codebases
+- When run from `/post-review` automatically
+
+---
+
+## Process
+
+```
+1. LOAD DESIGN SYSTEM
+   └── Read thoughts/design/design-system.md (required — abort if missing, suggest --define)
+
+2. DISCOVER SCOPE
+   └── $ARGUMENTS --files → specific directory
+   └── No args → scan src/ or app/ or equivalent
+
+3. INVOKE design-system-guardian
+   └── Finds violations across all files in scope
+
+4. GENERATE REPORT
+   └── Write thoughts/design/design-system-audit.md
+   └── Print summary to console
+```
+
+## What Gets Checked
+
+### 1. Hardcoded Color Values
+Grep for hex colors, rgb(), rgba(), hsl() that should be CSS variables or tokens.
+
+**Violation**: `color: #3B82F6` when `--color-primary: #3B82F6` exists in design system.
+**Fix**: Replace with `color: var(--color-primary)` or the framework equivalent.
+
+### 2. Hardcoded Spacing
+Grep for arbitrary px/rem values where a spacing token exists.
+
+**Violation**: `padding: 16px` when `space.4` = 16px exists.
+**Fix**: Replace with `p-4` (Tailwind) or `var(--space-4)` (CSS vars).
+
+### 3. Unused Tokens
+Tokens defined in design-system.md but never referenced in source files.
+
+**Output**: List of unused tokens to consider removing from the design system.
+
+### 4. Rogue Styles
+Components with inline styles or non-token CSS for properties covered by the design system.
+
+### 5. Component Inventory
+For each component in design-system.md: is it actually implemented? Does it expose the correct variants/states?
+
+## Output: `thoughts/design/design-system-audit.md`
+
+```markdown
+# Design System Audit: [Date]
+
+**Design system**: thoughts/design/design-system.md
+**Scope**: [files scanned]
+**Status**: N violations found
+
+## Violations
+
+### Hardcoded Colors (N)
+
+| File | Line | Found | Should be |
+|------|------|-------|-----------|
+| src/Button.tsx | 12 | #3B82F6 | var(--color-primary) |
+
+### Hardcoded Spacing (N)
+
+| File | Line | Found | Should be |
+|------|------|-------|-----------|
+| src/Card.tsx | 8 | padding: 16px | space.4 |
+
+### Unused Tokens (N)
+- color.secondary.light — defined but never used
+- shadow.xl — defined but never used
+
+### Components Missing Implementation (N)
+- Badge — in design system but no component file found
+
+## Coverage
+- Files scanned: N
+- Files with violations: M
+- Design system compliance: X%
+
+## Recommended Actions
+1. [Highest priority fix]
+2. [Second priority]
+```
+
+## Tips
+- Run `--files src/components` to audit just the component library
+- Compliance % is a lagging indicator — track it over time
+- Unused tokens accumulate — prune them in design:system-sync

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

@@ -0,0 +1,141 @@
+---
+name: devtronic:design-system-define
+description: Creates or extracts a design system — tokens, components, and style guide — persisted to thoughts/design/design-system.md.
+allowed-tools: Task, Read, Write, Edit, AskUserQuestion, Bash, Glob
+argument-hint: "[--extract]"
+---
+
+# Design:System-Define - Create or Extract Design System
+
+Two modes:
+- **Interactive** (default): define a design system from scratch through guided questions
+- **Extract** (`--extract`): read existing CSS, Tailwind config, or component files and normalize into tokens
+
+## When to Use
+- Starting a new project with no design system
+- Inheriting a codebase with implicit styles that need to be made explicit
+- After `/design:wireframe` — wireframes reveal what tokens are needed
+
+---
+
+## Process
+
+### Mode: Interactive (default)
+
+```
+1. ASK about existing constraints
+   └── Does a brand guide exist? Any existing color palette or typography?
+
+2. GUIDED TOKEN DEFINITION
+   ├── Colors: primary, secondary, neutral scale, semantic (success/error/warning/info)
+   ├── Typography: font families, size scale, weight, line-height
+   ├── Spacing: base unit and scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px)
+   ├── Borders: radius scale, border widths
+   ├── Shadows: elevation levels (0-5)
+   └── Motion: duration scale, easing functions
+
+3. COMPONENT INVENTORY
+   └── From wireframes (thoughts/design/wireframes.md), list components needed
+   └── For each: variants, states (default/hover/active/disabled/focus)
+
+4. INVOKE design-token-extractor
+   └── Normalize tokens to agnostic format
+
+5. PERSIST → thoughts/design/design-system.md
+```
+
+### Mode: Extract (`--extract`)
+
+```
+1. DISCOVER project config
+   ├── Glob for: tailwind.config.*, tokens.json, *.css with :root { }
+   └── Read relevant files
+
+2. INVOKE design-token-extractor
+   └── Extract and normalize all tokens found
+
+3. IDENTIFY GAPS
+   └── What's missing vs. what wireframes need?
+
+4. PERSIST → thoughts/design/design-system.md
+```
+
+## Output: `thoughts/design/design-system.md`
+
+```markdown
+# Design System: [Project]
+
+**Date**: YYYY-MM-DD
+**Source**: defined | extracted from [files]
+
+## Colors
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| color.primary | #... | Primary actions, links |
+| color.primary.hover | #... | Hover state |
+| color.neutral.100 | #... | Lightest background |
+| color.neutral.900 | #... | Body text |
+| color.success | #... | Success states |
+| color.error | #... | Error states |
+| color.warning | #... | Warning states |
+
+## Typography
+
+| Token | Value |
+|-------|-------|
+| font.family.base | Inter, system-ui, sans-serif |
+| font.size.sm | 14px |
+| font.size.md | 16px |
+| font.size.lg | 18px |
+| font.weight.normal | 400 |
+| font.weight.semibold | 600 |
+| font.weight.bold | 700 |
+
+## Spacing
+
+Base unit: 4px
+
+| Token | Value |
+|-------|-------|
+| space.1 | 4px |
+| space.2 | 8px |
+| space.4 | 16px |
+| space.6 | 24px |
+| space.8 | 32px |
+| space.12 | 48px |
+
+## Borders
+
+| Token | Value |
+|-------|-------|
+| radius.sm | 4px |
+| radius.md | 8px |
+| radius.lg | 16px |
+| radius.full | 9999px |
+
+## Shadows
+
+| Token | Value |
+|-------|-------|
+| shadow.sm | 0 1px 2px rgba(0,0,0,0.05) |
+| shadow.md | 0 4px 6px rgba(0,0,0,0.07) |
+
+## Components
+
+### [ComponentName]
+
+**Variants**: [default, primary, secondary, ghost]
+**States**: [default, hover, active, disabled, focus]
+**Props**: [key configurable aspects]
+
+## Next Steps
+
+- Run `/design:system --sync` to apply tokens to project config files
+- Run `/design:system --audit` to check existing code against this system
+```
+
+## Tips
+- Start with a minimal token set — add tokens when you need them, not in advance
+- Use semantic token names (color.error) not literal ones (color.red)
+- Every component needs its disabled and focus states defined

package/templates/claude-code/.claude/skills/design-system-sync/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: devtronic:design-system-sync
+description: Syncs design tokens from thoughts/design/design-system.md to project config files (Tailwind, CSS vars, tokens.json).
+allowed-tools: Task, Read, Write, Edit, Glob, Bash, AskUserQuestion
+argument-hint: "[--dry-run]"
+---
+
+# Design:System-Sync - Token Synchronization
+
+Syncs `thoughts/design/design-system.md` (source of truth) → project config files.
+
+Use `--dry-run` to preview changes without applying them.
+
+## When to Use
+- After `/design:system-define` — apply newly defined tokens to project
+- When design tokens change in the design file — propagate to code
+- Before `/execute-plan` — ensure tokens are available before implementation starts
+
+**Direction**: Always `design-system.md → project files`. Never reverse.
+
+---
+
+## Process
+
+```
+1. LOAD DESIGN SYSTEM
+   └── Read thoughts/design/design-system.md
+
+2. DETECT PROJECT CONFIG FORMAT
+   ├── tailwind.config.* → Tailwind format
+   ├── tokens.json / style-dictionary → Style Dictionary format
+   ├── CSS :root { } → CSS custom properties
+   └── Combination of above
+
+3. INVOKE design-token-extractor
+   └── Current state of project config tokens
+   └── Compute diff: design-system.md vs current config
+
+4. SHOW DIFF
+   └── Tokens to ADD, MODIFY, REMOVE
+   └── --dry-run: stop here
+
+5. CONFIRM & APPLY
+   └── AskUserQuestion to confirm if changes are significant
+   └── Apply to config files
+
+6. VERIFY
+   └── Re-read config files to confirm changes applied correctly
+```
+
+## Step 2: Config Format Detection
+
+### Tailwind
+```javascript
+// tailwind.config.js / tailwind.config.ts
+module.exports = {
+  theme: {
+    extend: {
+      colors: { primary: '#...' },
+      spacing: { ... }
+    }
+  }
+}
+```
+
+### CSS Custom Properties
+```css
+/* globals.css or tokens.css */
+:root {
+  --color-primary: #...;
+  --space-4: 16px;
+}
+```
+
+### Style Dictionary / tokens.json
+```json
+{
+  "color": { "primary": { "value": "#..." } }
+}
+```
+
+## Step 4: Diff Format
+
+```
+Design System Sync — Diff Preview
+
++ ADD: color.brand (new token)
+  tailwind: colors.brand → '#4F46E5'
+  CSS var: --color-brand → '#4F46E5'
+
+~ MODIFY: color.primary
+  current: '#3B82F6' → new: '#4F46E5'
+
+- REMOVE: color.secondary.light (unused)
+  Action: Remove from config (confirm first)
+
+N tokens added, M modified, K removed.
+Apply changes? [y/N]
+```
+
+## Tips
+- Always `--dry-run` first on production codebases
+- Removing tokens can break components — search for usages before removing
+- After sync, run the build to catch any broken references
+- Commit the sync as a separate `chore:` commit with message "sync design tokens"

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

@@ -0,0 +1,120 @@
+---
+name: devtronic:design-wireframe
+description: Wireframe specification phase — generates structured text-based wireframe specs per screen. Tool-agnostic. Reads IA and define artifacts.
+allowed-tools: Task, Read, Write, AskUserQuestion
+argument-hint: "[screen-name|--all]"
+---
+
+# Design:Wireframe - Screen Wireframe Specifications
+
+## When to Use
+- After `/design:ia` — reads thoughts/design/ia.md for screen list
+- Before implementation planning — wireframes inform component breakdown
+- When: layout decisions need to be made explicit before coding
+
+**Skip for:** Screens already designed in a design tool (use `/design:review` instead).
+
+---
+
+## Process
+```
+1. LOAD CONTEXT
+   ├── Read thoughts/design/ia.md (screen list, hierarchy, flows)
+   ├── Read thoughts/design/define.md (personas — who uses each screen)
+   └── Determine scope: all screens or specific screen from $ARGUMENTS
+
+2. PER SCREEN — generate wireframe spec:
+   ├── Layout zones (header, main, sidebar, footer, modals)
+   ├── Component list (what appears and where)
+   ├── Content hierarchy (order of elements)
+   ├── Interactive elements (buttons, inputs, links) + their actions
+   ├── States (empty, loading, error, success)
+   └── ASCII layout sketch (optional but helpful)
+
+3. REVIEW
+   └── Ask user to confirm key layout decisions
+
+4. PERSIST
+   └── Write thoughts/design/wireframes.md
+   └── Append to thoughts/design/design.md
+```
+
+## Wireframe Spec Format (per screen)
+
+Each screen uses this structure:
+
+```markdown
+### Screen: [Name]
+
+**Route/location**: [URL pattern or nav path]
+**Primary persona**: [who uses this most]
+**Primary action**: [the one thing users do here]
+
+#### Layout Zones
+- **Header**: [logo, nav, user menu, search]
+- **Main**: [primary content area]
+- **Sidebar**: [secondary navigation or filters — or "none"]
+- **Footer**: [secondary links, legal — or "none"]
+
+#### Components
+1. [Component name] — [brief description of content/purpose]
+2. [Component name] — [brief description]
+...
+
+#### Content Hierarchy
+1. [Most prominent element]
+2. [Secondary element]
+3. [Supporting content]
+
+#### Interactive Elements
+| Element | Type | Action |
+|---------|------|--------|
+| [Button label] | button | [what happens] |
+| [Field label] | input | [what it accepts] |
+
+#### States
+- **Empty**: [what shows when no content]
+- **Loading**: [skeleton? spinner? what kind]
+- **Error**: [how errors surface]
+- **Success**: [confirmation pattern]
+
+#### ASCII Sketch (optional)
+\`\`\`
+┌─────────────────────────────┐
+│ Logo         Nav    [Login] │
+├─────────────────────────────┤
+│ [Hero content]              │
+│                             │
+│ [Card] [Card] [Card]        │
+└─────────────────────────────┘
+\`\`\`
+```
+
+## Output: `thoughts/design/wireframes.md`
+
+Header:
+```markdown
+# Wireframe Specs: [Feature/Product]
+
+**Date**: YYYY-MM-DD
+**Screens**: N
+**Status**: draft
+
+## Screens
+[table of contents linking to each screen spec]
+```
+
+Then one section per screen using the format above.
+
+Footer:
+```markdown
+## Next Steps
+- Run `/design:system` to define design tokens and components
+- Run `/create-plan` — wireframes inform component breakdown in implementation plan
+```
+
+## Tips
+- Specs are tool-agnostic — no Figma required to write them
+- ASCII sketches clarify layout faster than 100 words of description
+- Every screen needs all 4 states defined (empty/loading/error/success)
+- Components listed here become the component list for `/create-plan`

package/templates/claude-code/.claude/skills/execute-plan/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: execute-plan
+name: devtronic:execute-plan
 description: Execute a plan in parallel phases. Reads task dependencies and runs independent tasks as concurrent subagents. Claude Code only.
 allowed-tools: Task, Read, Write, Bash, Glob, Grep, Edit
 argument-hint: "[plan-path|--latest]"

package/templates/claude-code/.claude/skills/generate-tests/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: generate-tests
+name: devtronic:generate-tests
 description: Generate failing tests from a spec before implementation (Tests-as-DoD). Creates test files encoding acceptance criteria as executable tests, plus a traceability manifest.
 allowed-tools: Read, Write, Glob, Grep, Bash
 argument-hint: "[--from-spec|spec-path]"

package/templates/claude-code/.claude/skills/handoff/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: handoff
+name: devtronic:handoff
 description: Context rotation for fresh sessions. Saves current state and signals to start a new session with clean context.
 allowed-tools: Read, Write, Bash, Glob
 argument-hint: "[reason]"

package/templates/claude-code/.claude/skills/investigate/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: investigate
+name: devtronic:investigate
 description: Deep analysis of errors and bugs. Use when you paste an error for detailed investigation. Identifies root cause, analyzes flow, and proposes fix with code.
 allowed-tools: Read, Grep, Glob, Bash, Write, Edit
 argument-hint: "[error or description]"

package/templates/claude-code/.claude/skills/learn/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: learn
+name: devtronic:learn
 description: Post-task teaching breakdown. After any task, get a detailed explanation of what was done, why, and how to apply the concepts yourself. Use when you say "explain what you did" or "teach me".
 allowed-tools: Read, Grep, Glob, AskUserQuestion
 argument-hint: "[topic or recent task]"

package/templates/claude-code/.claude/skills/opensrc/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: opensrc
+name: devtronic:opensrc
 description: Fetch source code of npm packages or GitHub repos so AI agents have full implementation context, not just type definitions. Uses vercel-labs/opensrc under the hood.
 allowed-tools: Bash, Read, Glob, Edit
 argument-hint: "<package[@version]|owner/repo[@ref]> [packages...]"

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

@@ -1,5 +1,5 @@
 ---
-name: post-review
+name: devtronic:post-review
 description: Post-feature review before PR. Checks requirements, architecture, quality, and captures lessons. Auto-invoke after completing a plan implementation. Use --strict for senior engineer mode.
 allowed-tools: Read, Grep, Glob, Bash, Edit, Write, Task
 argument-hint: "[--strict|--quick|files...]"

package/templates/claude-code/.claude/skills/quick/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: quick
+name: devtronic:quick
 description: Fast ad-hoc task execution. Skips spec/research/plan — just implement, verify, commit. For small, well-defined tasks.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 argument-hint: "<task description>"

package/templates/claude-code/.claude/skills/recap/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: recap
+name: devtronic:recap
 description: Quick structured session summary from git activity and modified files. Compact companion to /summary.
 allowed-tools: Read, Write, Bash, Glob, Grep
 ---

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

@@ -1,5 +1,5 @@
 ---
-name: research
+name: devtronic:research
 description: Codebase investigation. Quick mode (default) for fast orientation. Deep mode for thorough analysis. External mode for GitHub + user-configured MCPs.
 allowed-tools: Read, Grep, Glob, Bash, WebFetch, Task, Write
 argument-hint: "[topic] [--deep|--external|--all]"

package/templates/claude-code/.claude/skills/scaffold/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: scaffold
+name: devtronic:scaffold
 description: Create new projects from scratch with guided architecture and structure. Use when starting a brand new project.
 allowed-tools: Read, Glob, Bash, Write, AskUserQuestion
 argument-hint: "[project-name]"

package/templates/claude-code/.claude/skills/setup/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: setup
+name: devtronic:setup
 description: Configure devtronic for this project through interactive conversation. Use when setting up AI assistance in an existing project.
 allowed-tools: Bash, Read, Glob, AskUserQuestion, Write
 ---

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

@@ -1,5 +1,5 @@
 ---
-name: spec
+name: devtronic:spec
 description: Create a product specification (PRD) by interviewing the user. Captures requirements, UX decisions, edge cases, and success metrics before technical work begins.
 allowed-tools: AskUserQuestion, Write, Read, Glob
 argument-hint: "[feature]"

package/templates/claude-code/.claude/skills/summary/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: summary
+name: devtronic:summary
 description: Generate a structured post-change summary. Captures what changed, why, what's pending, and files modified.
 allowed-tools: Read, Write, Bash, Glob, Grep
 argument-hint: "[feature-name]"

package/templates/claude-code/.claude/skills/worktree/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: worktree
+name: devtronic:worktree
 description: Manage git worktrees with intuitive flags. Create, list, remove, and prune worktrees with consistent naming and enriched status.
 allowed-tools: Bash, AskUserQuestion, Read, Glob
 argument-hint: "[--create|--list|--remove|--prune] [name]"