prjct-cli 0.28.2 → 0.28.4

package/templates/global/CLAUDE.md

@@ -1,232 +1,172 @@
 <!-- prjct:start - DO NOT REMOVE THIS MARKER -->
 # prjct-cli
 
-**Developer momentum tool** - Track progress through natural language commands without PM overhead.
+**Developer momentum tool** - Track progress through natural language commands.
 
-## HOW TO USE PRJCT (Read This First)
-
-When user types `p. <command>`, load the template from `templates/commands/{command}.md` and execute it intelligently.
+## Command Resolution
 
 ```
-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
+p. <command> → 1. ~/.prjct-cli/commands/{command}.md (user)
+             → 2. templates/commands/{command}.md (built-in)
 ```
 
-**Key Insight**: Templates are GUIDANCE, not scripts. Use your intelligence to adapt them to the situation.
+Templates are GUIDANCE, not scripts. Adapt to the situation.
 
 ---
 
-## CRITICAL RULES
+## Quick Commands (User-Defined)
 
-### 1. Path Resolution (MOST IMPORTANT)
-**ALL writes go to global storage**: `~/.prjct-cli/projects/{projectId}/`
+Create custom commands in `~/.prjct-cli/commands/`:
 
-- **NEVER** write to `.prjct/` (config only, read-only)
-- **NEVER** write to `./` (current directory)
-- **ALWAYS** resolve projectId first from `.prjct/prjct.config.json`
+```yaml
+---
+description: Brief explanation
+agent: testing          # Optional: which agent
+model: sonnet           # Optional: sonnet | opus | haiku
+---
 
-### 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
+{Prompt with $ARGUMENTS, $1, $2...}
+!`shell command`        # Shell injection
+@filepath               # File inclusion
 ```
 
-### 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())"
-```
+---
 
-### 4. Git Commit Footer (CRITICAL - ALWAYS INCLUDE)
+## Critical Rules
 
-**Every commit made with prjct MUST include this footer:**
+### Path Resolution
+**ALL writes**: `~/.prjct-cli/projects/{projectId}/`
+- NEVER write to `.prjct/` (read-only config)
+- NEVER write to `./` for prjct data
 
+### Before Any Command
+```
+1. Read .prjct/prjct.config.json → projectId
+2. globalPath = ~/.prjct-cli/projects/{projectId}
+3. Execute using globalPath for writes
 ```
-🤖 Generated with [p/](https://www.prjct.app/)
-Designed for [Claude](https://www.anthropic.com/claude)
 
+### Timestamps & UUIDs
+```bash
+node -e "console.log(new Date().toISOString())"
+node -e "console.log(require('crypto').randomUUID())"
 ```
 
-**This is NON-NEGOTIABLE. The prjct signature (`🤖 Generated with [p/]`) must appear in ALL commits.**
+### Git Commit Footer (REQUIRED)
+```
+🤖 Generated with [p/](https://www.prjct.app/)
+```
 
 ---
 
-## CORE WORKFLOW
+## 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 ───┘
+p. sync → p. task "desc" → [work] → p. done → p. ship
 ```
 
-### 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 |
+| Command | Action |
+|---------|--------|
+| `p. sync` | Analyze project, generate agents |
+| `p. task` | Start task with classification |
+| `p. done` | Complete subtask |
+| `p. ship` | Ship with PR + version bump |
+| `p. bug` | Report bug with auto-priority |
 
 ---
 
-## ARCHITECTURE: Write-Through Pattern
+## Architecture
 
 ```
-User Action → Storage (JSON) → Context (MD) → Sync Events
+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
+├── storage/     # state.json, queue.json (SOURCE OF TRUTH)
+├── context/     # now.md, next.md (generated)
+├── agents/      # Domain specialists
+├── memory/      # events.jsonl
+└── sync/        # pending.json
 ```
 
 ---
 
-## 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
+## Intelligent Behavior
+
+| Action | Steps |
+|--------|-------|
+| `p. task` | Analyze → Classify → Explore → Ask → Design → Breakdown |
+| `p. done` | Check subtasks → Advance/Complete → Update storage |
+| `p. ship` | Tests → PR → Version bump → CHANGELOG → Tag |
+
+**Rules:**
+- Read before write
+- Use Task(Explore) before coding
+- AskUserQuestion when uncertain
+- Log to memory/events.jsonl
 
 ---
 
-## OUTPUT FORMAT
+## Domain Agents
 
-Concise responses (< 4 lines):
-```
-✅ [What was done]
+Load from `{globalPath}/agents/`:
+- `frontend.md`, `backend.md`, `database.md`
+- `uxui.md`, `testing.md`, `devops.md`
 
-[Key metrics]
-Next: [suggested action]
-```
+Agents contain project-specific patterns. **USE THEM**.
 
 ---
 
-## LOADING DOMAIN AGENTS
+## Output Format
 
-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
+```
+✅ [Action]
+[Metrics]
+Next: [suggestion]
+```
 
-These agents contain project-specific patterns. **USE THEM**.
+Keep output < 4 lines.
 
 ---
 
-## SKILL INTEGRATION (NEW in v0.27 - AGENTIC)
-
-Agents are linked to Claude Code skills from claude-plugins.dev.
+## Claude Code UX Enhancements
 
-**Skills are discovered AGENTICALLY** - Claude searches the marketplace dynamically.
+### Status Line
 
-### How Skills Work
+prjct provides a custom status line showing:
+- ⚡ Current prjct task
+-  Git branch with dirty indicator
+- +/- Lines changed this session
+- Context usage bar
+- Model icon (🎭/📝/🍃)
 
-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
+**Setup:** `p. setup-statusline`
 
-### 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
-```
+### Themes
 
-### Search Terms by Agent
+Available at `~/.prjct-cli/statusline/themes/`:
+- `default.json` - prjct brand (cyan/purple)
+- `gentleman.json` - Elegant blues/golds
+- `minimal.json` - Clean grayscale
 
-| 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" |
+### Output Styles
 
-### Skill Location
+Available at `~/.prjct-cli/output-styles/`:
+- `prjct.md` - Concise, actionable (default)
+- `verbose.md` - Detailed explanations
+- `ship-fast.md` - Minimum output, max velocity
 
-Skills are markdown files in `~/.claude/skills/`
+**Use:** `/output-style prjct`
 
-### Skill Configuration
+### Hooks
 
-After sync: `{globalPath}/config/skills.json` contains discovered mappings.
+Metrics tracked automatically:
+- `update-metrics.sh` - Tracks tool usage
+- `session-summary.sh` - Shows session stats on stop
 
 ---
 
-**Auto-managed by prjct-cli** | https://prjct.app | v0.27.0
+**prjct-cli** | https://prjct.app | v0.28.3
 
 <!-- prjct:end - DO NOT REMOVE THIS MARKER -->

package/templates/guides/agent-generation.md

@@ -0,0 +1,164 @@
+# Agent Generation Guide
+
+Complete guide for generating domain-specific agents. Referenced by `/p:sync`.
+
+## Overview
+
+Agents are generated from **REAL analysis** of the repository, not templates. You must:
+1. **ANALYZE** the actual codebase deeply
+2. **EXTRACT** real patterns, conventions, and examples
+3. **GENERATE** agents that enforce those exact patterns
+
+---
+
+## Step 1: Find Representative Files
+
+```bash
+# Frontend: Component files
+find . -type f \( -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" \) -not -path "*/node_modules/*" | head -10
+
+# Backend: API/route files
+find . -type f -name "*.ts" -path "*/api/*" -o -path "*/routes/*" | head -10
+
+# Database: Schema/model files
+find . -type f \( -name "schema.prisma" -o -name "*.model.ts" \) | head -5
+
+# Tests: Test files
+find . -type f \( -name "*.test.ts" -o -name "*.spec.ts" \) | head -10
+```
+
+---
+
+## Step 2: Analyze Actual Code
+
+```
+FOR EACH domain detected:
+  1. READ 3-5 representative files
+  2. EXTRACT patterns:
+     - File structure
+     - Naming conventions
+     - Import patterns
+     - Code style
+     - Architecture patterns
+     - Error handling
+     - Type patterns
+  3. IDENTIFY project-specific conventions
+```
+
+Check existing style guides:
+```bash
+ls -la .eslintrc* .prettierrc* tsconfig.json biome.json 2>/dev/null
+```
+
+---
+
+## Step 3: Agent Frontmatter Format
+
+```yaml
+---
+name: {domain}
+agentId: p.agent.{domain}
+description: {Domain} specialist for {stack}. Use PROACTIVELY for {triggers}.
+model: sonnet
+temperature: {0.0-1.0}
+maxSteps: {50-100}
+tools:
+  Read: true
+  Write: true
+  Edit: true
+  Bash: true
+  Glob: true
+  Grep: true
+permissions:
+  Read: allow
+  Write: allow
+  Edit: allow
+  Bash:
+    "git *": allow
+    "{test command}": allow
+    "rm -rf *": deny
+skills: [{detected-skill}]
+mcp: [{detected-mcp}]
+generatedAt: {timestamp}
+---
+```
+
+---
+
+## Step 4: Agent Body Structure
+
+```markdown
+# {Domain} Agent for {ProjectName}
+
+## Stack Detected
+{List EXACT technologies: "React 18, TypeScript 5.3, Tailwind 3.4"}
+
+## Project Structure
+{ACTUAL directory structure}
+
+## Code Patterns (MUST FOLLOW)
+
+### File Naming
+{EXACT convention: "PascalCase for components"}
+
+### Component/Module Structure
+{ACTUAL example from codebase}
+
+### Import Patterns
+{ACTUAL import style}
+
+### Error Handling
+{ACTUAL error pattern}
+
+## Quality Checklist
+- [ ] Follows naming convention
+- [ ] Uses correct import style
+- [ ] Matches existing structure
+
+## Commands
+| Action | Command |
+|--------|---------|
+| Dev | `{actual command}` |
+| Test | `{actual command}` |
+```
+
+---
+
+## Configuration Values
+
+**Temperature** (by domain):
+- `0.1` - Database, migrations (precise)
+- `0.2` - Backend, testing (deterministic)
+- `0.3` - Frontend (some creativity)
+- `0.4` - UX/UI (creative)
+
+**maxSteps** (by complexity):
+- `50` - Single file changes
+- `75` - Multi-file features
+- `100` - Complex refactors
+
+---
+
+## Domain Detection Table
+
+| If You Find | Generate | Key Files |
+|-------------|----------|-----------|
+| React/Vue/Svelte | `frontend.md` | Components, hooks |
+| Express/Fastify/Hono | `backend.md` | Routes, services |
+| Prisma/Drizzle/SQL | `database.md` | Schema, migrations |
+| Docker/K8s/Actions | `devops.md` | Dockerfile, workflows |
+| Jest/Vitest/Pytest | `testing.md` | Test files |
+| UI + design system | `uxui.md` | Design tokens |
+
+Generate agents for **any domain present** - not limited to this list.
+
+---
+
+## Output Format
+
+```
+🤖 Generated: {agent}.md
+   Stack: {technologies}
+   Patterns: {count} from {files}
+   Path: {globalPath}/agents/{agent}.md
+```