prjct-cli 0.28.0 → 0.28.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "description": "Built for Claude - Ship fast, track progress, stay focused. Developer momentum tool for indie hackers.",
   "main": "core/index.ts",
   "bin": {

package/templates/agentic/subagent-generation.md

@@ -18,16 +18,29 @@ Write sub-agents to: `{globalPath}/agents/` (global storage, NOT local project)
 ```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]
+projectId: {projectId}
+projectPath: {projectPath}
 ---
 
 Agent system prompt here...
 ```
 
-**The `skills` field links the agent to Claude Code skills from claude-plugins.dev.**
+**Required fields:**
+- `agentId`: Unique identifier for mentions. Format: `p.agent.{name}` (e.g., `p.agent.backend`, `p.agent.frontend`)
+- `skills`: Links the agent to Claude Code skills from claude-plugins.dev
+- `projectId`: Links agent to specific project
+- `projectPath`: Path to project root
+
+**Agent ID Convention:**
+- All prjct agents use prefix `p.agent.`
+- The `{name}` is derived from the agent filename without `.md`
+- Examples: `p.agent.backend`, `p.agent.frontend`, `p.agent.workflow`, `p.agent.planner`
+- Users can mention agents in prompts using this ID
 
 ## Generation Rules
 

package/templates/commands/cleanup.md

@@ -1,83 +1,24 @@
 ---
-allowed-tools: [Read, Edit, Write, Bash, Glob, Grep, Task]
-description: 'Deep code cleanup - dead code, comments, docs'
+allowed-tools: [Read, Edit, Bash]
+description: 'Code cleanup'
+tool-permissions:
+  bash:
+    allow: ["git status", "find . -type f", "wc -l"]
+    ask: ["rm *", "git clean"]
+    deny: ["rm -rf /", "rm -rf ~", "rm -rf .", "git reset --hard"]
 ---
 
 # /p:cleanup
 
-Limpieza profunda del código del proyecto.
-
-## Alcance
-
-### 1. Código Muerto
-- Funciones/métodos no usados
-- Variables declaradas sin usar
-- Imports no utilizados
-- Exports sin consumidores
-- Código comentado (bloques `// old code...`)
-- Condicionales siempre true/false
-
-### 2. Comentarios Inútiles
-- `// TODO` sin contexto útil
-- `// fix this` genéricos
-- Comentarios obvios (`// increment i`)
-- Comentarios desactualizados vs código
-- Console.log de debug olvidados
-
-### 3. Documentación
-- Actualizar README si hay cambios estructurales
-- Sincronizar JSDoc/TSDoc con firmas actuales
-- Limpiar docs de funciones eliminadas
+## Types
+- **code**: Remove logs, dead code
+- **imports**: Clean unused
+- **files**: Remove temp/empty
+- **deps**: Find unused
+- **all**: Everything
 
 ## Flow
-
-```
-1. ANALYZE: Escanear codebase con Task(Explore)
-   - Buscar dead code patterns
-   - Identificar comentarios verbose
-
-2. REPORT: Mostrar hallazgos al usuario
-   - Listar archivos afectados
-   - Mostrar qué se eliminará
-
-3. CONFIRM: Pedir confirmación antes de cambios destructivos
-
-4. CLEAN: Aplicar limpieza
-   - Editar archivos uno por uno
-   - Mantener formato/estilo existente
-
-5. VALIDATE: Verificar que el código compila/funciona
-   - Run build si existe
-   - Run tests si existen
-
-6. UPDATE DOCS: Si hay cambios significativos
-   - Actualizar README
-   - Actualizar CHANGELOG si existe
-```
-
-## Comandos
-
-| Variante | Acción |
-|----------|--------|
-| `p. cleanup` | Análisis + reporte (sin cambios) |
-| `p. cleanup fix` | Aplicar limpieza con confirmación |
-| `p. cleanup --force` | Aplicar sin confirmación |
+Parse type → Backup → Clean → Validate → Log
 
 ## Response
-
-```
-🧹 Cleanup Analysis
-
-Dead Code:
-- {file}: {N} unused functions
-- {file}: {N} unused imports
-
-Comments:
-- {file}: {N} debug logs
-- {file}: {N} TODO sin contexto
-
-Docs:
-- README.md: {status}
-
-Total: {N} issues | Run `p. cleanup fix` to apply
-```
+`🧹 Cleaned: {N} logs, {N} dead code, {N} imports | Freed: {X}MB`

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,11 @@
 ---
 allowed-tools: [Read, Write, Bash, Glob, Grep, AskUserQuestion]
 description: 'Ship feature with automated PR workflow'
+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"]
+    ask: ["npm publish", "npm version", "git tag"]
+    deny: ["git push --force", "git reset --hard", "git clean -fd", "rm -rf"]
 ---
 
 # /p:ship - Ship Feature
@@ -214,21 +219,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)
 
-BASH: `git log --oneline -10`
-Determine bump type:
-- "BREAKING" or "major:" → major
-- "feat:" or "feature:" → minor
-- else → patch
+**CRITICAL: Version MUST be bumped before creating PR.**
 
-UPDATE version file with new version
+#### 5.1 Read current version
+READ: `package.json` (or Cargo.toml, pyproject.toml, version.txt)
+EXTRACT: {currentVersion}
 
-### Step 6: Update CHANGELOG
-BASH: `git log --oneline -20 --pretty=format:"- %s"`
-INSERT new entry in CHANGELOG.md
+#### 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"`
+
+IF missing:
+  CREATE `CHANGELOG.md` with header:
+  ```markdown
+  # Changelog
+
+  All notable changes to this project will be documented in this file.
+
+  ## [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
 

package/templates/commands/sync.md

@@ -675,40 +675,48 @@ This template contains:
 
 ### 7.3 Generate Workflow Agents (ALWAYS)
 
-These 3 agents are ALWAYS created for every prjct project:
+These 3 agents are ALWAYS created for every prjct project.
+
+**CRITICAL: Each agent MUST include `agentId` in frontmatter.**
+
+The `agentId` format is: `p.agent.{name}` where `{name}` is derived from filename without `.md`.
 
 **prjct-workflow.md** - Handles: /p:now, /p:done, /p:next, /p:pause, /p:resume
 READ template: `templates/subagents/workflow/prjct-workflow.md`
 ADAPT with: projectId, projectPath
+ADD to frontmatter: `agentId: p.agent.workflow`
 WRITE to: `{globalPath}/agents/prjct-workflow.md`
 
 **prjct-planner.md** - Handles: /p:feature, /p:idea, /p:spec, /p:bug
 READ template: `templates/subagents/workflow/prjct-planner.md`
 ADAPT with: projectId, projectPath
+ADD to frontmatter: `agentId: p.agent.planner`
 WRITE to: `{globalPath}/agents/prjct-planner.md`
 
 **prjct-shipper.md** - Handles: /p:ship
 READ template: `templates/subagents/workflow/prjct-shipper.md`
 ADAPT with: projectId, projectPath, detected test/lint commands
+ADD to frontmatter: `agentId: p.agent.shipper`
 WRITE to: `{globalPath}/agents/prjct-shipper.md`
 
 ### 7.4 Generate Domain Agents (Based on Stack)
 
 Analyze `{techStack}` from Step 3 and generate ONLY relevant domain agents:
 
-| If Detected | Generate | Template |
-|-------------|----------|----------|
-| React, Vue, Angular, Svelte, CSS | `frontend.md` | `templates/subagents/domain/frontend.md` |
-| Node.js, Express, Go, Python API | `backend.md` | `templates/subagents/domain/backend.md` |
-| PostgreSQL, MySQL, MongoDB, Prisma | `database.md` | `templates/subagents/domain/database.md` |
-| Docker, Kubernetes, GitHub Actions | `devops.md` | `templates/subagents/domain/devops.md` |
-| Bun test, Jest, Pytest, testing | `testing.md` | `templates/subagents/domain/testing.md` |
-| **{hasFrontendUI} = true** | `uxui.md` | `templates/agentic/agents/uxui.md` |
+| If Detected | Generate | Template | agentId |
+|-------------|----------|----------|---------|
+| React, Vue, Angular, Svelte, CSS | `frontend.md` | `templates/subagents/domain/frontend.md` | `p.agent.frontend` |
+| Node.js, Express, Go, Python API | `backend.md` | `templates/subagents/domain/backend.md` | `p.agent.backend` |
+| PostgreSQL, MySQL, MongoDB, Prisma | `database.md` | `templates/subagents/domain/database.md` | `p.agent.database` |
+| Docker, Kubernetes, GitHub Actions | `devops.md` | `templates/subagents/domain/devops.md` | `p.agent.devops` |
+| Bun test, Jest, Pytest, testing | `testing.md` | `templates/subagents/domain/testing.md` | `p.agent.testing` |
+| **{hasFrontendUI} = true** | `uxui.md` | `templates/agentic/agents/uxui.md` | `p.agent.uxui` |
 
 For EACH detected stack:
 1. READ template from `templates/subagents/domain/{name}.md`
 2. ADAPT description with detected frameworks (e.g., "React specialist" not just "frontend")
-3. WRITE to `{globalPath}/agents/{name}.md`
+3. ADD to frontmatter: `agentId: p.agent.{name}` (e.g., `p.agent.backend`)
+4. WRITE to `{globalPath}/agents/{name}.md`
 
 ### 7.5 Generate UX/UI Agent (CRITICAL for Frontend Projects)
 
@@ -990,6 +998,13 @@ IF cloudSync AND no syncError:
 └── 🎨 UX/UI: uxui.md (Priority: UX > UI)
 {ENDIF}
 
+🏷️ Agent Mentions (use in prompts)
+├── p.agent.workflow, p.agent.planner, p.agent.shipper
+{IF domainAgents.length > 0}
+├── {domainAgents.map(a => 'p.agent.' + a).join(', ')}
+{ENDIF}
+└── Example: "p.agent.backend help me create an API endpoint"
+
 📦 Skills ({totalSkills})
 ├── Installed: {skillsInstalled.length ? skillsInstalled.join(', ') : 'none'}
 ├── Verified: {skillsVerified.length ? skillsVerified.join(', ') : 'none'}

package/templates/commands/task.md

@@ -7,6 +7,47 @@ description: 'Unified task workflow with intelligent classification'
 
 Start any work with automatic classification and intelligent breakdown.
 
+## @ Agent Mentions
+
+Invoke specific agents directly in your task using @ notation:
+
+| Mention | Agent | Use Case |
+|---------|-------|----------|
+| `@frontend` | frontend.md | UI components, React/Vue |
+| `@backend` | backend.md | APIs, server logic |
+| `@database` | database.md | Schema, queries |
+| `@uxui` | uxui.md | UX patterns, design |
+| `@testing` | testing.md | Tests, coverage |
+| `@devops` | devops.md | CI/CD, Docker |
+
+**Examples:**
+- `p. task @frontend add button` - Loads frontend specialist
+- `p. task @frontend @uxui dark mode` - Loads both agents
+- `p. task @backend optimize API` - Loads backend specialist
+
+**Note:** If no @ mention, agents are auto-assigned based on task analysis.
+
+## Claude Code Subagents
+
+Special @ mentions invoke Claude Code's native subagents:
+
+| Mention | Subagent | Use Case |
+|---------|----------|----------|
+| `@explore` | Explore | Fast codebase search, find patterns |
+| `@general` | General | Complex multi-step research |
+| `@plan` | Plan | Architecture design, implementation planning |
+
+**Examples:**
+- `p. task @explore find all API endpoints`
+- `p. task @general research caching strategies`
+- `p. task @plan design authentication system`
+
+**Combined:**
+- `p. task @frontend @explore add button like existing ones`
+  → Loads frontend agent + uses Explore subagent to find similar buttons
+
+---
+
 ## Context Variables
 
 - `{projectId}`: From `.prjct/prjct.config.json`