prjct-cli 0.13.2 → 0.15.0

package/templates/commands/analyze.md

@@ -1,20 +1,56 @@
 ---
 allowed-tools: [Read, Grep, Glob, Bash, TodoWrite]
 description: 'Analyze repo + generate summary'
+architecture: 'Write-Through (JSON → MD → Events)'
+storage-layer: true
+source-of-truth: 'storage/analysis.json'
+claude-context: 'context/analysis.md'
 ---
 
-# /p:analyze
+# /p:analyze - Analyze Repository
+
+## Architecture: Write-Through Pattern
+
+**Source of Truth**: `storage/analysis.json`
+**Claude Context**: `context/analysis.md` (generated)
+
+## Context Variables
+- `{projectId}`: From `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+- `{analysisStoragePath}`: `{globalPath}/storage/analysis.json`
+- `{analysisContextPath}`: `{globalPath}/context/analysis.md`
 
 ## Flow
+
 1. Scan structure → Detect tech (package.json, Gemfile, etc.)
 2. Analyze patterns → Git status
-3. Generate → `analysis/repo-summary.md`
+3. Write `storage/analysis.json` (source of truth)
+4. Generate `context/analysis.md` (for Claude)
 
 ## Report
+
 - Overview: type, lang, framework
 - Stack: technologies detected
 - Architecture: patterns, entry points
 - Agents: recommend specialists
 
+## Storage Format
+
+### storage/analysis.json
+```json
+{
+  "projectType": "web",
+  "languages": ["typescript", "javascript"],
+  "frameworks": ["react", "next.js"],
+  "entryPoints": ["src/index.ts"],
+  "patterns": ["component-based", "api-routes"],
+  "dependencies": {...},
+  "analyzedAt": "{timestamp}"
+}
+```
+
 ## Response
-`🔍 {project} | Stack: {tech} | Saved: analysis/repo-summary.md`
+
+```
+🔍 {project} | Stack: {tech} | Saved: context/analysis.md
+```

package/templates/commands/ask.md

@@ -1,18 +1,35 @@
 ---
 allowed-tools: [Read]
 description: 'Conversational intent to action translator - helps users understand what to do'
+architecture: 'Write-Through (JSON → MD → Events)'
+storage-layer: true
+source-of-truth: 'storage/*.json'
 ---
 
-# /p:ask
+# /p:ask - Intent to Action Translator
+
+## Architecture: Write-Through Pattern
+
+Reads from **Storage (JSON)** as source of truth.
+
+**Source of Truth**:
+- `storage/state.json` - Current task
+- `storage/queue.json` - Task queue
 
 ## Purpose
 
 Translate natural language intent into actionable prjct command flows. Helps users who know WHAT they want but don't know HOW.
 
+## Context Variables
+- `{projectId}`: From `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+- `{statePath}`: `{globalPath}/storage/state.json`
+- `{queuePath}`: `{globalPath}/storage/queue.json`
+
 ## Flow
 
 1. **Understand intent**: Parse user's natural language description
-2. **Analyze context**: Read project state (`core/now.md`, `core/next.md`, `planning/roadmap.md`)
+2. **Analyze context**: Read project state (`storage/state.json`, `storage/queue.json`)
 3. **Recommend flow**: Suggest specific command sequence with explanations
 4. **Ask confirmation**: Interactive - don't execute automatically
 
@@ -31,7 +48,45 @@ Translate natural language intent into actionable prjct command flows. Helps use
 → `/p:design {target} --type {architecture|api|component|database|flow}` → `/p:feature "implement {design}"` → `/p:build 1`
 
 **5. Lost/Confused**: "don't know", "help", "stuck", "what should"
-→ `/p:suggest` (context-aware recommendations) OR `/p:help` (interactive guide)
+→ `/p:suggest` (context-aware recommendations) OR `/p:dash` (see status)
+
+**6. Troubleshooting/Fixes**: "error", "broken", "not working", "fix", "stuck on"
+→ Diagnose issue → Provide fix or guidance
+
+## Troubleshooting Mode (absorbed from /p:fix)
+
+When intent is troubleshooting, provide structured guidance:
+
+### Auto-Fix (Technical Errors)
+- **Dependencies**: `npm install` missing packages
+- **Config**: Fix malformed JSON/YAML
+- **Syntax**: ESLint/Prettier auto-fix
+- **Tests**: Update snapshots, fix imports
+- **Git**: Resolve merge conflicts
+
+### Guidance (When Stuck)
+| Issue Type | Approach |
+|------------|----------|
+| Bug | Check logs → Isolate → Search error → Test fix |
+| Design | Define requirements → Start simple → Ship MVP → Iterate |
+| Performance | Profile first → Fix slowest → Cache ops → Measure |
+| Blocked | Break into tasks → Start smallest → Ship incrementally |
+
+### Response Format (troubleshooting)
+```
+🔍 Diagnosed: {issue}
+
+Suggested fixes:
+1. {fix_option_1}
+2. {fix_option_2}
+3. {fix_option_3}
+
+Let's break it down:
+1. {subtask} (~{time})
+2. {subtask} (~{time})
+
+Start with: /p:now "{first_subtask}"
+```
 
 ## Response Format
 

package/templates/commands/bug.md

@@ -1,9 +1,33 @@
 ---
 allowed-tools: [Read, Write, Task, Glob]
 description: 'Report bug with auto-priority'
+architecture: 'Write-Through (JSON → MD → Events)'
+storage-layer: true
+source-of-truth: 'storage/queue.json'
+claude-context: 'context/next.md'
+backend-sync: 'sync/pending.json'
 ---
 
-# /p:bug
+# /p:bug - Report Bug with Auto-Priority
+
+## Architecture: Write-Through Pattern
+
+```
+User Action → Storage (JSON) → Context (MD) → Sync Events
+```
+
+**Source of Truth**: `storage/queue.json`
+**Claude Context**: `context/next.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`
+- `{nextContextPath}`: `{globalPath}/context/next.md`
+- `{syncPath}`: `{globalPath}/sync/pending.json`
+- `{memoryPath}`: `{globalPath}/memory/events.jsonl`
+- `{description}`: User-provided bug description
 
 ## Agent Delegation (REQUIRED)
 
@@ -11,36 +35,103 @@ 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**:
+3. **Delegate via Task tool**
 
-```
-Task(
-  subagent_type: 'general-purpose',
-  prompt: '
-    ## Agent
-    Read: ~/.prjct-cli/projects/{projectId}/agents/{agent}.md
+## Severity Keywords
+
+| Keywords | Severity | Queue Position |
+|----------|----------|----------------|
+| crash, down, broken, production | Critical | Top |
+| error, fail, issue | High | Top |
+| bug, incorrect, wrong | Medium | Normal |
+| minor, typo, cosmetic | Low | Bottom |
 
-    ## Bug
-    {bug description}
+## Flow
+
+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
+
+## Update Storage (SOURCE OF TRUTH)
 
-    ## Flow
-    1. Read agent file
-    2. Apply expertise to fix bug
-    3. Return fix
-  '
-)
+GENERATE: {taskId} = UUID v4
+SET: {now} = GetTimestamp()
+
+### Create bug task
+```json
+{
+  "id": "{taskId}",
+  "description": "🐛 {description}",
+  "type": "bug",
+  "priority": "{severity}",
+  "section": "active",
+  "createdAt": "{now}"
+}
 ```
 
-## Severity Keywords
-- **Critical**: crash, down, broken, production
-- **High**: error, fail, issue
-- **Medium**: bug, incorrect
-- **Low**: minor, typo
+### Update queue.json
+READ: `{queuePath}`
+IF severity is "critical" or "high":
+  INSERT at top of tasks array
+ELSE:
+  APPEND to tasks array
+WRITE: `{queuePath}`
 
-## Flow
-1. Detect severity → Format: `🐛 [LEVEL] {desc}`
-2. Insert: top if critical/high, bottom if med/low
-3. Update `core/next.md` + log
+## Queue Sync Event
+
+```json
+{
+  "type": "queue.task_added",
+  "path": ["queue"],
+  "data": {
+    "taskId": "{taskId}",
+    "description": "🐛 {description}",
+    "priority": "{severity}",
+    "type": "bug"
+  },
+  "timestamp": "{now}",
+  "projectId": "{projectId}"
+}
+```
 
 ## Response
-`🐛 {severity} | Queued #{position} | Start: /p:now`
+
+```
+🐛 [{severity}] {description}
+
+Queued at position #{position}
+Priority: {severity}
+
+Start: /p:now "🐛 {description}"
+```
+
+## Examples
+
+### Critical Bug
+```
+Input: /p:bug production server is down
+
+Output:
+🐛 [critical] production server is down
+
+Queued at position #1
+Priority: critical
+
+Start: /p:now "🐛 production server is down"
+```
+
+### Normal Bug
+```
+Input: /p:bug login form validation not working
+
+Output:
+🐛 [medium] login form validation not working
+
+Queued at position #3
+Priority: medium
+
+Start: /p:now "🐛 login form validation not working"
+```

package/templates/commands/dash.md

@@ -2,9 +2,23 @@
 allowed-tools: [Read, GetTimestamp, GetDate]
 description: 'Unified dashboard - project status, progress, and roadmap'
 timestamp-rule: 'ALWAYS use GetTimestamp() and GetDate() tools for timestamps'
+architecture: 'Write-Through (JSON → MD → Events)'
+storage-layer: true
+source-of-truth: 'storage/*.json'
+claude-context: 'context/*.md'
 ---
 
-# /p:dash
+# /p:dash - Unified Dashboard
+
+## Architecture: Write-Through Pattern
+
+Reads from **Storage (JSON)** as source of truth.
+
+**Source of Truth**:
+- `storage/state.json` - Current/paused tasks
+- `storage/queue.json` - Task queue
+- `storage/ideas.json` - Ideas list
+- `storage/shipped.json` - Shipped features
 
 ## Usage
 
@@ -16,15 +30,21 @@ timestamp-rule: 'ALWAYS use GetTimestamp() and GetDate() tools for timestamps'
 /p:dash compact            # Minimal status only
 ```
 
+## Context Variables
+- `{projectId}`: From `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+- `{statePath}`: `{globalPath}/storage/state.json`
+- `{queuePath}`: `{globalPath}/storage/queue.json`
+- `{ideasPath}`: `{globalPath}/storage/ideas.json`
+- `{shippedPath}`: `{globalPath}/storage/shipped.json`
+
 ## Flow
 
-1. **Read all relevant files**:
-   - `core/stack.jsonl` → Active and paused tasks
-   - `core/next.md` → Priority queue
-   - `progress/shipped.md` → Recent ships
-   - `planning/roadmap.md` → Active roadmap
-   - `planning/ideas.md` → Recent ideas
-   - `progress/metrics.md` → Velocity metrics
+1. **Read all storage files**:
+   - `storage/state.json` → Active and paused tasks
+   - `storage/queue.json` → Priority queue
+   - `storage/shipped.json` → Recent ships
+   - `storage/ideas.json` → Recent ideas
 
 2. **Calculate metrics**:
    - Current task and elapsed time
@@ -33,7 +53,6 @@ timestamp-rule: 'ALWAYS use GetTimestamp() and GetDate() tools for timestamps'
    - Queue depth
    - Days since last ship
    - Velocity (tasks/week)
-   - Sprint progress percentage
 
 3. **Generate view based on param**:
    - Default → Balanced overview
@@ -51,33 +70,34 @@ timestamp-rule: 'ALWAYS use GetTimestamp() and GetDate() tools for timestamps'
 ├─────────────────────────────────────────┤
 │ 🎯 Current Focus                        │
 │ {active_task}                           │
-│ Started: {time_ago} | Agent: {agent}    │
+│ Started: {time_ago} | Session: {id}     │
 ├─────────────────────────────────────────┤
-│ ⏸️  Paused Tasks: {count}               │
-│ 1. {task} (paused {time} ago)          │
+│ ⏸️  Paused: {paused_task or "None"}     │
 ├─────────────────────────────────────────┤
-│ 📋 Priority Queue                       │
-│ • {next_task_1} ({estimate})           │
-│ • {next_task_2} ({estimate})           │
-│ • {next_task_3} ({estimate})           │
-│ → /p:next for full queue                │
+│ 📋 Queue ({queue_count})                │
+│ • {next_task_1}                         │
+│ • {next_task_2}                         │
+│ • {next_task_3}                         │
 ├─────────────────────────────────────────┤
-│ 📈 Progress This Week                   │
-│ Sprint: [████████░░] 80%                │
-│ Completed: {N} tasks                    │
-│ Shipped: {M} features                   │
-│ Velocity: {V} tasks/week                │
+│ 🚀 Recent Ships                         │
+│ • {ship_1} - {date}                     │
+│ • {ship_2} - {date}                     │
 ├─────────────────────────────────────────┤
-│ 🚀 Last Ship: {days} days ago          │
-│ {last_shipped_feature}                  │
-├─────────────────────────────────────────┤
-│ 🗺️ Roadmap Status                      │
-│ Phase: {current_phase} ({progress}%)    │
-│ Next milestone: {milestone}             │
+│ 💡 Ideas ({ideas_count})                │
 └─────────────────────────────────────────┘
 
-💡 Suggestions:
-{contextual_suggestions_based_on_state}
+Next: /p:now | /p:done | /p:ship
+```
+
+### Compact View
+
+```
+🎯 {active_task} ({time_elapsed})
+📋 Queue: {queue_count} | ⏸️ Paused: {paused ? "Yes" : "No"}
+🚀 Last ship: {days}d ago
+💡 Ideas: {ideas_count}
+
+→ /p:done | /p:next | /p:ship
 ```
 
 ### Weekly Progress View
@@ -85,157 +105,74 @@ timestamp-rule: 'ALWAYS use GetTimestamp() and GetDate() tools for timestamps'
 ```
 📊 WEEKLY PROGRESS - Week of {week_start}
 
-## 🎯 This Week's Accomplishments
-
-### Completed Tasks ({count})
+## Completed Tasks ({count})
 ✅ {task_1} - {duration}
 ✅ {task_2} - {duration}
-✅ {task_3} - {duration}
 
-### Features Shipped ({count})
-🚀 {feature_1} - {complexity} - {date}
-🚀 {feature_2} - {complexity} - {date}
-
-## 📈 Metrics
+## Features Shipped ({count})
+🚀 {feature_1} - {date}
 
+## Metrics
 **Velocity**: {tasks_per_day} tasks/day
 **Focus Time**: {total_hours} hours
-**Efficiency**: {completion_rate}%
-**Interruptions**: {pause_count} pauses
-
-## 🔄 Week-over-Week
-
-Compared to last week:
-• Tasks: {trend} ({percentage}%)
-• Velocity: {trend} ({percentage}%)
-• Ships: {trend} ({count_diff})
-
-## 📋 Upcoming
-
-Next week's priorities:
-1. {priority_1}
-2. {priority_2}
-3. {priority_3}
-```
-
-### Roadmap View
-
 ```
-🗺️ ROADMAP & PLANNING
 
-## Current Phase: {phase_name}
-Progress: [████████░░] {percentage}%
-Timeline: {start_date} → {end_date}
-Status: {on_track|at_risk|delayed}
+## Data Sources
 
-### Phase Goals
-• {goal_1} - {status}
-• {goal_2} - {status}
-• {goal_3} - {status}
+| Data | Storage File | Field |
+|------|--------------|-------|
+| Current Task | `storage/state.json` | `currentTask` |
+| Paused Task | `storage/state.json` | `pausedTask` |
+| Queue Tasks | `storage/queue.json` | `tasks[]` |
+| Ideas | `storage/ideas.json` | `ideas[]` |
+| Shipped | `storage/shipped.json` | `shipped[]` |
 
-### Completed Milestones
-✅ {milestone_1} - {date}
-✅ {milestone_2} - {date}
+## Error Handling
 
-### Upcoming Milestones
-🎯 {milestone_1} - {eta}
-🎯 {milestone_2} - {eta}
-
-## Future Phases
-
-**Phase 2**: {name} ({estimate})
-- {key_feature_1}
-- {key_feature_2}
-
-**Phase 3**: {name} ({estimate})
-- {key_feature_1}
-- {key_feature_2}
-
-## 💡 Recent Ideas ({count})
-• {idea_1} - {priority}
-• {idea_2} - {priority}
-• {idea_3} - {priority}
-
-→ /p:idea for new ideas
-→ /p:feature to add to roadmap
-```
-
-### Compact View
-
-```
-🎯 {active_task} ({time_elapsed})
-📋 Queue: {queue_count} | ⏸️ Paused: {paused_count}
-📈 Week: {tasks_done} done | {velocity}/day
-🚀 Last ship: {days}d ago
-
-→ /p:done | /p:next | /p:ship
-```
-
-## Contextual Suggestions
-
-Based on project state, suggest next actions:
-
-### If no active task
-```
-💡 Start working:
-→ /p:work 1 (from queue)
-→ /p:resume (paused task)
-```
-
-### If haven't shipped recently
-```
-⚠️ {days} days since last ship!
-→ /p:ship "{feature}"
-→ Find quick win in /p:next
-```
-
-### If velocity dropping
-```
-📉 Velocity trend down
-→ Check if tasks too complex
-→ Consider breaking down with /p:feature
-```
-
-### If many paused tasks
-```
-⏸️ {count} tasks paused
-→ Review with /p:stack
-→ Consider completing or dropping
-```
+| Error | Response |
+|-------|----------|
+| No project | "No prjct project. Run /p:init first." |
+| No storage files | Show empty dashboard |
+| Parse error | Skip that section |
 
 ## Natural Language Support
 
 Detect intent:
 - "p. dashboard" → Full dashboard
-- "p. status" → Default view
-- "p. progress" → Weekly view
+- "p. dash" → Full dashboard
+- "p. status" → Compact view (absorbed /p:status)
+- "p. progress" → Weekly view (absorbed /p:progress)
+- "p. recap" → Full dashboard (absorbed /p:recap)
 - "p. how am I doing" → Default view
-- "p. roadmap" → Roadmap view
 - "p. weekly" → Weekly progress
 
-## ASCII Art Helpers
+## Absorbed Commands
 
-For progress bars:
-```
-Empty: ░░░░░░░░░░
-Full:  ██████████
-Mixed: ████████░░
-```
+This command consolidates:
+- `/p:status` → Use `/p:dash compact`
+- `/p:progress` → Use `/p:dash week` or `/p:dash month`
+- `/p:recap` → Use `/p:dash` (default)
+- `/p:roadmap` → Use `/p:next roadmap`
 
-For borders:
+## KPI Metrics (from /p:status)
+
+Calculate and display:
 ```
-┌─┬─┐
-│ │ │
-├─┼─┤
-└─┴─┘
+Sprint: [████░] {%}
+Tasks: {done}/{total}
+Ship: {days} ago
+Focus: {task}
 ```
 
-## Migration Note
+## Progress Metrics (from /p:progress)
 
-This command replaces:
-- `/p:status` → Use `/p:dash`
-- `/p:recap` → Use `/p:dash`
-- `/p:progress` → Use `/p:dash week`
-- `/p:roadmap` → Use `/p:dash roadmap`
+For week/month views:
+```
+📈 {period} | 🚀 {N} shipped | ⚡ {velocity}/day | Trend: {↗%}
+```
 
-Old commands will show deprecation notice and redirect here.
+### Velocity Calculation
+```
+velocity = shipped_count / days_in_period
+trend = (current_velocity - previous_velocity) / previous_velocity * 100
+```