prjct-cli 0.28.1 → 0.28.3

package/templates/commands/task.md

@@ -219,44 +219,27 @@ If anything is unclear, use AskUserQuestion.
 If everything is clear, say so and continue.
 
 ### Phase 4: Design
-Load relevant agents from `{globalPath}/agents/` and their linked skills:
 
-**Agent + Skill Loading:**
+**Load agents + auto-invoke skills + query MCP docs.**
+
+See `templates/guides/integrations.md` for skill/MCP details.
+
 ```
-FOR EACH relevant agent in {globalPath}/agents/:
-  READ agent file
-  PARSE frontmatter → get `skills` array
-
-  IF skills exist:
-    FOR EACH skill in skills:
-      Invoke Skill(skill) for domain expertise
-      OUTPUT: "📚 {agent} using /{skill}"
+FOR EACH relevant agent:
+  1. READ: {globalPath}/agents/{domain}.md
+  2. PARSE frontmatter → skills, mcp
+  3. FOR skill in frontmatter.skills: Invoke Skill(skill) → "🎯 Activated"
+  4. FOR mcp in frontmatter.mcp: Query context7 for docs → "📚 Loaded"
 ```
 
-**Example flow for UI feature:**
-1. Load `uxui.md` agent (has `skills: [frontend-design]`)
-2. Invoke `/frontend-design` skill
-3. Skill provides anti-AI-slop patterns, typography guidelines
-4. Agent applies them to design options
-
-Propose 2-3 approaches:
+**Propose 2-3 options** using skill context + library docs:
 
 ```
 ### Option 1: Minimal
-- Approach: {desc}
-- Files: {count}
-- Pros/Cons: ...
-
-### Option 2: Clean Architecture
-- Approach: {desc}
-- Files: {count}
-- Pros/Cons: ...
-
-### Option 3: Recommended (Skill-informed)
-- Approach: {desc}
-- Files: {count}
-- Pros/Cons: ...
-- Skills applied: {skills}
+- Files: {count}, Pros/Cons: ...
+
+### Option 2: Recommended (Skill-informed)
+- Files: {count}, Skills applied: {skills}
 ```
 
 Use AskUserQuestion to get approval.

package/templates/global/CLAUDE.md

@@ -5,19 +5,155 @@
 
 ## HOW TO USE PRJCT (Read This First)
 
-When user types `p. <command>`, load the template from `templates/commands/{command}.md` and execute it intelligently.
+When user types `p. <command>`, resolve the command in this order:
+
+### Command Resolution Order
+
+1. **Quick Commands (User-defined)**: `~/.prjct-cli/commands/{command}.md`
+2. **Built-in Commands**: `templates/commands/{command}.md`
 
 ```
-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. sync     → templates/commands/sync.md (built-in)
+p. task X   → templates/commands/task.md (built-in)
+p. deploy   → ~/.prjct-cli/commands/deploy.md (user quick command)
+p. test     → ~/.prjct-cli/commands/test.md (user quick command)
 ```
 
 **Key Insight**: Templates are GUIDANCE, not scripts. Use your intelligence to adapt them to the situation.
 
 ---
 
+## QUICK COMMANDS (User-Defined)
+
+Users can create custom commands in `~/.prjct-cli/commands/`. These are checked FIRST before built-in commands.
+
+### Command Format (Full)
+
+```yaml
+---
+# Required
+description: Brief explanation shown in help
+
+# Optional - Execution control
+agent: {agent-name}              # Which agent executes (e.g., "testing", "frontend")
+model: sonnet                    # Override model (sonnet | opus | haiku)
+temperature: 0.3                 # Override temperature (0.0-1.0)
+
+# Optional - Permissions for this command
+permissions:
+  Bash: allow                    # Override default permissions
+  "npm *": allow
+---
+
+{Prompt template with variables and shell injection}
+```
+
+### Variable Substitution
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `$ARGUMENTS` | All arguments concatenated | `p. test src/` → "src/" |
+| `$1`, `$2`, `$3`... | Positional arguments | `p. diff main dev` → $1="main", $2="dev" |
+
+### Shell Injection
+
+Use `` !`command` `` to embed shell output:
+
+```yaml
+---
+description: Review current branch changes
+---
+
+# Branch: !`git branch --show-current`
+
+## Recent Commits
+!`git log --oneline -5`
+
+## Changed Files
+!`git diff --name-only`
+
+Review these changes for:
+- Code quality issues
+- Security vulnerabilities
+- Missing tests
+```
+
+### File References
+
+Use `@filepath` to include file contents:
+
+```yaml
+---
+description: Review a specific component
+---
+
+Review the component in @$1 for:
+- Performance issues
+- Accessibility
+- Best practices
+
+Suggest improvements.
+```
+
+### Example Commands
+
+**~/.prjct-cli/commands/test.md**
+```yaml
+---
+description: Run and fix tests
+agent: testing
+permissions:
+  Bash: allow
+---
+
+Run tests for $ARGUMENTS. If any fail, analyze and fix them.
+
+Current test status:
+!`{project test command} --reporter=dot 2>&1 | tail -20`
+```
+
+**~/.prjct-cli/commands/pr.md**
+```yaml
+---
+description: Create PR with AI-generated description
+permissions:
+  Bash:
+    "git *": allow
+    "gh *": allow
+---
+
+Create a pull request for branch !`git branch --show-current`.
+
+Changes since main:
+!`git log main..HEAD --oneline`
+
+Files changed:
+!`git diff --stat main`
+
+Generate a descriptive PR title and body based on these changes.
+```
+
+**~/.prjct-cli/commands/component.md**
+```yaml
+---
+description: Create a new React component
+agent: frontend
+---
+
+Create a new React component named $1 in the appropriate directory.
+
+Follow existing patterns from:
+@src/components/Button.tsx
+
+Match the project's:
+- File structure
+- Naming conventions
+- Styling approach
+- Type patterns
+```
+
+---
+
 ## CRITICAL RULES
 
 ### 1. Path Resolution (MOST IMPORTANT)
@@ -181,52 +317,47 @@ These agents contain project-specific patterns. **USE THEM**.
 
 ---
 
-## SKILL INTEGRATION (NEW in v0.27 - AGENTIC)
+## INTEGRATIONS (v0.27+)
 
-Agents are linked to Claude Code skills from claude-plugins.dev.
+Skills and MCP servers are auto-configured during `/p:sync`.
 
-**Skills are discovered AGENTICALLY** - Claude searches the marketplace dynamically.
+**See:** `templates/guides/integrations.md` for complete documentation.
 
-### How Skills Work
+### Quick Reference
 
-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
+| Feature | What Happens |
+|---------|--------------|
+| **Skills** | Auto-invoked when agent loads (`skills: [skill-name]`) |
+| **MCP** | Auto-queried for library docs (`mcp: [context7]`) |
 
-### Agentic Discovery Process
+### Pipeline
 
 ```
-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
+Load Agent → Invoke Skills → Query MCP → Execute with Context
 ```
 
-### 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" |
+## CLAUDE CODE SYNERGY
 
-### Skill Location
+prjct is designed to maximize Claude Code's capabilities:
 
-Skills are markdown files in `~/.claude/skills/`
+### Slash Commands
+All `/p:*` commands are optimized for Claude Code execution.
 
-### Skill Configuration
+### Agent System
+Domain agents (`frontend.md`, `backend.md`, etc.) integrate with Claude's Task tool.
+
+### Skill + MCP Pipeline
+```
+Task → Load Agent → Invoke Skills → Query MCP → Execute with Full Context
+```
 
-After sync: `{globalPath}/config/skills.json` contains discovered mappings.
+### Think Blocks
+Destructive commands (`/p:ship`, `/p:cleanup`) use `<think>` blocks for verification.
 
 ---
 
-**Auto-managed by prjct-cli** | https://prjct.app | v0.27.0
+**Auto-managed by 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
+```

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,55 +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"
-    },
-    "notion": {
-      "command": "npx",
-      "args": ["-y", "@notionhq/notion-mcp-server"],
-      "env": {
-        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ${NOTION_TOKEN}\", \"Notion-Version\": \"2022-06-28\"}"
-      },
-      "description": "Notion integration for prjct dashboards and progress tracking (optional)"
-    }
-  },
-  "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')"
-      ]
-    },
-    "notion": {
-      "when": [
-        "Syncing shipped features to Notion (auto on /p:ship)",
-        "Syncing ideas to Notion (auto on /p:idea)",
-        "Creating prjct databases during /p:init",
-        "Manual sync with /p:notion sync"
-      ],
-      "tools": [
-        "notion_create_database: Create a new database",
-        "notion_create_page: Create a page in a database",
-        "notion_update_page: Update an existing page",
-        "notion_query_database: Query database entries"
-      ],
-      "setup": [
-        "1. Create integration at https://www.notion.so/my-integrations",
-        "2. Set NOTION_TOKEN environment variable",
-        "3. Share a parent page with the integration",
-        "4. Run /p:notion setup to create databases"
+        "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."
 }