prjct-cli 0.34.0 → 0.35.0

package/core/agentic/command-executor.ts

@@ -18,6 +18,7 @@ import chainOfThought from './chain-of-thought'
 import memorySystem from './memory-system'
 import groundTruth from './ground-truth'
 import planMode from './plan-mode'
+import templateExecutor from './template-executor'
 
 import type {
   ExecutionResult,
@@ -160,13 +161,25 @@ export class CommandExecutor {
         }
       }
 
-      // 3. AGENTIC: Claude decides agent assignment via templates
+      // 3. AGENTIC: Template-first execution
+      // Claude decides agent assignment via templates - no hardcoded routing
+      const taskDescription = (params.task as string) || (params.description as string) || ''
+      const agenticExecContext = await templateExecutor.buildContext(
+        commandName,
+        taskDescription,
+        projectPath
+      )
+      const agenticInfo = templateExecutor.buildAgenticPrompt(agenticExecContext)
+
       // Build context with agent routing info for Claude delegation
       const context: PromptContext = {
         ...metadataContext,
-        agentsPath: path.join(os.homedir(), '.prjct-cli', 'projects', metadataContext.projectId || '', 'agents'),
-        agentRoutingPath: path.join(__dirname, '..', '..', 'templates', 'agentic', 'agent-routing.md'),
+        agentsPath: agenticExecContext.paths.agentsDir,
+        agentRoutingPath: agenticExecContext.paths.agentRouting,
+        orchestratorPath: agenticExecContext.paths.orchestrator,
+        taskFragmentationPath: agenticExecContext.paths.taskFragmentation,
         agenticDelegation: true,
+        agenticMode: true,
       }
 
       // 6. Load state with filtered context
@@ -214,7 +227,10 @@ export class CommandExecutor {
       )
 
       // Log agentic mode
-      console.log(`🤖 Agentic delegation enabled - Claude will assign agent via Task tool`)
+      console.log(`🤖 Template-first execution: Claude reads templates and decides`)
+      if (agenticInfo.requiresOrchestration) {
+        console.log(`   → Orchestration: ${agenticExecContext.paths.orchestrator}`)
+      }
 
       // Record successful attempt
       loopDetector.recordSuccess(commandName, loopContext)
@@ -229,8 +245,14 @@ export class CommandExecutor {
         state,
         prompt,
         agenticDelegation: true,
+        agenticMode: true,
+        agenticExecContext,
+        agenticPrompt: agenticInfo.prompt,
+        requiresOrchestration: agenticInfo.requiresOrchestration,
         agentsPath: context.agentsPath as string,
         agentRoutingPath: context.agentRoutingPath as string,
+        orchestratorPath: agenticExecContext.paths.orchestrator,
+        taskFragmentationPath: agenticExecContext.paths.taskFragmentation,
         reasoning,
         groundTruth: groundTruthResult,
         learnedPatterns,

package/core/agentic/index.ts

@@ -88,6 +88,7 @@ export {
 // Tool and template management
 export { default as toolRegistry } from './tool-registry'
 export { default as templateLoader } from './template-loader'
+export { default as templateExecutor, TemplateExecutor } from './template-executor'
 
 // ============ Utilities ============
 // Chain of thought, services

package/core/agentic/template-executor.ts

@@ -0,0 +1,261 @@
+/**
+ * Template Executor
+ *
+ * Executes templates as the entry point for agentic command execution.
+ * TypeScript provides infrastructure (paths, reads/writes).
+ * Claude takes all agentic decisions via templates.
+ *
+ * @module agentic/template-executor
+ * @version 1.0.0
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+import configManager from '../infrastructure/config-manager'
+import pathManager from '../infrastructure/path-manager'
+import { isNotFoundError } from '../types/fs'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TemplateExecutionContext {
+  projectPath: string
+  projectId: string
+  globalPath: string
+  command: string
+  args: string
+
+  // Paths for Claude (not content - Claude reads what it needs)
+  paths: {
+    orchestrator: string
+    agentRouting: string
+    taskFragmentation: string
+    commandTemplate: string
+    repoAnalysis: string
+    agentsDir: string
+    skillsDir: string
+    stateJson: string
+  }
+}
+
+export interface AgenticPromptInfo {
+  prompt: string
+  context: TemplateExecutionContext
+  requiresOrchestration: boolean
+}
+
+// Commands that require orchestration (task routing, fragmentation)
+const ORCHESTRATED_COMMANDS = ['task', 'done', 'ship', 'resume', 'bug', 'enrich']
+
+// Commands that do NOT need orchestration
+const SIMPLE_COMMANDS = ['init', 'sync', 'pause', 'next', 'dash', 'history', 'undo', 'redo']
+
+// =============================================================================
+// Template Executor Class
+// =============================================================================
+
+export class TemplateExecutor {
+  /**
+   * Get npm root for templates path
+   */
+  private async getNpmRoot(): Promise<string> {
+    // Get the templates path relative to this module
+    // In production, templates are in the npm package
+    const moduleDir = path.dirname(require.resolve('prjct-cli/package.json'))
+    return moduleDir
+  }
+
+  /**
+   * Get project ID from local config
+   */
+  private async getProjectId(projectPath: string): Promise<string> {
+    return configManager.getProjectId(projectPath)
+  }
+
+  /**
+   * Build execution context with paths only
+   * Claude reads files agentically - we don't inject content
+   */
+  async buildContext(
+    command: string,
+    args: string,
+    projectPath: string
+  ): Promise<TemplateExecutionContext> {
+    const projectId = await this.getProjectId(projectPath)
+    const globalPath = pathManager.getGlobalProjectPath(projectId)
+
+    // Get templates directory - use local path during development
+    let templatesDir: string
+    try {
+      const npmRoot = await this.getNpmRoot()
+      templatesDir = path.join(npmRoot, 'templates')
+    } catch {
+      // Fallback to local templates during development
+      templatesDir = path.join(__dirname, '..', '..', 'templates')
+    }
+
+    return {
+      projectPath,
+      projectId,
+      globalPath,
+      command,
+      args,
+      paths: {
+        orchestrator: path.join(templatesDir, 'agentic', 'orchestrator.md'),
+        agentRouting: path.join(templatesDir, 'agentic', 'agent-routing.md'),
+        taskFragmentation: path.join(templatesDir, 'agentic', 'task-fragmentation.md'),
+        commandTemplate: path.join(templatesDir, 'commands', `${command}.md`),
+        repoAnalysis: path.join(globalPath, 'analysis', 'repo-analysis.json'),
+        agentsDir: path.join(globalPath, 'agents'),
+        skillsDir: path.join(os.homedir(), '.claude', 'skills'),
+        stateJson: path.join(globalPath, 'storage', 'state.json'),
+      }
+    }
+  }
+
+  /**
+   * Check if a command requires orchestration
+   */
+  requiresOrchestration(command: string): boolean {
+    if (ORCHESTRATED_COMMANDS.includes(command)) return true
+    if (SIMPLE_COMMANDS.includes(command)) return false
+    // Default: assume orchestration needed for unknown commands
+    return true
+  }
+
+  /**
+   * Check if agents exist for the project
+   */
+  async hasAgents(projectPath: string): Promise<boolean> {
+    try {
+      const projectId = await this.getProjectId(projectPath)
+      const agentsDir = path.join(pathManager.getGlobalProjectPath(projectId), 'agents')
+      const files = await fs.readdir(agentsDir)
+      return files.some(f => f.endsWith('.md'))
+    } catch (error) {
+      if (isNotFoundError(error)) return false
+      return false
+    }
+  }
+
+  /**
+   * Get list of available agent names
+   */
+  async getAvailableAgents(projectPath: string): Promise<string[]> {
+    try {
+      const projectId = await this.getProjectId(projectPath)
+      const agentsDir = path.join(pathManager.getGlobalProjectPath(projectId), 'agents')
+      const files = await fs.readdir(agentsDir)
+      return files
+        .filter(f => f.endsWith('.md'))
+        .map(f => f.replace('.md', ''))
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Build prompt that tells Claude to execute templates agentically
+   */
+  buildAgenticPrompt(context: TemplateExecutionContext): AgenticPromptInfo {
+    const requiresOrchestration = this.requiresOrchestration(context.command)
+
+    const prompt = `
+## Agentic Execution Mode
+
+You are executing a prjct command. Follow the template-first approach.
+
+### Context
+- Command: ${context.command}
+- Args: ${context.args}
+- Project: ${context.projectPath}
+- Project ID: ${context.projectId}
+
+### Paths (Read as needed)
+- Orchestrator: ${context.paths.orchestrator}
+- Agent Routing: ${context.paths.agentRouting}
+- Task Fragmentation: ${context.paths.taskFragmentation}
+- Command Template: ${context.paths.commandTemplate}
+- Repo Analysis: ${context.paths.repoAnalysis}
+- Agents Directory: ${context.paths.agentsDir}
+- Skills Directory: ${context.paths.skillsDir}
+- State JSON: ${context.paths.stateJson}
+
+### Instructions
+
+1. **Read the command template** (${context.paths.commandTemplate})
+
+2. **Check if orchestration is needed**
+   - This command ${requiresOrchestration ? 'REQUIRES' : 'does NOT require'} orchestration
+   ${requiresOrchestration ? `
+3. **Orchestration steps:**
+   - Read: ${context.paths.orchestrator}
+   - Read: ${context.paths.repoAnalysis} to understand project technologies
+   - Analyze the task: "${context.args}"
+   - Determine which domains are ACTUALLY relevant based on:
+     a) What the task requires
+     b) What technologies exist in this project
+     c) What agents are available in ${context.paths.agentsDir}
+
+   - **IMPORTANTE**: Los agentes en ${context.paths.agentsDir} YA son específicos del proyecto
+     (fueron generados durante p. sync con las tecnologías reales)
+
+   - SIEMPRE usar el especialista si existe para el dominio
+   - Solo usar generalista si NO existe agente para ese dominio
+
+   - Check if task should be fragmented (read: ${context.paths.taskFragmentation})
+   - If agents loaded, check their skills and load from ${context.paths.skillsDir}
+` : `
+3. **Simple execution:**
+   - Execute the command template directly
+   - No agent routing needed
+`}
+
+4. **Execute the command template** with full context
+
+5. **Return results**
+
+### Agentic Decision Making
+
+YOU decide:
+- Whether to run orchestration (based on command type)
+- Which domains the task involves (frontend, backend, database, etc.)
+- Whether to fragment the task into subtasks
+- Which specialist agents to delegate to
+
+ALWAYS:
+- Use specialist agents when they exist (they're already project-specific)
+- Delegate subtasks to the appropriate specialist via Task tool
+- Let specialists handle their domain (they have the project patterns)
+- Generate and store summaries when subtasks complete
+
+ONLY use generalist when:
+- No specialist agent exists for that domain
+- Task is completely outside project scope
+- Extreme edge case
+
+### Subtask Management
+
+When fragmenting tasks:
+1. Store subtasks in state.json under currentTask.subtasks
+2. Track progress: currentSubtaskIndex, subtaskProgress
+3. Each completed subtask generates a summary
+4. Pass summary to next agent for context handoff
+`
+
+    return {
+      prompt,
+      context,
+      requiresOrchestration
+    }
+  }
+}
+
+// =============================================================================
+// Singleton Export
+// =============================================================================
+
+export const templateExecutor = new TemplateExecutor()
+export default templateExecutor

package/core/commands/workflow.ts

@@ -3,6 +3,9 @@
  * Core task management - Write-Through Architecture
  *
  * Uses storage layer: JSON (source) → MD (context) → Event (sync)
+ *
+ * AGENTIC: Uses template-executor for Claude-driven decisions.
+ * TypeScript provides infrastructure; Claude decides via templates.
  */
 
 import type { CommandResult, ProjectContext } from '../types'
@@ -15,6 +18,7 @@ import {
   out
 } from './base'
 import { stateStorage, queueStorage } from '../storage'
+import { templateExecutor } from '../agentic/template-executor'
 
 export class WorkflowCommands extends PrjctCommandsBase {
   /**
@@ -32,9 +36,12 @@ export class WorkflowCommands extends PrjctCommandsBase {
       }
 
       if (task) {
-        const context = await contextBuilder.build(projectPath, { task }) as ProjectContext
-        const agentResult = await this._assignAgentForTask(task, projectPath, context)
-        const agent = agentResult.agent?.name || 'generalist'
+        // AGENTIC: Build execution context for Claude to decide
+        const execContext = await templateExecutor.buildContext('task', task, projectPath)
+        const agenticInfo = templateExecutor.buildAgenticPrompt(execContext)
+
+        // Get available agents for context
+        const availableAgents = await templateExecutor.getAvailableAgents(projectPath)
 
         // Write-through: JSON → MD → Event
         await stateStorage.startTask(projectId, {
@@ -43,14 +50,29 @@ export class WorkflowCommands extends PrjctCommandsBase {
           sessionId: generateUUID()
         })
 
-        out.done(`${task} [${agent}]`)
+        // AGENTIC: Log that Claude will decide via templates
+        const agentsList = availableAgents.length > 0
+          ? availableAgents.join(', ')
+          : 'none (run p. sync)'
+
+        console.log(`🤖 Agentic mode: Claude will read templates and decide`)
+        out.done(`${task} [specialists: ${agentsList}]`)
 
         await this.logToMemory(projectPath, 'task_started', {
           task,
-          agent,
+          agenticMode: true,
+          availableAgents,
           timestamp: dateHelper.getTimestamp(),
         })
-        return { success: true, task, agent }
+
+        return {
+          success: true,
+          task,
+          agenticMode: true,
+          availableAgents,
+          execContext,
+          agenticPrompt: agenticInfo.prompt,
+        }
       } else {
         // Read from storage (JSON is source of truth)
         const currentTask = await stateStorage.getCurrentTask(projectId)

package/core/schemas/state.ts

@@ -17,15 +17,53 @@ import { z } from 'zod'
 export const PrioritySchema = z.enum(['low', 'medium', 'high', 'critical'])
 export const TaskTypeSchema = z.enum(['feature', 'bug', 'improvement', 'chore'])
 export const TaskSectionSchema = z.enum(['active', 'backlog', 'previously_active'])
-export const TaskStatusSchema = z.enum(['pending', 'in_progress', 'completed', 'blocked', 'paused'])
+export const TaskStatusSchema = z.enum(['pending', 'in_progress', 'completed', 'blocked', 'paused', 'failed'])
 export const ActivityTypeSchema = z.enum(['task_completed', 'feature_shipped', 'idea_captured', 'session_started'])
 
+// Subtask summary for context handoff between agents
+export const SubtaskSummarySchema = z.object({
+  title: z.string(),
+  description: z.string(),
+  filesChanged: z.array(z.object({
+    path: z.string(),
+    action: z.enum(['created', 'modified', 'deleted']),
+  })),
+  whatWasDone: z.array(z.string()),
+  outputForNextAgent: z.string().optional(),
+  notes: z.string().optional(),
+})
+
+// Subtask schema for task fragmentation
+export const SubtaskSchema = z.object({
+  id: z.string(),                    // subtask-xxx
+  description: z.string(),
+  domain: z.string(),                // frontend, backend, database, testing, etc.
+  agent: z.string(),                 // agent file name (e.g., "frontend.md")
+  status: TaskStatusSchema,
+  dependsOn: z.array(z.string()),    // IDs of dependent subtasks
+  startedAt: z.string().optional(),  // ISO8601
+  completedAt: z.string().optional(), // ISO8601
+  output: z.string().optional(),      // Brief output description
+  summary: SubtaskSummarySchema.optional(), // Full summary for context handoff
+})
+
+// Subtask progress tracking
+export const SubtaskProgressSchema = z.object({
+  completed: z.number(),
+  total: z.number(),
+  percentage: z.number(),
+})
+
 export const CurrentTaskSchema = z.object({
   id: z.string(),                   // task_xxxxxxxx
   description: z.string(),
   startedAt: z.string(),            // ISO8601
   sessionId: z.string(),            // sess_xxxxxxxx
   featureId: z.string().optional(), // feat_xxxxxxxx
+  // Subtask tracking for fragmented tasks
+  subtasks: z.array(SubtaskSchema).optional(),
+  currentSubtaskIndex: z.number().optional(),
+  subtaskProgress: SubtaskProgressSchema.optional(),
 })
 
 export const PreviousTaskSchema = z.object({
@@ -99,6 +137,10 @@ export type TaskSection = z.infer<typeof TaskSectionSchema>
 export type TaskStatus = z.infer<typeof TaskStatusSchema>
 export type ActivityType = z.infer<typeof ActivityTypeSchema>
 
+export type Subtask = z.infer<typeof SubtaskSchema>
+export type SubtaskSummary = z.infer<typeof SubtaskSummarySchema>
+export type SubtaskProgress = z.infer<typeof SubtaskProgressSchema>
+
 export type CurrentTask = z.infer<typeof CurrentTaskSchema>
 export type PreviousTask = z.infer<typeof PreviousTaskSchema>
 export type StateJson = z.infer<typeof StateJsonSchema>

package/core/services/agent-service.ts

@@ -68,8 +68,13 @@ export class AgentService {
   }
 
   /**
-   * Assign agent for a task using AgentRouter
-   * Returns agent info for Claude to delegate work
+   * Assign agent for a task - AGENTIC APPROACH
+   *
+   * NO keyword matching. Returns available agents and context
+   * for Claude to make the decision via templates/orchestrator.md
+   *
+   * The agents in {agentsDir} are already project-specific
+   * (generated during p. sync with real technologies)
    */
   async assignForTask(
     task: string,
@@ -81,67 +86,53 @@ export class AgentService {
       const agents = await this.agentRouter.getAgentNames()
 
       if (agents.length === 0) {
+        // No agents available - suggest running sync
         return {
-          agent: { name: 'generalist' },
+          agent: null, // Claude decides - don't default to generalist
           routing: {
-            confidence: 1.0,
-            reason: 'No specialized agents available',
+            confidence: 0,
+            reason: 'No specialized agents available. Run "p. sync" to generate agents.',
             availableAgents: [],
           },
+          _agenticNote: 'AGENTIC: Claude reads orchestrator.md and decides how to proceed',
         }
       }
 
-      // Simple keyword matching for agent assignment
-      // Claude will make the final decision via templates
-      const taskLower = task.toLowerCase()
-      let bestMatch = 'generalist'
-
-      for (const agentName of agents) {
-        const nameLower = agentName.toLowerCase()
-        if (taskLower.includes(nameLower) || nameLower.includes('general')) {
-          bestMatch = agentName
-          break
-        }
-        // Common domain keywords
-        if (
-          (nameLower.includes('fe') || nameLower.includes('frontend')) &&
-          (taskLower.includes('ui') ||
-            taskLower.includes('component') ||
-            taskLower.includes('react'))
-        ) {
-          bestMatch = agentName
-          break
-        }
-        if (
-          (nameLower.includes('be') || nameLower.includes('backend')) &&
-          (taskLower.includes('api') ||
-            taskLower.includes('server') ||
-            taskLower.includes('database'))
-        ) {
-          bestMatch = agentName
-          break
-        }
-      }
-
-      await this.agentRouter.logUsage(task, bestMatch, projectPath)
+      // AGENTIC: No keyword matching here
+      // Claude reads the orchestrator template and decides based on:
+      // 1. Task analysis (what domains are involved)
+      // 2. Available agents (from agents directory)
+      // 3. Whether to fragment into subtasks
+      //
+      // The TypeScript code just provides the list of available agents
 
       return {
-        agent: { name: bestMatch },
+        agent: null, // Claude decides via templates
         routing: {
-          confidence: 0.7,
-          reason: 'Keyword-based agent matching',
+          confidence: 0, // Claude determines confidence
+          reason: 'AGENTIC: Claude will analyze task and select appropriate specialist agents',
           availableAgents: agents,
         },
-        _agenticNote: 'Claude should verify this assignment using agent context',
+        _agenticNote: `
+          AGENTIC EXECUTION:
+          - Read: templates/agentic/orchestrator.md
+          - Analyze task: "${task}"
+          - Available specialists: ${agents.join(', ')}
+          - Claude decides which agent(s) to use
+          - Always prefer specialists over generalist
+          - Fragment complex tasks into subtasks
+        `,
       }
     } catch (_error) {
       // Agent routing unavailable - expected for new projects
       return {
-        agent: { name: 'generalist' },
+        agent: null,
         routing: {
-          confidence: 1.0,
-          reason: 'Agent routing unavailable',
+          confidence: 0,
+          reason: 'Agent routing unavailable - run "p. sync" first',
+          availableAgents: [],
         },
+        _agenticNote: 'AGENTIC: Suggest running p. sync to generate agents',
       }
     }
   }