prjct-cli 0.28.2 → 0.28.4

package/templates/guides/claude-code-ux.md

@@ -0,0 +1,232 @@
+# Claude Code UX Enhancements
+
+prjct provides rich terminal UX improvements for Claude Code while staying 100% compatible with Anthropic's Terms of Service.
+
+## Quick Setup
+
+```bash
+# Run the setup command
+p. setup-statusline
+```
+
+Or manually configure:
+
+```json
+// ~/.claude/settings.json
+{
+  "statusLine": {
+    "command": "~/.prjct-cli/statusline/statusline.sh"
+  }
+}
+```
+
+---
+
+## Features
+
+### 1. Status Line
+
+Displays real-time information in Claude Code's status area:
+
+```
+⚡ Current Task │ 󰉋 directory │  branch* │ +42 -15 │ ctx [████░░░░░░] 40% │ 🎭
+```
+
+| Segment | Description |
+|---------|-------------|
+| ⚡ Task | Current prjct task (from state.json) |
+| 󰉋 Dir | Current working directory |
+|  Branch | Git branch with dirty indicator (*) |
+| +/- | Lines added/removed this session |
+| ctx Bar | Context window usage (color-coded) |
+| Icon | Model: 🎭 Opus, 📝 Sonnet, 🍃 Haiku |
+
+**Context Bar Colors:**
+- 🟢 Green: < 50% usage
+- 🟡 Yellow: 50-80% usage
+- 🔴 Red: > 80% usage (warning!)
+
+### 2. Themes
+
+Three built-in themes at `~/.prjct-cli/statusline/themes/`:
+
+| Theme | File | Description |
+|-------|------|-------------|
+| **prjct** | `default.json` | Cyan and purple - matches prjct branding |
+| **Gentleman** | `gentleman.json` | Elegant blues and golds (inspired by GentlemanClaude) |
+| **Minimal** | `minimal.json` | Clean grayscale with accent colors |
+
+**Switch themes:**
+```json
+{
+  "env": {
+    "PRJCT_STATUSLINE_THEME": "~/.prjct-cli/statusline/themes/gentleman.json"
+  }
+}
+```
+
+### 3. Output Styles
+
+Custom output formatting at `~/.prjct-cli/output-styles/`:
+
+| Style | Use Case |
+|-------|----------|
+| `prjct.md` | Default - concise, actionable |
+| `verbose.md` | Learning - detailed explanations |
+| `ship-fast.md` | Maximum velocity - minimal output |
+
+**Activate:**
+```
+/output-style ~/.prjct-cli/output-styles/prjct.md
+```
+
+### 4. Hooks
+
+Automatic metrics tracking:
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `update-metrics.sh` | PostToolUse | Tracks file changes and commands |
+| `session-summary.sh` | Stop | Shows session statistics |
+
+**Enable hooks:**
+```json
+{
+  "hooks": [
+    {
+      "event": "PostToolUse",
+      "command": "~/.prjct-cli/hooks/update-metrics.sh",
+      "matcher": { "tool": "Write" }
+    },
+    {
+      "event": "Stop",
+      "command": "~/.prjct-cli/hooks/session-summary.sh"
+    }
+  ]
+}
+```
+
+### 5. Visual Theme (tweakcc)
+
+Full Claude Code visual theme at `~/.prjct-cli/tweakcc-theme.json`:
+
+- Custom color palette
+- Spanish thinking verbs
+- Diff highlighting
+- Shimmer effects
+
+---
+
+## File Locations
+
+```
+~/.prjct-cli/
+├── statusline/
+│   ├── statusline.sh          # Main script
+│   └── themes/
+│       ├── default.json       # prjct theme
+│       ├── gentleman.json     # Elegant theme
+│       └── minimal.json       # Clean theme
+├── hooks/
+│   ├── update-metrics.sh      # Track tool usage
+│   └── session-summary.sh     # Session stats
+├── output-styles/
+│   ├── prjct.md               # Concise output
+│   ├── verbose.md             # Detailed output
+│   └── ship-fast.md           # Minimal output
+├── tweakcc-theme.json         # Visual theme
+└── settings.template.json     # Full config template
+```
+
+---
+
+## ToS Compliance
+
+All features use **officially documented** Claude Code APIs:
+
+| Feature | API Used | Documentation |
+|---------|----------|---------------|
+| Status Line | `statusLine.command` | code.claude.com/docs/en/statusline |
+| Hooks | `hooks` array | code.claude.com/docs/en/hooks-guide |
+| Output Styles | Custom markdown | code.claude.com/docs/en/output-styles |
+| Themes | Environment vars | code.claude.com/docs/en/settings |
+
+**What we DON'T do:**
+- ❌ Modify Claude Code internals
+- ❌ Bypass rate limits
+- ❌ Reverse engineer protocols
+- ❌ Access unauthorized data
+
+---
+
+## Troubleshooting
+
+### Status line not showing
+
+1. Check `jq` is installed: `which jq`
+2. Verify script is executable: `ls -la ~/.prjct-cli/statusline/statusline.sh`
+3. Test manually:
+   ```bash
+   echo '{"model":{"display_name":"Claude Sonnet"}}' | ~/.prjct-cli/statusline/statusline.sh
+   ```
+
+### Theme not loading
+
+1. Check file exists: `ls ~/.prjct-cli/statusline/themes/`
+2. Verify JSON is valid: `jq . ~/.prjct-cli/statusline/themes/default.json`
+3. Check env var is set in settings.json
+
+### Hooks not firing
+
+1. Verify hook scripts are executable
+2. Check Claude Code logs for errors
+3. Test hook manually:
+   ```bash
+   echo '{"tool":"Write"}' | ~/.prjct-cli/hooks/update-metrics.sh
+   ```
+
+---
+
+## Customization
+
+### Create Custom Theme
+
+```json
+// ~/.prjct-cli/statusline/themes/my-theme.json
+{
+  "name": "My Theme",
+  "colors": {
+    "primary": "39",      // ANSI 256 color code
+    "accent": "208",
+    "success": "82",
+    "error": "196"
+  },
+  "icons": {
+    "brand": "🚀",
+    "branch": ""
+  }
+}
+```
+
+### Create Custom Output Style
+
+```markdown
+<!-- ~/.prjct-cli/output-styles/my-style.md -->
+---
+name: My Style
+description: Custom output formatting
+keep-coding-instructions: true
+---
+
+# My Custom Instructions
+
+[Your formatting rules here]
+```
+
+---
+
+## Credits
+
+Inspired by [GentlemanClaude](https://github.com/Gentleman-Programming/Gentleman.Dots/tree/main/GentlemanClaude) by Gentleman Programming.
+
+**prjct-cli** | https://prjct.app

package/templates/guides/integrations.md

@@ -0,0 +1,149 @@
+# Integrations Guide
+
+Skills and MCP server integration for prjct agents.
+
+---
+
+## Skills Integration
+
+### Overview
+
+Skills are Claude Code extensions from `claude-plugins.dev` that provide domain expertise.
+
+### How Skills Work
+
+1. **Discovery** (`/p:sync`): Search marketplace, install matches
+2. **Linking**: Agent frontmatter has `skills: [skill-name]`
+3. **Invocation** (`/p:task`): Skills auto-invoked when agent loads
+
+### Skill Flow
+
+```
+p. task @frontend add button
+  ↓
+Load frontend.md (skills: [frontend-design])
+  ↓
+Auto-invoke: Skill("frontend-design")
+  ↓
+Skill context active for design decisions
+```
+
+### Skill Location
+
+- Installed: `~/.claude/skills/`
+- Mapping: `{globalPath}/config/skills.json`
+
+### Search Terms by Agent
+
+| Agent | Search Terms |
+|-------|-------------|
+| frontend | "frontend-design", "react", "ui" |
+| backend | "{ecosystem} backend", "api" |
+| uxui | "ux-designer", "ui ux" |
+| testing | "testing", "test patterns" |
+| devops | "devops", "ci cd" |
+
+---
+
+## MCP Server Integration
+
+### Overview
+
+MCP (Model Context Protocol) servers provide external capabilities like documentation lookup.
+
+### How MCP Works
+
+1. **Configuration** (`/p:sync`): Analyze deps, configure servers
+2. **Linking**: Agent frontmatter has `mcp: [server-name]`
+3. **Usage** (`/p:task`): Agents auto-query MCP for docs
+
+### MCP Flow
+
+```
+p. task @backend add API endpoint
+  ↓
+Load backend.md (mcp: [context7])
+  ↓
+Auto-query: context7 for Hono/Express docs
+  ↓
+Documentation context available
+```
+
+### Available Servers
+
+| Server | Purpose | Tools |
+|--------|---------|-------|
+| context7 | Library docs | resolve-library-id, query-docs |
+
+### Per-Project Configuration
+
+Path: `{globalPath}/config/mcp-servers.json`
+
+```json
+{
+  "servers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"],
+      "enabled": true
+    }
+  },
+  "agentMcpMap": {
+    "frontend": ["context7"],
+    "backend": ["context7"],
+    "database": ["context7"]
+  }
+}
+```
+
+### Agent-MCP Guidelines
+
+| Agent | Needs MCP? | Reason |
+|-------|------------|--------|
+| frontend | Yes | Component library docs |
+| backend | Yes | Framework docs |
+| database | Yes | ORM docs |
+| devops | Rarely | Uses bash commands |
+| prjct-* | Sometimes | Framework planning |
+
+---
+
+## Combined Pipeline
+
+```
+Task Input
+    ↓
+Load Agent (frontmatter)
+    ├── skills: [skill1, skill2]
+    └── mcp: [context7]
+    ↓
+Auto-Invoke Skills
+    ↓
+Auto-Query MCP Docs
+    ↓
+Execute with Full Context
+```
+
+---
+
+## Configuration During Sync
+
+### Skills Configuration
+
+```
+FOR EACH agent generated:
+  1. Determine search terms
+  2. Search claude-plugins.dev
+  3. Install matching skills
+  4. Update agent frontmatter
+  5. Save to config/skills.json
+```
+
+### MCP Configuration
+
+```
+FOR EACH agent generated:
+  1. Check if uses external libraries
+  2. If yes, add context7 to mcp
+  3. Save to config/mcp-servers.json
+```

package/templates/mcp-config.json

@@ -1,27 +1,32 @@
 {
-  "mcpServers": {
+  "_comment": "REFERENCE ONLY - MCP config is generated agentically per-project in ~/.prjct-cli/projects/{id}/config/mcp-servers.json",
+  "knownServers": {
     "context7": {
+      "name": "context7",
+      "description": "Upstash Context7 - Library/framework documentation lookup",
       "command": "npx",
       "args": ["-y", "@upstash/context7-mcp@latest"],
-      "description": "Library documentation lookup - use for framework/library docs"
-    }
-  },
-  "usage": {
-    "context7": {
-      "when": [
-        "Looking up official documentation for any library/framework",
-        "Implementing features using specific libraries (React, Next.js, etc)",
-        "Checking API references and best practices",
-        "Troubleshooting library-specific issues"
+      "useWhen": [
+        "Project uses external libraries/frameworks",
+        "Agents need to look up API documentation",
+        "Working with React, Vue, Next.js, Express, Prisma, etc."
       ],
       "tools": [
-        "resolve-library-id: Find library ID from name (e.g., 'react' → '/facebook/react')",
-        "get-library-docs: Fetch documentation for a library ID"
-      ],
-      "examples": [
-        "resolve-library-id('nextjs') → get-library-docs('/vercel/next.js', 'app router')",
-        "resolve-library-id('tailwindcss') → get-library-docs('/tailwindlabs/tailwindcss', 'configuration')"
+        "resolve-library-id: Find library ID from name",
+        "query-docs: Fetch documentation for a library"
       ]
     }
-  }
+  },
+  "agentMcpGuidelines": {
+    "frontend": "Usually needs context7 for component library docs",
+    "backend": "Usually needs context7 for framework docs",
+    "database": "Usually needs context7 for ORM docs",
+    "uxui": "Usually needs context7 for UI library docs",
+    "testing": "May need context7 for testing library docs",
+    "devops": "Rarely needs MCP, uses bash commands",
+    "prjct-planner": "May need context7 for framework planning",
+    "prjct-shipper": "Rarely needs MCP",
+    "prjct-workflow": "Never needs MCP"
+  },
+  "discoveryInstructions": "When generating MCP config, analyze the project's package.json/dependencies to determine which MCP servers would be useful. Don't blindly apply all servers - only add what the project actually needs."
 }

package/templates/shared/git-operations.md

@@ -0,0 +1,68 @@
+# Git Operations (Batched)
+
+## Quick Status (Single Call)
+
+```bash
+git status --porcelain && git branch --show-current && git rev-list --count HEAD 2>/dev/null
+```
+
+Returns:
+- Uncommitted changes (first lines)
+- Current branch
+- Commit count
+
+## Full Analysis (Single Call)
+
+```bash
+git status --porcelain && \
+git log --oneline -10 --pretty=format:"%h|%s" && \
+git branch --show-current && \
+git rev-list --count HEAD && \
+git diff --stat HEAD~1 2>/dev/null
+```
+
+## Branch Operations
+
+### Create Feature Branch
+```bash
+git checkout -b {branchName} && git push -u origin {branchName}
+```
+
+### Check Branch State
+```bash
+git log main..HEAD --oneline 2>/dev/null | wc -l
+```
+
+## Stash Operations (for interrupts)
+
+```bash
+# Save work
+git stash push -m "prjct: {reason}" --include-untracked
+
+# Restore work
+git stash pop
+```
+
+## Diff Analysis
+
+```bash
+# Files changed
+git diff --name-only HEAD~{N}
+
+# Stats
+git diff --stat HEAD~{N}
+
+# Full diff for review
+git diff HEAD~{N}
+```
+
+## Commit (with prjct footer)
+
+```bash
+git add -A && git commit -m "$(cat <<'EOF'
+{message}
+
+🤖 Generated with [p/](https://www.prjct.app/)
+EOF
+)"
+```

package/templates/shared/io-patterns.md

@@ -0,0 +1,72 @@
+# I/O Patterns (Performance)
+
+## Parallel Reads
+
+**ALWAYS** read multiple files in single tool call batch:
+
+```
+READ (parallel):
+- {globalPath}/storage/state.json → {state}
+- {globalPath}/storage/queue.json → {queue}
+- {globalPath}/storage/ideas.json → {ideas}
+- {globalPath}/storage/shipped.json → {shipped}
+```
+
+## Parallel Writes
+
+**ALWAYS** write independent files in single batch:
+
+```
+WRITE (parallel):
+- {globalPath}/context/now.md
+- {globalPath}/context/next.md
+- {globalPath}/storage/state.json
+```
+
+## Conditional Writes
+
+Only write if content changed:
+
+```
+IF {newContent} != {existingContent}:
+  WRITE file
+ELSE:
+  SKIP (no-op)
+```
+
+## File Count (Use Glob, NOT find)
+
+```
+GLOB: **/*.{ts,tsx,js,jsx} (exclude node_modules)
+```
+
+Never use `find` - Glob is 10x faster.
+
+## Package.json (Single Read)
+
+Read once, extract all:
+
+```
+READ: package.json → {pkg}
+
+{projectName} = pkg.name
+{version} = pkg.version
+{scripts} = pkg.scripts
+{deps} = {...pkg.dependencies, ...pkg.devDependencies}
+{techStack} = detect from deps (react, vue, express, etc.)
+```
+
+## Ecosystem Detection (Single ls)
+
+```bash
+ls package.json bun.lockb pnpm-lock.yaml yarn.lock Cargo.toml go.mod 2>/dev/null
+```
+
+| Found | Package Manager |
+|-------|-----------------|
+| bun.lockb | bun |
+| pnpm-lock.yaml | pnpm |
+| yarn.lock | yarn |
+| package-lock.json | npm |
+| Cargo.toml | cargo |
+| go.mod | go |

package/templates/shared/standard.md

@@ -0,0 +1,70 @@
+# Standard Practices (Reference Only)
+
+All prjct commands inherit these patterns. Do NOT repeat in individual templates.
+
+## Context Variables
+
+| Variable | Source | Example |
+|----------|--------|---------|
+| `{projectId}` | `.prjct/prjct.config.json` | `bc401c41-c8b9-...` |
+| `{globalPath}` | `~/.prjct-cli/projects/{projectId}` | Full path |
+| `{cwd}` | Current directory | Repo root |
+
+## Architecture: Write-Through
+
+```
+Action → Storage (JSON) → Context (MD) → Sync Events
+```
+
+- **Source of Truth**: `{globalPath}/storage/*.json`
+- **Claude Context**: `{globalPath}/context/*.md`
+- **Sync Queue**: `{globalPath}/sync/pending.json`
+
+## Timestamps & UUIDs
+
+```bash
+# Timestamp (NEVER hardcode)
+node -e "console.log(new Date().toISOString())"
+
+# UUID
+node -e "console.log(require('crypto').randomUUID())"
+```
+
+## Path Resolution (CRITICAL)
+
+**ALL writes**: `~/.prjct-cli/projects/{projectId}/`
+
+- NEVER write to `.prjct/` (read-only config)
+- NEVER write to `./` for prjct data
+
+## Error Handling
+
+| Error | Response |
+|-------|----------|
+| No config | "No prjct project. Run p. init" → STOP |
+| Not git repo | WARN, continue without git |
+| File not found | Skip, continue |
+
+## Git Commit Footer (REQUIRED)
+
+```
+🤖 Generated with [p/](https://www.prjct.app/)
+```
+
+## Parallel Operations
+
+**ALWAYS batch** when operations are independent:
+- Multiple READs → single parallel batch
+- Multiple WRITEs → single parallel batch
+- Git commands → chain with `&&`
+
+## Output Format
+
+```
+✅ [Action completed]
+
+[Key metrics]
+Next: [suggested action]
+```
+
+Keep output under 4 lines unless errors occur.

package/templates/shared/validation.md

@@ -0,0 +1,75 @@
+# Standard Project Validation
+
+Reusable validation patterns for prjct commands.
+
+## Project Config Validation
+
+```
+READ: .prjct/prjct.config.json
+EXTRACT: projectId
+
+IF file not found OR projectId missing:
+  OUTPUT: "No prjct project. Run /p:init first."
+  STOP
+
+SET: {globalPath} = ~/.prjct-cli/projects/{projectId}
+```
+
+## Git Repository Check
+
+```
+BASH: git rev-parse --git-dir 2>/dev/null
+
+IF fails:
+  SET: {isGitRepo} = false
+  # Continue without git features
+ELSE:
+  SET: {isGitRepo} = true
+  BASH: git branch --show-current
+  SET: {currentBranch} = result
+```
+
+## Current Task Check
+
+```
+READ: {globalPath}/storage/state.json
+
+IF currentTask exists AND status == "active":
+  SET: {hasActiveTask} = true
+  SET: {activeTaskDescription} = currentTask.description
+  SET: {elapsedTime} = now - currentTask.startedAt
+ELSE:
+  SET: {hasActiveTask} = false
+```
+
+## Protected Branch Check
+
+```
+IF {currentBranch} == "main" OR {currentBranch} == "master":
+  OUTPUT: "Cannot execute on protected branch: {currentBranch}"
+  STOP
+```
+
+## Uncommitted Changes Check
+
+```
+BASH: git status --porcelain
+
+IF not empty:
+  SET: {hasUncommittedChanges} = true
+  SET: {modifiedFiles} = parse result
+ELSE:
+  SET: {hasUncommittedChanges} = false
+```
+
+## Timestamp Generation
+
+```bash
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
+```
+
+## UUID Generation
+
+```bash
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
+```