create-sdd-project 0.12.1 → 0.13.0

package/README.md

@@ -282,11 +282,12 @@ SDD DevFlow combines three proven practices:
 
 ## What's Included
 
-### 9 Specialized Agents
+### 10 Specialized Agents
 
 | Agent | Role | Step |
 |-------|------|------|
 | `spec-creator` | Draft/update specifications | 0 |
+| `ui-ux-designer` | Design guidelines, feature design notes | 0 (optional) |
 | `backend-planner` / `frontend-planner` | Create implementation plans | 2 |
 | `backend-developer` / `frontend-developer` | TDD implementation | 3 |
 | `production-code-validator` | Pre-commit quality scan | 4 |
@@ -416,7 +417,7 @@ project/
 │   └── workflows/ci.yml                 # CI pipeline (adapted to your stack)
 │
 ├── .claude/
-│   ├── agents/                          # 9 specialized agents
+│   ├── agents/                          # 10 specialized agents
 │   ├── skills/
 │   │   ├── development-workflow/        # Main task workflow (Steps 0-6)
 │   │   │   └── references/              # Templates, guides, examples
@@ -432,11 +433,12 @@ project/
 │   └── settings.json                    # Shared hooks (git-tracked)
 │
 ├── .gemini/
-│   ├── agents/                          # 9 agents (Gemini format)
+│   ├── agents/                          # 10 agents (Gemini format)
 │   ├── skills/                          # Same 4 skills
 │   ├── commands/                        # Slash commands (workflow + review + context + project review)
 │   └── settings.json                    # Gemini configuration
 │
+│
 ├── ai-specs/specs/
 │   ├── base-standards.mdc              # Constitution + methodology
 │   ├── backend-standards.mdc           # Backend patterns
@@ -449,7 +451,7 @@ project/
     │   ├── key_facts.md
     │   ├── bugs.md
     │   └── decisions.md
-    ├── specs/                           # API and UI specs
+    ├── specs/                           # API, UI, and design specs
     └── tickets/                         # Task tickets (workflow-generated)
 ```
 

package/lib/adapt-agents.js

@@ -80,10 +80,15 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
         [/,? components not in ui-components\.md/, ''],
         [/\.? ?Check components vs `ui-components\.md`/, ''],
       ]);
-      // SKILL.md: remove ui-components references
+      // SKILL.md: remove ui-components references and design review step
       replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
         [/,? `ui-components\.md`\)/, ')'],
         [/- UI components → `docs\/specs\/ui-components\.md` \(MANDATORY\)\n/, ''],
+        [/\d+\. \*\*Design Review \(optional\):\*\*[^\n]*\n/, ''],
+      ]);
+      // AGENTS.md: remove ui-ux-designer from hook description
+      replaceInFileFn(path.join(dest, 'AGENTS.md'), [
+        [', `ui-ux-designer`', ''],
       ]);
       // ticket-template: remove UI Changes section, ui-components from checklists
       replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'ticket-template.md'), [
@@ -95,6 +100,10 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
         [' / ui-components.md', ''],
       ]);
     }
+    // Shared files (outside tool dirs): remove ui-ux-designer and design-guidelines refs
+    replaceInFileFn(path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc'), [
+      [/\| `ui-ux-designer` \|[^\n]*\n/, ''],
+    ]);
   } else if (config.projectType === 'frontend') {
     for (const dir of toolDirs) {
       replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [

package/lib/config.js

@@ -90,7 +90,7 @@ const BRANCHING_STRATEGIES = [
 ];
 
 // Agent files categorized by scope
-const FRONTEND_AGENTS = ['frontend-developer.md', 'frontend-planner.md'];
+const FRONTEND_AGENTS = ['frontend-developer.md', 'frontend-planner.md', 'ui-ux-designer.md'];
 const BACKEND_AGENTS = ['backend-developer.md', 'backend-planner.md', 'database-architect.md'];
 
 // All template-provided agent files (for upgrade: detect custom agents)
@@ -98,6 +98,7 @@ const TEMPLATE_AGENTS = [
   ...FRONTEND_AGENTS,
   ...BACKEND_AGENTS,
   'spec-creator.md',
+  'ui-ux-designer.md',
   'code-review-specialist.md',
   'production-code-validator.md',
   'qa-engineer.md',

package/lib/generator.js

@@ -266,8 +266,9 @@ function removeFrontendFiles(dest, config) {
     safeDelete(path.join(dest, '.claude', 'agents', agent));
     safeDelete(path.join(dest, '.gemini', 'agents', agent));
   }
-  // Remove frontend spec
+  // Remove frontend specs
   safeDelete(path.join(dest, 'docs', 'specs', 'ui-components.md'));
+  safeDelete(path.join(dest, 'docs', 'specs', 'design-guidelines.md'));
 
   // Remove frontend from .env.example
   replaceInFile(path.join(dest, '.env.example'), [

package/lib/init-generator.js

@@ -120,6 +120,11 @@ function generateInit(config) {
       path.join(dest, 'docs', 'specs', 'ui-components.md'),
       skipped
     );
+    copyFileIfNotExists(
+      path.join(templateDir, 'docs', 'specs', 'design-guidelines.md'),
+      path.join(dest, 'docs', 'specs', 'design-guidelines.md'),
+      skipped
+    );
   }
 
   // docs/tickets/.gitkeep

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Create a new SDD DevFlow project with AI-assisted development workflow",
   "bin": {
     "create-sdd-project": "bin/cli.js"

package/template/.claude/agents/frontend-developer.md

@@ -20,8 +20,9 @@ Implement the frontend task following the **Implementation Plan** in the ticket.
 1. Read the ticket file (including the Spec and Implementation Plan)
 2. Read `ai-specs/specs/frontend-standards.mdc` for coding standards
 3. Read `docs/specs/ui-components.md` for current UI component specs
-4. Read `docs/specs/api-spec.yaml` for API endpoints to consume
-5. Read `docs/project_notes/key_facts.md` for project context
+4. Read `docs/specs/design-guidelines.md` if it exists — follow visual direction, colors, spacing, and animation patterns
+5. Read `docs/specs/api-spec.yaml` for API endpoints to consume
+6. Read `docs/project_notes/key_facts.md` for project context
 6. Read `docs/project_notes/bugs.md` for known issues to avoid
 
 ## TDD Cycle

package/template/.claude/agents/frontend-planner.md

@@ -24,8 +24,9 @@ Generate a detailed **Implementation Plan** and write it into the ticket's `## I
 2. Read `docs/project_notes/key_facts.md` for existing reusable components
 3. Read the ticket file passed as input (including the `## Spec` section)
 4. Read `docs/specs/ui-components.md` for current UI component specs
-5. Read `docs/specs/api-spec.yaml` for API endpoints to consume
-6. Explore existing components, utilities, services, stores, and pages
+5. Read `docs/specs/design-guidelines.md` if it exists — respect visual direction, colors, spacing, and animation patterns
+6. Read `docs/specs/api-spec.yaml` for API endpoints to consume
+7. Explore existing components, utilities, services, stores, and pages
 
 **Reuse over recreate.** Only propose new components when existing ones don't fit.
 

package/template/.claude/agents/ui-ux-designer.md

@@ -0,0 +1,72 @@
+---
+name: ui-ux-designer
+description: "Use this agent to create or update design guidelines and provide feature-specific design notes. Covers visual direction, color palettes, typography, spacing, animations, responsive strategy, and UX patterns. Invoke manually when a feature needs design attention. NEVER writes implementation code."
+tools: Glob, Grep, Read, Edit, Write
+model: sonnet
+memory: project
+---
+
+You are an expert UI/UX Designer with deep knowledge of modern web design, responsive layouts, accessibility standards, and conversion-focused design patterns.
+
+## Goal
+
+Produce actionable design specifications that `frontend-planner` and `frontend-developer` can follow consistently. You work in two modes:
+
+### Mode 1: Design System Setup
+Create or update `docs/specs/design-guidelines.md` — the project's global design reference.
+
+### Mode 2: Feature Design Notes
+Write a `### Design Notes` section in the ticket for feature-specific visual and interaction decisions.
+
+**NEVER write implementation code. Only produce design specifications.**
+
+## Before Designing
+
+1. Read `docs/project_notes/key_facts.md` for project context and tech stack
+2. Read `docs/specs/design-guidelines.md` if it exists — respect established patterns
+3. Read `docs/specs/ui-components.md` for existing component inventory
+4. Read `ai-specs/specs/frontend-standards.mdc` for coding conventions that affect design (component library, styling approach)
+5. If working on a feature → read the ticket file (including `## Spec` section)
+6. Ask the user about visual direction, brand references, and any constraints before proceeding
+
+## Mode 1: Design System Setup
+
+Update `docs/specs/design-guidelines.md` with these sections:
+
+1. **Visual Direction** — overall style, mood, references (e.g., "clean and modern like Stripe" or "warm and appetizing like Uber Eats")
+2. **Colors** — primary, secondary, accent, semantic (success/error/warning/info), neutrals. Include exact values.
+3. **Typography** — font families, size scale, weights, line heights. Specify heading and body styles.
+4. **Spacing & Layout** — spacing scale, grid system, max-width, breakpoints, how layouts reflow on mobile
+5. **Component Styles** — border-radius, shadows, hover/focus/active states, transitions
+6. **Animations & Interactions** — types allowed (fade, slide, scale), duration ranges, easing, when to use vs not use
+7. **States & Feedback** — loading, error, empty, success, disabled, validation patterns
+8. **Content Hierarchy** — heading patterns, CTA tone, helper text style, error message format
+9. **Accessibility** — minimum contrast ratios, focus indicators, ARIA patterns, touch targets
+10. **Imagery & Icons** — style (photography vs illustration vs icons), icon library, placeholder strategy
+11. **Constraints & Anti-Patterns** — what NOT to do (this is especially valuable for AI agents)
+
+**Only update sections that change.** Do not rewrite the entire document for a single palette adjustment.
+
+## Mode 2: Feature Design Notes
+
+Write a `### Design Notes` section in the ticket with feature-specific decisions:
+
+- Page/screen layout and visual hierarchy
+- Key user flows and what the user should notice first
+- Responsive behavior (not just breakpoints — how content reflows, what gets deprioritized on mobile)
+- Specific component styling if it deviates from the design system
+- Animation and interaction details for this feature
+- Conversion/marketing considerations (if applicable — e.g., landing pages, onboarding flows)
+
+**Reference `design-guidelines.md` instead of repeating global values.** Only document what is specific to this feature.
+
+## Rules
+
+- **NEVER** write implementation code — only design specifications
+- **NEVER** choose technical architecture or libraries — that is `frontend-planner`'s job
+- **NEVER** define business requirements — that is `spec-creator`'s job
+- **ALWAYS** ask the user for visual direction before generating guidelines from scratch
+- **ALWAYS** adapt recommendations to the detected tech stack (e.g., Tailwind classes if using Tailwind, CSS custom properties if using CSS modules)
+- **ALWAYS** provide specific, actionable values (not "use a modern font" — say "Inter, 16px base, 1.5 line-height")
+- **ALWAYS** include anti-patterns — what not to do is as important as what to do
+- **ALWAYS** consider accessibility (WCAG 2.1 AA minimum)

package/template/.claude/skills/development-workflow/SKILL.md

@@ -72,6 +72,7 @@ Ask user to classify complexity before starting. See `references/complexity-guid
 3. Agent writes spec summary into the ticket's `## Spec` section
 4. **Spec Self-Review:** Re-read the spec critically. Are requirements complete? Edge cases covered? API contract well-defined? Acceptance criteria testable? Does the spec conflict with existing architecture (`key_facts.md`, `decisions.md`)? Update the spec with any fixes found before proceeding.
 5. **Cross-Model Spec Review:** Run `/review-spec`. If at least one external CLI is available (`gemini`, `codex`), this provides independent validation from other models. If no external CLIs are detected, skip this step (the self-review above is sufficient).
+6. **Design Review (optional):** If this feature includes UI changes, mention to the user: "This feature has UI changes. Want to invoke `ui-ux-designer` for design notes?" If yes, use Task tool with `ui-ux-designer` agent. If `docs/specs/design-guidelines.md` does not exist yet, suggest creating it first.
 
 **→ CHECKPOINT: Spec Approval** — Update tracker (Active Session + Features table): step `0/6 (Spec)`
 
@@ -187,6 +188,7 @@ Update tracker (Active Session + Features table): step `4/6 (Finalize)`. Mark ti
 | `production-code-validator` | 4 | Pre-commit validation |
 | `code-review-specialist` | 5 | Pre-merge review |
 | `qa-engineer` | 5 | Edge cases, spec verification (Std/Cplx) |
+| `ui-ux-designer` | 0 (optional) | Design guidelines, feature design notes |
 | `database-architect` | Any | Schema, migrations, queries |
 
 ## References

package/template/.gemini/agents/frontend-developer.md

@@ -14,8 +14,9 @@ Implement the task following the Implementation Plan in the ticket. Use strict T
 1. Read ticket (including Spec and Implementation Plan)
 2. Read `ai-specs/specs/frontend-standards.mdc`
 3. Read `docs/specs/ui-components.md` for current UI component specs
-4. Read `docs/specs/api-spec.yaml` for API endpoints to consume
-5. Read `docs/project_notes/key_facts.md` and `bugs.md`
+4. Read `docs/specs/design-guidelines.md` if it exists — follow visual direction, colors, spacing, and animation patterns
+5. Read `docs/specs/api-spec.yaml` for API endpoints to consume
+6. Read `docs/project_notes/key_facts.md` and `bugs.md`
 
 ## Documentation Updates (MANDATORY — in real time)
 

package/template/.gemini/agents/frontend-planner.md

@@ -15,8 +15,9 @@ Generate a detailed Implementation Plan and write it into the ticket's `## Imple
 2. Read `docs/project_notes/key_facts.md`
 3. Read the ticket file (including `## Spec` section)
 4. Read `docs/specs/ui-components.md` for current UI component specs
-5. Read `docs/specs/api-spec.yaml` for API endpoints to consume
-6. Explore existing components, services, stores, pages
+5. Read `docs/specs/design-guidelines.md` if it exists — respect visual direction, colors, spacing, and animation patterns
+6. Read `docs/specs/api-spec.yaml` for API endpoints to consume
+7. Explore existing components, services, stores, pages
 
 **Reuse over recreate.** Only propose new components when existing ones don't fit.
 

package/template/.gemini/agents/ui-ux-designer.md

@@ -0,0 +1,56 @@
+# UI/UX Designer
+
+**Role**: Design specifications and visual guidelines
+**When to Use**: Manually invoke when a feature needs design attention or to set up the project's design system
+
+## Instructions
+
+Produce actionable design specifications that frontend-planner and frontend-developer can follow. Two modes:
+
+- **Design System Setup**: Create/update `docs/specs/design-guidelines.md`
+- **Feature Design Notes**: Write `### Design Notes` in the ticket for feature-specific decisions
+
+NEVER write implementation code — only design specifications.
+
+## Before Designing
+
+1. Read `docs/project_notes/key_facts.md` for project context
+2. Read `docs/specs/design-guidelines.md` if it exists
+3. Read `docs/specs/ui-components.md` for existing components
+4. Read `ai-specs/specs/frontend-standards.mdc` for coding conventions
+5. If working on a feature → read the ticket
+6. Ask the user about visual direction and constraints
+
+## Design System Sections (docs/specs/design-guidelines.md)
+
+1. Visual Direction — style, mood, references
+2. Colors — primary, secondary, accent, semantic, neutrals (exact values)
+3. Typography — fonts, sizes, weights, line heights
+4. Spacing & Layout — scale, grid, breakpoints, mobile reflow
+5. Component Styles — border-radius, shadows, states, transitions
+6. Animations & Interactions — types, duration, easing, when to use
+7. States & Feedback — loading, error, empty, success, disabled
+8. Content Hierarchy — headings, CTA tone, helper text, error messages
+9. Accessibility — contrast, focus indicators, ARIA, touch targets
+10. Imagery & Icons — style, icon library, placeholders
+11. Constraints & Anti-Patterns — what NOT to do
+
+## Feature Design Notes (in ticket)
+
+- Layout and visual hierarchy
+- Key user flows, what user notices first
+- Responsive behavior (how content reflows, mobile priorities)
+- Feature-specific styling deviations
+- Animation details
+- Conversion/marketing considerations (if applicable)
+
+## Rules
+
+- NEVER write implementation code
+- NEVER choose technical architecture (frontend-planner does that)
+- NEVER define business requirements (spec-creator does that)
+- ALWAYS ask user for visual direction before generating from scratch
+- ALWAYS provide specific values (not "modern font" — say "Inter, 16px, 1.5 line-height")
+- ALWAYS include anti-patterns
+- ALWAYS consider accessibility (WCAG 2.1 AA minimum)
+- ALWAYS adapt to detected tech stack

package/template/.gemini/skills/development-workflow/SKILL.md

@@ -72,6 +72,7 @@ Ask user to classify complexity before starting. See `references/complexity-guid
 3. Write spec summary into the ticket's `## Spec` section
 4. **Spec Self-Review:** Re-read the spec critically. Are requirements complete? Edge cases covered? API contract well-defined? Acceptance criteria testable? Does the spec conflict with existing architecture (`key_facts.md`, `decisions.md`)? Update the spec with any fixes found before proceeding.
 5. **Cross-Model Spec Review:** Run `/review-spec`. If at least one external CLI is available (`claude`, `codex`), this provides independent validation from other models. If no external CLIs are detected, skip this step (the self-review above is sufficient).
+6. **Design Review (optional):** If this feature includes UI changes, mention to the user: "This feature has UI changes. Want to invoke `ui-ux-designer` for design notes?" If yes, follow the `ui-ux-designer` agent instructions in `.gemini/agents/`. If `docs/specs/design-guidelines.md` does not exist yet, suggest creating it first.
 
 **→ CHECKPOINT: Spec Approval** — Update tracker (Active Session + Features table): step `0/6 (Spec)`
 
@@ -187,6 +188,7 @@ Update tracker (Active Session + Features table): step `4/6 (Finalize)`. Mark ti
 | `production-code-validator` | 4 | Pre-commit validation |
 | `code-review-specialist` | 5 | Pre-merge review |
 | `qa-engineer` | 5 | Edge cases, spec verification (Std/Cplx) |
+| `ui-ux-designer` | 0 (optional) | Design guidelines, feature design notes |
 | `database-architect` | Any | Schema, migrations, queries |
 
 Agent instructions are in `.gemini/agents/`. Read the relevant agent file when entering its step.

package/template/AGENTS.md

@@ -54,7 +54,7 @@ After context loss, new session, or context compaction — BEFORE continuing wor
 
 The project includes pre-configured hooks in `.claude/settings.json`:
 
-- **Quick Scan** (`SubagentStop`): After `backend-developer` or `frontend-developer` finishes, a fast grep-based scan (~2s, no additional API calls) checks for `console.log`, `debugger`, `TODO/FIXME`, hardcoded secrets, and localhost references. Critical issues block; warnings are non-blocking (full review happens in Step 5).
+- **Quick Scan** (`SubagentStop`): After `backend-developer`, `frontend-developer`, or `ui-ux-designer` finishes, a fast grep-based scan (~2s, no additional API calls) checks for `console.log`, `debugger`, `TODO/FIXME`, hardcoded secrets, and localhost references. Critical issues block; warnings are non-blocking (full review happens in Step 5).
 - **Compaction Recovery** (`SessionStart → compact`): After context compaction, injects a reminder to read the product tracker Active Session for context recovery.
 
 Personal notification hooks (macOS/Linux) are in `.claude/settings.local.json` — see that file for examples.

package/template/ai-specs/specs/base-standards.mdc

@@ -84,6 +84,7 @@ Quality gates (tests, lint, build, validators) **always run** regardless of leve
 | `production-code-validator` | Pre-commit validation (debug code, TODOs, secrets, spec drift) |
 | `code-review-specialist` | Pre-merge code review |
 | `qa-engineer` | Edge cases, spec verification, regression (Std/Cplx) |
+| `ui-ux-designer` | Design guidelines and feature design notes (invoke manually) |
 | `database-architect` | Schema design, migrations, query optimization (invoke manually) |
 
 ## 5. Shared Types Strategy

package/template/docs/specs/design-guidelines.md

@@ -0,0 +1,50 @@
+# Design Guidelines
+
+> Project design system. Updated by the `ui-ux-designer` agent, consumed by `frontend-planner` and `frontend-developer`.
+> Invoke `ui-ux-designer` to populate this document with your project's visual direction.
+
+<!-- CONFIG: This file starts empty. Run the ui-ux-designer agent to fill it based on your brand and requirements. -->
+
+## Visual Direction
+
+[Style, mood, and visual references — to be defined by ui-ux-designer]
+
+## Colors
+
+[Primary, secondary, accent, semantic (success/error/warning/info), neutrals — exact values]
+
+## Typography
+
+[Font families, size scale, weights, line heights — heading and body styles]
+
+## Spacing & Layout
+
+[Spacing scale, grid system, max-width, breakpoints, mobile reflow strategy]
+
+## Component Styles
+
+[Border-radius, shadows, hover/focus/active states, transitions]
+
+## Animations & Interactions
+
+[Allowed types, duration ranges, easing functions, when to use vs when not to]
+
+## States & Feedback
+
+[Loading, error, empty, success, disabled, validation — visual patterns for each]
+
+## Content Hierarchy
+
+[Heading patterns, CTA tone and placement, helper text style, error message format]
+
+## Accessibility
+
+[Minimum contrast ratios, focus indicators, ARIA patterns, touch target sizes]
+
+## Imagery & Icons
+
+[Photography vs illustration vs icons, icon library, placeholder strategy]
+
+## Constraints & Anti-Patterns
+
+[What NOT to do — specific patterns to avoid in this project]