prjct-cli 0.28.0 → 0.28.1

package/CHANGELOG.md

@@ -1,21 +1,42 @@
 # Changelog
 
-## [0.28.0] - 2026-01-10
+## [0.28.1] - 2026-01-10
 
-### Feature: Claude Code Native Integration
+### Feature: @ Agent Mentions
 
-**Skills as First-Class Citizens**: prjct commands are now installed as Claude Code Skills for automatic discovery.
+Direct agent invocation via @ notation in tasks.
 
-- **SessionStart Hook**: Injects fresh project context at session start via `~/.claude/hooks/prjct-session-start.sh`
-- **Skills Auto-Install**: 4 skills installed to `~/.claude/skills/` during `npm install`:
-  - `prjct-task` - Start tasks with classification
-  - `prjct-sync` - Analyze codebase, generate agents
-  - `prjct-done` - Complete current subtask
-  - `prjct-ship` - Ship with PR + version bump
-- **Setup Integration**: `core/infrastructure/setup.ts` now installs hooks and skills automatically
-- **Simplified CLAUDE.md**: Reduced global template from 221 to ~50 lines - hooks handle fresh context
+**New Capabilities:**
+
+1. **@ Agent Mentions**
+   - `p. task @frontend add button` - Loads frontend specialist directly
+   - `p. task @frontend @uxui dark mode` - Loads multiple agents
+   - Supports all prjct agents: `@frontend`, `@backend`, `@database`, `@uxui`, `@testing`, `@devops`
+
+2. **@ Claude Subagents**
+   - `@explore` - Fast codebase search (Task tool with subagent_type=Explore)
+   - `@general` - Complex multi-step research
+   - `@plan` - Architecture design and planning
+   - Example: `p. task @frontend @explore add button like existing ones`
 
-**Upgrade Impact**: Run `npm install -g prjct-cli` to install hooks and skills.
+3. **Performance Improvements**
+   - Template cache: O(1) LRU using ES6 Map insertion order
+   - Agent loading: Parallel Promise.all() for faster startup
+   - Glob searches: Parallel execution in context estimation
+
+4. **Tool Permissions**
+   - Templates can specify `tool-permissions` in frontmatter
+   - Supports `allow`, `ask`, and `deny` rules per tool
+   - Example: `ship.md` now declares safe vs dangerous git commands
+
+**Files Changed:**
+- `core/agentic/command-executor.ts` - Parse @ mentions, load mentioned agents
+- `core/agentic/prompt-builder.ts` - Build subagent instructions, tool permissions
+- `core/agentic/template-loader.ts` - LRU cache optimization, tool-permissions parsing
+- `core/agentic/agent-router.ts` - `loadAgentsByMention()` method
+- `core/domain/agent-loader.ts` - Parallel agent loading
+- `core/domain/context-estimator.ts` - Parallel glob execution
+- `templates/commands/task.md` - @ mention documentation
 
 ---
 

package/CLAUDE.md

@@ -145,34 +145,26 @@ Next: [suggested action]
 
 ---
 
-## CLAUDE CODE INTEGRATION (v0.28)
+## SKILL INTEGRATION (v0.27)
 
-prjct-cli uses Claude Code's native features for robust integration:
+Agents are linked to Claude Code skills from claude-plugins.dev.
 
-### SessionStart Hook
+### Agent → Skill Mapping
 
-A hook runs at the start of every Claude Code session to inject fresh context:
-- Located at: `~/.claude/hooks/prjct-session-start.sh`
-- Automatically reads project state and injects into session
-- Bypasses CLAUDE.md caching issues
+| Agent | Skill |
+|-------|-------|
+| `frontend.md` | `frontend-design` |
+| `uxui.md` | `frontend-design` |
+| `backend.md` | `javascript-typescript` |
+| `testing.md` | `developer-kit` |
+| `devops.md` | `developer-kit` |
+| `prjct-planner.md` | `feature-dev` |
+| `prjct-shipper.md` | `code-review` |
 
-### Skills (Auto-Discovery)
+### Usage
 
-Skills are auto-discovered by Claude Code when relevant:
+- `p. sync` installs required skills automatically
+- `p. task` invokes skills based on task type
+- Skills config: `{globalPath}/config/skills.json`
 
-| Skill | Trigger |
-|-------|---------|
-| `prjct-task` | "p. task", starting work, features/bugs |
-| `prjct-sync` | "p. sync", analyze codebase |
-| `prjct-done` | "p. done", completing work |
-| `prjct-ship` | "p. ship", releasing features |
-
-Skills location: `~/.claude/skills/prjct-*/SKILL.md`
-
-### Setup
-
-All integration is installed automatically via `npm install -g prjct-cli`:
-1. SessionStart hook → `~/.claude/hooks/`
-2. Skills → `~/.claude/skills/`
-3. Commands → `~/.claude/commands/p/`
-4. Settings → `~/.claude/settings.json`
+See `templates/agentic/skill-integration.md` for details.

package/core/agentic/agent-router.ts

@@ -104,6 +104,21 @@ class AgentRouter {
     }
   }
 
+  /**
+   * Load multiple agents by @ mention names
+   * @example loadAgentsByMention(["frontend", "uxui"]) -> [Agent, Agent]
+   */
+  async loadAgentsByMention(mentions: string[]): Promise<Agent[]> {
+    const agents: Agent[] = []
+    for (const name of mentions) {
+      const agent = await this.loadAgent(name)
+      if (agent) {
+        agents.push(agent)
+      }
+    }
+    return agents
+  }
+
   /**
    * Log agent usage to JSONL file
    */

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 AgentRouter from './agent-router'
 
 import type {
   ExecutionResult,
@@ -107,6 +108,18 @@ export class CommandExecutor {
     }
 
     try {
+      // 0. Parse @ agent mentions from task input
+      const taskInput = (params.task as string) || (params.description as string) || ''
+      const { prjctAgents, claudeSubagents, cleanInput } = promptBuilder.parseAgentMentions(taskInput)
+
+      // Update params with clean input (without @ mentions)
+      if (prjctAgents.length > 0 || claudeSubagents.length > 0) {
+        if (params.task) params.task = cleanInput
+        if (params.description) params.description = cleanInput
+        params._mentionedAgents = prjctAgents
+        params._claudeSubagents = claudeSubagents
+      }
+
       // 1. Load template
       const template = await templateLoader.load(commandName)
 
@@ -195,27 +208,62 @@ export class CommandExecutor {
         )
       }
 
-      // 9. Build prompt - NO agent assignment here, Claude decides via templates
+      // 8.5. Load @ mentioned agents if any
+      let primaryAgent = null
+      if (prjctAgents.length > 0) {
+        const agentRouter = new AgentRouter()
+        await agentRouter.initialize(projectPath)
+        const loadedAgents = await agentRouter.loadAgentsByMention(prjctAgents)
+
+        if (loadedAgents.length > 0) {
+          primaryAgent = {
+            name: loadedAgents[0].name,
+            content: loadedAgents[0].content,
+            role: undefined,
+            skills: [],
+          }
+          console.log(`🤖 Loading agents: ${loadedAgents.map((a) => `@${a.name}`).join(', ')}`)
+        }
+      }
+
+      // 9. Build prompt - use mentioned agent or let Claude decide via templates
       const planInfo = {
         isPlanning: requiresPlanning || isInPlanningMode,
         requiresApproval: isDestructive && !params.approved,
         active: activePlan,
         allowedTools: planMode.getAllowedTools(isInPlanningMode, template.frontmatter['allowed-tools'] || []),
       }
-      // Agent is null - Claude assigns via Task tool using agent-routing.md
-      const prompt = promptBuilder.build(
+
+      // Build base prompt
+      let prompt = promptBuilder.build(
         template,
         context as Parameters<typeof promptBuilder.build>[1],
         state,
-        null,
+        primaryAgent,
         learnedPatterns,
         null,
         relevantMemories,
         planInfo
       )
 
+      // Add Claude subagent instructions if @ mentioned
+      if (claudeSubagents.length > 0) {
+        const subagentInstructions = promptBuilder.buildSubagentInstructions(claudeSubagents)
+        prompt = prompt + subagentInstructions
+        console.log(`🔧 Claude subagents requested: ${claudeSubagents.map((s) => `@${s}`).join(', ')}`)
+      }
+
+      // Add tool permissions from template if present
+      const toolPermissions = template.frontmatter['tool-permissions'] as Record<string, { allow?: string[]; ask?: string[]; deny?: string[] }> | undefined
+      if (toolPermissions) {
+        const permissionsSection = promptBuilder.buildToolPermissions(toolPermissions)
+        prompt = prompt + permissionsSection
+      }
+
       // Log agentic mode
-      console.log(`🤖 Agentic delegation enabled - Claude will assign agent via Task tool`)
+      if (!primaryAgent) {
+        console.log(`🤖 Agentic delegation enabled - Claude will assign agent via Task tool`)
+      }
 
       // Record successful attempt
       loopDetector.recordSuccess(commandName, loopContext)

package/core/agentic/prompt-builder.ts

@@ -498,6 +498,87 @@ class PromptBuilder {
     return result || null
   }
 
+  /**
+   * Claude Code subagents that can be invoked via @ notation
+   */
+  private readonly CLAUDE_SUBAGENTS = ['explore', 'general', 'plan']
+
+  /**
+   * Parse @ agent mentions from input
+   * Separates prjct agents from Claude Code subagents
+   * @example "@frontend @explore add dark mode" -> { prjctAgents: ["frontend"], claudeSubagents: ["explore"], cleanInput: "add dark mode" }
+   */
+  parseAgentMentions(input: string): {
+    prjctAgents: string[]
+    claudeSubagents: string[]
+    cleanInput: string
+  } {
+    if (!input) return { prjctAgents: [], claudeSubagents: [], cleanInput: '' }
+
+    const mentionPattern = /@(\w+)/g
+    const prjctAgents: string[] = []
+    const claudeSubagents: string[] = []
+    let match
+
+    while ((match = mentionPattern.exec(input)) !== null) {
+      const name = match[1].toLowerCase()
+      if (this.CLAUDE_SUBAGENTS.includes(name)) {
+        claudeSubagents.push(name)
+      } else {
+        prjctAgents.push(name)
+      }
+    }
+
+    const cleanInput = input.replace(mentionPattern, '').trim()
+    return { prjctAgents, claudeSubagents, cleanInput }
+  }
+
+  /**
+   * Build Claude subagent instructions for the prompt
+   */
+  buildSubagentInstructions(claudeSubagents: string[]): string {
+    if (!claudeSubagents.length) return ''
+
+    const instructions = claudeSubagents.map((sub) => {
+      switch (sub) {
+        case 'explore':
+          return '- USE Task tool with subagent_type=Explore for fast codebase exploration'
+        case 'general':
+          return '- USE Task tool with subagent_type=general-purpose for complex multi-step research'
+        case 'plan':
+          return '- USE Task tool with subagent_type=Plan for architecture design'
+        default:
+          return null
+      }
+    }).filter(Boolean)
+
+    if (!instructions.length) return ''
+
+    return `
+## CLAUDE SUBAGENT INSTRUCTIONS
+${instructions.join('\n')}
+`
+  }
+
+  /**
+   * Build tool permissions section from template frontmatter
+   */
+  buildToolPermissions(toolPermissions: Record<string, { allow?: string[]; ask?: string[]; deny?: string[] }> | null): string {
+    if (!toolPermissions) return ''
+
+    const parts: string[] = ['\n## TOOL PERMISSIONS\n', 'Check these BEFORE executing:\n']
+
+    for (const [tool, rules] of Object.entries(toolPermissions)) {
+      parts.push(`\n**${tool}:**`)
+      if (rules.allow?.length) parts.push(`- ALLOW: ${rules.allow.join(', ')}`)
+      if (rules.ask?.length) parts.push(`- ASK USER: ${rules.ask.join(', ')}`)
+      if (rules.deny?.length) parts.push(`- NEVER: ${rules.deny.join(', ')}`)
+    }
+
+    parts.push('\n⚠️ DENY = Never execute. ASK = Confirm with user first.\n')
+    return parts.join('\n')
+  }
+
   /**
    * Build critical anti-hallucination rules section
    */

package/core/agentic/template-loader.ts

@@ -15,26 +15,92 @@ import type { Frontmatter, ParsedTemplate } from '../types'
 const TEMPLATES_DIR = path.join(__dirname, '..', '..', 'templates', 'commands')
 const MAX_CACHE_SIZE = 50
 
+// Use single Map for O(1) LRU operations (ES6 Maps maintain insertion order)
 const cache = new Map<string, ParsedTemplate>()
-const cacheOrder: string[] = []
 
 // ============ Cache Helpers ============
 
-function updateLruOrder(key: string): void {
-  const index = cacheOrder.indexOf(key)
-  if (index > -1) cacheOrder.splice(index, 1)
-  cacheOrder.push(key)
-}
+function setWithLru(key: string, value: ParsedTemplate): void {
+  // Delete first to move to end when re-adding (most recently used)
+  cache.delete(key)
+  cache.set(key, value)
 
-function evictLru(): void {
-  while (cache.size >= MAX_CACHE_SIZE && cacheOrder.length > 0) {
-    const oldest = cacheOrder.shift()
+  // Evict oldest (first item) if over limit
+  if (cache.size > MAX_CACHE_SIZE) {
+    const oldest = cache.keys().next().value
     if (oldest) cache.delete(oldest)
   }
 }
 
+function getWithLru(key: string): ParsedTemplate | undefined {
+  const value = cache.get(key)
+  if (value !== undefined) {
+    // Move to end (most recently used)
+    cache.delete(key)
+    cache.set(key, value)
+  }
+  return value
+}
+
 // ============ Parsing Functions ============
 
+/**
+ * Parse tool-permissions YAML block
+ * Handles nested structure like:
+ * tool-permissions:
+ *   bash:
+ *     allow: ["git *"]
+ *     deny: ["rm -rf"]
+ */
+function parseToolPermissions(lines: string[], startIndex: number): {
+  permissions: Record<string, { allow?: string[]; ask?: string[]; deny?: string[] }>
+  endIndex: number
+} {
+  const permissions: Record<string, { allow?: string[]; ask?: string[]; deny?: string[] }> = {}
+  let i = startIndex
+  let currentTool: string | null = null
+
+  while (i < lines.length) {
+    const line = lines[i]
+    const trimmed = line.trim()
+
+    // End if we hit a new top-level key (no leading spaces)
+    if (line.length > 0 && !line.startsWith(' ') && !line.startsWith('\t')) {
+      break
+    }
+
+    // Tool name (2 spaces indent)
+    const toolMatch = line.match(/^ {2}(\w+):$/)
+    if (toolMatch) {
+      currentTool = toolMatch[1]
+      permissions[currentTool] = {}
+      i++
+      continue
+    }
+
+    // Permission array (4 spaces indent)
+    const permMatch = line.match(/^ {4}(allow|ask|deny):\s*\[(.+)\]/)
+    if (permMatch && currentTool) {
+      const [, permType, arrayContent] = permMatch
+      permissions[currentTool][permType as 'allow' | 'ask' | 'deny'] = arrayContent
+        .split(',')
+        .map((v) => v.trim().replace(/^["']|["']$/g, ''))
+      i++
+      continue
+    }
+
+    // Skip empty lines within block
+    if (trimmed === '') {
+      i++
+      continue
+    }
+
+    i++
+  }
+
+  return { permissions, endIndex: i }
+}
+
 export function parseFrontmatter(content: string): ParsedTemplate {
   const frontmatterRegex = /^---\n([\s\S]+?)\n---\n([\s\S]*)$/
   const match = content.match(frontmatterRegex)
@@ -45,21 +111,35 @@ export function parseFrontmatter(content: string): ParsedTemplate {
 
   const [, frontmatterText, mainContent] = match
   const frontmatter: Frontmatter = {}
+  const lines = frontmatterText.split('\n')
 
-  frontmatterText.split('\n').forEach((line) => {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
     const [key, ...valueParts] = line.split(':')
-    if (key && valueParts.length > 0) {
-      const value = valueParts.join(':').trim()
-
-      // Parse arrays
-      if (value.startsWith('[') && value.endsWith(']')) {
-        frontmatter[key.trim()] = value.slice(1, -1).split(',').map((v) => v.trim())
-      } else {
-        // Remove quotes if present
-        frontmatter[key.trim()] = value.replace(/^["']|["']$/g, '')
-      }
+
+    if (!key || line.startsWith(' ') || line.startsWith('\t')) {
+      continue
     }
-  })
+
+    const keyTrimmed = key.trim()
+    const value = valueParts.join(':').trim()
+
+    // Handle tool-permissions nested block
+    if (keyTrimmed === 'tool-permissions' && value === '') {
+      const { permissions, endIndex } = parseToolPermissions(lines, i + 1)
+      frontmatter['tool-permissions'] = permissions
+      i = endIndex - 1
+      continue
+    }
+
+    // Parse arrays
+    if (value.startsWith('[') && value.endsWith(']')) {
+      frontmatter[keyTrimmed] = value.slice(1, -1).split(',').map((v) => v.trim())
+    } else if (value) {
+      // Remove quotes if present
+      frontmatter[keyTrimmed] = value.replace(/^["']|["']$/g, '')
+    }
+  }
 
   return { frontmatter, content: mainContent.trim() }
 }
@@ -67,10 +147,10 @@ export function parseFrontmatter(content: string): ParsedTemplate {
 // ============ Main Functions ============
 
 export async function load(commandName: string): Promise<ParsedTemplate> {
-  // Check cache first
-  if (cache.has(commandName)) {
-    updateLruOrder(commandName)
-    return cache.get(commandName)!
+  // Check cache first with LRU update
+  const cached = getWithLru(commandName)
+  if (cached) {
+    return cached
   }
 
   const templatePath = path.join(TEMPLATES_DIR, `${commandName}.md`)
@@ -79,12 +159,8 @@ export async function load(commandName: string): Promise<ParsedTemplate> {
     const rawContent = await fs.readFile(templatePath, 'utf-8')
     const parsed = parseFrontmatter(rawContent)
 
-    // Evict LRU if needed before adding
-    evictLru()
-
-    // Cache result
-    cache.set(commandName, parsed)
-    cacheOrder.push(commandName)
+    // Cache with LRU management
+    setWithLru(commandName, parsed)
 
     return parsed
   } catch {
@@ -99,7 +175,6 @@ export async function getAllowedTools(commandName: string): Promise<string[]> {
 
 export function clearCache(): void {
   cache.clear()
-  cacheOrder.length = 0
 }
 
 // ============ Default Export (backwards compat) ============

package/core/domain/agent-loader.ts

@@ -70,23 +70,21 @@ class AgentLoader {
   }
 
   /**
-   * Load all agents for the project
+   * Load all agents for the project (parallel loading for performance)
    */
   async loadAllAgents(): Promise<Agent[]> {
     try {
       const files = await fs.readdir(this.agentsDir)
       const agentFiles = files.filter((f) => f.endsWith('.md') && !f.startsWith('.'))
 
-      const agents: Agent[] = []
-      for (const file of agentFiles) {
+      // Load all agents in parallel for better performance
+      const agentPromises = agentFiles.map((file) => {
         const agentName = file.replace('.md', '')
-        const agent = await this.loadAgent(agentName)
-        if (agent) {
-          agents.push(agent)
-        }
-      }
+        return this.loadAgent(agentName)
+      })
 
-      return agents
+      const results = await Promise.all(agentPromises)
+      return results.filter((agent): agent is Agent => agent !== null)
     } catch (error) {
       if (isNotFoundError(error)) {
         return [] // Agents directory doesn't exist yet

package/core/domain/context-estimator.ts

@@ -137,21 +137,21 @@ class ContextEstimator {
         globPatterns.push(`*${ext}`)
       }
 
-      // Execute glob searches
-      for (const pattern of globPatterns) {
-        try {
-          const matches = await glob(pattern, {
-            cwd: projectPath,
-            ignore: patterns.exclude.map((ex) => `**/${ex}/**`),
-            nodir: true,
-            follow: false,
-          })
-
-          if (Array.isArray(matches)) {
-            files.push(...matches)
-          }
-        } catch {
-          // Skip invalid patterns
+      // Execute glob searches in parallel for better performance
+      const ignorePatterns = patterns.exclude.map((ex) => `**/${ex}/**`)
+      const globPromises = globPatterns.map((pattern) =>
+        glob(pattern, {
+          cwd: projectPath,
+          ignore: ignorePatterns,
+          nodir: true,
+          follow: false,
+        }).catch(() => [] as string[]) // Return empty array on error
+      )
+
+      const results = await Promise.all(globPromises)
+      for (const matches of results) {
+        if (Array.isArray(matches)) {
+          files.push(...matches)
         }
       }
 

package/core/infrastructure/config-manager.ts

@@ -42,6 +42,10 @@ function parseJsonc<T>(content: string): T {
 }
 
 class ConfigManager {
+  // Cache projectId lookups with TTL (30 seconds) to avoid repeated disk reads
+  private projectIdCache = new Map<string, { id: string; timestamp: number }>()
+  private readonly CACHE_TTL = 30000
+
   /**
    * Read the project configuration file
    * Supports both .json and .jsonc formats (with comments)
@@ -228,13 +232,30 @@ class ConfigManager {
 
   /**
    * Get the project ID from config, or generate it if config doesn't exist
+   * Uses in-memory cache with TTL to avoid repeated disk reads
    */
   async getProjectId(projectPath: string): Promise<string> {
-    const config = await this.readConfig(projectPath)
-    if (config && config.projectId) {
-      return config.projectId
+    // Check cache first
+    const cached = this.projectIdCache.get(projectPath)
+    if (cached && Date.now() - cached.timestamp < this.CACHE_TTL) {
+      return cached.id
     }
-    return pathManager.generateProjectId(projectPath)
+
+    // Read from disk
+    const config = await this.readConfig(projectPath)
+    const id = config?.projectId || pathManager.generateProjectId(projectPath)
+
+    // Cache the result
+    this.projectIdCache.set(projectPath, { id, timestamp: Date.now() })
+
+    return id
+  }
+
+  /**
+   * Clear the projectId cache (useful for testing or after config changes)
+   */
+  clearProjectIdCache(): void {
+    this.projectIdCache.clear()
   }
 
   /**