prjct-cli 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [0.20.0] - 2025-12-21
+
+### Feature: UX/UI Design Agent Integration
+
+Auto-generated UX/UI specialist agent for all frontend projects (web + mobile).
+
+**Priority: UX > UI** - Experience is more important than visuals.
+
+#### New Agent: `templates/agentic/agents/uxui.md`
+- **Part 1: UX Principles** - User analysis, clarity, feedback, reduced friction, error handling, accessibility (a11y)
+- **Part 2: UI Guidelines** - Aesthetic directions, typography trends (avoiding "AI slop"), color framework, purposeful animation
+- **Part 3: Quality Checklists** - Mandatory UX/UI gates before shipping
+
+#### Frontend Detection in `/p:sync`
+Auto-generates uxui.md when ANY frontend tech is detected:
+
+| Platform | Technologies |
+|----------|-------------|
+| Web | React, Vue, Svelte, Angular, Next.js, Nuxt |
+| Mobile | React Native, Expo, Flutter, SwiftUI, Jetpack Compose |
+
+#### Enhanced `/p:feature` Phase 4
+For frontend features, now includes:
+1. **UX Analysis** - Who, problem, happy path, edge cases
+2. **UX Requirements Checklist** - 6 mandatory accessibility/usability checks
+3. **Aesthetic Direction Selection** - Minimal, Bold, Soft, Brutalist
+4. **UI Guidelines Application** - Typography, color, animation, layout
+
+#### Anti-patterns Avoided ("AI Slop")
+- Generic fonts: Inter, Roboto, Arial, Space Grotesk
+- Purple/blue gradients on white
+- Centered layouts without personality
+- Unstyled component libraries
+
+**Files Added:**
+- `templates/agentic/agents/uxui.md` - Complete UX/UI specialist agent
+
+**Files Modified:**
+- `templates/commands/sync.md` - Frontend detection + uxui.md generation
+- `templates/commands/feature.md` - Phase 4.0 UX/UI analysis
+- `templates/commands/ship.md` - Pre-flight checks + confidence scoring
+
 ## [0.19.0] - 2025-12-21
 
 ### Breaking: Web Package Removed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Built for Claude - Ship fast, track progress, stay focused. Developer momentum tool for indie hackers.",
   "main": "core/index.ts",
   "bin": {

package/templates/agentic/agents/uxui.md

@@ -0,0 +1,210 @@
+# AGENT: UX/UI Design Specialist
+
+Role: User Experience and Interface Design Expert
+**Prioridad: UX > UI** - La experiencia es más importante que lo visual.
+
+---
+
+## META-INSTRUCTION
+
+You are an intelligent agent responsible for UX/UI design.
+Your mission is to ensure every interface is:
+1. **Usable** - Users understand what to do immediately
+2. **Accessible** - Works for everyone (a11y compliant)
+3. **Distinctive** - Avoids generic "AI slop" aesthetics
+
+---
+
+## PARTE 1: UX - Experiencia de Usuario
+
+### 1.1 Antes de Diseñar NADA
+
+**Preguntas obligatorias:**
+1. ¿Quién es el usuario? (persona, contexto, habilidades)
+2. ¿Qué problema resuelve? (pain point específico)
+3. ¿Cuál es el flujo crítico? (happy path)
+4. ¿Qué puede salir mal? (edge cases, errores)
+
+### 1.2 Principios UX Fundamentales
+
+#### Claridad > Creatividad
+- El usuario debe entender qué hacer en < 3 segundos
+- Evitar ambigüedad en acciones principales
+- Labels claros, no cleverness
+
+#### Feedback Inmediato
+- Cada acción tiene respuesta visual
+- Loading states para operaciones > 100ms
+- Confirmaciones para acciones destructivas
+
+#### Reducir Fricción
+- Mínimos pasos para completar tarea
+- Defaults inteligentes
+- Autocompletar cuando sea posible
+- Remember user preferences
+
+#### Manejo de Errores
+- Mensajes de error claros y actionables
+- Prevenir errores > Recuperarse de errores
+- Validación inline, no al submit
+
+#### Accesibilidad (A11y)
+- Contrast ratio mínimo 4.5:1
+- Keyboard navigation completa
+- Screen reader compatible
+- Touch targets mínimo 44x44px (mobile)
+
+### 1.3 Patrones UX por Contexto
+
+#### Forms
+- Single column layout
+- Inline validation
+- Clear labels (no placeholder-only)
+- Progress indicator si multi-step
+
+#### Navigation
+- Max 7±2 items en nav principal
+- Breadcrumbs para deep hierarchy
+- Current location siempre visible
+
+#### Mobile
+- Thumb-zone friendly actions
+- Bottom nav para acciones frecuentes
+- Swipe gestures naturales
+- Pull-to-refresh donde aplique
+
+---
+
+## PARTE 2: UI - Diseño Visual
+
+### 2.1 Elegir Dirección Estética
+
+**ANTES de diseñar, elegir UNA dirección:**
+
+| Estética | Cuándo Usar |
+|----------|-------------|
+| Minimal | Herramientas productividad, B2B |
+| Bold/Maximalist | Entretenimiento, creativos |
+| Soft/Organic | Wellness, lifestyle |
+| Brutalist | Tech startups, developer tools |
+| Luxury | Finance, premium products |
+| Playful | Consumer apps, gaming |
+| Editorial | Content-heavy, news |
+
+### 2.2 Tipografía (Trending 2024-2025)
+
+**USAR:**
+- Display: Clash Display, Cabinet Grotesk, Satoshi, Geist
+- Body: Plus Jakarta Sans, General Sans, Outfit, Geist Mono
+- Serif accent: Fraunces, Instrument Serif
+
+**EVITAR (AI Slop):**
+- Inter, Space Grotesk, Roboto, Arial, Poppins
+- Cualquier font que veas en 90% de landing pages
+
+### 2.3 Color
+
+**Framework 60-30-10:**
+- 1 color dominante (60%)
+- 1 color secundario (30%)
+- 1 color accent (10%)
+- Usar CSS variables para tema
+
+**EVITAR:**
+- Purple/blue gradients genéricos
+- Paletas sin personalidad
+- Demasiados colores
+
+### 2.4 Animación
+
+**High Impact (usar):**
+- Staggered entrance animations
+- Page transitions suaves
+- Hover states con micro-motion
+- Skeleton loaders
+
+**Low Impact (evitar):**
+- Animaciones sin propósito
+- Bounces excesivos
+- Todo animándose a la vez
+
+**Herramientas:**
+- Web: CSS animations, Framer Motion
+- Mobile: React Native Animated, Lottie
+
+### 2.5 Layout
+
+**EXPLORAR:**
+- Bento grids
+- Overlapping elements
+- Asymmetric compositions
+- Generous whitespace
+
+**EVITAR:**
+- Todo centrado uniformemente
+- Spacing uniforme sin jerarquía
+- Layouts predecibles y genéricos
+
+---
+
+## PARTE 3: Checklist de Calidad
+
+### UX Checklist (OBLIGATORIO)
+- [ ] ¿El usuario entiende qué hacer inmediatamente?
+- [ ] ¿Cada acción tiene feedback visual?
+- [ ] ¿Los errores son claros y recuperables?
+- [ ] ¿Funciona con teclado?
+- [ ] ¿Contrast ratio >= 4.5:1?
+- [ ] ¿Touch targets >= 44px? (mobile)
+
+### UI Checklist
+- [ ] ¿Tiene dirección estética clara?
+- [ ] ¿Tipografía distintiva (no genérica)?
+- [ ] ¿Paleta de color con personalidad?
+- [ ] ¿Animaciones en momentos clave?
+- [ ] ¿Layout tiene algo memorable?
+- [ ] ¿Evita estética "AI genérica"?
+
+---
+
+## Anti-patrones a EVITAR
+
+### "AI Slop" Visual
+- Inter font everywhere
+- Purple/blue gradients genéricos
+- Generic vector illustrations
+- Centered layouts sin personalidad
+- Componentes de librería sin customizar
+- Shadows y borders idénticos en todo
+
+### Bad UX
+- Forms sin validación inline
+- No loading states
+- Errores sin solución clara
+- Click/touch targets muy pequeños
+- Navigation con 15+ items
+- No keyboard support
+- Low contrast text
+
+---
+
+## DOMAIN AUTHORITY
+
+You are the owner of the UX/UI domain.
+You have full authority to make design decisions within this scope.
+When reviewing frontend code, apply this checklist.
+When creating UI, follow these principles.
+
+## ORCHESTRATION PROTOCOL
+
+1. **ANALYZE**: Read the context. Understand the user.
+2. **PLAN**: Define aesthetic direction + UX requirements.
+3. **EXECUTE**: Implement with attention to both UX and UI.
+4. **VERIFY**: Run through checklists before delivery.
+
+## RULES
+- UX comes before UI - usability over aesthetics
+- Stay in your domain (design decisions)
+- No generic "AI slop" - be distinctive
+- Accessibility is not optional
+- Optimize for real users, not screenshots

package/templates/commands/bug.md

@@ -1,14 +1,23 @@
 ---
-allowed-tools: [Read, Write, Task, Glob]
-description: 'Report bug with auto-priority'
+allowed-tools: [Read, Write, Bash, Task, Glob]
+description: 'Report bug with auto-priority and auto-start'
 architecture: 'Write-Through (JSON → MD → Events)'
 storage-layer: true
-source-of-truth: 'storage/queue.json'
-claude-context: 'context/next.md'
+source-of-truth: 'storage/queue.json + storage/state.json'
+claude-context: 'context/next.md + context/now.md'
 backend-sync: 'sync/pending.json'
 ---
 
-# /p:bug - Report Bug with Auto-Priority
+# /p:bug - Report Bug with Auto-Start
+
+## Usage
+
+```
+/p:bug <description> [--later]
+```
+
+- `description`: Bug description
+- `--later`: Only queue, don't auto-start (default: auto-starts)
 
 ## Architecture: Write-Through Pattern
 
@@ -16,27 +25,21 @@ backend-sync: 'sync/pending.json'
 User Action → Storage (JSON) → Context (MD) → Sync Events
 ```
 
-**Source of Truth**: `storage/queue.json`
-**Claude Context**: `context/next.md` (generated)
+**Source of Truth**: `storage/queue.json` + `storage/state.json`
+**Claude Context**: `context/next.md` + `context/now.md` (generated)
 **Backend Sync**: `sync/pending.json` (events)
 
 ## Context Variables
 - `{projectId}`: From `.prjct/prjct.config.json`
 - `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
 - `{queuePath}`: `{globalPath}/storage/queue.json`
+- `{statePath}`: `{globalPath}/storage/state.json`
 - `{nextContextPath}`: `{globalPath}/context/next.md`
+- `{nowContextPath}`: `{globalPath}/context/now.md`
 - `{syncPath}`: `{globalPath}/sync/pending.json`
 - `{memoryPath}`: `{globalPath}/memory/events.jsonl`
 - `{description}`: User-provided bug description
 
-## Agent Delegation (REQUIRED)
-
-Before fixing a bug, delegate to specialist agent:
-
-1. **List agents**: `Glob("~/.prjct-cli/projects/{projectId}/agents/*.md")`
-2. **Analyze bug domain**: frontend, backend, database, etc.
-3. **Delegate via Task tool**
-
 ## Severity Keywords
 
 | Keywords | Severity | Queue Position |
@@ -46,25 +49,48 @@ Before fixing a bug, delegate to specialist agent:
 | bug, incorrect, wrong | Medium | Normal |
 | minor, typo, cosmetic | Low | Bottom |
 
-## Flow
+## Step 1: Read Config
+
+READ: `.prjct/prjct.config.json`
+EXTRACT: `projectId`
+
+IF file not found:
+  OUTPUT: "No prjct project. Run /p:init first."
+  STOP
+
+## Step 2: Parse Arguments
 
-1. Parse description for severity keywords
-2. Generate task ID (UUID)
-3. Add to queue with appropriate priority
-4. Generate context/next.md
-5. Queue sync event
-6. Log to memory
+SET: {laterFlag} = false
+IF args contain "--later":
+  SET: {laterFlag} = true
+  REMOVE "--later" from description
 
-## Update Storage (SOURCE OF TRUTH)
+PARSE description for severity keywords
+SET: {severity} based on keywords found (default: "medium")
 
-GENERATE: {taskId} = UUID v4
-SET: {now} = GetTimestamp()
+## Step 3: Generate IDs and Timestamps
+
+GET timestamp:
+```bash
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
+```
+
+GET taskId (UUID):
+```bash
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
+```
+
+SET: {now} = timestamp
+SET: {taskId} = UUID
+SET: {bugDescription} = "🐛 {description}"
+
+## Step 4: Update Queue Storage (SOURCE OF TRUTH)
 
 ### Create bug task
 ```json
 {
   "id": "{taskId}",
-  "description": "🐛 {description}",
+  "description": "{bugDescription}",
   "type": "bug",
   "priority": "{severity}",
   "section": "active",
@@ -73,22 +99,81 @@ SET: {now} = GetTimestamp()
 ```
 
 ### Update queue.json
-READ: `{queuePath}`
+READ: `{queuePath}` (or create empty { "tasks": [] })
 IF severity is "critical" or "high":
   INSERT at top of tasks array
 ELSE:
   APPEND to tasks array
+SET: lastUpdated = {now}
 WRITE: `{queuePath}`
 
-## Queue Sync Event
+### Calculate queue position
+{position} = index of task in array + 1
+
+## Step 5: Auto-Start Task (unless --later)
+
+READ: `{statePath}`
+
+IF {laterFlag} == true:
+  {autoStarted} = false
+  → Skip to Step 6
+
+IF currentTask exists AND status == "active":
+  {autoStarted} = false
+  {conflictTask} = currentTask.description
+  → Continue to Step 6
 
+### No active task - Auto-Start
+GENERATE: {sessionId} = UUID v4
+```bash
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
+```
+
+### Update state.json
+```json
+{
+  "currentTask": {
+    "id": "{taskId}",
+    "description": "{bugDescription}",
+    "status": "active",
+    "startedAt": "{now}",
+    "sessionId": "{sessionId}",
+    "type": "bug",
+    "priority": "{severity}"
+  },
+  "previousTask": {existing previousTask if any},
+  "lastUpdated": "{now}"
+}
+```
+WRITE: `{statePath}`
+
+### Generate context/now.md
+```markdown
+# NOW
+
+**{bugDescription}**
+
+Priority: {severity}
+Started: {now}
+Session: {sessionId}
+```
+WRITE: `{nowContextPath}`
+
+{autoStarted} = true
+
+## Step 6: Queue Sync Events
+
+READ: `{syncPath}` or create empty array
+
+### Queue added event
+APPEND:
 ```json
 {
   "type": "queue.task_added",
   "path": ["queue"],
   "data": {
     "taskId": "{taskId}",
-    "description": "🐛 {description}",
+    "description": "{bugDescription}",
     "priority": "{severity}",
     "type": "bug"
   },
@@ -97,41 +182,134 @@ WRITE: `{queuePath}`
 }
 ```
 
-## Response
+### Task started event (if auto-started)
+IF {autoStarted}:
+  APPEND:
+  ```json
+  {
+    "type": "task.started",
+    "path": ["state"],
+    "data": {
+      "taskId": "{taskId}",
+      "description": "{bugDescription}",
+      "sessionId": "{sessionId}"
+    },
+    "timestamp": "{now}",
+    "projectId": "{projectId}"
+  }
+  ```
+
+WRITE: `{syncPath}`
+
+## Step 7: Log to Memory
+
+APPEND to `{memoryPath}`:
+
+IF {autoStarted}:
+```json
+{"timestamp":"{now}","action":"bug_reported_started","taskId":"{taskId}","sessionId":"{sessionId}","description":"{bugDescription}","priority":"{severity}"}
+```
+
+ELSE:
+```json
+{"timestamp":"{now}","action":"bug_reported","taskId":"{taskId}","description":"{bugDescription}","priority":"{severity}"}
+```
 
+## Output
+
+### Auto-Started (default)
+```
+🐛 [{severity}] {description}
+
+Started working on fix
+Session: {sessionId}
+
+/p:done when fixed
+```
+
+### Queue Only (--later flag)
 ```
 🐛 [{severity}] {description}
 
 Queued at position #{position}
 Priority: {severity}
 
-Start: /p:now "🐛 {description}"
+Start: /p:now "{bugDescription}"
+```
+
+### Already Working on Something
+```
+🐛 [{severity}] {description}
+
+Queued at position #{position}
+Priority: {severity}
+
+⚠️ Already working on: {conflictTask}
+Complete current task first or use /p:pause
+
+Start later: /p:now "{bugDescription}"
 ```
 
 ## Examples
 
-### Critical Bug
+### Example 1: Auto-Start Bug Fix (default)
+```
+Input: /p:bug login form not validating
+
+Output:
+🐛 [medium] login form not validating
+
+Started working on fix
+Session: a1b2c3d4-...
+
+/p:done when fixed
+```
+
+### Example 2: Queue for Later
+```
+Input: /p:bug minor typo in footer --later
+
+Output:
+🐛 [low] minor typo in footer
+
+Queued at position #5
+Priority: low
+
+Start: /p:now "🐛 minor typo in footer"
+```
+
+### Example 3: Critical Bug (Auto-Start)
 ```
 Input: /p:bug production server is down
 
 Output:
 🐛 [critical] production server is down
 
-Queued at position #1
-Priority: critical
+Started working on fix
+Session: x9y8z7w6-...
 
-Start: /p:now "🐛 production server is down"
+/p:done when fixed
 ```
 
-### Normal Bug
+### Example 4: Already Working on Something
 ```
-Input: /p:bug login form validation not working
+Input: /p:bug payment not processing
 
 Output:
-🐛 [medium] login form validation not working
+🐛 [high] payment not processing
+
+Queued at position #1
+Priority: high
 
-Queued at position #3
-Priority: medium
+⚠️ Already working on: implement auth flow
+Complete current task first or use /p:pause
 
-Start: /p:now "🐛 login form validation not working"
+Start later: /p:now "🐛 payment not processing"
 ```
+
+## Error Handling
+
+| Error | Response | Action |
+|-------|----------|--------|
+| No project | "No prjct project" | STOP |
+| Write fails | Log warning | CONTINUE |