prjct-cli 0.25.2 → 0.27.0

package/templates/commands/test.md

@@ -1,11 +1,16 @@
 ---
 allowed-tools: [Bash, Read, Write, Edit]
-description: 'Run tests with auto-fix'
+description: 'Run tests and advance workflow phase'
 timestamp-rule: 'GetTimestamp() for ALL timestamps'
+architecture: 'Write-Through (JSON -> MD -> Events)'
+storage-layer: true
+source-of-truth: 'storage/state.json'
 ---
 
 # /p:test
 
+Run tests to advance from implement phase to test phase in the workflow.
+
 ## Usage
 
 ```
@@ -17,7 +22,9 @@ timestamp-rule: 'GetTimestamp() for ALL timestamps'
 - `{projectId}`: From `.prjct/prjct.config.json`
 - `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
 - `{configPath}`: `~/.prjct-cli/config.json`
+- `{statePath}`: `{globalPath}/storage/state.json`
 - `{memoryPath}`: `{globalPath}/memory/events.jsonl`
+- `{syncPath}`: `{globalPath}/sync/pending.json`
 
 ## Step 1: Read Project Config
 
@@ -28,6 +35,26 @@ IF file not found:
   OUTPUT: "No prjct project. Run /p:init first."
   STOP
 
+## Step 1.5: Validate Workflow Phase
+
+READ: `{globalPath}/storage/state.json`
+
+IF currentTask is null:
+  OUTPUT: "No active task. Use p. task to start one."
+  STOP
+
+IF currentTask.workflow exists:
+  IF currentTask.workflow.phase != "implement":
+    OUTPUT:
+    ```
+    Cannot run tests. Current phase: {currentTask.workflow.phase}
+
+    Required phase: implement
+
+    Workflow: analyze → branch → implement → test → review → merge → ship → verify
+    ```
+    STOP
+
 ## Step 2: Parse Arguments
 
 SET defaults:
@@ -141,14 +168,59 @@ IF {blocking} AND {failed} > 0:
 ### Success Response
 
 IF {testStatus} == "passed":
+  ### Update Workflow Phase (if workflow exists)
+  IF currentTask.workflow exists:
+    SET: {now} = GetTimestamp()
+
+    SET: currentTask.workflow.phase = "test"
+    SET: currentTask.workflow.checkpoints.implement = {
+      "completedAt": "{now}",
+      "data": { "filesChanged": {count}, "commits": {count} }
+    }
+    SET: currentTask.workflow.checkpoints.test = {
+      "completedAt": "{now}",
+      "data": { "passed": {passed}, "coverage": "{coverage}" }
+    }
+    SET: currentTask.workflow.lastCheckpoint = "test"
+
+    WRITE: `{statePath}`
+
+    ### Log workflow events
+    APPEND to `{memoryPath}`:
+    ```json
+    {"timestamp":"{now}","action":"phase_advanced","taskId":"{currentTask.id}","from":"implement","to":"test"}
+    {"timestamp":"{now}","action":"checkpoint_completed","taskId":"{currentTask.id}","checkpoint":"implement"}
+    {"timestamp":"{now}","action":"checkpoint_completed","taskId":"{currentTask.id}","checkpoint":"test"}
+    ```
+
+    ### Queue sync event
+    APPEND to `{syncPath}`:
+    ```json
+    {"type":"workflow.phase_advanced","data":{"taskId":"{currentTask.id}","from":"implement","to":"test"},"timestamp":"{now}"}
+    ```
+
   OUTPUT: "✅ All tests passing!"
   OUTPUT: ""
   OUTPUT: "📊 Results:"
   OUTPUT: "• Passed: {passed}"
   IF {coverage}:
     OUTPUT: "• Coverage: {coverage}%"
-  OUTPUT: ""
-  OUTPUT: "🎯 Next: /p:ship"
+
+  IF currentTask.workflow exists:
+    OUTPUT: ""
+    OUTPUT: "Phase: test (4/11 checkpoints)"
+    OUTPUT: ""
+    OUTPUT: "Workflow:"
+    OUTPUT: "1. analyze ✓"
+    OUTPUT: "2. branch ✓"
+    OUTPUT: "3. implement ✓"
+    OUTPUT: "4. test ✓"
+    OUTPUT: "5. review ← next"
+    OUTPUT: ""
+    OUTPUT: "🎯 Next: p. review"
+  ELSE:
+    OUTPUT: ""
+    OUTPUT: "🎯 Next: /p:ship"
 
 ### Failure Response
 

package/templates/commands/verify.md

@@ -0,0 +1,204 @@
+---
+allowed-tools: [Bash, Read, Write]
+description: 'Verify workflow completion and close task'
+timestamp-rule: 'GetTimestamp() for ALL timestamps'
+architecture: 'Write-Through (JSON -> MD -> Events)'
+storage-layer: true
+source-of-truth: 'storage/state.json'
+---
+
+# /p:verify
+
+Verify all workflow checkpoints are complete and close the task.
+
+## Usage
+
+```
+/p:verify
+```
+
+## Context Variables
+- `{projectId}`: From `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+- `{statePath}`: `{globalPath}/storage/state.json`
+- `{memoryPath}`: `{globalPath}/memory/events.jsonl`
+- `{syncPath}`: `{globalPath}/sync/pending.json`
+- `{nowContextPath}`: `{globalPath}/context/now.md`
+
+## Step 1: Validate Project
+
+READ: `.prjct/prjct.config.json`
+EXTRACT: `projectId`
+
+IF file not found:
+  OUTPUT: "No prjct project. Run /p:init first."
+  STOP
+
+## Step 2: Validate Workflow Phase
+
+READ: `{globalPath}/storage/state.json`
+
+IF currentTask is null:
+  OUTPUT: "No active task. Nothing to verify."
+  STOP
+
+IF currentTask.workflow is null:
+  OUTPUT: "Task has no workflow. This is a legacy task."
+  STOP
+
+IF currentTask.workflow.phase != "register":
+  OUTPUT:
+  ```
+  Cannot verify. Current phase: {currentTask.workflow.phase}
+
+  Required phase: register (after ship)
+
+  Workflow: analyze → branch → implement → test → review → merge → ship → verify
+  
+  Complete p. ship first.
+  ```
+  STOP
+
+## Step 3: Validate All Checkpoints
+
+SET: {checkpoints} = currentTask.workflow.checkpoints
+SET: {required} = ["analyze", "branch", "implement", "test", "review", "merge", "tag", "release", "deploy", "register"]
+SET: {missing} = []
+
+FOR each checkpoint in {required}:
+  IF {checkpoints}[checkpoint] is null:
+    APPEND checkpoint to {missing}
+
+IF {missing}.length > 0:
+  OUTPUT:
+  ```
+  ⚠️ Incomplete workflow
+
+  Missing checkpoints:
+  {FOR each in missing: "- {checkpoint}"}
+
+  Complete all phases before verifying.
+  ```
+  STOP
+
+## Step 4: Calculate Workflow Summary
+
+SET: {startedAt} = currentTask.workflow.startedAt
+SET: {now} = GetTimestamp()
+SET: {totalDuration} = time between {startedAt} and {now}
+FORMAT: as "Xh Ym" or "Xd Xh"
+
+### Gather metrics from checkpoints
+SET: {scope} = checkpoints.analyze.data.scope
+SET: {branchName} = checkpoints.branch.data.branchName
+SET: {coverage} = checkpoints.test.data.coverage
+SET: {mcpScore} = checkpoints.review.data.mcpScore
+SET: {approvals} = checkpoints.review.data.approvals.length
+SET: {mergeCommit} = checkpoints.merge.data.mergeCommit
+SET: {version} = checkpoints.tag.data.version
+SET: {releaseUrl} = checkpoints.release.data.releaseUrl
+
+## Step 5: Complete Workflow
+
+SET: currentTask.workflow.phase = "verify"
+SET: currentTask.workflow.checkpoints.verify = {
+  "completedAt": "{now}",
+  "data": {
+    "verified": true,
+    "totalDuration": "{totalDuration}"
+  }
+}
+SET: currentTask.workflow.completedAt = "{now}"
+SET: currentTask.workflow.lastCheckpoint = "verify"
+
+### Move to previousTask
+SET: state.previousTask = {
+  ...currentTask,
+  "status": "completed",
+  "completedAt": "{now}"
+}
+SET: state.currentTask = null
+SET: state.lastUpdated = "{now}"
+
+WRITE: `{statePath}`
+
+## Step 6: Generate Context
+
+WRITE: `{nowContextPath}`
+
+```markdown
+# NOW
+
+_No active task_
+
+Last completed: {previousTask.description}
+Duration: {totalDuration}
+Version: {version}
+
+Use p. task to start new work.
+```
+
+## Step 7: Log Events
+
+APPEND to `{memoryPath}`:
+```json
+{"timestamp":"{now}","action":"workflow_completed","taskId":"{previousTask.id}","duration":"{totalDuration}","checkpoints":11}
+{"timestamp":"{now}","action":"checkpoint_completed","taskId":"{previousTask.id}","checkpoint":"verify"}
+```
+
+APPEND to `{syncPath}`:
+```json
+{"type":"workflow.completed","data":{"taskId":"{previousTask.id}","duration":"{totalDuration}","version":"{version}"},"timestamp":"{now}"}
+```
+
+## Output
+
+```
+✓ Workflow Complete
+
+Task: {previousTask.description}
+Type: {previousTask.type}
+Duration: {totalDuration}
+Version: {version}
+
+Checkpoints (11/11):
+1. analyze ✓ - Scope: {scope}
+2. branch ✓ - {branchName}
+3. implement ✓
+4. test ✓ - Coverage: {coverage}
+5. review ✓ - MCP: {mcpScore}/100, Approvals: {approvals}
+6. merge ✓ - {mergeCommit}
+7. tag ✓ - v{version}
+8. release ✓ - {releaseUrl}
+9. deploy ✓ - Reminded
+10. register ✓ - Logged
+11. verify ✓ - Complete
+
+Summary:
+- All phases completed
+- Audit trail recorded
+- Task closed
+
+Next: p. task to start new work
+```
+
+## Error Handling
+
+| Error | Response | Action |
+|-------|----------|--------|
+| No project | "No prjct project" | STOP |
+| No active task | "Nothing to verify" | STOP |
+| No workflow | "Legacy task" | STOP |
+| Wrong phase | Show required phase | STOP |
+| Missing checkpoints | List missing | STOP |
+
+## Natural Language Triggers
+
+- `p. verify` -> /p:verify
+- `p. complete` -> /p:verify
+- `p. close` -> /p:verify
+
+## References
+
+- Architecture: `~/.prjct-cli/docs/architecture.md`
+- Workflow: `~/.prjct-cli/docs/workflow.md`

package/templates/config/skill-mappings.json

@@ -0,0 +1,87 @@
+{
+  "version": "1.0.0",
+  "description": "Search hints for finding skills on claude-plugins.dev - NOT hardcoded mappings",
+  "note": "Claude should SEARCH claude-plugins.dev dynamically using these hints",
+  "searchEndpoint": "https://claude-plugins.dev/skills?q={query}",
+  "skillsDirectory": "~/.claude/skills/",
+  "searchHints": {
+    "frontend": {
+      "searchTerms": ["frontend-design", "react components", "vue components", "ui design"],
+      "preferredAuthors": ["@anthropics", "@wshobson"],
+      "fallbackSearch": "frontend ui components",
+      "description": "UI components, styling, frontend patterns"
+    },
+    "uxui": {
+      "searchTerms": ["ux-designer", "frontend-design", "user experience", "ui ux design"],
+      "preferredAuthors": ["@anthropics", "@aj-geddes"],
+      "fallbackSearch": "ux ui design patterns",
+      "description": "UX/UI design, user experience, accessibility"
+    },
+    "backend": {
+      "ecosystemSpecific": {
+        "javascript": ["typescript backend", "nodejs patterns", "express api"],
+        "typescript": ["typescript backend", "nodejs patterns", "api design"],
+        "python": ["python backend", "fastapi django", "python api"],
+        "go": ["golang backend", "go api patterns"],
+        "rust": ["rust backend", "axum actix"]
+      },
+      "preferredAuthors": ["@wshobson", "@anthropics"],
+      "fallbackSearch": "backend api patterns",
+      "description": "API design, backend patterns, server logic"
+    },
+    "database": {
+      "searchTerms": ["database design", "sql patterns", "prisma drizzle"],
+      "preferredAuthors": ["@wshobson"],
+      "fallbackSearch": "database sql patterns",
+      "description": "Database design, queries, migrations"
+    },
+    "testing": {
+      "searchTerms": ["testing automation", "test patterns", "jest pytest"],
+      "preferredAuthors": ["@anthropics", "@claudebase"],
+      "fallbackSearch": "testing automation patterns",
+      "description": "Test automation, TDD, test patterns"
+    },
+    "devops": {
+      "searchTerms": ["devops automation", "ci cd", "docker kubernetes", "github actions"],
+      "preferredAuthors": ["@claudebase", "@anthropics"],
+      "fallbackSearch": "devops ci cd automation",
+      "description": "CI/CD, containers, infrastructure"
+    },
+    "prjct-planner": {
+      "searchTerms": ["architecture patterns", "feature development", "system design"],
+      "preferredAuthors": ["@anthropics", "@wshobson"],
+      "fallbackSearch": "architecture planning patterns",
+      "description": "Feature planning, architecture, task breakdown"
+    },
+    "prjct-shipper": {
+      "searchTerms": ["code review", "pr review", "shipping best practices"],
+      "preferredAuthors": ["@anthropics"],
+      "fallbackSearch": "code review automation",
+      "description": "Code review, PR quality, shipping"
+    }
+  },
+  "selectionCriteria": {
+    "priority": [
+      "Match agent domain",
+      "Prefer @anthropics (official)",
+      "High download count",
+      "Recent updates",
+      "Good documentation"
+    ],
+    "skipIf": [
+      "Low download count (<100)",
+      "No recent updates (>6 months)",
+      "Duplicate of installed skill"
+    ]
+  },
+  "installMethod": {
+    "steps": [
+      "1. Search claude-plugins.dev/skills?q={searchTerm}",
+      "2. Analyze results, pick best match",
+      "3. Get skill markdown from GitHub source",
+      "4. Write to ~/.claude/skills/{name}.md",
+      "5. Verify skill loads with /skills command"
+    ],
+    "fallback": "Create custom skill if marketplace has no good match"
+  }
+}

package/templates/global/CLAUDE.md

@@ -1,75 +1,232 @@
 <!-- prjct:start - DO NOT REMOVE THIS MARKER -->
 # prjct-cli
 
-## CRITICAL RULES (READ FIRST)
+**Developer momentum tool** - Track progress through natural language commands without PM overhead.
+
+## HOW TO USE PRJCT (Read This First)
+
+When user types `p. <command>`, load the template from `templates/commands/{command}.md` and execute it intelligently.
+
+```
+p. sync     → templates/commands/sync.md
+p. task X   → templates/commands/task.md
+p. done     → templates/commands/done.md
+p. ship X   → templates/commands/ship.md
+```
+
+**Key Insight**: Templates are GUIDANCE, not scripts. Use your intelligence to adapt them to the situation.
+
+---
+
+## CRITICAL RULES
 
 ### 1. Path Resolution (MOST IMPORTANT)
 **ALL writes go to global storage**: `~/.prjct-cli/projects/{projectId}/`
 
-- **NEVER** write to `.prjct/` (config only)
+- **NEVER** write to `.prjct/` (config only, read-only)
 - **NEVER** write to `./` (current directory)
-- **ALWAYS** use global storage path
+- **ALWAYS** resolve projectId first from `.prjct/prjct.config.json`
 
-### 2. Project Detection
-Read `.prjct/prjct.config.json` → extract `projectId`
-- If missing: "No prjct project. Run /p:init first." → STOP
+### 2. Before Any Command
+```
+1. Read .prjct/prjct.config.json → get projectId
+2. Set globalPath = ~/.prjct-cli/projects/{projectId}
+3. Execute command using globalPath for all writes
+4. Log to {globalPath}/memory/events.jsonl
+```
 
-### 3. Timestamps
+### 3. Timestamps & UUIDs
 ```bash
+# Timestamp (NEVER hardcode)
 bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
+
+# UUID
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
 ```
-Result: `"2025-12-20T10:30:00.000Z"` - NEVER hardcode
 
-### 4. Git Commit Footer
+### 4. Git Commit Footer (CRITICAL - ALWAYS INCLUDE)
+
+**Every commit made with prjct MUST include this footer:**
+
 ```
 🤖 Generated with [p/](https://www.prjct.app/)
 Designed for [Claude](https://www.anthropic.com/claude)
+
+```
+
+**This is NON-NEGOTIABLE. The prjct signature (`🤖 Generated with [p/]`) must appear in ALL commits.**
+
+---
+
+## CORE WORKFLOW
+
+```
+p. sync  →  p. task "description"  →  [work]  →  p. done  →  p. ship
+   │              │                                  │            │
+   │              └─ Creates branch, breaks down     │            │
+   │                 task, starts tracking           │            │
+   │                                                 │            │
+   └─ Analyzes project, generates agents             │            │
+                                                     │            │
+                              Completes subtask ─────┘            │
+                                                                  │
+                                        Ships feature, PR, tag ───┘
+```
+
+### Quick Reference
+
+| Trigger | What It Does |
+|---------|--------------|
+| `p. sync` | Analyze project, generate domain agents |
+| `p. task <desc>` | Start task with auto-classification |
+| `p. done` | Complete current subtask |
+| `p. ship [name]` | Ship feature with PR + version bump |
+| `p. pause` | Pause current task |
+| `p. resume` | Resume paused task |
+| `p. bug <desc>` | Report bug with auto-priority |
+
+---
+
+## ARCHITECTURE: Write-Through Pattern
+
+```
+User Action → Storage (JSON) → Context (MD) → Sync Events
+```
+
+| Layer | Path | Purpose |
+|-------|------|---------|
+| **Storage** | `storage/*.json` | Source of truth |
+| **Context** | `context/*.md` | Claude-readable summaries |
+| **Memory** | `memory/events.jsonl` | Audit trail (append-only) |
+| **Agents** | `agents/*.md` | Domain specialists |
+| **Sync** | `sync/pending.json` | Backend sync queue |
+
+### File 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)
+│   └── next.md         # Queue (generated)
+├── config/
+│   └── skills.json     # Agent-to-skill mappings (NEW)
+├── memory/
+│   └── events.jsonl    # Audit trail
+├── agents/             # Domain specialists (auto-generated)
+└── sync/
+    └── pending.json    # Events for backend
 ```
 
 ---
 
-## Quick Reference
+## INTELLIGENT BEHAVIOR
+
+### When Starting Tasks (`p. task`)
+1. **Analyze** - Understand what user wants to achieve
+2. **Classify** - Determine type: feature, bug, improvement, refactor, chore
+3. **Explore** - Find similar code, patterns, affected files
+4. **Ask** - Clarify ambiguities (use AskUserQuestion)
+5. **Design** - Propose 2-3 approaches, get approval
+6. **Break down** - Create actionable subtasks
+7. **Track** - Update storage/state.json
+
+### When Completing Tasks (`p. done`)
+1. Check if there are more subtasks
+2. If yes, advance to next subtask
+3. If no, task is complete
+4. Update storage, generate context
+
+### When Shipping (`p. ship`)
+1. Run tests (if configured)
+2. Create PR (if on feature branch)
+3. Bump version
+4. Update CHANGELOG
+5. Create git tag
+
+### Key Intelligence Rules
+- **Read before write** - Always read existing files before modifying
+- **Explore before coding** - Use Task(Explore) to understand codebase
+- **Ask when uncertain** - Use AskUserQuestion to clarify
+- **Adapt templates** - Templates are guidance, not rigid scripts
+- **Log everything** - Append to memory/events.jsonl
 
-| Command | Purpose |
-|---------|---------|
-| `/p:sync` | Analyze project, generate agents |
-| `/p:task <description>` | Start task (auto-classifies type) |
-| `/p:done` | Complete current task |
-| `/p:ship [feature]` | Ship with quality checks |
+---
 
-**Workflow**: `/p:sync` → `/p:task` → [work] → `/p:done` → `/p:ship`
+## OUTPUT FORMAT
 
-### Natural Language Triggers
+Concise responses (< 4 lines):
+```
+✅ [What was done]
 
-Messages starting with `p.` trigger commands:
-- `p. task add auth` → /p:task "add auth"
-- `p. done` → /p:done
-- `p. ship login` → /p:ship "login"
+[Key metrics]
+Next: [suggested action]
+```
 
 ---
 
-## Detailed Documentation
+## LOADING DOMAIN AGENTS
 
-For detailed information, read these files:
+When working on tasks, load relevant agents from `{globalPath}/agents/`:
+- `frontend.md` - Frontend patterns, components
+- `backend.md` - Backend patterns, APIs
+- `database.md` - Database patterns, queries
+- `uxui.md` - UX/UI guidelines
+- `testing.md` - Testing patterns
+- `devops.md` - CI/CD, containers
 
-| 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` |
+These agents contain project-specific patterns. **USE THEM**.
 
 ---
 
-## Before Any Command
+## SKILL INTEGRATION (NEW in v0.27 - AGENTIC)
+
+Agents are linked to Claude Code skills from claude-plugins.dev.
+
+**Skills are discovered AGENTICALLY** - Claude searches the marketplace dynamically.
+
+### How Skills Work
+
+1. **During `p. sync`**: Search claude-plugins.dev, install best matches
+2. **During `p. task`**: Skills are auto-invoked for domain expertise
+3. **Agent frontmatter** has `skills: [discovered-skill-name]` field
+
+### Agentic Discovery Process
+
+```
+FOR EACH generated agent:
+  1. Read search hints from templates/config/skill-mappings.json
+  2. Search: https://claude-plugins.dev/skills?q={searchTerm}
+  3. Analyze results (prefer @anthropics, high downloads)
+  4. Download skill markdown from GitHub
+  5. Write to ~/.claude/skills/{name}.md
+  6. Update agent frontmatter
+```
+
+### Search Terms by Agent
+
+| Agent | Search Terms |
+|-------|-------------|
+| `frontend.md` | "frontend-design", "react", "ui components" |
+| `uxui.md` | "ux-designer", "frontend-design", "ui ux" |
+| `backend.md` | "{ecosystem} backend", "api design" |
+| `testing.md` | "testing automation", "test patterns" |
+| `devops.md` | "devops", "ci cd", "docker kubernetes" |
+| `prjct-planner.md` | "architecture patterns", "feature development" |
+| `prjct-shipper.md` | "code review", "pr review" |
+
+### Skill Location
+
+Skills are markdown files in `~/.claude/skills/`
+
+### Skill Configuration
 
-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`
+After sync: `{globalPath}/config/skills.json` contains discovered mappings.
 
 ---
 
-**Auto-managed by prjct-cli** | https://prjct.app | v0.24.0
+**Auto-managed by prjct-cli** | https://prjct.app | v0.27.0
 
 <!-- prjct:end - DO NOT REMOVE THIS MARKER -->