prjct-cli 0.19.0 → 0.20.1

package/templates/subagents/domain/devops.md

@@ -59,7 +59,7 @@ jobs:
         with:
           node-version: '20'
       - run: npm ci
-      - run: npm test
+      - run: npm test  # or pnpm test / yarn test / bun test depending on the repo
 ```
 
 ### docker-compose

package/templates/subagents/domain/testing.md

@@ -1,6 +1,6 @@
 ---
 name: testing
-description: Testing specialist for Jest, Vitest, Pytest, and testing libraries. Use PROACTIVELY when user works on tests, coverage, or test infrastructure.
+description: Testing specialist for Bun test, Jest, Pytest, and testing libraries. Use PROACTIVELY when user works on tests, coverage, or test infrastructure.
 tools: Read, Write, Bash
 model: sonnet
 ---
@@ -9,7 +9,7 @@ You are a testing specialist agent for this project.
 
 ## Your Expertise
 
-- **JS/TS**: Jest, Vitest, Mocha, Bun test
+- **JS/TS**: Bun test, Jest, Mocha
 - **React**: Testing Library, Enzyme
 - **Python**: Pytest, unittest
 - **Go**: testing package, testify
@@ -18,15 +18,15 @@ You are a testing specialist agent for this project.
 ## Project Context
 
 When invoked, analyze the project's testing setup:
-1. Check for test config (jest.config.js, vitest.config.ts, pytest.ini)
+1. Check for test config (bunfig.toml, jest.config.js, pytest.ini)
 2. Identify test file patterns
 3. Check for existing test utilities
 
 ## Code Patterns
 
-### Vitest/Jest (Unit)
+### Bun (Unit)
 ```typescript
-import { describe, it, expect, vi } from 'vitest'
+import { describe, it, expect, mock } from 'bun:test'
 import { calculateTotal } from './cart'
 
 describe('calculateTotal', () => {
@@ -48,7 +48,7 @@ import { Button } from './Button'
 
 describe('Button', () => {
   it('calls onClick when clicked', () => {
-    const onClick = vi.fn()
+    const onClick = mock(() => {})
     render(<Button onClick={onClick}>Click me</Button>)
 
     fireEvent.click(screen.getByRole('button'))
@@ -118,7 +118,6 @@ func TestCalculateTotal(t *testing.T) {
 # JavaScript
 npm test
 bun test
-vitest run
 
 # Python
 pytest
@@ -131,9 +130,6 @@ go test -cover ./...
 
 ### Coverage
 ```bash
-# Vitest
-vitest run --coverage
-
 # Jest
 jest --coverage
 

package/templates/subagents/workflow/prjct-shipper.md

@@ -30,13 +30,22 @@ Run in sequence, stop on failure:
 
 ```bash
 # 1. Lint (if configured)
-npm run lint || bun run lint
+# Use the project's own tooling (do not assume JS/Bun).
+# Examples:
+# - JS: pnpm run lint / yarn lint / npm run lint / bun run lint
+# - Python: ruff/flake8 (only if project already uses it)
 
-# 2. Type check (if TypeScript)
-npm run typecheck || tsc --noEmit
+# 2. Type check (if configured)
+# - TS: pnpm run typecheck / yarn typecheck / npm run typecheck / bun run typecheck
 
 # 3. Tests (if configured)
-npm test || bun test
+# Use the project's own test runner:
+# - JS: {packageManager} test (e.g. pnpm test, yarn test, npm test, bun test)
+# - Python: pytest
+# - Go: go test ./...
+# - Rust: cargo test
+# - .NET: dotnet test
+# - Java: mvn test / ./gradlew test
 ```
 
 If any fail:
@@ -125,12 +134,12 @@ Read from `.prjct/ship.config.json` if exists:
     "typecheck": true,
     "test": true
   },
-  "testCommand": "bun test",
-  "lintCommand": "bun run lint"
+  "testCommand": "pytest",
+  "lintCommand": "npm run lint"
 }
 ```
 
-If no config, auto-detect from package.json scripts.
+If no config, auto-detect from the repository (package.json scripts, pytest.ini, Cargo.toml, go.mod, etc.).
 
 ## Dry Run Mode
 

package/templates/tools/bash.txt

@@ -0,0 +1,22 @@
+Execute shell commands in a persistent bash session.
+
+Use this tool for terminal operations like git, npm, docker, build commands, and system utilities. NOT for file operations (use Read, Write, Edit instead).
+
+Capabilities:
+- Run any shell command
+- Persistent session (environment persists between calls)
+- Support for background execution
+- Configurable timeout (up to 10 minutes)
+
+Best practices:
+- Quote paths with spaces using double quotes
+- Use absolute paths to avoid cd
+- Chain dependent commands with &&
+- Run independent commands in parallel (multiple tool calls)
+- Never use for file reading (use Read tool)
+- Never use echo/printf to communicate (output text directly)
+
+Git operations:
+- Never update git config
+- Never use destructive commands without explicit request
+- Always use HEREDOC for commit messages

package/templates/tools/edit.txt

@@ -0,0 +1,18 @@
+Edit files using exact string replacement.
+
+Use this tool to make precise changes to existing files. Requires reading the file first to ensure accurate matching.
+
+Capabilities:
+- Replace exact string matches in files
+- Support for replace_all to change all occurrences
+- Preserves file formatting and indentation
+
+Requirements:
+- Must read the file first (tool will error otherwise)
+- old_string must be unique in the file (or use replace_all)
+- Preserve exact indentation from the original
+
+Best practices:
+- Include enough context to make old_string unique
+- Use replace_all for renaming variables/functions
+- Never include line numbers in old_string or new_string

package/templates/tools/glob.txt

@@ -0,0 +1,19 @@
+Find files by pattern matching.
+
+Use this tool to locate files using glob patterns. Fast and efficient for any codebase size.
+
+Capabilities:
+- Match files using glob patterns (e.g., "**/*.ts", "src/**/*.tsx")
+- Returns paths sorted by modification time
+- Works with any codebase size
+
+Pattern examples:
+- "**/*.ts" - all TypeScript files
+- "src/**/*.tsx" - React components in src
+- "**/test*.ts" - test files anywhere
+- "core/**/*" - all files in core directory
+
+Best practices:
+- Use specific patterns to narrow results
+- Prefer glob over bash find command
+- Run multiple patterns in parallel if needed

package/templates/tools/grep.txt

@@ -0,0 +1,21 @@
+Search file contents using regex patterns.
+
+Use this tool to search for code patterns, function definitions, imports, and text across the codebase. Built on ripgrep for speed.
+
+Capabilities:
+- Full regex syntax support
+- Filter by file type or glob pattern
+- Multiple output modes: files_with_matches, content, count
+- Context lines before/after matches (-A, -B, -C)
+- Multiline matching support
+
+Output modes:
+- files_with_matches (default): just file paths
+- content: matching lines with context
+- count: match counts per file
+
+Best practices:
+- Use specific patterns to reduce noise
+- Filter by file type when possible (type: "ts")
+- Use content mode with context for understanding matches
+- Never use bash grep/rg directly (use this tool)

package/templates/tools/read.txt

@@ -0,0 +1,14 @@
+Read files from the filesystem.
+
+Use this tool to read file contents before making edits. Always read a file before attempting to modify it to understand the current state and structure.
+
+Capabilities:
+- Read any text file by absolute path
+- Supports line offset and limit for large files
+- Returns content with line numbers for easy reference
+- Can read images, PDFs, and Jupyter notebooks
+
+Best practices:
+- Always read before editing
+- Use offset/limit for files > 2000 lines
+- Read multiple related files in parallel when exploring

package/templates/tools/task.txt

@@ -0,0 +1,20 @@
+Launch specialized agents for complex tasks.
+
+Use this tool to delegate multi-step tasks to autonomous agents. Each agent type has specific capabilities and tools.
+
+Agent types:
+- Explore: Fast codebase exploration, file search, pattern finding
+- Plan: Software architecture, implementation planning
+- general-purpose: Research, code search, multi-step tasks
+
+When to use:
+- Complex multi-step tasks
+- Open-ended exploration
+- When multiple search rounds may be needed
+- Tasks matching agent descriptions
+
+Best practices:
+- Provide clear, detailed prompts
+- Launch multiple agents in parallel when independent
+- Use Explore for codebase questions
+- Use Plan for implementation design

package/templates/tools/webfetch.txt

@@ -0,0 +1,16 @@
+Fetch and analyze web content.
+
+Use this tool to retrieve content from URLs and process it with AI. Useful for documentation, API references, and external resources.
+
+Capabilities:
+- Fetch any URL content
+- Automatic HTML to markdown conversion
+- AI-powered content extraction based on prompt
+- 15-minute cache for repeated requests
+- Automatic HTTP to HTTPS upgrade
+
+Best practices:
+- Provide specific prompts for extraction
+- Handle redirects by following the provided URL
+- Use for documentation and reference lookup
+- Results may be summarized for large content

package/templates/tools/websearch.txt

@@ -0,0 +1,18 @@
+Search the web for current information.
+
+Use this tool to find up-to-date information beyond the knowledge cutoff. Returns search results with links.
+
+Capabilities:
+- Real-time web search
+- Domain filtering (allow/block specific sites)
+- Returns formatted results with URLs
+
+Requirements:
+- MUST include Sources section with URLs after answering
+- Use current year in queries for recent info
+
+Best practices:
+- Be specific in search queries
+- Include year for time-sensitive searches
+- Always cite sources in response
+- Filter domains when targeting specific sites

package/templates/tools/write.txt

@@ -0,0 +1,17 @@
+Write or create files on the filesystem.
+
+Use this tool to create new files or completely overwrite existing ones. For modifications to existing files, prefer the Edit tool instead.
+
+Capabilities:
+- Create new files with specified content
+- Overwrite existing files completely
+- Create parent directories automatically
+
+Requirements:
+- Must read existing file first before overwriting
+- Use absolute paths only
+
+Best practices:
+- Prefer Edit for modifications to existing files
+- Only create new files when truly necessary
+- Never create documentation files unless explicitly requested

package/core/agentic/command-executor/command-executor.ts

@@ -1,312 +0,0 @@
-/**
- * Command Executor Class
- * Orchestrates command execution with agentic delegation.
- */
-
-import path from 'path'
-import os from 'os'
-import templateLoader from '../template-loader'
-import contextBuilder from '../context-builder'
-import promptBuilder from '../prompt-builder'
-import toolRegistry from '../tool-registry'
-import loopDetector from '../loop-detector'
-import chainOfThought from '../chain-of-thought'
-import memorySystem from '../memory-system'
-import groundTruth from '../ground-truth'
-import planMode from '../plan-mode'
-import { signalStart, signalEnd } from './status-signal'
-import type { ExecutionResult, SimpleExecutionResult, ExecutionToolsFn } from './types'
-
-export class CommandExecutor {
-  /**
-   * Signal that a command is running (for status line)
-   */
-  signalStart(commandName: string): void {
-    signalStart(commandName)
-  }
-
-  /**
-   * Signal that command has finished (for status line)
-   */
-  signalEnd(): void {
-    signalEnd()
-  }
-
-  /**
-   * Execute a prjct command with full agentic delegation
-   */
-  async execute(
-    commandName: string,
-    params: Record<string, unknown>,
-    projectPath: string
-  ): Promise<ExecutionResult> {
-    // Signal start for status line
-    this.signalStart(commandName)
-
-    // Context for loop detection
-    const loopContext = (params.task as string) || (params.description as string) || ''
-
-    // Check if we're in a loop BEFORE attempting
-    if (loopDetector.shouldEscalate(commandName, loopContext)) {
-      const escalation = loopDetector.getEscalationInfo(commandName, loopContext)
-      this.signalEnd()
-      return {
-        success: false,
-        error: escalation?.message,
-        escalation,
-        isLoopDetected: true,
-        suggestion: escalation?.suggestion,
-      }
-    }
-
-    try {
-      // 1. Load template
-      const template = await templateLoader.load(commandName)
-
-      // 2. Build METADATA context only (lazy loading - no file reads yet)
-      const metadataContext = await contextBuilder.build(projectPath, params)
-
-      // 2.55. P3.4 PLAN MODE: Check if command requires planning
-      const requiresPlanning = planMode.requiresPlanning(commandName)
-      const isDestructive = planMode.isDestructive(commandName)
-      const isInPlanningMode = planMode.isInPlanningMode(metadataContext.projectId!)
-
-      // Start planning mode if required and not already in it
-      let activePlan = null
-      if (requiresPlanning && !isInPlanningMode && !params.skipPlanning) {
-        activePlan = planMode.startPlanning(metadataContext.projectId!, commandName, params)
-      } else if (isInPlanningMode) {
-        activePlan = planMode.getActivePlan(metadataContext.projectId!)
-      }
-
-      // 2.6. GROUND TRUTH: Verify actual state before critical operations
-      let groundTruthResult = null
-      if (groundTruth.requiresVerification(commandName)) {
-        const preState = await contextBuilder.loadStateForCommand(metadataContext, commandName)
-        groundTruthResult = await groundTruth.verify(
-          commandName,
-          metadataContext as unknown as Parameters<typeof groundTruth.verify>[1],
-          preState
-        )
-
-        // Log warnings but don't block (user can override)
-        if (!groundTruthResult.verified && groundTruthResult.warnings.length > 0) {
-          console.log(groundTruth.formatWarnings(groundTruthResult))
-        }
-      }
-
-      // 2.8. CHAIN OF THOUGHT: Reasoning for critical commands
-      let reasoning = null
-      if (chainOfThought.requiresReasoning(commandName)) {
-        const reasoningState = await contextBuilder.loadStateForCommand(metadataContext, commandName)
-        reasoning = await chainOfThought.reason(
-          commandName,
-          metadataContext as unknown as Parameters<typeof chainOfThought.reason>[1],
-          reasoningState as Parameters<typeof chainOfThought.reason>[2]
-        )
-
-        // If reasoning shows critical issues, warn but continue
-        if (reasoning.reasoning && !reasoning.reasoning.allPassed) {
-          console.log('⚠️  Chain of Thought detected issues:')
-          console.log(chainOfThought.formatPlan(reasoning))
-        }
-      }
-
-      // 3. AGENTIC: Claude decides agent assignment via templates
-      let context: Record<string, unknown> = metadataContext as unknown as Record<string, unknown>
-
-      // Provide agent info to context so Claude can delegate
-      context = {
-        ...context,
-        agentsPath: path.join(os.homedir(), '.prjct-cli', 'projects', metadataContext.projectId || '', 'agents'),
-        agentRoutingPath: path.join(__dirname, '..', '..', '..', 'templates', 'agentic', 'agent-routing.md'),
-        agenticDelegation: true,
-      }
-
-      // 6. Load state with filtered context
-      const state = await contextBuilder.loadState(metadataContext)
-
-      // 7. MEMORY: Load learned patterns AND relevant memories for this command
-      let learnedPatterns = null
-      let relevantMemories = null
-      if (metadataContext.projectId) {
-        learnedPatterns = {
-          commit_footer: await memorySystem.getSmartDecision(metadataContext.projectId, 'commit_footer'),
-          branch_naming: await memorySystem.getSmartDecision(metadataContext.projectId, 'branch_naming'),
-          test_before_ship: await memorySystem.getSmartDecision(metadataContext.projectId, 'test_before_ship'),
-          preferred_agent: await memorySystem.getSmartDecision(
-            metadataContext.projectId,
-            `preferred_agent_${commandName}`
-          ),
-        }
-
-        // P3.3: Get relevant memories for context
-        relevantMemories = await memorySystem.getRelevantMemories(
-          metadataContext.projectId,
-          { commandName, params },
-          5
-        )
-      }
-
-      // 9. Build prompt - NO agent assignment here, Claude decides 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(
-        template,
-        context as Parameters<typeof promptBuilder.build>[1],
-        state,
-        null,
-        learnedPatterns,
-        null,
-        relevantMemories,
-        planInfo
-      )
-
-      // Log agentic mode
-      console.log(`🤖 Agentic delegation enabled - Claude will assign agent via Task tool`)
-
-      // Record successful attempt
-      loopDetector.recordSuccess(commandName, loopContext)
-
-      // Signal end for status line
-      this.signalEnd()
-
-      return {
-        success: true,
-        template,
-        context,
-        state,
-        prompt,
-        agenticDelegation: true,
-        agentsPath: context.agentsPath as string,
-        agentRoutingPath: context.agentRoutingPath as string,
-        reasoning,
-        groundTruth: groundTruthResult,
-        learnedPatterns,
-        relevantMemories,
-        memory: {
-          create: (memory: unknown) =>
-            memorySystem.createMemory(metadataContext.projectId!, memory as Parameters<typeof memorySystem.createMemory>[1]),
-          autoRemember: (type: string, value: string, ctx?: string) =>
-            memorySystem.autoRemember(metadataContext.projectId!, type, value, ctx),
-          search: (query: string) => memorySystem.searchMemories(metadataContext.projectId!, query),
-          findByTags: (tags: string[]) => memorySystem.findByTags(metadataContext.projectId!, tags),
-          getStats: () => memorySystem.getMemoryStats(metadataContext.projectId!),
-        },
-        plan: {
-          active: activePlan,
-          isPlanning: requiresPlanning || isInPlanningMode,
-          isDestructive,
-          requiresApproval: isDestructive && !params.approved,
-          recordInfo: (info: unknown) =>
-            planMode.recordGatheredInfo(metadataContext.projectId!, info as Parameters<typeof planMode.recordGatheredInfo>[1]),
-          setAnalysis: (analysis: unknown) => planMode.setAnalysis(metadataContext.projectId!, analysis),
-          propose: (plan: unknown) =>
-            planMode.proposePlan(metadataContext.projectId!, plan as Parameters<typeof planMode.proposePlan>[1]),
-          approve: (feedback?: string | null) => planMode.approvePlan(metadataContext.projectId!, feedback),
-          reject: (reason?: string | null) => planMode.rejectPlan(metadataContext.projectId!, reason),
-          getApprovalPrompt: () =>
-            planMode.generateApprovalPrompt(commandName, context as Parameters<typeof planMode.generateApprovalPrompt>[1]),
-          startExecution: () => planMode.startExecution(metadataContext.projectId!),
-          getNextStep: () => planMode.getNextStep(metadataContext.projectId!),
-          completeStep: (result?: unknown) => planMode.completeStep(metadataContext.projectId!, result),
-          failStep: (error: string) => planMode.failStep(metadataContext.projectId!, error),
-          abort: (reason?: string) => planMode.abortPlan(metadataContext.projectId!, reason),
-          getStatus: () => planMode.formatStatus(metadataContext.projectId!),
-          getAllowedTools: () =>
-            planMode.getAllowedTools(isInPlanningMode, template.frontmatter['allowed-tools'] || []),
-        },
-      }
-    } catch (error) {
-      // Signal end for status line
-      this.signalEnd()
-
-      // Record failed attempt for loop detection
-      const attemptInfo = loopDetector.recordAttempt(commandName, loopContext, {
-        success: false,
-        error: (error as Error).message,
-      })
-
-      // Check if we should escalate after this failure
-      if (attemptInfo.shouldEscalate) {
-        const escalation = loopDetector.getEscalationInfo(commandName, loopContext)
-        return {
-          success: false,
-          error: escalation?.message,
-          escalation,
-          isLoopDetected: true,
-          suggestion: escalation?.suggestion,
-        }
-      }
-
-      return {
-        success: false,
-        error: (error as Error).message,
-        attemptNumber: attemptInfo.attemptNumber,
-        isLooping: attemptInfo.isLooping,
-      }
-    }
-  }
-
-  /**
-   * Execute tool with permission check
-   */
-  async executeTool(toolName: string, args: unknown[], allowedTools: string[]): Promise<unknown> {
-    // Check if tool is allowed
-    if (!toolRegistry.isAllowed(toolName, allowedTools)) {
-      throw new Error(`Tool ${toolName} not allowed for this command`)
-    }
-
-    // Get tool function
-    const tool = toolRegistry.get(toolName)
-    if (!tool) {
-      throw new Error(`Tool ${toolName} not found`)
-    }
-
-    // Execute tool
-    return await tool(...args)
-  }
-
-  /**
-   * Simple execution for direct tool access (legacy migration helper)
-   */
-  async executeSimple(
-    commandName: string,
-    executionFn: ExecutionToolsFn,
-    projectPath: string
-  ): Promise<SimpleExecutionResult> {
-    try {
-      // Load template to get allowed tools
-      const template = await templateLoader.load(commandName)
-      const allowedTools = template.frontmatter['allowed-tools'] || []
-
-      // Build context
-      const context = await contextBuilder.build(projectPath)
-
-      // Create tools proxy that checks permissions
-      const tools = {
-        read: async (filePath: string) => this.executeTool('Read', [filePath], allowedTools),
-        write: async (filePath: string, content: string) => this.executeTool('Write', [filePath, content], allowedTools),
-        bash: async (command: string) => this.executeTool('Bash', [command], allowedTools),
-      }
-
-      // Execute user function with tools
-      const result = await executionFn(tools, context)
-
-      return {
-        success: true,
-        result,
-      }
-    } catch (error) {
-      return {
-        success: false,
-        error: (error as Error).message,
-      }
-    }
-  }
-}

package/core/agentic/command-executor/index.ts

@@ -1,16 +0,0 @@
-/**
- * Command Executor
- * Orchestrates command execution with agentic delegation.
- *
- * @module agentic/command-executor
- * @version 3.4
- */
-
-export type { ExecutionResult, SimpleExecutionResult, ExecutionToolsFn } from './types'
-export { signalStart, signalEnd } from './status-signal'
-export { CommandExecutor } from './command-executor'
-
-import { CommandExecutor } from './command-executor'
-
-const commandExecutor = new CommandExecutor()
-export default commandExecutor

package/core/agentic/command-executor/status-signal.ts

@@ -1,38 +0,0 @@
-/**
- * Status Signal
- * Running file for status line integration
- */
-
-import fs from 'fs'
-import path from 'path'
-import os from 'os'
-
-const RUNNING_FILE = path.join(os.homedir(), '.prjct-cli', '.running')
-
-/**
- * Signal that a command is running (for status line)
- */
-export function signalStart(commandName: string): void {
-  try {
-    const dir = path.dirname(RUNNING_FILE)
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true })
-    }
-    fs.writeFileSync(RUNNING_FILE, `/p:${commandName}`)
-  } catch {
-    // Silently ignore - status line is optional
-  }
-}
-
-/**
- * Signal that command has finished (for status line)
- */
-export function signalEnd(): void {
-  try {
-    if (fs.existsSync(RUNNING_FILE)) {
-      fs.unlinkSync(RUNNING_FILE)
-    }
-  } catch {
-    // Silently ignore - status line is optional
-  }
-}