prjct-cli 0.28.1 → 0.28.3

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # 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
+
+**Agent Mentions (p.agent.{name}):**
+- New `agentId` field in agent frontmatter for identification
+- Users can invoke agents in prompts: `p.agent.backend help me...`
+- Format: `p.agent.workflow`, `p.agent.planner`, `p.agent.frontend`, etc.
+
+**Deprecated Commands Removed:**
+- `/p:now` - Use `/p:task` instead
+- `/p:feature` - Use `/p:task` instead
+- `/p:work` - Use `/p:task` instead
+
+**Notion Integration Removed:**
+- Removed entire `core/integrations/notion/` directory
+- Removed Notion skills and MCP config
+- Cleaned up type references
+
+**Code Cleanup:**
+- Removed `executeWithoutProject()` deprecated method
+- Cleaned dead code in prompt-builder arrays
+- Removed ARCHITECTURE.md (outdated)
+
+**Ship Template Enhancement:**
+- Version bump now REQUIRED before PR creation
+- CHANGELOG.md update now REQUIRED before PR creation
+- Better categorization of changes (Added/Fixed/Changed)
+
+---
+
 ## [0.28.1] - 2026-01-10
 
 ### Feature: @ Agent Mentions

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/prompt-builder.ts

@@ -283,7 +283,7 @@ class PromptBuilder {
 
     // Agent assignment (CONDITIONAL - only for code-modifying commands)
     const commandName = template.frontmatter?.name?.replace('p:', '') || ''
-    const agentCommands = ['now', 'build', 'feature', 'design', 'fix', 'bug', 'test', 'work', 'cleanup', 'spec']
+    const agentCommands = ['task', 'design', 'fix', 'bug', 'test', 'cleanup', 'spec']
     const needsAgent = agentCommands.includes(commandName)
 
     if (agent && needsAgent) {
@@ -332,7 +332,7 @@ class PromptBuilder {
     }
 
     // OPTIMIZED: Only include patterns for code-modifying commands
-    const codeCommands = ['now', 'build', 'feature', 'design', 'cleanup', 'fix', 'bug', 'test', 'init', 'spec', 'work']
+    const codeCommands = ['task', 'design', 'cleanup', 'fix', 'bug', 'test', 'init', 'spec']
     const needsPatterns = codeCommands.includes(commandName)
 
     // Include code patterns analysis for code-modifying commands

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/commands/command-data.ts

@@ -62,17 +62,6 @@ export const COMMANDS: CommandMeta[] = [
     requiresProject: true,
     features: ['Agentic type classification', '7-phase workflow', 'Git branch management', 'Task breakdown'],
   },
-  {
-    name: 'feature',
-    group: 'core',
-    description: 'DEPRECATED - Use /p:task instead',
-    usage: { claude: '/p:task "<description>"', terminal: 'prjct task "<description>"' },
-    params: '<description>',
-    implemented: true,
-    hasTemplate: true,
-    requiresProject: true,
-    deprecated: true,
-  },
   {
     name: 'spec',
     group: 'core',
@@ -83,28 +72,6 @@ export const COMMANDS: CommandMeta[] = [
     hasTemplate: true,
     requiresProject: true,
   },
-  {
-    name: 'now',
-    group: 'core',
-    description: 'DEPRECATED - Use /p:task instead',
-    usage: { claude: '/p:task "<description>"', terminal: 'prjct task "<description>"' },
-    params: '[task]',
-    implemented: true,
-    hasTemplate: true,
-    requiresProject: true,
-    deprecated: true,
-  },
-  {
-    name: 'work',
-    group: 'core',
-    description: 'DEPRECATED - Use /p:task instead',
-    usage: { claude: '/p:task "<description>"', terminal: 'prjct task "<description>"' },
-    params: '[task]',
-    implemented: true,
-    hasTemplate: true,
-    requiresProject: true,
-    deprecated: true,
-  },
   {
     name: 'pause',
     group: 'core',

package/core/commands/commands.ts

@@ -3,12 +3,12 @@
  *
  * MD-First Architecture - All state in Markdown files.
  *
- * COMMANDS (22 total):
- * - Workflow (5): work, done, next, pause, resume
- * - Planning (5): init, feature, bug, idea, spec
+ * COMMANDS (20 total):
+ * - Workflow (4): done, next, pause, resume
+ * - Planning (4): init, bug, idea, spec
  * - Shipping (1): ship
  * - Analytics (2): dash, help
- * - Maintenance (5): cleanup, design, recover, undo, redo, history
+ * - Maintenance (6): cleanup, design, recover, undo, redo, history
  * - Analysis (2): analyze, sync
  * - Setup (3): start, setup, migrateAll
  */
@@ -69,10 +69,6 @@ class PrjctCommands {
 
   // ========== Workflow Commands ==========
 
-  async work(task: string | null = null, projectPath: string = process.cwd()): Promise<CommandResult> {
-    return this.workflow.now(task, projectPath)
-  }
-
   async done(projectPath: string = process.cwd()): Promise<CommandResult> {
     return this.workflow.done(projectPath)
   }
@@ -95,10 +91,6 @@ class PrjctCommands {
     return this.planning.init(idea, projectPath)
   }
 
-  async feature(description: string, projectPath: string = process.cwd()): Promise<CommandResult> {
-    return this.planning.feature(description, projectPath)
-  }
-
   async bug(description: string, projectPath: string = process.cwd()): Promise<CommandResult> {
     return this.planning.bug(description, projectPath)
   }

package/core/commands/registry.ts

@@ -388,43 +388,6 @@ export class CommandRegistry {
     }
   }
 
-  /**
-   * Execute without requiring project (for init, setup commands)
-   * @deprecated Use execute() - it auto-detects based on command metadata
-   */
-  async executeWithoutProject<TParams = void>(
-    name: string,
-    params: TParams,
-    projectPath: string = process.cwd()
-  ): Promise<CommandResult> {
-    const handler = this.handlers.get(name)
-    if (handler) {
-      const context: ExecutionContext = {
-        projectId: '',
-        projectPath,
-        globalPath: '',
-        timestamp: getTimestamp(),
-      }
-      return handler.execute(params, context)
-    }
-
-    const handlerFn = this.handlerFns.get(name)
-    if (handlerFn) {
-      const context: ExecutionContext = {
-        projectId: '',
-        projectPath,
-        globalPath: '',
-        timestamp: getTimestamp(),
-      }
-      return handlerFn(params, context)
-    }
-
-    return {
-      success: false,
-      error: `Command not found: ${name}`,
-    }
-  }
-
   /**
    * Clear all registrations (useful for testing)
    */

package/core/index.ts

@@ -97,14 +97,12 @@ async function main(): Promise<void> {
       const param = parsedArgs.join(' ') || null
       const standardCommands: Record<string, (p: string | null) => Promise<CommandResult>> = {
         // Core workflow
-        work: (p) => commands.work(p),
         done: () => commands.done(),
         next: () => commands.next(),
         pause: (p) => commands.pause(p || ''),
         resume: (p) => commands.resume(p),
         // Planning
         init: (p) => commands.init(p),
-        feature: (p) => commands.feature(p || ''),
         bug: (p) => commands.bug(p || ''),
         idea: (p) => commands.idea(p || ''),
         spec: (p) => commands.spec(p),

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
   }