prjct-cli 0.28.2 → 0.28.4

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # Changelog
 
+## [0.28.4] - 2026-01-11
+
+### Feature: Claude Code UX Enhancements
+
+Rich terminal experience for Claude Code - 100% ToS compliant.
+
+**Status Line System:**
+- Custom status line script showing prjct task, git branch, lines changed
+- Context usage bar with color-coded warnings (green/yellow/red)
+- Model icons (🎭 Opus, 📝 Sonnet, 🍃 Haiku)
+- Installed at `~/.prjct-cli/statusline/statusline.sh`
+
+**Theme System:**
+- Three built-in themes: default (prjct), gentleman, minimal
+- JSON-based theme configuration
+- ANSI 256 color support
+- Located at `~/.prjct-cli/statusline/themes/`
+
+**Output Styles:**
+- `prjct.md` - Concise, actionable output (default)
+- `verbose.md` - Detailed explanations for learning
+- `ship-fast.md` - Minimal output for max velocity
+- Located at `~/.prjct-cli/output-styles/`
+
+**Hooks Integration:**
+- `update-metrics.sh` - Tracks tool usage per session
+- `session-summary.sh` - Shows stats when Claude stops
+- Located at `~/.prjct-cli/hooks/`
+
+**Visual Theme (tweakcc):**
+- Full Claude Code color theme
+- Spanish thinking verbs
+- Located at `~/.prjct-cli/tweakcc-theme.json`
+
+**New Templates:**
+- `templates/commands/setup-statusline.md` - Interactive setup
+- `templates/guides/claude-code-ux.md` - Full documentation
+- Updated `templates/global/CLAUDE.md` with UX section
+
+**Template Optimization:**
+- Further reduced template sizes
+- New shared patterns in `templates/shared/`
+
+## [0.28.3] - 2026-01-11
+
+### Feature: Claude Code Synergy Optimization
+
+Major improvements to maximize prjct + Claude Code integration efficiency.
+
+**Skill Auto-Invocation (Phase 4 of /p:task):**
+- Skills are now automatically invoked when loading agents
+- Agent frontmatter `skills: [skill-name]` triggers `Skill("skill-name")`
+- Example: Loading `frontend.md` auto-activates `/frontend-design`
+
+**MCP Auto-Usage:**
+- Agents with `mcp: [context7]` auto-query documentation during tasks
+- Per-project MCP config at `{globalPath}/config/mcp-servers.json`
+- Seamless library documentation lookup during implementation
+
+**Think Blocks for Destructive Commands:**
+- `/p:ship` now includes mandatory `<think>` block
+- Pre-ship verification checklist (completeness, quality, git state)
+- Prevents shipping incomplete or broken code
+
+**Agent Auto-Refresh in /p:sync:**
+- Detects when dependencies change (package.json, etc.)
+- Regenerates stale agents (>7 days old)
+- Versions previous agents as `.backup` files
+- Logs refresh events to memory
+
+**Slash Command Registration:**
+- New `slash-commands.json` config for Claude Code integration
+- Enables command discovery and validation
+- Path: `{globalPath}/config/slash-commands.json`
+
+**Token Budget Analysis:**
+- Estimates context token usage during sync
+- Warns if approaching 80% of budget (160k tokens)
+- Auto-summarizes large agents if needed
+
+**Client Migration on Update:**
+- Setup now creates missing config files for existing projects
+- `slash-commands.json` auto-created for existing installations
+- Seamless upgrade experience for npm update users
+
+**New TypeScript Modules:**
+- `core/infrastructure/slash-command-registry.ts` - Command validation
+- `core/agentic/token-estimator.ts` - Token budget estimation
+
+**Template Context Optimization:**
+- Reduced main templates from 3,197 to 2,214 lines (-31%)
+- `sync.md`: 1,602 → 835 lines (-48%)
+- `global/CLAUDE.md`: 429 → 363 lines (-15%)
+- `task.md`: 397 → 336 lines (-15%)
+- `ship.md`: 769 → 680 lines (-12%)
+- New `templates/guides/` for on-demand documentation
+- New `templates/shared/validation.md` for reusable validation
+
+**Files Removed (Agentic Generation):**
+- Deleted hardcoded domain agents from `templates/subagents/domain/`
+- Deleted `.mcp.json` (now generated per-project)
+- Deleted `CLAUDE.md` from root (moved to templates/global/)
+
+---
+
 ## [0.28.2] - 2026-01-10
 
 ### Feature: Agent Mentions and Major Cleanup

package/core/agentic/index.ts

@@ -90,9 +90,19 @@ export { default as toolRegistry } from './tool-registry'
 export { default as templateLoader } from './template-loader'
 
 // ============ Utilities ============
-// Chain of thought, services
+// Chain of thought, services, token estimation
 export { default as chainOfThought } from './chain-of-thought'
 export { default as services } from './services'
+export {
+  default as tokenEstimator,
+  estimateTokens,
+  getTokenBudget,
+  estimateContext,
+  filterContext,
+  summarizeForTokens,
+  createContextSections,
+  formatEstimate,
+} from './token-estimator'
 
 // ============ Types ============
 // All types re-exported from ../types (canonical source)

package/core/agentic/memory-system.ts

@@ -43,7 +43,6 @@ import type {
   MemoryDatabase,
   HistoryEntry,
   HistoryEventType,
-  Decision,
   Workflow,
   Preference,
   Patterns,
@@ -269,8 +268,13 @@ export class HistoryStore {
 /**
  * Patterns - Tier 2
  * Persistent learned preferences and decisions.
+ * OPTIMIZED: Debounced saves to reduce I/O
  */
 export class PatternStore extends CachedStore<Patterns> {
+  private _saveTimeout: ReturnType<typeof setTimeout> | null = null
+  private _pendingSave: string | null = null
+  private static readonly SAVE_DEBOUNCE_MS = 500 // Batch saves within 500ms
+
   protected getFilename(): string {
     return 'patterns.json'
   }
@@ -285,6 +289,41 @@ export class PatternStore extends CachedStore<Patterns> {
     }
   }
 
+  /**
+   * OPTIMIZED: Debounced save - batches multiple updates
+   */
+  private async debouncedSave(projectId: string): Promise<void> {
+    this._pendingSave = projectId
+
+    if (this._saveTimeout) {
+      clearTimeout(this._saveTimeout)
+    }
+
+    return new Promise((resolve) => {
+      this._saveTimeout = setTimeout(async () => {
+        if (this._pendingSave) {
+          await this.save(this._pendingSave)
+          this._pendingSave = null
+        }
+        resolve()
+      }, PatternStore.SAVE_DEBOUNCE_MS)
+    })
+  }
+
+  /**
+   * Force flush any pending saves (call before process exit)
+   */
+  async flush(projectId: string): Promise<void> {
+    if (this._saveTimeout) {
+      clearTimeout(this._saveTimeout)
+      this._saveTimeout = null
+    }
+    if (this._pendingSave) {
+      await this.save(projectId)
+      this._pendingSave = null
+    }
+  }
+
   // Convenience alias for backward compatibility
   async loadPatterns(projectId: string): Promise<Patterns> {
     return this.load(projectId)
@@ -330,7 +369,8 @@ export class PatternStore extends CachedStore<Patterns> {
       }
     }
 
-    await this.save(projectId)
+    // OPTIMIZED: Debounced save instead of immediate
+    await this.debouncedSave(projectId)
   }
 
   async getDecision(projectId: string, key: string): Promise<{ value: string; confidence: string } | null> {
@@ -364,13 +404,12 @@ export class PatternStore extends CachedStore<Patterns> {
       patterns.workflows[workflowName].lastSeen = now
     }
 
-    await this.save(projectId)
+    await this.debouncedSave(projectId)
   }
 
   async getWorkflow(projectId: string, workflowName: string): Promise<Workflow | null> {
     const patterns = await this.load(projectId)
     const workflow = patterns.workflows[workflowName]
-
     if (!workflow || workflow.count < 3) return null
     return workflow
   }
@@ -378,7 +417,7 @@ export class PatternStore extends CachedStore<Patterns> {
   async setPreference(projectId: string, key: string, value: Preference['value']): Promise<void> {
     const patterns = await this.load(projectId)
     patterns.preferences[key] = { value, updatedAt: getTimestamp() }
-    await this.save(projectId)
+    await this.debouncedSave(projectId)
   }
 
   async getPreference(projectId: string, key: string, defaultValue: unknown = null): Promise<unknown> {

package/core/agentic/smart-context.ts

@@ -13,7 +13,6 @@ import { outcomeAnalyzer } from '../outcomes'
 import type { TaskType } from '../types'
 import type {
   ContextDomain,
-  SmartContextProjectState,
   FullContext,
   FilteredContext,
   StackInfo,
@@ -32,8 +31,22 @@ export type {
   FilterMetrics,
 } from '../types'
 
-// Local type alias for backward compatibility
-type ProjectState = SmartContextProjectState
+/**
+ * PERFORMANCE: Pre-built keyword → domain map for O(1) lookup
+ * Instead of iterating 5 arrays of keywords, we do a single pass
+ */
+const KEYWORD_DOMAIN_MAP: Map<string, ContextDomain> = new Map([
+  // Frontend
+  ...['ui', 'component', 'react', 'vue', 'angular', 'css', 'style', 'button', 'form', 'modal', 'layout', 'responsive', 'animation', 'dom', 'html', 'frontend', 'fe', 'client', 'browser', 'jsx', 'tsx'].map(k => [k, 'frontend' as ContextDomain] as const),
+  // Backend
+  ...['api', 'server', 'database', 'db', 'endpoint', 'route', 'handler', 'controller', 'service', 'repository', 'model', 'query', 'backend', 'be', 'rest', 'graphql', 'prisma', 'sql', 'redis', 'auth'].map(k => [k, 'backend' as ContextDomain] as const),
+  // DevOps
+  ...['deploy', 'docker', 'kubernetes', 'k8s', 'ci', 'cd', 'pipeline', 'terraform', 'ansible', 'aws', 'gcp', 'azure', 'nginx', 'devops', 'infrastructure', 'monitoring', 'logging'].map(k => [k, 'devops' as ContextDomain] as const),
+  // Docs
+  ...['document', 'docs', 'readme', 'changelog', 'comment', 'jsdoc', 'tutorial', 'guide', 'explain', 'describe', 'markdown'].map(k => [k, 'docs' as ContextDomain] as const),
+  // Testing
+  ...['test', 'spec', 'jest', 'mocha', 'cypress', 'playwright', 'pytest', 'unittest', 'e2e', 'unit', 'integration', 'coverage', 'mock', 'fixture'].map(k => [k, 'testing' as ContextDomain] as const),
+])
 
 /**
  * SmartContext - Intelligent context filtering.
@@ -41,63 +54,20 @@ type ProjectState = SmartContextProjectState
 class SmartContext {
   /**
    * Detect the domain of a task from its description.
+   * OPTIMIZED: Single-pass O(n) where n = words in description
    */
   detectDomain(taskDescription: string): DomainAnalysis {
-    const lower = taskDescription.toLowerCase()
-
-    // Frontend indicators
-    const frontendKeywords = [
-      'ui', 'component', 'react', 'vue', 'angular', 'css', 'style',
-      'button', 'form', 'modal', 'layout', 'responsive', 'animation',
-      'dom', 'html', 'frontend', 'fe', 'client', 'browser', 'jsx', 'tsx'
-    ]
-
-    // Backend indicators
-    const backendKeywords = [
-      'api', 'server', 'database', 'db', 'endpoint', 'route', 'handler',
-      'controller', 'service', 'repository', 'model', 'query', 'backend',
-      'be', 'rest', 'graphql', 'prisma', 'sql', 'redis', 'auth'
-    ]
-
-    // DevOps indicators
-    const devopsKeywords = [
-      'deploy', 'docker', 'kubernetes', 'k8s', 'ci', 'cd', 'pipeline',
-      'terraform', 'ansible', 'aws', 'gcp', 'azure', 'config', 'nginx',
-      'devops', 'infrastructure', 'monitoring', 'logging', 'build'
-    ]
-
-    // Docs indicators
-    const docsKeywords = [
-      'document', 'docs', 'readme', 'changelog', 'comment', 'jsdoc',
-      'tutorial', 'guide', 'explain', 'describe', 'markdown'
-    ]
-
-    // Testing indicators
-    const testingKeywords = [
-      'test', 'spec',
-      // JS/TS
-      'bun', 'bun test', 'jest', 'mocha', 'cypress', 'playwright',
-      // Python
-      'pytest', 'unittest',
-      // Go
-      'go test',
-      // Rust
-      'cargo test',
-      // .NET
-      'dotnet test',
-      // Java
-      'mvn test', 'gradle test', 'gradlew test',
-      'e2e', 'unit', 'integration', 'coverage', 'mock', 'fixture'
-    ]
-
-    // Count matches
+    const words = taskDescription.toLowerCase().split(/\s+/)
     const scores: Record<ContextDomain, number> = {
-      frontend: frontendKeywords.filter(k => lower.includes(k)).length,
-      backend: backendKeywords.filter(k => lower.includes(k)).length,
-      devops: devopsKeywords.filter(k => lower.includes(k)).length,
-      docs: docsKeywords.filter(k => lower.includes(k)).length,
-      testing: testingKeywords.filter(k => lower.includes(k)).length,
-      general: 0,
+      frontend: 0, backend: 0, devops: 0, docs: 0, testing: 0, general: 0
+    }
+
+    // Single pass: check each word against the map
+    for (const word of words) {
+      const domain = KEYWORD_DOMAIN_MAP.get(word)
+      if (domain) {
+        scores[domain]++
+      }
     }
 
     // Find primary and secondary domains
@@ -139,14 +109,16 @@ class SmartContext {
       agent => relevantDomains.includes(agent.domain)
     )
 
-    // Enrich with performance data
-    for (const agent of filteredAgents) {
-      const perf = await agentPerformanceTracker.getAgentPerformance(
-        projectId,
-        agent.name
-      )
+    // OPTIMIZED: Enrich with performance data in parallel
+    const perfPromises = filteredAgents.map(agent =>
+      agentPerformanceTracker.getAgentPerformance(projectId, agent.name)
+    )
+    const perfResults = await Promise.all(perfPromises)
+
+    for (let i = 0; i < filteredAgents.length; i++) {
+      const perf = perfResults[i]
       if (perf) {
-        agent.successRate = perf.successRate
+        filteredAgents[i].successRate = perf.successRate
       }
     }
 

package/core/agentic/token-estimator.ts

@@ -0,0 +1,264 @@
+/**
+ * Token Budget Estimator
+ * Estimates token usage and provides context filtering for large projects.
+ *
+ * This prevents context overflow by:
+ * - Estimating token count before sending to Claude
+ * - Prioritizing critical context over nice-to-have
+ * - Truncating or summarizing when needed
+ *
+ * @version 1.0.0
+ */
+
+export interface TokenEstimate {
+  total: number
+  breakdown: {
+    projectContext: number
+    agentContext: number
+    skillContext: number
+    userPrompt: number
+    systemPrompt: number
+  }
+  withinBudget: boolean
+  recommendations: string[]
+}
+
+export interface ContextSection {
+  name: string
+  content: string
+  priority: 'critical' | 'high' | 'medium' | 'low'
+  tokens: number
+}
+
+/**
+ * Approximate tokens per character ratio
+ * Claude uses ~4 characters per token on average for English text
+ * Code tends to be slightly more efficient (~3.5 chars/token)
+ */
+const CHARS_PER_TOKEN = 3.8
+
+/**
+ * Default token budgets by model
+ */
+const TOKEN_BUDGETS = {
+  'claude-3-opus': 200000,
+  'claude-3-sonnet': 200000,
+  'claude-3-haiku': 200000,
+  'claude-3.5-sonnet': 200000,
+  'claude-opus-4': 200000,
+  default: 100000, // Conservative default
+}
+
+/**
+ * Estimate tokens from string content
+ */
+export function estimateTokens(content: string): number {
+  if (!content) return 0
+  return Math.ceil(content.length / CHARS_PER_TOKEN)
+}
+
+/**
+ * Get token budget for a model
+ */
+export function getTokenBudget(model: string = 'default'): number {
+  return TOKEN_BUDGETS[model as keyof typeof TOKEN_BUDGETS] || TOKEN_BUDGETS.default
+}
+
+/**
+ * Estimate total context tokens
+ */
+export function estimateContext(sections: ContextSection[]): TokenEstimate {
+  const breakdown = {
+    projectContext: 0,
+    agentContext: 0,
+    skillContext: 0,
+    userPrompt: 0,
+    systemPrompt: 0,
+  }
+
+  let total = 0
+
+  for (const section of sections) {
+    const tokens = estimateTokens(section.content)
+    section.tokens = tokens
+    total += tokens
+
+    // Categorize for breakdown
+    if (section.name.includes('agent')) {
+      breakdown.agentContext += tokens
+    } else if (section.name.includes('skill')) {
+      breakdown.skillContext += tokens
+    } else if (section.name.includes('user') || section.name.includes('prompt')) {
+      breakdown.userPrompt += tokens
+    } else if (section.name.includes('system')) {
+      breakdown.systemPrompt += tokens
+    } else {
+      breakdown.projectContext += tokens
+    }
+  }
+
+  const budget = getTokenBudget()
+  const withinBudget = total < budget * 0.8 // Leave 20% buffer for response
+
+  const recommendations: string[] = []
+
+  if (!withinBudget) {
+    recommendations.push(`Context exceeds safe limit (${total} tokens vs ${Math.floor(budget * 0.8)} budget)`)
+
+    // Find sections that can be reduced
+    const lowPriority = sections.filter(s => s.priority === 'low')
+    if (lowPriority.length > 0) {
+      const lowTokens = lowPriority.reduce((sum, s) => sum + s.tokens, 0)
+      recommendations.push(`Remove low-priority sections to save ~${lowTokens} tokens`)
+    }
+
+    const mediumPriority = sections.filter(s => s.priority === 'medium')
+    if (mediumPriority.length > 0) {
+      const medTokens = mediumPriority.reduce((sum, s) => sum + s.tokens, 0)
+      recommendations.push(`Consider summarizing medium-priority sections (~${medTokens} tokens)`)
+    }
+  }
+
+  return {
+    total,
+    breakdown,
+    withinBudget,
+    recommendations,
+  }
+}
+
+/**
+ * Filter context to fit within budget
+ */
+export function filterContext(
+  sections: ContextSection[],
+  maxTokens?: number
+): { filtered: ContextSection[]; removed: string[]; totalTokens: number } {
+  const budget = maxTokens || getTokenBudget() * 0.8
+
+  // Sort by priority (critical first)
+  const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 }
+  const sorted = [...sections].sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority])
+
+  const filtered: ContextSection[] = []
+  const removed: string[] = []
+  let totalTokens = 0
+
+  for (const section of sorted) {
+    const sectionTokens = estimateTokens(section.content)
+
+    if (totalTokens + sectionTokens <= budget) {
+      filtered.push({ ...section, tokens: sectionTokens })
+      totalTokens += sectionTokens
+    } else if (section.priority === 'critical') {
+      // Critical sections are always included, even if over budget
+      filtered.push({ ...section, tokens: sectionTokens })
+      totalTokens += sectionTokens
+    } else {
+      removed.push(section.name)
+    }
+  }
+
+  return { filtered, removed, totalTokens }
+}
+
+/**
+ * Summarize content to reduce tokens
+ */
+export function summarizeForTokens(content: string, targetTokens: number): string {
+  const currentTokens = estimateTokens(content)
+
+  if (currentTokens <= targetTokens) {
+    return content
+  }
+
+  // Calculate target character count
+  const targetChars = targetTokens * CHARS_PER_TOKEN
+
+  // Split into lines and take priority lines
+  const lines = content.split('\n')
+
+  // Keep headers and first lines of sections
+  const priorityLines: string[] = []
+  let charCount = 0
+
+  for (const line of lines) {
+    const isHeader = line.startsWith('#') || line.startsWith('**')
+    const isImportant = line.includes('CRITICAL') || line.includes('IMPORTANT') || line.includes('TODO')
+
+    if (isHeader || isImportant) {
+      priorityLines.push(line)
+      charCount += line.length + 1
+    } else if (charCount < targetChars * 0.8) {
+      priorityLines.push(line)
+      charCount += line.length + 1
+    }
+
+    if (charCount >= targetChars) {
+      break
+    }
+  }
+
+  if (priorityLines.length < lines.length) {
+    priorityLines.push('')
+    priorityLines.push(`[... ${lines.length - priorityLines.length} lines truncated for context limit ...]`)
+  }
+
+  return priorityLines.join('\n')
+}
+
+/**
+ * Create context sections from project state
+ */
+export function createContextSections(
+  projectContext: string,
+  agentContext: string,
+  skillContext: string,
+  userPrompt: string
+): ContextSection[] {
+  return [
+    { name: 'user-prompt', content: userPrompt, priority: 'critical', tokens: 0 },
+    { name: 'agent-context', content: agentContext, priority: 'high', tokens: 0 },
+    { name: 'project-context', content: projectContext, priority: 'medium', tokens: 0 },
+    { name: 'skill-context', content: skillContext, priority: 'medium', tokens: 0 },
+  ]
+}
+
+/**
+ * Format token estimate for display
+ */
+export function formatEstimate(estimate: TokenEstimate): string {
+  const lines = [
+    '📊 Token Budget',
+    '',
+    `Total: ${estimate.total.toLocaleString()} tokens`,
+    '',
+    'Breakdown:',
+    `  Project: ${estimate.breakdown.projectContext.toLocaleString()}`,
+    `  Agents: ${estimate.breakdown.agentContext.toLocaleString()}`,
+    `  Skills: ${estimate.breakdown.skillContext.toLocaleString()}`,
+    `  Prompt: ${estimate.breakdown.userPrompt.toLocaleString()}`,
+    '',
+    `Status: ${estimate.withinBudget ? '✅ Within budget' : '⚠️ Over budget'}`,
+  ]
+
+  if (estimate.recommendations.length > 0) {
+    lines.push('')
+    lines.push('Recommendations:')
+    for (const rec of estimate.recommendations) {
+      lines.push(`  - ${rec}`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+export default {
+  estimateTokens,
+  getTokenBudget,
+  estimateContext,
+  filterContext,
+  summarizeForTokens,
+  createContextSections,
+  formatEstimate,
+}

package/core/infrastructure/path-manager.ts

@@ -115,20 +115,20 @@ class PathManager {
   /**
    * Ensure the project-specific global structure exists
    * Creates the layered directory structure for a project
+   * OPTIMIZED: Parallel directory creation
    */
   async ensureProjectStructure(projectId: string): Promise<string> {
     await this.ensureGlobalStructure()
 
     const projectPath = this.getGlobalProjectPath(projectId)
 
-    const layers = ['core', 'progress', 'planning', 'analysis', 'memory', 'agents']
+    // OPTIMIZED: Create all directories in parallel
+    const dirs = [
+      'core', 'progress', 'planning', 'analysis', 'memory', 'agents',
+      'planning/tasks', 'sessions', 'storage', 'context', 'sync'
+    ].map(dir => path.join(projectPath, dir))
 
-    for (const layer of layers) {
-      await fileHelper.ensureDir(path.join(projectPath, layer))
-    }
-
-    await fileHelper.ensureDir(path.join(projectPath, 'planning', 'tasks'))
-    await fileHelper.ensureDir(path.join(projectPath, 'sessions'))
+    await Promise.all(dirs.map(dir => fileHelper.ensureDir(dir)))
 
     return projectPath
   }