prjct-cli 0.35.3 → 0.36.1

package/templates/global/STORAGE-SPEC.md

@@ -0,0 +1,256 @@
+# Storage Specification
+
+**Canonical specification for prjct storage format.**
+
+This document defines the exact format for all storage files. Both Claude and Gemini agents MUST produce **identical output** for the same operations to ensure cross-agent compatibility and future remote sync.
+
+---
+
+## Directory Structure
+
+```
+~/.prjct-cli/projects/{projectId}/
+├── storage/
+│   ├── state.json      # Current task (SOURCE OF TRUTH)
+│   ├── queue.json      # Task queue
+│   └── shipped.json    # Shipped features
+├── context/
+│   ├── now.md          # Current task (generated from state.json)
+│   └── next.md         # Queue (generated from queue.json)
+├── config/
+│   └── skills.json     # Agent-to-skill mappings
+├── memory/
+│   └── events.jsonl    # Audit trail (append-only)
+├── agents/             # Domain specialists (auto-generated)
+└── sync/
+    └── pending.json    # Events for backend sync
+```
+
+---
+
+## JSON Schemas
+
+### state.json
+
+```json
+{
+  "task": {
+    "id": "uuid-v4",
+    "title": "string",
+    "type": "feature|bug|improvement|refactor|chore",
+    "status": "active|paused|done",
+    "branch": "string|null",
+    "subtasks": [
+      {
+        "id": "uuid-v4",
+        "title": "string",
+        "status": "pending|done"
+      }
+    ],
+    "currentSubtask": 0,
+    "createdAt": "2024-01-15T10:30:00.000Z",
+    "updatedAt": "2024-01-15T10:30:00.000Z"
+  }
+}
+```
+
+**Empty state (no active task):**
+```json
+{
+  "task": null
+}
+```
+
+### queue.json
+
+```json
+{
+  "tasks": [
+    {
+      "id": "uuid-v4",
+      "title": "string",
+      "type": "feature|bug|improvement|refactor|chore",
+      "priority": 1,
+      "createdAt": "2024-01-15T10:30:00.000Z"
+    }
+  ],
+  "updatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### shipped.json
+
+```json
+{
+  "features": [
+    {
+      "id": "uuid-v4",
+      "name": "string",
+      "version": "1.0.0",
+      "type": "feature|bug|improvement|refactor|chore",
+      "shippedAt": "2024-01-15T10:30:00.000Z"
+    }
+  ],
+  "updatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### events.jsonl (append-only)
+
+One JSON object per line. NEVER modify existing lines.
+
+```jsonl
+{"type":"task.created","timestamp":"2024-01-15T10:30:00.000Z","data":{"taskId":"uuid","title":"string"}}
+{"type":"task.started","timestamp":"2024-01-15T10:30:00.000Z","data":{"taskId":"uuid"}}
+{"type":"subtask.completed","timestamp":"2024-01-15T10:35:00.000Z","data":{"taskId":"uuid","subtaskIndex":0}}
+{"type":"task.completed","timestamp":"2024-01-15T10:40:00.000Z","data":{"taskId":"uuid"}}
+{"type":"feature.shipped","timestamp":"2024-01-15T10:45:00.000Z","data":{"featureId":"uuid","name":"string","version":"1.0.0"}}
+```
+
+**Event Types:**
+- `task.created` - New task created
+- `task.started` - Task activated
+- `task.paused` - Task paused
+- `task.resumed` - Task resumed
+- `task.completed` - Task completed
+- `subtask.completed` - Subtask completed
+- `feature.shipped` - Feature shipped
+
+### skills.json
+
+```json
+{
+  "mappings": {
+    "frontend.md": ["frontend-design"],
+    "backend.md": ["javascript-typescript"],
+    "testing.md": ["developer-kit"]
+  },
+  "updatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### pending.json (sync queue)
+
+```json
+{
+  "events": [
+    {
+      "id": "uuid-v4",
+      "type": "task.created",
+      "timestamp": "2024-01-15T10:30:00.000Z",
+      "data": {},
+      "synced": false
+    }
+  ],
+  "lastSync": "2024-01-15T10:30:00.000Z"
+}
+```
+
+---
+
+## Formatting Rules (MANDATORY)
+
+All agents MUST follow these rules for cross-agent compatibility:
+
+| Rule | Value |
+|------|-------|
+| JSON indentation | 2 spaces |
+| Trailing commas | NEVER |
+| Key ordering | Logical (as shown in schemas above) |
+| Timestamps | ISO-8601 with milliseconds (`.000Z`) |
+| UUIDs | v4 format (lowercase) |
+| Line endings | LF (not CRLF) |
+| File encoding | UTF-8 without BOM |
+| Empty objects | `{}` |
+| Empty arrays | `[]` |
+| Null values | `null` (lowercase) |
+
+### Timestamp Generation
+
+```bash
+# ALWAYS use dynamic timestamps, NEVER hardcode
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
+```
+
+### UUID Generation
+
+```bash
+# ALWAYS generate fresh UUIDs
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
+```
+
+---
+
+## Write Rules (CRITICAL)
+
+### Direct Writes Only
+
+**NEVER use temporary files** - Write directly to final destination:
+
+```
+WRONG: Create `.tmp/file.json`, then `mv` to final path
+CORRECT: Write directly to `{globalPath}/storage/state.json`
+```
+
+### Atomic Updates
+
+```javascript
+// Read → Modify → Write (no temp files)
+const data = JSON.parse(fs.readFileSync(path, 'utf-8'))
+data.newField = value
+fs.writeFileSync(path, JSON.stringify(data, null, 2))
+```
+
+### NEVER Do These
+
+- Use `.tmp/` directories
+- Use `mv` or `rename` operations for storage files
+- Create backup files like `*.bak` or `*.old`
+- Modify existing lines in `events.jsonl`
+- Use different JSON formatting between agents
+
+---
+
+## Cross-Agent Compatibility
+
+### Why This Matters
+
+1. **User freedom**: Switch between Claude and Gemini freely
+2. **Remote sync**: Storage will sync to prjct.app backend
+3. **Single truth**: Both agents produce identical output
+
+### Verification Test
+
+```bash
+# Start task with Claude
+p. task "add feature X"
+
+# Switch to Gemini, continue
+p. done  # Should work seamlessly
+
+# Switch back to Claude
+p. ship  # Should read Gemini's changes correctly
+
+# Verify JSON format
+cat ~/.prjct-cli/projects/{id}/storage/state.json | python -m json.tool
+# Must be valid, formatted JSON
+```
+
+### Remote Sync Flow
+
+```
+Local Storage (Claude/Gemini)
+        ↓
+    sync/pending.json (events queue)
+        ↓
+    prjct.app API
+        ↓
+    Global Remote Storage
+        ↓
+    Any device, any agent
+```
+
+---
+
+**Version**: 1.0.0
+**Last Updated**: 2024-01-15

package/templates/global/docs/agents.md

@@ -0,0 +1,88 @@
+# Using Agents
+
+## What Are Agents?
+
+Agents are specialized Claude configurations for different domains:
+
+| Agent | Domain | When to Use |
+|-------|--------|-------------|
+| `fe.md` | Frontend | React, CSS, UI components |
+| `be.md` | Backend | APIs, databases, servers |
+| `ux.md` | UX Design | Layouts, user flows |
+| `qa.md` | Testing | Tests, QA, bug fixes |
+| `docs.md` | Documentation | README, docs, comments |
+
+## Agent Location
+
+Agents live in global storage:
+
+```
+~/.prjct-cli/projects/{projectId}/agents/
+├── fe.md       # Frontend specialist
+├── be.md       # Backend specialist
+├── ux.md       # UX specialist
+├── qa.md       # Testing specialist
+└── docs.md     # Documentation specialist
+```
+
+## When to Read Agent Files
+
+Read the relevant agent file before working in that domain:
+
+```
+Task: "implement React component"
+→ Read agents/fe.md for React patterns
+→ Follow detected conventions
+
+Task: "add API endpoint"
+→ Read agents/be.md for API patterns
+→ Follow project architecture
+```
+
+## Agent File Structure
+
+Each agent file contains:
+
+```markdown
+---
+name: fe
+description: Frontend specialist for React/TypeScript
+tools: Read, Write, Glob, Grep, Bash
+---
+
+## Expertise
+- React components and hooks
+- TypeScript patterns
+- CSS/styling conventions
+
+## Project Patterns
+- Components in src/components/
+- Use functional components
+- CSS modules for styling
+
+## Code Conventions
+- Named exports
+- Props interfaces defined inline
+- Error boundaries for async components
+```
+
+## Auto-Detection
+
+When starting a task with `/p:now`, agents are auto-detected by keywords:
+
+| Keywords | Agent |
+|----------|-------|
+| UI, frontend, React, component, CSS | `fe` |
+| API, backend, database, server | `be` |
+| design, UX, layout, wireframe | `ux` |
+| test, QA, bug, coverage | `qa` |
+| docs, README, documentation | `docs` |
+
+## Agent Generation
+
+Agents are generated by `/p:sync` based on:
+- Detected tech stack (package.json, etc.)
+- Project structure
+- Code patterns found in codebase
+
+Re-run `/p:sync` to regenerate agents after major changes.

package/templates/global/docs/architecture.md

@@ -0,0 +1,103 @@
+# prjct Architecture
+
+## Write-Through Pattern
+
+All data flows through three layers:
+
+```
+User Action → Storage (JSON) → Context (MD) → Sync Events (JSONL)
+```
+
+### Layer Responsibilities
+
+| Layer | Path | Purpose | Format |
+|-------|------|---------|--------|
+| **Storage** | `storage/*.json` | Source of truth | JSON |
+| **Context** | `context/*.md` | Claude-readable summaries | Markdown |
+| **Sync** | `sync/pending.json` | Backend event queue | JSON array |
+| **Memory** | `memory/events.jsonl` | Audit trail | JSONL (append-only) |
+
+### Data Flow Example
+
+When user runs `/p:now "implement auth"`:
+
+1. **Storage**: Write to `storage/state.json`
+   ```json
+   { "currentTask": { "description": "implement auth", ... } }
+   ```
+
+2. **Context**: Generate `context/now.md`
+   ```markdown
+   # NOW
+   **implement auth**
+   Started: 2025-12-20T10:30:00.000Z
+   ```
+
+3. **Sync**: Append to `sync/pending.json`
+   ```json
+   { "type": "task.started", "data": {...} }
+   ```
+
+4. **Memory**: Append to `memory/events.jsonl`
+   ```json
+   {"timestamp":"...","action":"task_started","task":"implement auth"}
+   ```
+
+## File Structure
+
+```
+~/.prjct-cli/projects/{projectId}/
+├── storage/                    # SOURCE OF TRUTH
+│   ├── state.json             # Current task state
+│   ├── shipped.json           # Shipped features
+│   ├── ideas.json             # Ideas backlog
+│   └── queue.json             # Task queue
+│
+├── context/                    # CLAUDE-READABLE (generated)
+│   ├── now.md                 # Current task summary
+│   ├── shipped.md             # Recent ships
+│   └── next.md                # Priority queue
+│
+├── sync/                       # BACKEND EVENTS
+│   └── pending.json           # Events waiting for sync
+│
+├── memory/                     # AUDIT TRAIL
+│   └── events.jsonl           # Append-only log
+│
+├── agents/                     # DOMAIN SPECIALISTS
+│   ├── fe.md                  # Frontend agent
+│   ├── be.md                  # Backend agent
+│   └── ...
+│
+└── CLAUDE.md                   # Project context (read first)
+```
+
+## Storage vs Context
+
+| Aspect | Storage (JSON) | Context (MD) |
+|--------|----------------|--------------|
+| Format | Structured JSON | Human-readable Markdown |
+| Purpose | Source of truth | Claude summaries |
+| Updates | Direct writes | Generated from storage |
+| Read by | Code, Claude | Primarily Claude |
+
+## Timestamps
+
+All timestamps use ISO 8601 format:
+
+```bash
+# Prefer bun, fallback to node
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
+# Output: "2025-12-20T10:30:00.000Z"
+```
+
+**NEVER** hardcode timestamps. Always generate dynamically.
+
+## IDs
+
+Use UUID v4 for all IDs:
+
+```bash
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
+# Output: "550e8400-e29b-41d4-a716-446655440000"
+```

package/templates/global/docs/commands.md

@@ -0,0 +1,96 @@
+# prjct Commands Reference
+
+## Command Table
+
+| Trigger | Purpose | Arguments |
+|---------|---------|-----------|
+| `p. sync` | Analyze project, generate agents | - |
+| `p. task [desc] [estimate]` | Start/show current task | desc: string, estimate: "2h", "30m" |
+| `p. done` | Complete current task | - |
+| `p. ship [feature]` | Ship with quality checks | feature: string |
+| `p. next` | Show priority queue | - |
+| `p. idea [text]` | Quick idea capture | text: string |
+| `p. dash` | Project dashboard | - |
+| `p. pause [reason]` | Pause current task | reason: string |
+| `p. resume` | Resume paused task | - |
+| `p. bug [desc]` | Report bug | desc: string |
+
+## Recommended Workflow
+
+```
+1. p. sync      → Analyze project, generate agents
+2. p. idea      → Capture what to build
+3. p. task      → Start working on task
+4. [code...]    → Do the actual work
+5. p. done      → Mark task complete
+6. p. ship      → Ship and celebrate
+```
+
+## Command Examples
+
+### Starting Work
+```
+p. task implement user authentication 2h
+```
+- Sets current task
+- Optional estimate for tracking accuracy
+
+### Completing Work
+```
+p. done
+```
+- Calculates duration
+- Logs metrics (files changed, commits)
+- Clears current task
+
+### Shipping
+```
+p. ship user authentication
+```
+- Runs lint/tests (optional)
+- Bumps version
+- Creates git commit
+- Updates CHANGELOG
+
+### Quick Capture
+```
+p. idea add dark mode support
+```
+- Saves to ideas backlog
+- Doesn't interrupt current work
+
+## How It Works
+
+Start your message with `p.` followed by the command:
+
+```
+p. task login form
+→ Starts task "login form"
+
+p. done
+→ Completes current task
+
+p. ship authentication
+→ Ships "authentication" feature
+```
+
+## Command Output Format
+
+All commands output concise responses:
+
+```
+✅ [What was done]
+
+[Key metrics if applicable]
+
+Next: [suggested action]
+```
+
+Example:
+```
+✅ implement auth (2h 15m)
+
+Files: 5 | +120/-30 | Commits: 3
+
+Next: p. ship or p. task
+```

package/templates/global/docs/validation.md

@@ -0,0 +1,95 @@
+# Validation Patterns
+
+## Before Any Command
+
+```javascript
+// 1. Check project exists
+const config = await Read('.prjct/prjct.config.json')
+if (!config) {
+  return "No prjct project. Run /p:init first."
+}
+
+// 2. Extract projectId
+const { projectId } = JSON.parse(config)
+
+// 3. Construct global path
+const globalPath = `~/.prjct-cli/projects/${projectId}`
+```
+
+## Before /p:done
+
+```javascript
+const state = await Read(`${globalPath}/storage/state.json`)
+
+if (!state || !state.currentTask) {
+  return "Not working on anything. Use /p:now to start a task."
+}
+
+if (state.currentTask.status !== 'active') {
+  return "No active task. Use /p:now to start one."
+}
+```
+
+## Before /p:ship
+
+```javascript
+// Check git status
+const gitStatus = await Bash('git status --porcelain')
+
+if (!gitStatus.trim()) {
+  return "No changes to ship. Make some commits first."
+}
+
+// Verify git repo
+const isGitRepo = await Bash('git rev-parse --is-inside-work-tree')
+if (!isGitRepo) {
+  return "Not a git repository. Initialize git first."
+}
+```
+
+## Before /p:pause
+
+```javascript
+const state = await Read(`${globalPath}/storage/state.json`)
+
+if (!state?.currentTask || state.currentTask.status !== 'active') {
+  return "No active task to pause."
+}
+```
+
+## Before /p:resume
+
+```javascript
+const state = await Read(`${globalPath}/storage/state.json`)
+
+if (!state?.pausedTask) {
+  return "No paused task to resume. Use /p:now to start a new task."
+}
+```
+
+## Error Handling
+
+| Error | Response | Action |
+|-------|----------|--------|
+| Config not found | "No prjct project" | STOP |
+| No current task | "Not working on anything" | STOP |
+| No paused task | "No paused task" | STOP |
+| Git fails | Use defaults for metrics | CONTINUE |
+| Write fails | Log warning | CONTINUE |
+| File not found | Return empty/default state | CONTINUE |
+
+## Path Resolution
+
+**CRITICAL**: All paths resolve to global storage.
+
+```javascript
+// Template says:
+"Read: storage/state.json"
+
+// Actually reads:
+`~/.prjct-cli/projects/${projectId}/storage/state.json`
+
+// NEVER:
+".prjct/storage/state.json"  // Wrong - local
+"./storage/state.json"       // Wrong - current dir
+```