prjct-cli 0.10.12 → 0.10.14

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.10.14] - 2025-11-29
+
+### Refactored - 100% Agentic Subagent Delegation via Task Tool
+
+Claude now delegates to specialist agents using the Task tool with efficient reference passing.
+
+- **`command-executor.js`** - Eliminated all if/else agent assignment logic
+  - Removed: `MandatoryAgentRouter`, `ContextFilter`, `ContextEstimator`
+  - Removed: `isTaskCommand()`, `shouldUseAgent()` methods
+  - JS only loads templates and context, Claude decides everything
+  - Added: `agentsPath` and `agentRoutingPath` to context for Claude
+
+- **Templates updated with Agent Delegation section**:
+  - `feature.md` - Added Task + Glob tools, agent delegation instructions
+  - `bug.md` - Added Task + Glob tools, agent delegation instructions
+  - `task.md` - Added Task + Glob tools, agent delegation instructions
+
+- **`agent-routing.md`** - Added efficient Task tool invocation
+  - Pass file PATH (~200 bytes), not content (3-5KB)
+  - Subagent reads agent file itself
+  - Reduced context bloat by 95%
+
+### Architecture
+
+```
+Usuario: "p. feature mejorar UX"
+    ↓
+Claude lee agent-routing.md → decide: "ux-ui"
+    ↓
+Claude: Task(prompt='Read: path/agents/ux-ui.md + Task: mejorar UX')
+    ↓
+Subagente: Lee archivo → aplica expertise → ejecuta
+```
+
+**Benefits:**
+- 95% reduction in prompt size for delegation
+- Lower hallucination risk
+- True 100% agentic - JS is pure orchestration
+
 ## [0.10.12] - 2025-11-29
 
 ### Refactored - Mandatory Agent Assignment (100% Agentic)

package/CLAUDE.md

@@ -55,8 +55,14 @@ p. ship       → Lint/test/commit/push
 
 When message starts with `p.`:
 1. Check `.prjct/prjct.config.json` exists
-2. If exists → Detect intent → Execute `/p:*` command
-3. If not exists → "No prjct project. Run /p:init first."
+2. Detect intent from message
+3. **USE SlashCommand tool** to execute the command
+
+⚠️ **CRITICAL** - Always use SlashCommand, never work directly:
+- ✅ `SlashCommand("/p:feature add dark mode")`
+- ❌ Directly creating files without the command
+
+If no project: "No prjct project. Run /p:init first."
 
 ### Intent Map
 
@@ -201,3 +207,42 @@ Use: `generator.generateDynamicAgent(name, config)`
 4. **Confirm before executing** - Always show plan first
 5. **Log actions** - Append to memory/context.jsonl
 6. **Suggest next actions** - Maintain user momentum
+
+## Output Philosophy
+
+**Task completion responses MUST be concise (< 4 lines):**
+
+Format:
+```
+✅ [What was done]
+
+Files: [count] | Modified: [key file]
+Next: [action]
+```
+
+**NEVER include in task summaries:**
+- Tables listing files
+- "Created Files" / "Modified Files" sections
+- "How It Works" explanations
+- Code snippets or implementation details
+- Detailed breakdowns of what was done
+
+**Example (GOOD):**
+```
+✅ Agentic checklists integrated
+
+Files: 11 created | Modified: prompt-builder.js
+Next: /p:ship or test with /p:now
+```
+
+**Example (BAD):**
+```
+Created Files:
+| File | Purpose |
+|------|---------|
+| x.md | Does X  |
+...
+
+How It Works:
+Claude reads → decides → applies...
+```

package/core/agentic/command-executor.js

@@ -1,27 +1,32 @@
 /**
  * Command Executor
- * WITH MANDATORY AGENT ASSIGNMENT
- * Every task MUST use a specialized agent
+ * 100% AGENTIC - Claude decides agent assignment via Task tool
  *
- * OPTIMIZATION (P0.2): Explicit Validation
- * - Pre-flight checks before execution
- * - Specific error messages, never generic failures
- * - Actionable suggestions in every error
+ * NO if/else logic for agent selection here.
+ * Claude reads templates/agentic/agent-routing.md and delegates via Task tool.
  *
- * P3.4: Plan Mode + Approval Flow
- * - Separates planning from execution
- * - Requires approval for destructive commands
+ * JS only:
+ * - Loads templates
+ * - Builds context
+ * - Returns prompt for Claude
+ *
+ * Claude:
+ * - Reads agent-routing.md
+ * - Decides best agent for task
+ * - Delegates via Task(subagent_type='general-purpose', prompt='Read: path/to/agent.md...')
  *
  * Source: Claude Code, Devin, Augment Code patterns
  */
 
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
 const templateLoader = require('./template-loader')
 const contextBuilder = require('./context-builder')
 const promptBuilder = require('./prompt-builder')
 const toolRegistry = require('./tool-registry')
-const MandatoryAgentRouter = require('./agent-router')
-const ContextFilter = require('./context-filter')
-const ContextEstimator = require('../domain/context-estimator')
+// REMOVED: MandatoryAgentRouter, ContextFilter, ContextEstimator
+// Agent assignment is 100% agentic - Claude decides via templates
 const { validate, formatError } = require('./validation-rules')
 const loopDetector = require('./loop-detector')
 const chainOfThought = require('./chain-of-thought')
@@ -32,6 +37,9 @@ const groundTruth = require('./ground-truth')
 const thinkBlocks = require('./think-blocks')
 const parallelTools = require('./parallel-tools')
 const planMode = require('./plan-mode')
+
+// Running file for status line integration
+const RUNNING_FILE = path.join(os.homedir(), '.prjct-cli', '.running')
 // P3.5, P3.6, P3.7: DELEGATED TO CLAUDE CODE
 // - semantic-search → Claude Code has Grep/Glob with semantic understanding
 // - code-intelligence → Claude Code has native LSP integration
@@ -39,21 +47,52 @@ const planMode = require('./plan-mode')
 
 class CommandExecutor {
   constructor() {
-    this.agentRouter = new MandatoryAgentRouter()
-    this.contextFilter = new ContextFilter()
-    this.contextEstimator = null
+    // 100% AGENTIC: No agent router here
+    // Claude decides agent assignment via templates and Task tool
+  }
+
+  /**
+   * Signal that a command is running (for status line)
+   */
+  signalStart(commandName) {
+    try {
+      const dir = path.dirname(RUNNING_FILE)
+      if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true })
+      }
+      fs.writeFileSync(RUNNING_FILE, `/p:${commandName}`)
+    } catch {
+      // Silently ignore - status line is optional
+    }
+  }
+
+  /**
+   * Signal that command has finished (for status line)
+   */
+  signalEnd() {
+    try {
+      if (fs.existsSync(RUNNING_FILE)) {
+        fs.unlinkSync(RUNNING_FILE)
+      }
+    } catch {
+      // Silently ignore - status line is optional
+    }
   }
 
   /**
    * Execute command with MANDATORY agent assignment
    */
   async execute(commandName, params, projectPath) {
+    // Signal start for status line
+    this.signalStart(commandName)
+
     // Context for loop detection
     const loopContext = params.task || params.description || ''
 
     // Check if we're in a loop BEFORE attempting
     if (loopDetector.shouldEscalate(commandName, loopContext)) {
       const escalation = loopDetector.getEscalationInfo(commandName, loopContext)
+      this.signalEnd()
       return {
         success: false,
         error: escalation.message,
@@ -73,6 +112,7 @@ class CommandExecutor {
       // 2.5. VALIDATE: Pre-flight checks with specific errors
       const validation = await validate(commandName, metadataContext)
       if (!validation.valid) {
+        this.signalEnd()
         return {
           success: false,
           error: formatError(validation),
@@ -134,72 +174,18 @@ class CommandExecutor {
         }
       }
 
-      // 3. CRITICAL: Force agent assignment for ALL task-related commands
-      const requiresAgent = template.metadata?.['required-agent'] !== false &&
-                           (template.metadata?.['required-agent'] === true ||
-                            this.isTaskCommand(commandName) ||
-                            this.shouldUseAgent(commandName))
-
+      // 3. AGENTIC: Claude decides agent assignment via templates
+      // NO if/else logic here - templates instruct Claude to use Task tool
+      // See templates/agentic/agent-routing.md for routing rules
       let context = metadataContext
-      let assignedAgent = null
-
-      // MANDATORY: Assign specialized agent for task commands
-      if (requiresAgent) {
-        // 4. Create task object for analysis
-        const task = {
-          description: params.task || params.description || commandName,
-          type: commandName
-        }
-
-        // 5. LAZY CONTEXT: Analyze task FIRST, then estimate files needed
-        // This avoids reading all files before knowing what we need
-        const agentAssignment = await this.agentRouter.executeTask(
-          task,
-          metadataContext, // Only metadata, no files yet
-          projectPath
-        )
-
-        assignedAgent = agentAssignment.agent
-        const taskAnalysis = agentAssignment.taskAnalysis
 
-        // Validate agent was assigned
-        if (!assignedAgent || !assignedAgent.name) {
-          throw new Error(
-            `CRITICAL: Failed to assign agent for command "${commandName}". ` +
-            `System requires ALL task commands to use specialized agents.`
-          )
-        }
-
-        // 6. PRE-FILTER: Estimate which files are needed BEFORE reading
-        if (!this.contextEstimator) {
-          this.contextEstimator = new ContextEstimator()
-        }
-
-        const estimatedFiles = await this.contextEstimator.estimateFiles(
-          taskAnalysis,
-          projectPath
-        )
-
-        // 7. Build context ONLY with estimated files (lazy loading)
-        const filtered = await this.contextFilter.filterForAgent(
-          assignedAgent,
-          task,
-          projectPath,
-          {
-            ...metadataContext,
-            estimatedFiles, // Pre-filtered file list
-            fileCount: estimatedFiles.length
-          }
-        )
-
-        context = {
-          ...filtered,
-          agent: assignedAgent,
-          originalSize: estimatedFiles.length, // Estimated, not actual full size
-          filteredSize: filtered.files?.length || 0,
-          reduction: filtered.metrics?.reductionPercent || 0,
-          lazyLoaded: true // Flag indicating lazy loading was used
-        }
+      // Provide agent info to context so Claude can delegate
+      context = {
+        ...context,
+        agentsPath: path.join(os.homedir(), '.prjct-cli', 'projects', metadataContext.projectId || '', 'agents'),
+        agentRoutingPath: path.join(__dirname, '..', '..', 'templates', 'agentic', 'agent-routing.md'),
+        // Flag: Claude must delegate to subagent via Task tool
+        agenticDelegation: true
       }
 
       // 6. Load state with filtered context
@@ -246,7 +232,7 @@ class CommandExecutor {
         )
       }
 
-      // 9. Build prompt with agent assignment, learned patterns, think blocks, memories, AND plan mode
+      // 9. Build prompt - NO agent assignment here, Claude decides via templates
       const planInfo = {
         isPlanning: requiresPlanning || isInPlanningMode,
         requiresApproval: isDestructive && !params.approved,
@@ -256,25 +242,28 @@ class CommandExecutor {
           template.frontmatter['allowed-tools'] || []
         )
       }
-      const prompt = promptBuilder.build(template, context, state, assignedAgent, learnedPatterns, thinkBlock, relevantMemories, planInfo)
+      // Agent is null - Claude assigns via Task tool using agent-routing.md
+      const prompt = promptBuilder.build(template, context, state, null, learnedPatterns, thinkBlock, relevantMemories, planInfo)
 
-      // 8. Log agent usage
-      if (assignedAgent) {
-        console.log(`🤖 Task assigned to: ${assignedAgent.name}`)
-        console.log(`📉 Context reduced by: ${context.reduction}%`)
-      }
+      // Log agentic mode
+      console.log(`🤖 Agentic delegation enabled - Claude will assign agent via Task tool`)
 
       // Record successful attempt
       loopDetector.recordSuccess(commandName, loopContext)
 
+      // Signal end for status line
+      this.signalEnd()
+
       return {
         success: true,
         template,
         context,
         state,
         prompt,
-        assignedAgent,
-        contextReduction: context.reduction,
+        // AGENTIC: No pre-assigned agent - Claude delegates via Task tool
+        agenticDelegation: true,
+        agentsPath: context.agentsPath,
+        agentRoutingPath: context.agentRoutingPath,
         reasoning, // Chain of thought results
         thinkBlock, // Think blocks (P3.1)
         groundTruth: groundTruthResult, // Ground truth verification (P1.3)
@@ -334,6 +323,9 @@ class CommandExecutor {
         // - Native LSP for code intelligence
       }
     } catch (error) {
+      // Signal end for status line
+      this.signalEnd()
+
       // Record failed attempt for loop detection
       const attemptInfo = loopDetector.recordAttempt(commandName, loopContext, {
         success: false,
@@ -361,30 +353,9 @@ class CommandExecutor {
     }
   }
 
-  /**
-   * Check if command is task-related
-   */
-  isTaskCommand(commandName) {
-    const taskCommands = [
-      'work', 'now', 'build', 'feature', 'bug', 'done',
-      'task', 'design', 'cleanup', 'fix', 'test'
-    ]
-    return taskCommands.includes(commandName)
-  }
-
-  /**
-   * Determine if command should use an agent
-   * Expanded list of commands that benefit from agent specialization
-   */
-  shouldUseAgent(commandName) {
-    // Commands that should ALWAYS use agents
-    const agentCommands = [
-      'work', 'now', 'build', 'feature', 'bug', 'done',
-      'task', 'design', 'cleanup', 'fix', 'test',
-      'sync', 'analyze' // These analyze/modify code, need specialization
-    ]
-    return agentCommands.includes(commandName)
-  }
+  // REMOVED: isTaskCommand() and shouldUseAgent()
+  // Agent assignment is now 100% agentic - Claude decides via templates
+  // See templates/agentic/agent-routing.md
 
   /**
    * Execute tool with permission check

package/core/agentic/prompt-builder.js

@@ -7,9 +7,65 @@
  * P3.1: Includes think blocks for anti-hallucination
  * P3.3: Includes relevant memories from semantic database
  * P3.4: Includes plan mode instructions
+ * P4.1: Includes quality checklists (Claude decides which to apply)
  */
 
+const fs = require('fs')
+const path = require('path')
+
 class PromptBuilder {
+  constructor() {
+    this._checklistsCache = null
+    this._checklistRoutingCache = null
+  }
+
+  /**
+   * Load quality checklists from templates/checklists/
+   * Returns checklist content - Claude decides which to apply
+   * NO if/else logic here - just load and provide
+   */
+  loadChecklists() {
+    if (this._checklistsCache) return this._checklistsCache
+
+    const checklistsDir = path.join(__dirname, '..', '..', 'templates', 'checklists')
+    const checklists = {}
+
+    try {
+      if (fs.existsSync(checklistsDir)) {
+        const files = fs.readdirSync(checklistsDir).filter(f => f.endsWith('.md'))
+        for (const file of files) {
+          const name = file.replace('.md', '')
+          const content = fs.readFileSync(path.join(checklistsDir, file), 'utf-8')
+          checklists[name] = content
+        }
+      }
+    } catch (err) {
+      // Silent fail - checklists are optional enhancement
+    }
+
+    this._checklistsCache = checklists
+    return checklists
+  }
+
+  /**
+   * Load checklist routing template
+   * Claude reads this to decide which checklists to apply
+   */
+  loadChecklistRouting() {
+    if (this._checklistRoutingCache) return this._checklistRoutingCache
+
+    const routingPath = path.join(__dirname, '..', '..', 'templates', 'agentic', 'checklist-routing.md')
+
+    try {
+      if (fs.existsSync(routingPath)) {
+        this._checklistRoutingCache = fs.readFileSync(routingPath, 'utf-8')
+      }
+    } catch (err) {
+      // Silent fail
+    }
+
+    return this._checklistRoutingCache || null
+  }
   /**
    * Build concise prompt - only essentials
    * CRITICAL: Includes full agent content if agent is provided
@@ -154,6 +210,22 @@ class PromptBuilder {
       parts.push(`\n## APPROVAL REQUIRED\nShow changes, list affected files, ask for confirmation.\n`)
     }
 
+    // P4.1: Quality Checklists (Claude decides which to apply)
+    // Only for code-modifying commands that benefit from quality gates
+    const checklistCommands = ['now', 'build', 'feature', 'design', 'fix', 'bug', 'cleanup', 'spec', 'work']
+    if (checklistCommands.includes(commandName)) {
+      const routing = this.loadChecklistRouting()
+      const checklists = this.loadChecklists()
+
+      if (routing && Object.keys(checklists).length > 0) {
+        parts.push('\n## QUALITY CHECKLISTS\n')
+        parts.push('Apply relevant checklists based on task. Read checklist-routing.md for guidance.\n')
+        parts.push(`Available: ${Object.keys(checklists).join(', ')}\n`)
+        parts.push('Path: templates/checklists/{name}.md\n')
+        parts.push('Use Read tool to load checklists you determine are relevant.\n')
+      }
+    }
+
     // Simple execution directive
     parts.push('\nEXECUTE: Follow flow. Use tools. Decide.\n')
 

package/core/commands.js

@@ -1925,6 +1925,15 @@ Agent: ${agent} (${Math.round(confidence * 100)}% confidence)
       console.log(`⚠️  ${configResult.error}`)
     }
 
+    // Install status line for Claude Code
+    console.log('\n⚡ Installing status line...')
+    const statusLineResult = await this.installStatusLine()
+    if (statusLineResult.success) {
+      console.log('✅ Status line configured')
+    } else {
+      console.log(`⚠️  ${statusLineResult.error}`)
+    }
+
     console.log('\n🎉 Setup complete!\n')
 
     // Show beautiful ASCII art
@@ -1936,6 +1945,69 @@ Agent: ${agent} (${Math.round(confidence * 100)}% confidence)
     }
   }
 
+  /**
+   * Install status line script and configure settings.json
+   */
+  async installStatusLine() {
+    const fs = require('fs')
+    const path = require('path')
+    const os = require('os')
+
+    try {
+      const claudeDir = path.join(os.homedir(), '.claude')
+      const settingsPath = path.join(claudeDir, 'settings.json')
+      const statusLinePath = path.join(claudeDir, 'prjct-statusline.sh')
+
+      // Copy status line script
+      const scriptContent = `#!/bin/bash
+# prjct Status Line for Claude Code
+# Shows ⚡ prjct with animated spinner when command is running
+
+# Read JSON context from stdin (provided by Claude Code)
+read -r json
+
+# Spinner frames
+frames=('⠋' '⠙' '⠹' '⠸' '⠼' '⠴' '⠦' '⠧' '⠇' '⠏')
+
+# Calculate frame based on time (changes every 80ms)
+frame=$(($(date +%s%N 2>/dev/null || echo 0) / 80000000 % 10))
+
+# Check if prjct command is running
+running_file="$HOME/.prjct-cli/.running"
+
+if [ -f "$running_file" ]; then
+  task=$(cat "$running_file" 2>/dev/null || echo "working")
+  echo "⚡ prjct \${frames[$frame]} $task"
+else
+  echo "⚡ prjct"
+fi
+`
+      fs.writeFileSync(statusLinePath, scriptContent, { mode: 0o755 })
+
+      // Update settings.json
+      let settings = {}
+      if (fs.existsSync(settingsPath)) {
+        try {
+          settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'))
+        } catch {
+          // Invalid JSON, start fresh
+        }
+      }
+
+      // Set status line configuration
+      settings.statusLine = {
+        type: 'command',
+        command: statusLinePath
+      }
+
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2))
+
+      return { success: true }
+    } catch (error) {
+      return { success: false, error: error.message }
+    }
+  }
+
   /**
    * Show beautiful ASCII art with quick start
    */

package/core/index.js

@@ -6,6 +6,7 @@
 
 const { PrjctCommands } = require('./commands')
 const registry = require('./command-registry')
+const out = require('./utils/output')
 
 async function main() {
   const [commandName, ...rawArgs] = process.argv.slice(2)
@@ -25,6 +26,9 @@ async function main() {
 
   // === DYNAMIC COMMAND EXECUTION ===
 
+  // Show branding header
+  out.start()
+
   try {
     // 1. Find command in registry
     const cmd = registry.getByName(commandName)
@@ -32,6 +36,7 @@ async function main() {
     if (!cmd) {
       console.error(`Unknown command: ${commandName}`)
       console.error(`\nUse 'prjct --help' to see available commands.`)
+      out.end()
       process.exit(1)
     }
 
@@ -41,6 +46,7 @@ async function main() {
       if (cmd.replacedBy) {
         console.error(`Use 'prjct ${cmd.replacedBy}' instead.`)
       }
+      out.end()
       process.exit(1)
     }
 
@@ -49,6 +55,7 @@ async function main() {
       console.error(`Command '${commandName}' exists but is not yet implemented.`)
       console.error(`Check the roadmap or contribute: https://github.com/jlopezlira/prjct-cli`)
       console.error(`\nUse 'prjct --help' to see available commands.`)
+      out.end()
       process.exit(1)
     }
 
@@ -90,12 +97,16 @@ async function main() {
       console.log(result.message)
     }
 
+    // Show branding footer
+    out.end()
     process.exit(result && result.success ? 0 : 1)
   } catch (error) {
     console.error('Error:', error.message)
     if (process.env.DEBUG) {
       console.error(error.stack)
     }
+    // Show branding footer even on error
+    out.end()
     process.exit(1)
   }
 }

package/core/utils/branding.js

@@ -0,0 +1,47 @@
+/**
+ * Branding Configuration for prjct-cli
+ * Single source of truth for all branding across CLI and Claude Code
+ */
+
+const chalk = require('chalk')
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
+const SPINNER_SPEED = 80
+
+const branding = {
+  // Core identity
+  name: 'prjct',
+  icon: '⚡',
+  signature: '⚡ prjct',
+
+  // Spinner config
+  spinner: {
+    frames: SPINNER_FRAMES,
+    speed: SPINNER_SPEED
+  },
+
+  // CLI output (with chalk colors)
+  cli: {
+    header: () => chalk.cyan.bold('⚡') + ' ' + chalk.cyan('prjct'),
+    footer: () => chalk.dim('⚡ prjct'),
+    spin: (frame, msg) => chalk.cyan('⚡') + ' ' + chalk.cyan('prjct') + ' ' + chalk.cyan(SPINNER_FRAMES[frame % 10]) + ' ' + chalk.dim(msg || '')
+  },
+
+  // Template/Claude (plain text)
+  template: {
+    header: '⚡ prjct',
+    footer: '⚡ prjct'
+  },
+
+  // Git commit footer
+  commitFooter: `🤖 Generated with [p/](https://www.prjct.app/)
+Designed for [Claude](https://www.anthropic.com/claude)`,
+
+  // URLs
+  urls: {
+    website: 'https://prjct.app',
+    docs: 'https://prjct.app/docs'
+  }
+}
+
+module.exports = branding