prjct-cli 0.28.1 → 0.28.3

package/templates/agentic/subagent-generation.md

@@ -1,127 +1,287 @@
-# Sub-Agent Generation
+# Sub-Agent Generation (AGENTIC)
 
-Generate Claude Code sub-agents for this project based on detected stack.
+Generate Claude Code sub-agents dynamically based on ACTUAL project analysis.
+
+**CRITICAL**: There are NO hardcoded templates. You MUST analyze the project and GENERATE agents from scratch.
 
 ## Input Context
 
 You have access to:
-- `{analysis}` - repo-summary.md with detected technologies
+- `{analysis}` - repo-analysis.json with detected technologies
 - `{projectPath}` - Path to project root
 - `{projectId}` - Project identifier
+- `{globalPath}` - ~/.prjct-cli/projects/{projectId}
 
 ## Output Location
 
-Write sub-agents to: `{globalPath}/agents/` (global storage, NOT local project)
+Write sub-agents to: `{globalPath}/agents/`
 
 ## Sub-Agent Format (Claude Code)
 
 ```markdown
 ---
 name: agent-name
+agentId: p.agent.{name}
 description: When to use this agent. Include "Use PROACTIVELY" for auto-invocation.
-tools: Read, Write, Glob, Grep, Bash
 model: sonnet
-skills: [skill-name]
+temperature: {0.1-0.4}
+maxSteps: {50-100}
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+permissions:
+  Bash: ask
+  Write: allow
+  Edit: allow
+  "rm *": deny
+skills: [{detected-skill}]
+mcp: [{detected-mcp-servers}]
+projectId: {projectId}
+projectPath: {projectPath}
 ---
 
-Agent system prompt here...
+# {Agent Name}
+
+## Stack Detected
+{ACTUAL technologies found in THIS project}
+
+## Project Structure
+{ACTUAL directory structure for this domain}
+
+## Code Patterns (EXTRACTED FROM PROJECT)
+{REAL patterns found by reading actual files}
+
+## Quality Checklist
+{Based on project conventions}
+
+## Commands
+{ACTUAL commands from package.json/Makefile/etc}
 ```
 
-**The `skills` field links the agent to Claude Code skills from claude-plugins.dev.**
+---
+
+## Generation Process (AGENTIC)
 
-## Generation Rules
+### Step 1: Analyze Project Deeply
 
-### 1. ALWAYS Generate Workflow Agents
+DO NOT use templates. Instead:
+
+```
+1. READ package.json, go.mod, Cargo.toml, requirements.txt, etc.
+2. GLOB for source files: **/*.ts, **/*.tsx, **/*.py, **/*.go, etc.
+3. READ 3-5 representative files from each domain
+4. EXTRACT actual patterns, conventions, naming
+5. CHECK for linter/formatter configs
+```
+
+### Step 2: Determine Domains Present
+
+Based on your analysis, identify which domains exist:
+
+| Domain | Detection Method |
+|--------|------------------|
+| frontend | React/Vue/Angular/Svelte in deps, .tsx/.vue files |
+| backend | Express/Fastify/Hono/Gin/Flask in deps, API routes |
+| database | Prisma/Drizzle/TypeORM schemas, SQL files |
+| testing | Jest/Vitest/Pytest configs, *.test.* files |
+| devops | Dockerfile, .github/workflows, k8s/ |
+| uxui | UI components + design tokens/theme |
+| mobile | React Native/Flutter/SwiftUI |
+| cli | Command definitions, arg parsing |
+| ml | Model files, training scripts |
+
+### Step 3: Generate Each Agent FROM SCRATCH
+
+For EACH detected domain:
+
+1. **Analyze domain-specific files**
+   ```
+   READ actual source files in that domain
+   EXTRACT: imports, exports, naming, structure
+   ```
 
-These are REQUIRED for every prjct project:
+2. **Determine configuration**
+   - `temperature`: 0.1 for DB, 0.2 for backend/testing, 0.3 for frontend, 0.4 for uxui
+   - `maxSteps`: 50 for simple, 75 for medium, 100 for complex
+   - `tools`: Based on what the domain needs
+   - `permissions`: Deny destructive commands
+
+3. **Discover skills and MCP**
+   - Search claude-plugins.dev for relevant skills
+   - Determine if context7 MCP is needed (library docs)
+
+4. **Write agent with REAL patterns**
+   ```
+   Include ACTUAL code examples from the project
+   Include ACTUAL commands from package.json
+   Include ACTUAL file structure
+   ```
+
+### Step 4: Generate Workflow Agents (ALWAYS)
+
+These 3 agents are always generated but STILL need project context:
 
 #### prjct-workflow.md
 - Commands: /p:now, /p:done, /p:next, /p:pause, /p:resume
-- Tools: Read, Write, Glob
-- Purpose: Task lifecycle management
+- Adapt with: project paths, detected commands
 
 #### prjct-planner.md
 - Commands: /p:feature, /p:idea, /p:spec, /p:bug
-- Tools: Read, Write, Glob, Grep
-- Purpose: Feature planning and breakdown
+- Adapt with: detected stack for planning context
 
 #### prjct-shipper.md
 - Commands: /p:ship
-- Tools: Read, Write, Bash, Glob
-- Purpose: Git operations, testing, deployment
+- Adapt with: actual test/build/lint commands from project
 
-### 2. Generate Domain Agents Based on Stack
+---
 
-Analyze `{analysis}` and create ONLY relevant domain agents:
+## MCP Integration
 
-| If Detected | Generate | Tools | Skill |
-|-------------|----------|-------|-------|
-| React, Vue, Angular, Svelte, CSS, HTML | `frontend.md` | Read, Write, Glob, Grep | `frontend-design` |
-| Node.js, Express, Go, Python API, REST, GraphQL | `backend.md` | Read, Write, Bash, Glob, Grep | `javascript-typescript` or `python-development` |
-| PostgreSQL, MySQL, MongoDB, Redis, Prisma | `database.md` | Read, Write, Bash | (none) |
-| Docker, Kubernetes, CI/CD, GitHub Actions | `devops.md` | Read, Bash, Glob | `developer-kit` |
-| Bun test, Jest, Pytest, Testing Library | `testing.md` | Read, Write, Bash | `developer-kit` |
-| ANY frontend UI (web or mobile) | `uxui.md` | Read, Write, Glob, Grep | `frontend-design` |
+Determine which agents need MCP servers:
 
-### 3. Adapt to Project Context
+```
+IF agent works with libraries/frameworks:
+  ADD mcp: [context7]
 
-Each generated agent should include:
-- Project-specific paths from analysis
-- Detected frameworks and versions
-- Relevant patterns found in codebase
+Agents that typically need context7:
+- frontend (React, Vue docs)
+- backend (Express, Hono docs)
+- database (Prisma, Drizzle docs)
+- uxui (component library docs)
+- prjct-planner (framework docs for planning)
+```
 
-## Execution Steps
+---
 
-1. **Read Analysis**
-   ```
-   Read("{globalPath}/analysis/repo-summary.md")
-   ```
+## Skill Discovery
 
-2. **Create Directory**
-   ```
-   Bash("mkdir -p {globalPath}/agents")
-   ```
+For each agent, search for relevant skills:
 
-3. **Generate Workflow Agents** (always)
-   - Read template from `templates/subagents/workflow/prjct-workflow.md`
-   - Adapt with project context
-   - Write to `{globalPath}/agents/prjct-workflow.md`
-   - Repeat for prjct-planner.md and prjct-shipper.md
-
-4. **Generate Domain Agents** (based on analysis)
-   - For each detected technology stack:
-     - Read corresponding template from `templates/subagents/domain/`
-     - Adapt with project-specific details
-     - Write to `{globalPath}/agents/`
-
-5. **Link Skills to Agents**
-   - Read `templates/config/skill-mappings.json`
-   - For each generated agent, add the corresponding skill to frontmatter
-   - Skill mappings:
-     - `frontend.md` → `skills: [frontend-design]`
-     - `uxui.md` → `skills: [frontend-design]`
-     - `backend.md` → `skills: [javascript-typescript]` (or `python-development` for Python)
-     - `testing.md` → `skills: [developer-kit]`
-     - `devops.md` → `skills: [developer-kit]`
-     - `prjct-planner.md` → `skills: [feature-dev]`
-     - `prjct-shipper.md` → `skills: [code-review]`
-
-6. **Report Generated Agents**
-   ```
-   Generated sub-agents in {globalPath}/agents/:
-   - prjct-workflow.md (workflow)
-   - prjct-planner.md (workflow) → /feature-dev
-   - prjct-shipper.md (workflow) → /code-review
-   - frontend.md (detected: React) → /frontend-design
-   - backend.md (detected: Node.js) → /javascript-typescript
-   ```
+```
+WebFetch: https://claude-plugins.dev/skills?q={domain}+{stack}
+
+Examples:
+- frontend + React → search "react frontend"
+- backend + TypeScript → search "typescript backend"
+- testing + Bun → search "bun testing"
+```
+
+If no skill found, leave skills empty or create minimal custom skill.
+
+---
+
+## Output Format
+
+After generating each agent:
+
+```
+Generated: {agent}.md
+  Stack: {detected technologies}
+  Patterns: {count} extracted from {files analyzed}
+  Skills: {linked skills}
+  MCP: {linked mcp servers}
+  Path: {globalPath}/agents/{agent}.md
+```
+
+---
+
+## Critical Rules
+
+1. **NO TEMPLATES** - Generate everything from project analysis
+2. **NO HARDCODING** - Every value comes from detection
+3. **REAL PATTERNS** - Include actual code examples from the project
+4. **ACTUAL COMMANDS** - Use real commands from package.json/Makefile
+5. **PROJECT-SPECIFIC** - Each agent is unique to this project
+6. **GLOBAL STORAGE** - Write to `{globalPath}/agents/`, never local
+
+---
+
+## Example: Generated Backend Agent
+
+This is an EXAMPLE of what a generated agent might look like (NOT a template to copy):
+
+```markdown
+---
+name: backend
+agentId: p.agent.backend
+description: Backend specialist for Hono + Bun. Use PROACTIVELY for API routes and server logic.
+model: sonnet
+temperature: 0.2
+maxSteps: 75
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+permissions:
+  Bash: ask
+  Write: allow
+  Edit: allow
+  "rm *": deny
+skills: [javascript-typescript]
+mcp: [context7]
+projectId: abc123
+projectPath: /Users/dev/my-project
+---
+
+# Backend Agent for my-project
+
+## Stack Detected
+- Runtime: Bun 1.0
+- Framework: Hono 4.x
+- Validation: Zod
+- Database: Drizzle + SQLite
+
+## Project Structure
+```
+core/
+├── routes/       # API endpoints
+├── services/     # Business logic
+├── middleware/   # Auth, logging
+└── types/        # TypeScript types
+```
+
+## Code Patterns (FROM THIS PROJECT)
+
+### Route Structure
+```typescript
+// Extracted from core/routes/users.ts
+app.get('/users/:id', async (c) => {
+  const { id } = c.req.param()
+  const user = await userService.findById(id)
+  return c.json(user)
+})
+```
+
+### Error Handling
+```typescript
+// Extracted from core/middleware/error.ts
+app.onError((err, c) => {
+  console.error(err)
+  return c.json({ error: err.message }, 500)
+})
+```
+
+## Commands
+
+| Action | Command |
+|--------|---------|
+| Dev | `bun run dev` |
+| Test | `bun test` |
+| Build | `bun run build` |
+| Lint | `bun run lint` |
 
 ## Critical Rules
+- Use Hono's context (c) pattern
+- Validate with Zod before processing
+- Return proper HTTP status codes
+- Use existing service layer pattern
+```
 
-- **NEVER write agents to local project directories** (`.claude/`, `.prjct/`)
-- **ALWAYS write agents to `{globalPath}/agents/`** (global storage)
-- NEVER hardcode technology detection in TypeScript
-- ALWAYS read and analyze repo-summary.md
-- ADAPT templates to project context
-- Use Claude Code frontmatter format exactly
-- Include "Use PROACTIVELY" in descriptions for auto-invocation
+This agent was GENERATED by analyzing the actual project, not copied from a template.

package/templates/commands/init.md

@@ -136,45 +136,6 @@ WRITE: `.prjct/prjct.config.json`
 }
 ```
 
-## Step: Optional Integrations
-
-After core setup, offer optional integrations.
-
-### Notion Integration (Optional)
-
-Ask: "Would you like to connect with Notion for dashboards and progress tracking?"
-
-If yes:
-1. Guide user to create Notion integration at https://www.notion.so/my-integrations
-2. Ask for API token (starts with `ntn_`)
-3. Ask for parent page ID (where to create databases)
-4. Create 4 databases:
-   - prjct: Shipped Features
-   - prjct: Roadmap
-   - prjct: Ideas
-   - prjct: Active Tasks
-5. Store config in `project.json`:
-
-```json
-{
-  "integrations": {
-    "notion": {
-      "enabled": true,
-      "workspaceName": "{workspace}",
-      "databases": {
-        "shipped": "{dbId}",
-        "roadmap": "{dbId}",
-        "ideas": "{dbId}",
-        "tasks": "{dbId}"
-      },
-      "syncOn": { "ship": true, "idea": true }
-    }
-  }
-}
-```
-
-If no: Skip and continue (integration can be added later with `/p:notion setup`).
-
 ## Response
 
 ```
@@ -189,13 +150,9 @@ Structure:
 ├── sync/       # Backend events
 └── agents/     # Specialists
 
-Integrations:
-• Notion: {enabled|disabled}
-
 Next:
 • /p:sync - Analyze project and generate agents
-• /p:feature "{first_feature}" - Start first feature
-• /p:notion setup - Connect Notion (if skipped)
+• /p:task "{first_task}" - Start first task
 • /p:help - See all commands
 ```
 

package/templates/commands/ship.md

@@ -1,6 +1,7 @@
 ---
 allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
 description: 'Ship feature with automated PR workflow'
+requires-thinking: true
 tool-permissions:
   bash:
     allow: ["git status", "git log", "git diff", "git add", "git commit", "git push", "gh pr create", "gh pr view", "npm test", "npm run", "bun test", "bun run"]
@@ -12,6 +13,18 @@ tool-permissions:
 
 Ship completed work with pre-flight checks, code review, PR creation, and CI verification.
 
+## Pre-Ship Think Block (MANDATORY)
+
+**Use `<think>` to verify before ANY ship action:**
+
+<think>
+- [ ] All subtasks complete? No TODO/FIXME left?
+- [ ] Tests + lint pass? No debug statements or secrets?
+- [ ] On feature branch (not main)? All changes committed?
+- [ ] Breaking changes documented? Migrations ready?
+If ANY fails → STOP and fix first.
+</think>
+
 ## Usage
 ```
 /p:ship [feature] [--blocking] [--skip-review] [--draft]
@@ -219,21 +232,96 @@ IF {issues}.length > 0:
 ELSE:
   OUTPUT: "Code review passed. No high-confidence issues found."
 
-### Step 5: Version Bump
-READ: `package.json` (or Cargo.toml, pyproject.toml)
-EXTRACT: current version
+### Step 5: Version Bump (REQUIRED)
+
+**CRITICAL: Version MUST be bumped before creating PR.**
+
+#### 5.1 Read current version
+READ: `package.json` (or Cargo.toml, pyproject.toml, version.txt)
+EXTRACT: {currentVersion}
+
+#### 5.2 Determine bump type from commits
+BASH: `git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~20")..HEAD`
+ANALYZE commits:
+- "BREAKING" or "major:" → major bump
+- "feat:" or "feature:" → minor bump
+- else → patch bump
+
+SET: {bumpType} = detected type
+SET: {newVersion} = calculated version
+
+#### 5.3 Update version file
+UPDATE version in package.json (or equivalent):
+```bash
+# For Node.js projects
+npm version {bumpType} --no-git-tag-version
+```
+
+IF version update fails:
+  OUTPUT: "❌ Failed to update version. Fix manually and retry."
+  STOP
+
+OUTPUT: "📦 Version: {currentVersion} → {newVersion}"
+
+### Step 6: Update CHANGELOG (REQUIRED)
+
+**CRITICAL: CHANGELOG.md MUST be updated before creating PR.**
+
+#### 6.1 Check if CHANGELOG exists
+BASH: `test -f CHANGELOG.md && echo "exists" || echo "missing"`
 
-BASH: `git log --oneline -10`
-Determine bump type:
-- "BREAKING" or "major:" → major
-- "feat:" or "feature:" → minor
-- else → patch
+IF missing:
+  CREATE `CHANGELOG.md` with header:
+  ```markdown
+  # Changelog
 
-UPDATE version file with new version
+  All notable changes to this project will be documented in this file.
 
-### Step 6: Update CHANGELOG
-BASH: `git log --oneline -20 --pretty=format:"- %s"`
-INSERT new entry in CHANGELOG.md
+  ## [Unreleased]
+
+  ## [{newVersion}] - {date}
+  ```
+
+#### 6.2 Get commits since last tag
+BASH: `git log --oneline --pretty=format:"- %s" $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~20")..HEAD`
+SET: {commits} = result
+
+#### 6.3 Categorize changes
+PARSE commits and categorize:
+- `feat:` → ### Added
+- `fix:` → ### Fixed
+- `refactor:` → ### Changed
+- `docs:` → ### Documentation
+- `perf:` → ### Performance
+- `BREAKING:` → ### Breaking Changes
+
+#### 6.4 Insert changelog entry
+GET date: `date +%Y-%m-%d`
+SET: {today} = result
+
+INSERT after `## [Unreleased]` in CHANGELOG.md:
+```markdown
+
+## [{newVersion}] - {today}
+
+### Added
+{feat commits}
+
+### Fixed
+{fix commits}
+
+### Changed
+{other commits}
+```
+
+OUTPUT: "📝 CHANGELOG.md updated for v{newVersion}"
+
+#### 6.5 Verify changes are staged
+BASH: `git add package.json CHANGELOG.md`
+
+IF no changes staged:
+  OUTPUT: "❌ Version or CHANGELOG not updated. Cannot ship."
+  STOP
 
 ### Step 7: Create Pull Request
 
@@ -580,76 +668,13 @@ Check CI status on GitHub.
 
 ## Examples
 
-### Example 1: Successful Ship with PR
 ```
-/p:ship "add user auth"
-
-Pre-flight: Medium changes (87 lines in 5 files)
-Quality: Lint ✅ | Tests ✅
-Review: Passed
-
-📎 PR created: https://github.com/user/repo/pull/42
-Waiting for CI checks...
-⏳ Waiting for 3 CI checks...
-✅ All CI checks passed
-
-🚀 PR Ready: add user auth
-
-Version: 1.2.0 → 1.3.0
-Changes: medium (87 lines in 5 files)
-Quality: Lint ✅ | Tests ✅
-CI: ✅ Passed
-
-📎 PR: https://github.com/user/repo/pull/42
-
-Next steps:
-1. Request review from team
-2. Merge when approved
-```
-
-### Example 2: Ship with CI Failure
-```
-/p:ship "fix login bug"
-
-Pre-flight: Small changes (28 lines in 2 files)
-Quality: Lint ✅ | Tests ✅
-Review: Passed
-
-📎 PR created: https://github.com/user/repo/pull/43
-Waiting for CI checks...
-
-❌ CI checks failed:
-- build: failure
-- test: failure
-
-⚠️ PR Created (CI Failed): fix login bug
-
-📎 PR: https://github.com/user/repo/pull/43
-
-Fix CI issues and push again.
-```
-
-### Example 3: Blocked on Protected Branch
-```
-/p:ship "new feature"
-
-⚠️ Cannot ship from protected branch: main
-
-Create a feature branch first with /p:now "task name"
-```
-
-### Example 4: Draft PR
-```
-/p:ship "work in progress" --draft
-
-📎 PR created (draft): https://github.com/user/repo/pull/44
-
-🚀 PR Created: work in progress
-CI: ⏳ Still running
-
-📎 PR: https://github.com/user/repo/pull/44
+/p:ship "add auth"     → 🚀 v1.2.0→1.3.0 | PR: .../pull/42 | CI ✅
+/p:ship "fix bug"      → ⚠️ PR created, CI ❌ - fix and push
+/p:ship --draft        → 📎 Draft PR created
+/p:ship (on main)      → ⚠️ Cannot ship from protected branch
 ```
 
 ## References
-- Architecture details: `~/.prjct-cli/docs/architecture.md`
-- Validation patterns: `~/.prjct-cli/docs/validation.md`
+- Architecture: `~/.prjct-cli/docs/architecture.md`
+- Validation: `templates/shared/validation.md`