prjct-cli 0.18.2 → 0.20.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # 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
+
+The web dashboard (`packages/web/`) has been extracted to a separate repository for independent development.
+
+**Removed:**
+- `packages/web/` - Next.js dashboard app (~200 files)
+- `bin/serve.js`, `bin/dev.js` - Web server scripts
+- `templates/commands/serve.md` - /p:serve command
+- `prjct-serve`, `prjct-dev` bin entries
+
+### Fix: Prompt Builder Now Sends Full Templates
+
+Fixed critical bug where `prompt-builder.ts` only extracted `## Flow` sections, causing Claude to miss important instructions.
+
+**Before:** Claude only saw the Flow section (~30% of template)
+**After:** Claude sees the full template content
+
+**Files Modified:**
+- `core/agentic/prompt-builder.ts` - Removed regex extraction, send full content
+
+### Improved: Templates Simplified
+
+Reduced template verbosity for better Claude comprehension:
+
+| Template | Before | After |
+|----------|--------|-------|
+| ship.md | 359 lines | ~110 lines |
+| done.md | 318 lines | ~117 lines |
+| now.md | 346 lines | ~141 lines |
+
+### Improved: Timestamp Generation
+
+Changed from undefined `GetTimestamp()` to actual bash commands:
+
+```bash
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
+```
+
 ## [0.18.2] - 2025-12-15
 
 ### Fix: Agents Write to Global Storage

package/CLAUDE.md

@@ -6,255 +6,118 @@ This file provides guidance to Claude Code when working with prjct-cli.
 
 **prjct-cli** is a developer momentum tool. Track progress through slash commands without meetings or traditional PM overhead.
 
-## CRITICAL: Timestamp Management
+## CRITICAL RULES
 
-**LLM DOES NOT KNOW CURRENT DATE/TIME** - Never generate timestamps manually.
-
-### Tools (MUST USE)
-- `GetTimestamp()` → ISO format: "2025-10-07T14:30:00.000Z"
-- `GetDate()` → YYYY-MM-DD format: "2025-10-07"
-
-### Rules
-1. **NEVER** generate timestamps manually - All hardcoded dates are WRONG
-2. **ALWAYS** call GetTimestamp() for session files (*.jsonl)
-3. **ALWAYS** call GetDate() for index files (shipped.md, roadmap.md, ideas.md)
-
-## Core Workflow
+### 1. Path Resolution
+**ALL writes go to global storage**: `~/.prjct-cli/projects/{projectId}/`
+- NEVER write to `.prjct/` (config only)
+- NEVER write to `./` (current directory)
 
+### 2. Timestamps
+```bash
+# Prefer bun, fallback to node
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
 ```
-p. analyze    → Analyze stack, generate agents
-p. feature    → Add feature with tasks
-p. done       → Mark complete, next task
-p. ship       → Lint/test/commit/push
-```
-
-## Architecture: MD-First
+- Result: `"2025-12-20T10:30:00.000Z"`
+- NEVER hardcode dates or times
 
-**MD files are the source of truth.** No JSON data files - all state is stored directly in Markdown.
+### 3. UUIDs
+```bash
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
+```
 
-### Global Storage
+### 4. Git Commit Footer
 ```
-~/.prjct-cli/projects/{id}/
-├── core/           # now.md (current task), next.md (queue)
-├── progress/       # shipped.md, sessions/
-├── planning/       # ideas.md, roadmap.md
-├── analysis/       # repo-summary.md
-├── memory/         # context.jsonl (append-only logs)
-├── agents/         # Generated specialists
-└── project.json    # Metadata only (name, repoPath, techStack)
+🤖 Generated with [p/](https://www.prjct.app/)
+Designed for [Claude](https://www.anthropic.com/claude)
 ```
 
-### Key Files (Source of Truth)
-| File | Purpose |
-|------|---------|
-| `core/now.md` | Current task state |
-| `core/next.md` | Task queue |
-| `planning/ideas.md` | Ideas backlog |
-| `planning/roadmap.md` | Feature roadmap |
-| `progress/shipped.md` | Shipped features |
+## Architecture: Write-Through
 
-### Local Config
 ```
-.prjct/prjct.config.json  # Links to global data via projectId
-```
-
-### Session Format (JSONL)
-```jsonl
-{"ts":"{GetTimestamp()}","type":"task_complete","task":"auth","duration":"2h15m"}
+User Action → Storage (JSON) → Context (MD) → Sync Events
 ```
 
-## Natural Language: p. Trigger
-
-When message starts with `p.`:
-1. Check `.prjct/prjct.config.json` exists
-2. Detect intent from message
-3. **USE SlashCommand tool** to execute the command
-
-⚠️ **CRITICAL** - Always use SlashCommand, never work directly:
-- ✅ `SlashCommand("/p:feature add dark mode")`
-- ❌ Directly creating files without the command
-
-If no project: "No prjct project. Run /p:init first."
-
-### Intent Map
-
-| User Intent | Command | What It Does |
-|-------------|---------|--------------|
-| Start/focus on task | `/p:now` | Sets current task |
-| Finished work | `/p:done` | Marks complete |
-| Ready to ship | `/p:ship` | Ship feature |
-| Has an idea | `/p:idea` | Saves to backlog |
-| See progress | `/p:recap` | Shows overview |
-| What's next | `/p:next` | Priority queue |
-| Need help | `/p:help` | Interactive guide |
-
-**Any language works** - English, Spanish, etc.
-
-## Command Execution
-
-All `/p:*` commands:
-1. Read `.prjct/prjct.config.json` → get projectId
-2. Operate on `~/.prjct-cli/projects/{id}/`
-3. Update files atomically
-4. Return formatted response
-
-### Confirmation Policy
-
-**ALL commands MUST ask for confirmation before execution:**
-1. User triggers command
-2. Present plan of what will be done
-3. User approves
-4. Execute
-
-### Command Distinctions
-
-**`/p:idea`** - Quick idea capture (simple write)
-**`/p:workflow`** - Multi-agent workflow management (state machine)
-
-## Available Commands
-
-### Work
-- `/p:now [task]` - Set current task
-- `/p:next` - Priority queue
-- `/p:done` - Complete task
-- `/p:ship <feature>` - Ship and celebrate
-- `/p:bug <desc>` - Report bug
-
-### Planning
-- `/p:idea <text>` - Capture idea
-- `/p:feature <desc>` - Add feature
-- `/p:workflow` - Workflow status
-
-### Progress
-- `/p:recap` - Project overview
-- `/p:progress [period]` - Metrics
-- `/p:status` - KPI dashboard
+| Layer | Path | Purpose |
+|-------|------|---------|
+| Storage | `storage/*.json` | Source of truth |
+| Context | `context/*.md` | Claude-readable (generated) |
+| Sync | `sync/pending.json` | Backend events |
+| Memory | `memory/events.jsonl` | Audit trail |
 
-### Help
-- `/p:init` - Initialize project
-- `/p:help` - Interactive guide
-- `/p:ask <question>` - Intent translator
-- `/p:suggest` - Smart recommendations
-- `/p:analyze` - Analyze repository
-- `/p:sync` - Sync state
-
-### Quality
-- `/p:cleanup` - Clean up
-- `/p:design` - System design
-
-## Agentic Architecture
-
-prjct-cli is template-driven. Claude reads templates and executes using tools.
-
-### Flow
+### File Structure
 ```
-Template (MD) → Claude reads → Claude decides → Claude uses tools → Result
+~/.prjct-cli/projects/{projectId}/
+├── storage/
+│   ├── state.json         # Current task (source of truth)
+│   ├── shipped.json       # Shipped features
+│   └── queue.json         # Task queue
+├── context/
+│   ├── now.md             # Generated from state.json
+│   └── shipped.md         # Generated from shipped.json
+├── sync/pending.json      # Backend events
+├── memory/events.jsonl    # Audit trail
+└── agents/                # Domain specialists
 ```
 
-### Structure
-```
-core/agentic/
-├── template-loader.js    # Loads command templates
-├── context-builder.js    # Builds project context
-├── prompt-builder.js     # Generates prompts
-├── command-executor.js   # Executes commands
-└── tool-registry.js      # Maps tools
+## Core Workflow
 
-templates/commands/       # Command instructions
-templates/workflows/      # Workflow guides
-templates/analysis/       # Analysis instructions
 ```
-
-### Templates as Source of Truth
-
-Templates define what Claude should do:
-
-```markdown
-# /p:done
-
-## Validation
-- Requires: `core/now.md` has content
-
-## Flow
-1. Read `core/now.md` → calculate duration
-2. Clear now.md
-3. Update metrics
-
-## Response
-✅ {task} ({duration})
+/p:sync → /p:now "task" → [work] → /p:done → /p:ship
 ```
 
-Claude reads this and:
-1. Checks validation
-2. Executes flow using tools
-3. Generates response
-4. Suggests next actions
+## Commands
 
-## Git Commit Format
+| Command | Purpose |
+|---------|---------|
+| `/p:sync` | Analyze repo, generate agents |
+| `/p:now [task]` | Start/show current task |
+| `/p:done` | Complete current task |
+| `/p:ship [feature]` | Ship with quality checks |
+| `/p:feature` | Add to roadmap |
+| `/p:idea` | Quick idea capture |
+| `/p:recap` | Project overview |
 
-**ALL commits by prjct MUST use this footer:**
+## Natural Language Trigger
 
+Messages starting with `p.` trigger commands:
 ```
-🤖 Generated with [p/](https://www.prjct.app/)
-Designed for [Claude](https://www.anthropic.com/claude)
+p. start auth → /p:now "auth"
+p. done       → /p:done
+p. ship login → /p:ship "login"
 ```
 
-**Never use:**
-- "Generated with Claude Code"
-- "Co-Authored-By: Claude"
-
-## Agent Generation
+## Template-Driven Execution
 
-Dynamic agents based on project analysis.
-
-See `templates/agents/AGENTS.md` for reference.
+Templates define command behavior:
+```
+templates/commands/{command}.md
+```
 
-Use: `generator.generateDynamicAgent(name, config)`
+Claude reads template → executes flow → generates response.
 
 ## Key Rules
 
 1. **Read files before editing** - Never assume structure
-2. **Use system timestamps** - Never hardcode dates
+2. **Use node commands for timestamps** - Never hardcode dates
 3. **Follow template instructions** - Templates are source of truth
-4. **Confirm before executing** - Always show plan first
-5. **Log actions** - Append to memory/context.jsonl
-6. **Suggest next actions** - Maintain user momentum
-
-## Output Philosophy
+4. **Log to memory** - Append to `memory/events.jsonl`
+5. **Suggest next actions** - Maintain user momentum
 
-**Task completion responses MUST be concise (< 4 lines):**
+## Output Format
 
-Format:
+Concise responses (< 4 lines):
 ```
 ✅ [What was done]
 
-Files: [count] | Modified: [key file]
-Next: [action]
+[Key metrics]
+Next: [suggested action]
 ```
 
-**NEVER include in task summaries:**
-- Tables listing files
-- "Created Files" / "Modified Files" sections
-- "How It Works" explanations
-- Code snippets or implementation details
-- Detailed breakdowns of what was done
+## Documentation
 
-**Example (GOOD):**
-```
-✅ Agentic checklists integrated
-
-Files: 11 created | Modified: prompt-builder.js
-Next: /p:ship or test with /p:now
-```
-
-**Example (BAD):**
-```
-Created Files:
-| File | Purpose |
-|------|---------|
-| x.md | Does X  |
-...
-
-How It Works:
-Claude reads → decides → applies...
-```
+For detailed information:
+- Architecture: `~/.prjct-cli/docs/architecture.md`
+- Commands: `~/.prjct-cli/docs/commands.md`
+- Validation: `~/.prjct-cli/docs/validation.md`
+- Agents: `~/.prjct-cli/docs/agents.md`

package/core/agentic/prompt-builder.ts

@@ -330,13 +330,9 @@ class PromptBuilder {
 
     parts.push('\n---\n')
 
-    // Template (only the flow section, skip verbose explanations)
-    const flowMatch = template.content.match(/## Flow([\s\S]*?)(?=##|$)/)
-    if (flowMatch) {
-      parts.push(flowMatch[0])
-    } else {
-      parts.push(template.content)
-    }
+    // Template content (include full template, frontmatter already stripped by loader)
+    // This ensures Claude sees ALL instructions including critical rules at the top
+    parts.push(template.content)
 
     // Current state (only if exists and relevant)
     const relevantState = this.filterRelevantState(state)

package/core/command-registry/optional-commands.ts

@@ -160,24 +160,4 @@ export const OPTIONAL_COMMANDS: Command[] = [
     ],
   },
 
-  {
-    name: 'serve',
-    category: 'optional',
-    description: 'Start prjct web server',
-    usage: {
-      claude: '/p:serve',
-      terminal: 'prjct serve',
-    },
-    params: '[port]',
-    implemented: true,
-    hasTemplate: true,
-    requiresInit: true,
-    blockingRules: null,
-    isOptional: true,
-    features: [
-      'Local dashboard server',
-      'API endpoints',
-      'Real-time updates',
-    ],
-  },
 ]

package/core/infrastructure/command-installer/command-installer.ts

@@ -7,7 +7,7 @@ import fs from 'fs/promises'
 import path from 'path'
 import os from 'os'
 import type { InstallResult, UninstallResult, CheckResult, SyncResult, GlobalConfigResult } from './types'
-import { installGlobalConfig } from './global-config'
+import { installGlobalConfig, installDocs } from './global-config'
 
 export class CommandInstaller {
   homeDir: string
@@ -317,4 +317,11 @@ export class CommandInstaller {
   async installGlobalConfig(): Promise<GlobalConfigResult> {
     return installGlobalConfig(this.claudeConfigPath, () => this.detectClaude())
   }
+
+  /**
+   * Install documentation files to ~/.prjct-cli/docs/
+   */
+  async installDocs(): Promise<{ success: boolean; error?: string }> {
+    return installDocs()
+  }
 }

package/core/infrastructure/command-installer/global-config.ts

@@ -1,6 +1,6 @@
 /**
  * Global Config Operations
- * Install/update global CLAUDE.md configuration
+ * Install/update global CLAUDE.md configuration and docs
  */
 
 import fs from 'fs/promises'
@@ -8,6 +8,36 @@ import path from 'path'
 import os from 'os'
 import type { GlobalConfigResult } from './types'
 
+/**
+ * Install documentation files to ~/.prjct-cli/docs/
+ */
+export async function installDocs(): Promise<{ success: boolean; error?: string }> {
+  try {
+    const docsDir = path.join(os.homedir(), '.prjct-cli', 'docs')
+    const templateDocsDir = path.join(__dirname, '../../../templates/global/docs')
+
+    // Ensure docs directory exists
+    await fs.mkdir(docsDir, { recursive: true })
+
+    // Read all doc files from template
+    const docFiles = await fs.readdir(templateDocsDir)
+
+    // Copy each doc file
+    for (const file of docFiles) {
+      if (file.endsWith('.md')) {
+        const srcPath = path.join(templateDocsDir, file)
+        const destPath = path.join(docsDir, file)
+        const content = await fs.readFile(srcPath, 'utf-8')
+        await fs.writeFile(destPath, content, 'utf-8')
+      }
+    }
+
+    return { success: true }
+  } catch (error) {
+    return { success: false, error: (error as Error).message }
+  }
+}
+
 /**
  * Install or update global CLAUDE.md configuration
  */

package/core/infrastructure/command-installer/index.ts

@@ -16,7 +16,7 @@ export type {
   GlobalConfigResult,
 } from './types'
 
-export { installGlobalConfig } from './global-config'
+export { installGlobalConfig, installDocs } from './global-config'
 export { CommandInstaller } from './command-installer'
 
 import { CommandInstaller } from './command-installer'

package/core/infrastructure/setup.ts

@@ -103,6 +103,9 @@ export async function run(): Promise<SetupResults> {
     if (configResult.success) {
       results.configAction = configResult.action
     }
+
+    // Step 4b: Install documentation files
+    await installer.installDocs()
   }
 
   // Step 5: Save version in editors-config

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "prjct-cli",
-  "version": "0.18.2",
+  "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": {
-    "prjct": "bin/prjct",
-    "prjct-dev": "bin/dev.js",
-    "prjct-serve": "bin/serve.js"
+    "prjct": "bin/prjct"
   },
   "workspaces": [
     "packages/*"
@@ -16,11 +14,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "scripts": {
-    "dev": "bun run --filter '*' dev",
-    "build": "bun run --filter '@prjct/shared' build && bun run --filter 'web' build",
+    "build": "bun run --filter '@prjct/shared' build",
     "build:shared": "bun run --filter '@prjct/shared' build",
-    "build:web": "bun run --filter 'web' build",
-    "serve": "bun run --filter 'web' dev",
     "postinstall": "bun scripts/postinstall.js",
     "update-commands": "bun -e \"const installer = require('./core/infrastructure/command-installer'); installer.syncCommands().then(r => console.log('Commands updated:', r)).catch(e => console.error('Error:', e.message))\"",
     "install-global": "./scripts/install.sh",
@@ -84,15 +79,6 @@
     "bin/",
     "core/",
     "packages/shared/",
-    "packages/web/app/",
-    "packages/web/components/",
-    "packages/web/context/",
-    "packages/web/hooks/",
-    "packages/web/lib/",
-    "packages/web/public/",
-    "packages/web/*.ts",
-    "packages/web/*.json",
-    "packages/web/*.mjs",
     "templates/",
     "scripts/postinstall.js",
     "scripts/install.sh",