prjct-cli 0.27.0 → 0.28.0

package/package.json

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

package/templates/commands/cleanup.md

@@ -1,19 +1,83 @@
 ---
-allowed-tools: [Read, Edit, Bash]
-description: 'Code cleanup'
+allowed-tools: [Read, Edit, Write, Bash, Glob, Grep, Task]
+description: 'Deep code cleanup - dead code, comments, docs'
 ---
 
 # /p:cleanup
 
-## Types
-- **code**: Remove logs, dead code
-- **imports**: Clean unused
-- **files**: Remove temp/empty
-- **deps**: Find unused
-- **all**: Everything
+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
 
 ## Flow
-Parse type → Backup → Clean → Validate → Log
+
+```
+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 |
 
 ## Response
-`🧹 Cleaned: {N} logs, {N} dead code, {N} imports | Freed: {X}MB`
+
+```
+🧹 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
+```

package/templates/global/CLAUDE.md

@@ -1,163 +1,52 @@
 <!-- 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 with natural language commands.
 
-## HOW TO USE PRJCT (Read This First)
+## BEFORE ANY COMMAND
 
-When user types `p. <command>`, load the template from `templates/commands/{command}.md` and execute it intelligently.
-
-```
-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
-```
-
-**Key Insight**: Templates are GUIDANCE, not scripts. Use your intelligence to adapt them to the situation.
-
----
-
-## CRITICAL RULES
-
-### 1. Path Resolution (MOST IMPORTANT)
-**ALL writes go to global storage**: `~/.prjct-cli/projects/{projectId}/`
-
-- **NEVER** write to `.prjct/` (config only, read-only)
-- **NEVER** write to `./` (current directory)
-- **ALWAYS** resolve projectId first from `.prjct/prjct.config.json`
-
-### 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
+3. ALL writes go to globalPath (NEVER .prjct/)
 4. Log to {globalPath}/memory/events.jsonl
 ```
 
-### 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())"
-```
+## PATHS (CRITICAL)
 
-### 4. Git Commit Footer (CRITICAL - ALWAYS INCLUDE)
+| Type | Path | Access |
+|------|------|--------|
+| Config | `.prjct/prjct.config.json` | Read-only |
+| Storage | `{globalPath}/storage/*.json` | Read-Write |
+| Context | `{globalPath}/context/*.md` | Read-Write |
+| Memory | `{globalPath}/memory/events.jsonl` | Append |
+| Agents | `{globalPath}/agents/*.md` | Read |
 
-**Every commit made with prjct MUST include this footer:**
+## COMMANDS
 
-```
-🤖 Generated with [p/](https://www.prjct.app/)
-Designed for [Claude](https://www.anthropic.com/claude)
-
-```
-
-**This is NON-NEGOTIABLE. The prjct signature (`🤖 Generated with [p/]`) must appear in ALL commits.**
-
----
-
-## 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 ───┘
-```
-
-### Quick Reference
-
-| Trigger | What It Does |
-|---------|--------------|
-| `p. sync` | Analyze project, generate domain agents |
-| `p. task <desc>` | Start task with auto-classification |
+| Trigger | Action |
+|---------|--------|
+| `p. sync` | Analyze project, generate agents |
+| `p. task <desc>` | Start task with 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 |
+| `p. ship [name]` | Ship with PR + version bump |
 
----
-
-## ARCHITECTURE: Write-Through Pattern
+## TIMESTAMPS
 
-```
-User Action → Storage (JSON) → Context (MD) → Sync Events
+```bash
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
 ```
 
-| 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 |
+## GIT COMMITS
 
-### File Structure
+Always include footer:
 ```
-~/.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
+🤖 Generated with [p/](https://www.prjct.app/)
+Designed for [Claude](https://www.anthropic.com/claude)
 ```
 
----
-
-## 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
-
----
-
 ## OUTPUT FORMAT
 
-Concise responses (< 4 lines):
 ```
 ✅ [What was done]
 
@@ -167,66 +56,6 @@ Next: [suggested action]
 
 ---
 
-## LOADING DOMAIN AGENTS
-
-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
-
-These agents contain project-specific patterns. **USE THEM**.
-
----
-
-## SKILL INTEGRATION (NEW in v0.27 - AGENTIC)
-
-Agents are linked to Claude Code skills from claude-plugins.dev.
-
-**Skills are discovered AGENTICALLY** - Claude searches the marketplace dynamically.
-
-### How Skills Work
-
-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
-
-### 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
-```
-
-### 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" |
-
-### Skill Location
-
-Skills are markdown files in `~/.claude/skills/`
-
-### Skill Configuration
-
-After sync: `{globalPath}/config/skills.json` contains discovered mappings.
-
----
-
-**Auto-managed by prjct-cli** | https://prjct.app | v0.27.0
+Detailed instructions loaded via Skills. | https://prjct.app
 
 <!-- prjct:end - DO NOT REMOVE THIS MARKER -->

package/templates/hooks/prjct-session-start.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# prjct-cli SessionStart Hook
+# Inyecta contexto fresco del proyecto al inicio de cada sesión Claude Code
+# https://prjct.app
+
+set -e
+
+# Solo ejecutar si estamos en un proyecto prjct
+if [[ -f ".prjct/prjct.config.json" ]]; then
+  # Extraer projectId
+  PROJECT_ID=$(cat .prjct/prjct.config.json 2>/dev/null | grep -o '"projectId"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
+
+  if [[ -n "$PROJECT_ID" ]]; then
+    PRJCT_HOME="$HOME/.prjct-cli/projects/$PROJECT_ID"
+
+    if [[ -d "$PRJCT_HOME" ]]; then
+      # Leer versión CLI
+      CLI_VERSION="unknown"
+      if [[ -f "$PRJCT_HOME/project.json" ]]; then
+        CLI_VERSION=$(cat "$PRJCT_HOME/project.json" 2>/dev/null | grep -o '"cliVersion"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
+        [[ -z "$CLI_VERSION" ]] && CLI_VERSION="unknown"
+      fi
+
+      # Leer tarea actual
+      CURRENT_TASK=""
+      if [[ -f "$PRJCT_HOME/context/now.md" ]]; then
+        CURRENT_TASK=$(cat "$PRJCT_HOME/context/now.md" 2>/dev/null | head -20)
+      fi
+
+      # Leer nombre del proyecto
+      PROJECT_NAME=""
+      if [[ -f "$PRJCT_HOME/project.json" ]]; then
+        PROJECT_NAME=$(cat "$PRJCT_HOME/project.json" 2>/dev/null | grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
+      fi
+
+      # Output para Claude Code
+      echo "---"
+      echo "prjct-cli v$CLI_VERSION"
+      echo "Project: $PROJECT_NAME ($PROJECT_ID)"
+      echo "Storage: $PRJCT_HOME"
+      echo "---"
+
+      if [[ -n "$CURRENT_TASK" ]]; then
+        echo ""
+        echo "Current Task:"
+        echo "$CURRENT_TASK"
+      fi
+    fi
+  fi
+fi

package/templates/skills/prjct-done/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: prjct-done
+description: Complete current task or subtask. Use when user says "p. done", "finished", "completed", or indicates they finished working on something.
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task, TodoWrite]
+user-invocable: true
+---
+
+# prjct Done
+
+Mark current task or subtask as complete and advance workflow.
+
+## Context Loading (ALWAYS FIRST)
+
+```
+1. Read `.prjct/prjct.config.json` → extract projectId
+2. Set globalPath = ~/.prjct-cli/projects/{projectId}
+3. Read {globalPath}/storage/state.json → current task
+```
+
+## Done Workflow
+
+### 1. Check Current State
+
+Read `{globalPath}/storage/state.json`:
+- If no currentTask: "No active task. Use p. task to start one."
+- If has subtasks: Check which is in_progress
+
+### 2. Complete Subtask (if applicable)
+
+If task has subtasks:
+```json
+{
+  "subtasks": [
+    { "id": "1", "status": "completed", "completedAt": "..." },
+    { "id": "2", "status": "in_progress" },  // ← Mark complete, advance
+    { "id": "3", "status": "pending" }        // ← Start this one
+  ]
+}
+```
+
+### 3. Complete Task (if no more subtasks)
+
+When all subtasks done OR no subtasks:
+```json
+{
+  "currentTask": null,
+  "lastCompleted": {
+    "id": "...",
+    "title": "...",
+    "completedAt": "ISO timestamp"
+  }
+}
+```
+
+### 4. Update Context
+
+Write to `{globalPath}/context/now.md`:
+- If more subtasks: Show next subtask
+- If task complete: Show completion + suggest next
+
+### 5. Log Event
+
+Append to `{globalPath}/memory/events.jsonl`:
+```json
+{"timestamp": "...", "action": "subtask_completed", "subtask": {...}}
+```
+or
+```json
+{"timestamp": "...", "action": "task_completed", "task": {...}}
+```
+
+## Paths (CRITICAL)
+
+| Type | Path | Access |
+|------|------|--------|
+| Config | `.prjct/prjct.config.json` | Read-only |
+| Storage | `{globalPath}/storage/state.json` | Read-Write |
+| Context | `{globalPath}/context/now.md` | Write |
+| Memory | `{globalPath}/memory/events.jsonl` | Append |
+
+## Output Format
+
+**Subtask completed:**
+```
+✅ Subtask completed: {title}
+
+Progress: {completed}/{total}
+Next: {next subtask title}
+```
+
+**Task completed:**
+```
+✅ Task completed: {title}
+
+Duration: {time}
+Next: p. ship "{feature}" or p. task "next thing"
+```

package/templates/skills/prjct-ship/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: prjct-ship
+description: Ship a feature with PR, version bump, and changelog. Use when user says "p. ship", wants to release/deploy, or is ready to merge their work.
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task, AskUserQuestion, TodoWrite]
+user-invocable: true
+---
+
+# prjct Ship
+
+Ship features with automated PR creation, version bumping, and changelog updates.
+
+## Context Loading (ALWAYS FIRST)
+
+```
+1. Read `.prjct/prjct.config.json` → extract projectId
+2. Set globalPath = ~/.prjct-cli/projects/{projectId}
+3. Read {globalPath}/storage/state.json → current/last task
+4. Check git status for branch and changes
+```
+
+## Ship Workflow
+
+### 1. Pre-Ship Checks
+
+```bash
+# Check for uncommitted changes
+git status --porcelain
+
+# Check current branch (should not be main/master)
+git branch --show-current
+
+# Run tests if configured
+npm test || bun test || yarn test
+```
+
+### 2. Create/Update PR
+
+If on feature branch:
+```bash
+# Push branch
+git push -u origin $(git branch --show-current)
+
+# Create PR with gh CLI
+gh pr create --title "feat: {feature name}" --body "..."
+```
+
+PR body template:
+```markdown
+## Summary
+{Brief description}
+
+## Changes
+- {change 1}
+- {change 2}
+
+## Test Plan
+- [ ] Tests pass
+- [ ] Manual verification
+
+---
+🤖 Generated with [p/](https://www.prjct.app/)
+Designed for [Claude](https://www.anthropic.com/claude)
+```
+
+### 3. Version Bump (if applicable)
+
+Read `package.json`, determine bump type:
+- **patch**: Bug fixes (0.0.x)
+- **minor**: New features (0.x.0)
+- **major**: Breaking changes (x.0.0)
+
+```bash
+npm version patch -m "chore: bump version to %s"
+```
+
+### 4. Update Changelog
+
+Prepend to `CHANGELOG.md`:
+```markdown
+## [x.x.x] - YYYY-MM-DD
+
+### Added
+- {new feature}
+
+### Fixed
+- {bug fix}
+```
+
+### 5. Record Shipment
+
+Write to `{globalPath}/storage/shipped.json`:
+```json
+{
+  "shipped": [
+    {
+      "id": "uuid",
+      "name": "{feature}",
+      "version": "x.x.x",
+      "prUrl": "https://github.com/...",
+      "shippedAt": "ISO timestamp"
+    }
+  ]
+}
+```
+
+### 6. Update Context
+
+Write to `{globalPath}/context/shipped.md`:
+```markdown
+# Recently Shipped
+
+## {feature name}
+- Version: x.x.x
+- PR: {url}
+- Date: {date}
+```
+
+### 7. Log Event
+
+Append to `{globalPath}/memory/events.jsonl`:
+```json
+{"timestamp": "...", "action": "feature_shipped", "feature": {...}, "version": "..."}
+```
+
+## Paths (CRITICAL)
+
+| Type | Path | Access |
+|------|------|--------|
+| Config | `.prjct/prjct.config.json` | Read-only |
+| Storage | `{globalPath}/storage/shipped.json` | Read-Write |
+| Context | `{globalPath}/context/shipped.md` | Write |
+| Memory | `{globalPath}/memory/events.jsonl` | Append |
+
+## Git Commit Footer
+
+ALWAYS include in commits:
+```
+🤖 Generated with [p/](https://www.prjct.app/)
+Designed for [Claude](https://www.anthropic.com/claude)
+```
+
+## Output Format
+
+```
+🚀 SHIPPED: {feature name}
+
+Version: {x.x.x}
+PR: {url}
+Next: Celebrate! Then p. task "next feature"
+```