prjct-cli 0.13.2 → 0.15.0

package/templates/commands/init.md

@@ -2,35 +2,116 @@
 allowed-tools: [Read, Write, Bash]
 description: 'Initialize prjct'
 timestamp-rule: 'GetTimestamp() for all timestamps'
+architecture: 'Write-Through (JSON → MD → Events)'
+storage-layer: true
 ---
 
-# /p:init
+# /p:init - Initialize Project
+
+## Architecture: Write-Through Pattern
+
+Creates the full storage structure for a new project.
 
 ## Context Variables
-- `{projectId}`: Generated unique ID (12 chars hex)
+- `{projectId}`: Generated UUID (standard format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
 - `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
 - `{cwd}`: Current working directory (repository path)
 
+## Project ID Format
+
+**CRITICAL**: Project IDs MUST be standard UUIDs for PostgreSQL consistency.
+
+```
+Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+Example: 550e8400-e29b-41d4-a716-446655440000
+```
+
+Generate using: `crypto.randomUUID()`
+
 ## Flow
 
-**Existing**: ID → dirs → config → analyze → agents
-**Blank + idea**: ARCHITECT → analyze → recommend stack → create → roadmap
+1. **Check existing**: Read `.prjct/prjct.config.json`
+2. **Generate UUID**: Use `crypto.randomUUID()`
+3. **Create directories**: storage/, context/, sync/, agents/, memory/
+4. **Create config files**: local + global
+5. **Analyze project**: Detect stack, dependencies
+6. **Generate agents**: Based on detected stack
+
+## Directory Structure
+
+```
+~/.prjct-cli/projects/{projectId}/
+├── storage/                  # Source of Truth (JSON)
+│   ├── state.json           # Current + paused task
+│   ├── queue.json           # Task queue
+│   ├── ideas.json           # Ideas list
+│   └── shipped.json         # Shipped features
+├── context/                  # For Claude (MD)
+│   ├── CLAUDE.md            # Full context
+│   ├── now.md               # Current task
+│   ├── next.md              # Queue
+│   ├── ideas.md             # Ideas
+│   └── shipped.md           # Shipped
+├── sync/                     # Backend Sync
+│   └── pending.json         # Events queue
+├── agents/                   # Specialists
+├── memory/                   # Audit Trail
+│   └── events.jsonl
+├── progress/                 # Historical Data
+│   └── sessions/{YYYY-MM}/
+└── project.json             # Metadata
+```
+
+## Step: Create Storage Files
+
+### storage/state.json
+```json
+{
+  "currentTask": null,
+  "pausedTask": null,
+  "previousTask": null,
+  "lastUpdated": null
+}
+```
+
+### storage/queue.json
+```json
+{
+  "tasks": [],
+  "lastUpdated": null
+}
+```
+
+### storage/ideas.json
+```json
+{
+  "ideas": [],
+  "lastUpdated": null
+}
+```
 
-## Structure
-`~/.prjct-cli/projects/{id}/`: core, progress, planning, analysis, agents, memory
+### storage/shipped.json
+```json
+{
+  "shipped": [],
+  "lastUpdated": null
+}
+```
 
-## Config
-`.prjct/prjct.config.json`: version, projectId, dataPath, author
+### sync/pending.json
+```json
+[]
+```
 
 ## Step: Create project.json (REQUIRED)
 
-This file is the source of truth for the web dashboard. It maps projectId → repoPath.
+This file is the source of truth for the web dashboard.
 
 ### Determine Project Name
 - Try package.json → `name` field
 - Try Cargo.toml → `[package] name`
 - Try pyproject.toml → `[project] name`
-- Fallback to directory name (last segment of current path)
+- Fallback to directory name
 
 WRITE: `{globalPath}/project.json`
 
@@ -44,18 +125,41 @@ WRITE: `{globalPath}/project.json`
 }
 ```
 
+## Step: Create Local Config
+
+WRITE: `.prjct/prjct.config.json`
+
+```json
+{
+  "projectId": "{projectId}",
+  "dataPath": "~/.prjct-cli/projects/{projectId}"
+}
+```
+
 ## Response
-`✅ Init | {stack} | {N} agents | Next: /p:feature or /p:help`
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 WHAT'S NEXT?
-━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+✅ Initialized prjct
+
+Project ID: {projectId}
+Data Path: ~/.prjct-cli/projects/{projectId}/
 
-1. 🚀 Start first feature (RECOMMENDED) → /p:feature "{first_feature}"
-2. 📊 See roadmap → /p:roadmap
-3. 🔍 Review structure → /p:recap
-4. 💡 Modify plan → Just tell me
+Structure:
+├── storage/    # JSON (source of truth)
+├── context/    # MD (for Claude)
+├── sync/       # Backend events
+└── agents/     # Specialists
+
+Next:
+• /p:sync - Analyze project and generate agents
+• /p:feature "{first_feature}" - Start first feature
+• /p:help - See all commands
+```
 
-💬 REMEMBER: Talk naturally! "Start with auth" / "Show roadmap" / "Add another feature"
+## Error Handling
 
-Ready to start building? 🚀
+| Error | Response |
+|-------|----------|
+| Already initialized | Show existing projectId |
+| Permission denied | Suggest chmod |
+| Write fails | Show error |

package/templates/commands/migrate-all.md

@@ -1,61 +1,96 @@
 ---
 allowed-tools: [Read, Write, Bash]
-description: 'Migrate all legacy projects to global storage architecture'
+description: 'Migrate all projects to UUID format'
 ---
 
 # /p:migrate-all
 
+Migrate all projects to UUID format.
+
 ## Usage
 
 ```
-/p:migrate-all [--deep-scan] [--remove-legacy] [--dry-run]
+/p:migrate-all [--deep-scan] [--dry-run]
 ```
 
 ## What It Does
 
-1. **Scans global storage** → Reads all project IDs from `~/.prjct-cli/projects/`
-2. **Detects legacy structure** → Checks each project for old `.prjct/` directory
-3. **Migrates each project** → Moves data from local `.prjct/` to global storage
-4. **Cleanup (optional)** → Removes legacy `.prjct/` directories (with `--remove-legacy`)
-5. **Reports summary** → Shows migrated, skipped, failed counts
+1. **Scans global storage** → Lists all projects in `~/.prjct-cli/projects/`
+2. **Checks UUID format** → Identifies projects with non-UUID IDs
+3. **Migrates each project** → Renames folders and updates configs to UUID
+4. **Reports summary** → Shows migrated, skipped, failed counts
 
 ## Options
 
-- `--deep-scan`: Scan entire file system (slow but thorough)
-- `--remove-legacy`: Delete old `.prjct/` after successful migration
+- `--deep-scan`: Also scan for projects in common locations
 - `--dry-run`: Show what would be migrated without making changes
 
-## When to Use
+## Migration Flow
+
+For each project:
+
+1. Read `project.json` to get current ID
+2. Check if ID is already UUID format
+3. If not UUID:
+   - Generate new UUID
+   - Rename folder to new UUID
+   - Update `project.json`
+   - Find and update linked `.prjct/prjct.config.json`
+
+## UUID Format
 
-- After major version updates (architecture changes)
-- Upgrading from v0.7.x to v0.8.x (new global storage)
-- Troubleshooting projects not working after update
+Standard UUID: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (36 chars)
+Example: `550e8400-e29b-41d4-a716-446655440000`
 
-## Migration: Before → After
+## Before → After
 
-**Before (Legacy)**:
+**Before**:
 ```
-your-project/.prjct/     # All data locally
-  core/, planning/, progress/, memory/, analysis/
+~/.prjct-cli/projects/
+  3a5667a5dedb/    # Hash-based ID
+  abc12345/        # Short ID
 ```
 
-**After (Global)**:
+**After**:
 ```
-your-project/.prjct/
-  prjct.config.json      # Minimal (projectId + dataPath only)
-
-~/.prjct-cli/projects/{id}/
-  core/, planning/, progress/, memory/, analysis/, agents/
+~/.prjct-cli/projects/
+  550e8400-e29b-41d4-a716-446655440000/  # UUID
+  7c9e6679-7425-40de-944b-e07fc1f90ae7/  # UUID
 ```
 
 ## Safety
 
-- **Idempotent**: Safe to run multiple times
-- **Non-destructive**: Original files only removed with `--remove-legacy`
+- **Idempotent**: Safe to run multiple times (skips UUIDs)
+- **Non-destructive**: Renames, doesn't delete
 - **Dry run**: Test with `--dry-run` first
-- **Automatic backup**: Legacy data preserved until explicitly removed
 
 ## Requirements
 
-- Write permissions to `~/.prjct-cli/` and project directories
-- Projects must have valid global config in `project.json`
+- Write permissions to `~/.prjct-cli/`
+- Projects must have valid `project.json`
+
+## Output
+
+```
+📦 UUID Migration
+
+Scanning ~/.prjct-cli/projects/...
+
+Found 5 projects:
+- 3a5667a5dedb: Needs migration
+- abc12345: Needs migration
+- 550e8400-e29b-...: Already UUID ✓
+- def67890: Needs migration
+- 7c9e6679-7425-...: Already UUID ✓
+
+Migrating 3 projects...
+
+✅ 3a5667a5dedb → 9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d
+✅ abc12345 → 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d
+✅ def67890 → 2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e
+
+Summary:
+- Migrated: 3
+- Skipped (already UUID): 2
+- Failed: 0
+```

package/templates/commands/migrate.md

@@ -0,0 +1,140 @@
+---
+allowed-tools: [Read, Write, Bash, Glob]
+description: 'Migrate project to UUID format + sync'
+---
+
+# /p:migrate - UUID Migration
+
+Migrate project ID to UUID format and run full sync.
+
+## Context Variables
+
+- `{projectId}`: Current ID from `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+
+## Step 1: Read Configuration
+
+READ: `.prjct/prjct.config.json`
+EXTRACT: `projectId`
+
+IF file not found:
+  OUTPUT: "No prjct project. Run /p:init first."
+  STOP
+
+## Step 2: Check UUID Format
+
+UUID format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` (36 chars with dashes)
+
+IF projectId matches UUID regex `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i`:
+  OUTPUT: "✅ Already UUID: {projectId}"
+  GOTO: Step 7 (Run Sync)
+
+IF projectId does NOT match UUID format:
+  CONTINUE to Step 3
+
+## Step 3: Generate New UUID
+
+Generate new UUID using Node.js `crypto.randomUUID()`.
+
+Store:
+- `{oldId}` = current projectId
+- `{newId}` = generated UUID
+
+## Step 4: Show Migration Plan
+
+OUTPUT:
+```
+📦 UUID Migration Plan
+
+Current ID: {oldId} (non-UUID format)
+New UUID:   {newId}
+
+Actions:
+1. Rename folder: ~/.prjct-cli/projects/{oldId}/ → ~/.prjct-cli/projects/{newId}/
+2. Update .prjct/prjct.config.json
+3. Update project.json
+4. Run /p:sync
+
+Continue? (yes/no)
+```
+
+WAIT for user confirmation.
+
+## Step 5: Rename Global Folder
+
+BASH:
+```bash
+mv ~/.prjct-cli/projects/{oldId} ~/.prjct-cli/projects/{newId}
+```
+
+IF error:
+  OUTPUT: "❌ Failed to rename folder: {error}"
+  STOP
+
+## Step 6: Update Configuration Files
+
+### Local Config (.prjct/prjct.config.json)
+
+READ current config, UPDATE:
+```json
+{
+  "projectId": "{newId}",
+  "dataPath": "~/.prjct-cli/projects/{newId}"
+}
+```
+
+WRITE back to `.prjct/prjct.config.json`
+
+### Global Config (project.json)
+
+READ: `~/.prjct-cli/projects/{newId}/project.json`
+REPLACE all occurrences of `{oldId}` with `{newId}`
+WRITE back
+
+## Step 7: Run Sync
+
+Execute `/p:sync` to:
+- Analyze project
+- Regenerate CLAUDE.md
+- Update agents
+
+## Output
+
+**If migrated:**
+```
+✅ Migrated to UUID
+
+Old ID: {oldId}
+New ID: {newId}
+
+Updated:
+- Folder renamed
+- Config updated
+- Sync completed
+
+Next: Continue working with /p:now
+```
+
+**If skipped (already UUID):**
+```
+✅ Already UUID: {projectId}
+
+Sync completed.
+
+Next: Continue working with /p:now
+```
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| No config | "Run /p:init first" |
+| Folder not found | "Global data missing - reinitialize" |
+| Rename failed | Show error, abort |
+| User cancels | STOP without changes |
+
+## Notes
+
+- Migration is idempotent: if already UUID, skips to sync
+- UUIDs are standard format for PostgreSQL consistency
+- Always runs sync after migration

package/templates/commands/next.md

@@ -1,14 +1,124 @@
 ---
 allowed-tools: [Read]
 description: 'Show priority queue'
+architecture: 'Write-Through (JSON → MD → Events)'
+storage-layer: true
+source-of-truth: 'storage/queue.json'
+claude-context: 'context/next.md'
 ---
 
-# /p:next
+# /p:next - Show Priority Queue
+
+## Architecture: Write-Through Pattern
+
+Reads from **Storage (JSON)** as source of truth.
+
+**Source of Truth**: `storage/queue.json`
+**Also reads**: `storage/state.json` for current task status
+
+## Context Variables
+- `{projectId}`: From `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+- `{queuePath}`: `{globalPath}/storage/queue.json`
+- `{statePath}`: `{globalPath}/storage/state.json`
 
 ## Flow
-1. Check `core/now.md` → warn if active
-2. Read `core/next.md` → top 5 non-blocked
+
+1. Read `storage/state.json` → Check if active task
+2. Read `storage/queue.json` → Get queue tasks
+3. Display top 5 non-blocked tasks
 
 ## Response
-**Active**: `⚠️ Active: {task} | Complete: /p:done`
-**Queue**: Show 1-5 → `/p:work {N}`
+
+**If active task**:
+```
+⚠️ Active: {currentTask.description}
+
+Complete with /p:done first, or:
+
+📋 Queue ({count})
+1. {task_1}
+2. {task_2}
+3. {task_3}
+...
+
+Start: /p:work {N}
+```
+
+**If no active task**:
+```
+📋 Queue ({count})
+
+1. {task_1} {priority}
+2. {task_2} {priority}
+3. {task_3} {priority}
+4. {task_4}
+5. {task_5}
+
+{IF count > 5: ... and {count - 5} more}
+
+Start: /p:work 1 or /p:now "{task}"
+```
+
+**If empty queue**:
+```
+📋 Queue is empty
+
+Add tasks:
+• /p:feature "description"
+• /p:bug "description"
+• /p:idea "quick note"
+```
+
+## Data Source
+
+| Data | Storage File | Field |
+|------|--------------|-------|
+| Current Task | `storage/state.json` | `currentTask` |
+| Queue Tasks | `storage/queue.json` | `tasks[]` |
+| Shipped | `storage/shipped.json` | `shipped[]` |
+
+## Usage Variants
+
+```
+/p:next                    # Priority queue (default)
+/p:next roadmap            # Feature-grouped view
+/p:next --roadmap          # Same as above
+```
+
+## Roadmap View
+
+When called with `roadmap` parameter, show feature-grouped view:
+
+```
+📍 PRODUCT ROADMAP
+
+🚀 Current Sprint
+├── ✅ {completed_feature} - shipped {date}
+├── 🔄 {active_feature} ({X}% complete)
+│   └── 🎯 {current_task}
+└── ⏳ {pending_feature} ({N} tasks)
+
+📅 Next Up ({N} features)
+├── {feature_1} - {effort}
+└── {feature_2} - {effort}
+
+📊 Velocity: {X.X} features/week
+
+/p:now "{next}" | /p:done
+```
+
+### Roadmap Data Aggregation
+
+1. Group queue tasks by `featureId`
+2. Calculate completion % per feature
+3. Sort by priority/dependency
+4. Show current task within active feature
+
+## Natural Language Support
+
+- "p. next" → Priority queue
+- "p. queue" → Priority queue
+- "p. what's next" → Priority queue
+- "p. roadmap" → Roadmap view
+- "p. features" → Roadmap view