prjct-cli 0.18.2 → 0.20.0

package/templates/commands/test.md

@@ -1,6 +1,7 @@
 ---
-allowed-tools: [Bash, Read, Edit]
+allowed-tools: [Bash, Read, Write, Edit]
 description: 'Run tests with auto-fix'
+timestamp-rule: 'GetTimestamp() for ALL timestamps'
 ---
 
 # /p:test
@@ -8,41 +9,180 @@ description: 'Run tests with auto-fix'
 ## Usage
 
 ```
-/p:test [all|unit|e2e|failed|fix]  # Default: all
+/p:test [all|unit|e2e|failed|fix]
+        [--blocking]           # Exit with error if tests fail
 ```
 
-## Flow
+## Context Variables
+- `{projectId}`: From `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+- `{configPath}`: `~/.prjct-cli/config.json`
+- `{memoryPath}`: `{globalPath}/memory/events.jsonl`
 
-1. Detect: test runner (jest/vitest/pytest/etc)
-2. Run: tests with appropriate command
-3. Parse: results
-4. Auto-fix: simple failures (snapshots, timeouts, imports)
-5. Update: coverage in `progress/metrics.md`
+## Step 1: Read Project Config
 
-## Response (success)
+READ: `.prjct/prjct.config.json`
+EXTRACT: `projectId`
 
+IF file not found:
+  OUTPUT: "No prjct project. Run /p:init first."
+  STOP
+
+## Step 2: Parse Arguments
+
+SET defaults:
+- {testMode} = "all"
+- {blocking} = false
+
+PARSE args:
+- IF arg is "all|unit|e2e|failed|fix": {testMode} = arg
+- IF arg contains "--blocking": {blocking} = true
+
+## Step 3: Detect Testing Strategy
+
+### Check for Native Test Runner
+
+READ: `package.json`
+IF has "scripts.test":
+  {runner} = "npm"
+  {runnerCmd} = "npm test"
+  → Go to Step 4 (Native Testing)
+
+IF file exists: `pytest.ini` OR `pyproject.toml` with pytest:
+  {runner} = "pytest"
+  {runnerCmd} = "pytest"
+  → Go to Step 4
+
+IF file exists: `Cargo.toml`:
+  {runner} = "cargo"
+  {runnerCmd} = "cargo test"
+  → Go to Step 4
+
+IF no runner found:
+  OUTPUT: "No test runner detected."
+  OUTPUT: ""
+  OUTPUT: "Options:"
+  OUTPUT: "• Add 'test' script to package.json"
+  OUTPUT: "• Add pytest.ini for Python projects"
+  OUTPUT: "• Add Cargo.toml for Rust projects"
+  STOP
+
+## Step 4: Native Test Runner
+
+OUTPUT: "🧪 Running tests with {runner}..."
+
+BASH: `{runnerCmd} 2>&1`
+CAPTURE output as {testOutput}
+
+### Parse Results
+
+IF {testOutput} contains "passed" AND NOT contains "failed":
+  {testStatus} = "passed"
+  {passed} = extract number of passed tests
+  {failed} = 0
+ELSE IF {testOutput} contains "failed" OR contains "FAIL":
+  {testStatus} = "failed"
+  {passed} = extract passed count
+  {failed} = extract failed count
+ELSE:
+  {testStatus} = "unknown"
+
+### Handle Fix Mode
+IF {testMode} == "fix" AND {testStatus} == "failed":
+  OUTPUT: "🔧 Attempting auto-fix..."
+
+  IF {runner} == "npm":
+    BASH: `npm test -- -u 2>&1`  # Update snapshots
+
+  OUTPUT: "Snapshots updated. Re-running tests..."
+  BASH: `{runnerCmd} 2>&1`
+  CAPTURE and re-parse results
+
+→ Go to Step 5 (Results)
+
+## Step 5: Results & Response
+
+### Log to Memory
+
+SET: {now} = GetTimestamp()
+
+APPEND to `{memoryPath}`:
+```json
+{"ts":"{now}","type":"test_run","tool":"{runner}","passed":{passed},"failed":{failed},"mode":"{testMode}"}
+```
+
+### Check Blocking Mode
+
+IF {blocking} AND {failed} > 0:
+  OUTPUT: "❌ {failed} tests failed. Blocking."
+  OUTPUT: ""
+  OUTPUT: "Fix failing tests or run without --blocking flag."
+  EXIT with error (non-zero)
+
+### Success Response
+
+IF {testStatus} == "passed":
+  OUTPUT: "✅ All tests passing!"
+  OUTPUT: ""
+  OUTPUT: "📊 Results:"
+  OUTPUT: "• Passed: {passed}"
+  IF {coverage}:
+    OUTPUT: "• Coverage: {coverage}%"
+  OUTPUT: ""
+  OUTPUT: "🎯 Next: /p:ship"
+
+### Failure Response
+
+IF {testStatus} == "failed":
+  OUTPUT: "❌ {failed} tests failing"
+  OUTPUT: ""
+  OUTPUT: "{testOutput}"  # Show relevant failure output
+  OUTPUT: ""
+  OUTPUT: "💡 Auto-fix: /p:test fix"
+  OUTPUT: ""
+  OUTPUT: "📊 Summary: {passed}/{passed + failed} passed"
+
+## Error Handling
+
+| Error | Response | Action |
+|-------|----------|--------|
+| No project | "No prjct project" | STOP |
+| No test runner | "No test runner detected" | Show setup options |
+| Tests timeout | "Tests timed out" | Suggest increasing timeout |
+
+## Examples
+
+### Example 1: Native Tests Pass
 ```
+🧪 Running tests with npm...
+
 ✅ All tests passing!
 
 📊 Results:
-• Unit: {N}/{N}
-• Integration: {N}/{N}
-• E2E: {N}/{N}
+• Passed: 42
+• Coverage: 87%
 
-🎯 Coverage: {X}%
-⚡ Time: {X}s
+🎯 Next: /p:ship
+```
 
-/p:ship
+### Example 2: Tests with Failures
 ```
+🧪 Running tests with npm...
 
-## Response (failures)
+❌ 3 tests failing
 
+[test output here]
+
+💡 Auto-fix: /p:test fix
+
+📊 Summary: 39/42 passed
 ```
-❌ {N} tests failing
 
-{failure_details}
+### Example 3: Blocking Mode
+```
+🧪 Running tests with npm...
 
-💡 Auto-fix: /p:test fix
+❌ 2 tests failed. Blocking.
 
-📊 Summary: {passed}/{total} ({X}%)
+Fix failing tests or run without --blocking flag.
 ```

package/templates/global/CLAUDE.md

@@ -1,233 +1,68 @@
 <!-- prjct:start - DO NOT REMOVE THIS MARKER -->
-# prjct Configuration
+# prjct-cli
 
-This section provides global context for all `/p:*` commands across any prjct project.
+## CRITICAL RULES (READ FIRST)
 
-**Auto-managed by prjct-cli** - This section is automatically updated when you install or update prjct.
+### 1. Path Resolution (MOST IMPORTANT)
+**ALL writes go to global storage**: `~/.prjct-cli/projects/{projectId}/`
 
-## 🚀 Quick Command Reference
+- **NEVER** write to `.prjct/` (config only)
+- **NEVER** write to `./` (current directory)
+- **ALWAYS** use global storage path
 
-| Command | Purpose | Example |
-|---------|---------|---------|
-| `/p:sync` | Analyze project & generate agents | Run first in any project |
-| `/p:now [task]` | Set current focus | `/p:now "implement auth"` |
-| `/p:done` | Complete current task | After finishing work |
-| `/p:next` | Show priority queue | See what's pending |
-| `/p:ship [feature]` | Ship & celebrate | `/p:ship "user login"` |
-| `/p:feature [desc]` | Add feature to roadmap | `/p:feature "dark mode"` |
-| `/p:idea [text]` | Quick idea capture | `/p:idea "add caching"` |
-| `/p:recap` | Project overview | Status check |
-| `/p:progress` | Show metrics | Weekly/monthly stats |
+### 2. Project Detection
+Read `.prjct/prjct.config.json` → extract `projectId`
+- If missing: "No prjct project. Run /p:init first." → STOP
 
-## 🎯 Recommended Workflow
-
-```
-1. /p:sync          → Analyze project, generate agents
-2. /p:feature       → Plan what to build
-3. /p:now           → Start working
-4. [code...]        → Do the actual work
-5. /p:done          → Mark complete
-6. /p:ship          → Celebrate & commit
-```
-
-## 🤖 Project Context (CRITICAL)
-
-**BEFORE working on any prjct project, READ the project context:**
-
-1. Read `.prjct/prjct.config.json` → get `projectId`
-2. Read `~/.prjct-cli/projects/{projectId}/CLAUDE.md` → dynamic project context
-
-The project CLAUDE.md contains:
-- Tech stack (languages, frameworks, dependencies)
-- Project structure (directories)
-- Available agents with their expertise
-- Current task and priority queue
-- Recent git activity
-- Active roadmap features
-
-**If CLAUDE.md doesn't exist**: Suggest running `/p:sync` to generate it.
-
-## 📋 Common Usage Patterns
-
-### Starting Work on a Project
-```
-User: "p. sync"
-→ Analyze repo, generate agents, create context
-→ Now Claude knows: stack, structure, agents available
-```
-
-### Adding a New Feature
+### 3. Timestamps
+```bash
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
 ```
-User: "p. feature add user authentication"
-→ Creates roadmap entry with tasks
-→ Analyzes impact and effort
-→ Suggests starting first task
-```
-
-### Daily Development Flow
-```
-User: "p. now implement login form"
-→ Sets current focus
-→ [User works on code]
-User: "p. done"
-→ Marks complete, suggests next task
-User: "p. ship authentication"
-→ Commits, celebrates, updates metrics
-```
-
-### Quick Idea Capture
-```
-User: "p. idea we should add dark mode later"
-→ Saves to ideas.md
-→ Doesn't interrupt current work
-```
-
-## ⚠️ Anti-Patterns (What NOT to Do)
-
-| ❌ Don't | ✅ Do Instead |
-|----------|---------------|
-| Write to `.prjct/` folder | Write to `~/.prjct-cli/projects/{id}/` |
-| Skip reading project context | Always read CLAUDE.md first |
-| Execute without projectId | Check `.prjct/prjct.config.json` exists |
-| Hardcode file paths | Use projectId to construct paths |
-| Ignore agents | Use specialized agents for their domains |
-
-## 🎯 Path Resolution for ALL /p:* Commands
-
-**CRITICAL**: Every `/p:*` command operates on **global storage**, NOT local files.
-
-### Resolution Steps:
-
-1. **Detect prjct project**: Check if `.prjct/prjct.config.json` exists
-2. **Read config**: Extract `projectId` from config
-3. **Construct base path**: `~/.prjct-cli/projects/{projectId}/`
-4. **Resolve all file operations**: Paths are relative to base path
-
-### Examples:
-
-```
-Template says: "Write: core/now.md"
-Actual path:  ~/.prjct-cli/projects/{projectId}/core/now.md
-
-Template says: "Read: memory/context.jsonl"
-Actual path:  ~/.prjct-cli/projects/{projectId}/memory/context.jsonl
-```
-
-### Validation Rules:
-
-- ❌ **NEVER** write to `.prjct/core/now.md` (local project directory)
-- ❌ **NEVER** write to `./core/now.md` (current working directory)
-- ✅ **ALWAYS** write to `~/.prjct-cli/projects/{projectId}/core/now.md`
-
-### When NOT in prjct Project:
-
-If `.prjct/prjct.config.json` doesn't exist:
-- Respond: "No prjct project detected. Initialize first with `/p:init`"
-- Do NOT execute the command
-- Do NOT create files
-
-## 📁 File Structure
-
-All prjct data lives in global storage:
-
-```
-~/.prjct-cli/projects/{projectId}/
-├── CLAUDE.md            # ⭐ READ THIS FIRST - Rich project context
-├── core/                # Current focus
-│   ├── now.md          # Single current task
-│   └── next.md         # Priority queue
-├── progress/           # Completed work
-│   ├── shipped.md      # Recent ships
-│   └── metrics.md      # Aggregated metrics
-├── planning/           # Future planning
-│   ├── ideas.md        # Quick ideas
-│   └── roadmap.md      # Feature roadmap
-├── analysis/           # Technical analysis
-│   └── repo-summary.md # Full repo analysis
-├── memory/             # Decision history
-│   └── context.jsonl   # Append-only log
-└── agents/             # ⭐ Specialized AI agents
-    ├── fe.md           # Frontend specialist
-    ├── be.md           # Backend specialist
-    └── ...             # More based on stack
-```
-
-## 🤖 Using Agents Effectively
-
-When project has specialized agents:
-
-1. **Read agent file** before working in that domain
-2. **Follow agent patterns** for code style and architecture
-3. **Agent expertise** is in CLAUDE.md summary
-
-Example:
-```
-Task: "implement React component"
-→ Check CLAUDE.md for frontend agent
-→ Read agents/fe.md for React patterns
-→ Follow detected conventions
-```
-
-## 🤖 Git Commit Format
-
-**ALL commits made by prjct MUST use this footer:**
+Result: `"2025-12-20T10:30:00.000Z"` - NEVER hardcode
 
+### 4. Git Commit Footer
 ```
 🤖 Generated with [p/](https://www.prjct.app/)
 Designed for [Claude](https://www.anthropic.com/claude)
 ```
 
-**Never use:**
-- ❌ "Generated with Claude Code"
-- ❌ "Co-Authored-By: Claude"
+---
 
-## ⚠️ Common Validation Patterns
+## Quick Reference
 
-### Before /p:done:
-```javascript
-const nowContent = await Read('~/.prjct-cli/projects/{projectId}/core/now.md')
-if (!nowContent || nowContent.trim() === '') {
-  return "Not working on anything. Use /p:now to start a task."
-}
-```
+| Command | Purpose |
+|---------|---------|
+| `/p:sync` | Analyze project, generate agents |
+| `/p:now [task]` | Start/show current task |
+| `/p:done` | Complete current task |
+| `/p:ship [feature]` | Ship with quality checks |
 
-### Before /p:ship:
-```javascript
-const nowContent = await Read('~/.prjct-cli/projects/{projectId}/core/now.md')
-if (!nowContent || nowContent.trim() === '') {
-  return "Nothing to ship yet. Build something first with /p:now."
-}
-```
+**Workflow**: `/p:sync` → `/p:now` → [work] → `/p:done` → `/p:ship`
 
-## 🔧 Error Handling
+---
 
-| Error | Solution |
-|-------|----------|
-| File not found | Return empty state, don't fail |
-| Invalid JSON config | Suggest `/p:init` again |
-| Permission denied | Suggest `chmod -R u+w ~/.prjct-cli/` |
-| No project detected | Suggest `/p:init` |
+## Detailed Documentation
 
-## 🎯 Command Execution Flow
+For detailed information, read these files:
 
-Standard pattern for all `/p:*` commands:
+| Topic | File |
+|-------|------|
+| Architecture (Write-Through, file structure) | `~/.prjct-cli/docs/architecture.md` |
+| All commands and examples | `~/.prjct-cli/docs/commands.md` |
+| Validation patterns | `~/.prjct-cli/docs/validation.md` |
+| Using agents | `~/.prjct-cli/docs/agents.md` |
 
-1. **Validate**: Check `.prjct/prjct.config.json` exists
-2. **Read config**: Extract projectId
-3. **Read context**: Load `~/.prjct-cli/projects/{id}/CLAUDE.md`
-4. **Execute**: Read/write files in global storage
-5. **Log**: Append to `memory/context.jsonl`
-6. **Respond**: Formatted response with next action suggestions
+---
 
-## 📚 Additional Context
+## Before Any Command
 
-- **Website**: https://prjct.app
-- **Documentation**: https://prjct.app/docs
-- **Support**: jlopezlira@gmail.com
+1. Read `.prjct/prjct.config.json` → get `projectId`
+2. Read `~/.prjct-cli/projects/{projectId}/CLAUDE.md` → project context
+3. Execute using global storage paths
+4. Log to `memory/events.jsonl`
 
 ---
 
-**Last updated**: Auto-managed by prjct-cli
-**Config version**: 0.10.5
+**Auto-managed by prjct-cli** | https://prjct.app | v0.19.0
 
 <!-- prjct:end - DO NOT REMOVE THIS MARKER -->

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"
+```