prjct-cli 0.28.2 → 0.28.3

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## [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/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/setup.ts

@@ -146,9 +146,34 @@ async function migrateProjectsCliVersion(): Promise<void> {
       .map(dirent => dirent.name)
 
     let migrated = 0
+    let configsCreated = 0
 
     for (const projectId of projectDirs) {
       const projectJsonPath = path.join(projectsDir, projectId, 'project.json')
+      const configDir = path.join(projectsDir, projectId, 'config')
+
+      // Ensure config directory exists for new config files
+      if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true })
+      }
+
+      // Create slash-commands.json if missing (v0.28+ feature)
+      const slashCommandsPath = path.join(configDir, 'slash-commands.json')
+      if (!fs.existsSync(slashCommandsPath)) {
+        const slashCommandsConfig = {
+          version: '1.0.0',
+          generatedAt: new Date().toISOString(),
+          note: 'Run /p:sync to regenerate with full command list',
+          commands: {
+            'p:task': { description: 'Start any task', category: 'workflow' },
+            'p:done': { description: 'Complete subtask', category: 'workflow' },
+            'p:ship': { description: 'Ship feature', category: 'shipping' },
+            'p:sync': { description: 'Sync project', category: 'planning' },
+          }
+        }
+        fs.writeFileSync(slashCommandsPath, JSON.stringify(slashCommandsConfig, null, 2))
+        configsCreated++
+      }
 
       if (!fs.existsSync(projectJsonPath)) {
         continue
@@ -172,6 +197,9 @@ async function migrateProjectsCliVersion(): Promise<void> {
     if (migrated > 0) {
       console.log(`   ${GREEN}✓${NC} Updated ${migrated} project(s) to v${VERSION}`)
     }
+    if (configsCreated > 0) {
+      console.log(`   ${GREEN}✓${NC} Created ${configsCreated} new config file(s)`)
+    }
   } catch {
     // Silently fail - migration is optional
   }

package/core/infrastructure/slash-command-registry.ts

@@ -0,0 +1,176 @@
+/**
+ * Slash Command Registry
+ * Generates Claude Code native slash command configuration.
+ *
+ * This enables:
+ * - Native /p:* command autocomplete in Claude Code
+ * - Command validation before execution
+ * - Command discoverability in help systems
+ *
+ * @version 1.0.0
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+
+export interface SlashCommand {
+  name: string
+  description: string
+  args?: string
+  category: 'workflow' | 'planning' | 'shipping' | 'analytics' | 'maintenance'
+  requiresProject: boolean
+  deprecated?: boolean
+  replacedBy?: string
+}
+
+export interface SlashCommandRegistry {
+  version: string
+  generatedAt: string
+  commands: Record<string, SlashCommand>
+}
+
+/**
+ * Core prjct commands with metadata
+ */
+const PRJCT_COMMANDS: SlashCommand[] = [
+  // Workflow
+  { name: 'task', description: 'Start any task with intelligent classification', args: '<description>', category: 'workflow', requiresProject: true },
+  { name: 'done', description: 'Complete current subtask', category: 'workflow', requiresProject: true },
+  { name: 'pause', description: 'Pause current task', category: 'workflow', requiresProject: true },
+  { name: 'resume', description: 'Resume paused task', category: 'workflow', requiresProject: true },
+  { name: 'next', description: 'Show next tasks in queue', category: 'workflow', requiresProject: true },
+
+  // Planning
+  { name: 'init', description: 'Initialize prjct in current directory', args: '[description]', category: 'planning', requiresProject: false },
+  { name: 'sync', description: 'Deep sync - analyze project, generate agents', category: 'planning', requiresProject: true },
+  { name: 'idea', description: 'Capture an idea for later', args: '<idea>', category: 'planning', requiresProject: true },
+  { name: 'spec', description: 'Generate feature specification', args: '<feature>', category: 'planning', requiresProject: true },
+  { name: 'bug', description: 'Report a bug with auto-priority', args: '<description>', category: 'planning', requiresProject: true },
+
+  // Shipping
+  { name: 'ship', description: 'Ship feature with PR workflow', args: '[feature]', category: 'shipping', requiresProject: true },
+  { name: 'review', description: 'Run code review on changes', category: 'shipping', requiresProject: true },
+  { name: 'test', description: 'Run tests for current changes', category: 'shipping', requiresProject: true },
+  { name: 'verify', description: 'Verify deployment', category: 'shipping', requiresProject: true },
+
+  // Analytics
+  { name: 'dash', description: 'Show project dashboard', category: 'analytics', requiresProject: true },
+  { name: 'history', description: 'Show task history', category: 'analytics', requiresProject: true },
+  { name: 'analyze', description: 'Analyze codebase', category: 'analytics', requiresProject: true },
+
+  // Maintenance
+  { name: 'cleanup', description: 'Clean up project files', category: 'maintenance', requiresProject: true },
+  { name: 'undo', description: 'Undo last action', category: 'maintenance', requiresProject: true },
+  { name: 'redo', description: 'Redo undone action', category: 'maintenance', requiresProject: true },
+
+  // Deprecated
+  { name: 'now', description: 'Start task (deprecated)', args: '<task>', category: 'workflow', requiresProject: true, deprecated: true, replacedBy: 'task' },
+  { name: 'feature', description: 'Plan feature (deprecated)', args: '<feature>', category: 'planning', requiresProject: true, deprecated: true, replacedBy: 'task' },
+]
+
+/**
+ * Generate slash command registry for Claude Code
+ */
+export async function generateRegistry(): Promise<SlashCommandRegistry> {
+  const commands: Record<string, SlashCommand> = {}
+
+  for (const cmd of PRJCT_COMMANDS) {
+    commands[`p:${cmd.name}`] = cmd
+  }
+
+  return {
+    version: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    commands,
+  }
+}
+
+/**
+ * Write registry to project's global path
+ */
+export async function writeRegistry(projectId: string): Promise<{ success: boolean; path?: string; error?: string }> {
+  try {
+    const globalPath = path.join(os.homedir(), '.prjct-cli', 'projects', projectId, 'config')
+    await fs.mkdir(globalPath, { recursive: true })
+
+    const registry = await generateRegistry()
+    const registryPath = path.join(globalPath, 'slash-commands.json')
+
+    await fs.writeFile(registryPath, JSON.stringify(registry, null, 2), 'utf-8')
+
+    return { success: true, path: registryPath }
+  } catch (error) {
+    return { success: false, error: (error as Error).message }
+  }
+}
+
+/**
+ * Get command by name
+ */
+export function getCommand(name: string): SlashCommand | undefined {
+  return PRJCT_COMMANDS.find(cmd => cmd.name === name)
+}
+
+/**
+ * Get all commands by category
+ */
+export function getCommandsByCategory(category: SlashCommand['category']): SlashCommand[] {
+  return PRJCT_COMMANDS.filter(cmd => cmd.category === category && !cmd.deprecated)
+}
+
+/**
+ * Validate command exists
+ */
+export function validateCommand(name: string): { valid: boolean; command?: SlashCommand; error?: string } {
+  const cmd = getCommand(name)
+
+  if (!cmd) {
+    return { valid: false, error: `Unknown command: ${name}` }
+  }
+
+  if (cmd.deprecated) {
+    return {
+      valid: true,
+      command: cmd,
+      error: `Command '${name}' is deprecated. Use '${cmd.replacedBy}' instead.`,
+    }
+  }
+
+  return { valid: true, command: cmd }
+}
+
+/**
+ * Format commands for help display
+ */
+export function formatHelpText(): string {
+  const categories = ['workflow', 'planning', 'shipping', 'analytics', 'maintenance'] as const
+  const lines: string[] = ['# prjct Commands', '']
+
+  for (const category of categories) {
+    const cmds = getCommandsByCategory(category)
+    if (cmds.length === 0) continue
+
+    lines.push(`## ${category.charAt(0).toUpperCase() + category.slice(1)}`)
+    lines.push('')
+
+    for (const cmd of cmds) {
+      const args = cmd.args ? ` ${cmd.args}` : ''
+      lines.push(`- \`/p:${cmd.name}${args}\` - ${cmd.description}`)
+    }
+
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+export default {
+  generateRegistry,
+  writeRegistry,
+  getCommand,
+  getCommandsByCategory,
+  validateCommand,
+  formatHelpText,
+  PRJCT_COMMANDS,
+}

package/core/types/integrations.ts

@@ -3,10 +3,37 @@
  * Types for external service integrations
  */
 
+/**
+ * MCP Server Configuration
+ */
+export interface McpServerConfig {
+  name: string
+  description?: string
+  command: string
+  args: string[]
+  enabled: boolean
+  linkedAgents?: string[]
+  autoLoad?: boolean
+  setupAt?: string
+}
+
+/**
+ * MCP Servers Configuration for a project
+ */
+export interface McpServersConfig {
+  projectId: string
+  version: string
+  servers: Record<string, McpServerConfig>
+  agentMcpMap: Record<string, string[]>
+}
+
 /**
  * Integrations Config
  * Container for all external integrations
  */
 export interface IntegrationsConfig {
-  // Future integrations can be added here
+  mcp?: {
+    enabled: boolean
+    configPath: string
+  }
 }

package/package.json

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