@compilr-dev/sdk 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -43,7 +43,9 @@ export { resolveProvider, detectProviderFromEnv, createProviderFromType } from '
 export { DEFAULT_MODELS, getContextWindow, DEFAULT_CONTEXT_WINDOW } from './models.js';
 export { type ModelTier, type TierInfo, type ProviderModelMap, MODEL_TIERS, TIER_INFO, isValidTier, type ThinkingFormat, type ModelStatus, type ModelInfo, MODEL_REGISTRY, getModelsForProvider, getModelsSortedForDisplay, getModelInfo, isKnownModel, isModelSupported, getThinkingFormat, getStatusIndicator, getStatusLabel, getDefaultModelForTier, areThinkingFormatsCompatible, shouldClearHistoryOnModelChange, getModelContextWindow, getModelDisplayName, getModelDescription, getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefaultTierMappings, type ProviderMetadata, type OthersProviderModel, PROVIDER_METADATA, TOGETHER_MODELS, GROQ_MODELS, FIREWORKS_MODELS, PERPLEXITY_MODELS, OPENROUTER_MODELS, getModelsForOthersProvider, getOthersProviders, getProviderMetadata, isOthersProvider, } from './models/index.js';
 export { assembleTools, deduplicateTools } from './tools.js';
-export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
-export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPManager, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
+export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
+export type { SystemPromptContext, BuildResult, SystemPromptModule, ModuleConditions, } from './system-prompt/index.js';
+export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, MCPManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
+export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
 export { readFileTool, writeFileTool, createBashTool, bashTool, bashOutputTool, killShellTool, grepTool, globTool, editTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, webFetchTool, suggestTool, } from '@compilr-dev/agents';
 export { gitStatusTool, gitDiffTool, gitLogTool, gitCommitTool, gitBranchTool, gitStashTool, gitBlameTool, gitFileHistoryTool, detectProjectTool, findProjectRootTool, runTestsTool, runLintTool, runBuildTool, runFormatTool, findDefinitionTool, findReferencesTool, findTodosTool, checkOutdatedTool, findVulnerabilitiesTool, analyzeTestCoverageTool, getFileStructureTool, getComplexityTool, allCodingTools, unifiedTools, } from '@compilr-dev/agents-coding';

package/dist/index.js

@@ -61,6 +61,16 @@ getModelForTier, getTierMappings, getTierDisplayName, getShortModelName, getDefa
 // =============================================================================
 export { assembleTools, deduplicateTools } from './tools.js';
 // =============================================================================
+// System Prompt Builder
+// =============================================================================
+export { 
+// Builder
+SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, 
+// Module constants
+ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, 
+// Module utilities
+shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './system-prompt/index.js';
+// =============================================================================
 // Re-exports from @compilr-dev/agents (convenience — no need to install separately)
 // =============================================================================
 export { 
@@ -84,6 +94,8 @@ TOOL_NAMES, getDefaultShellManager,
 builtinSkills, 
 // Anchors
 AnchorManager, 
+// MCP (class — used as value in dynamic imports)
+MCPManager, 
 // Error types
 AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
 // =============================================================================

package/dist/system-prompt/builder.d.ts

@@ -0,0 +1,115 @@
+/**
+ * System Prompt Builder
+ *
+ * Assembles system prompt from modules based on current context.
+ * Provides ~50% token reduction by only including relevant modules.
+ *
+ * Git/CWD detection is injectable via SystemPromptContext for non-Node environments.
+ * Falls back to execSync detection in Node.js when not provided.
+ */
+import { type SystemPromptModule } from './modules.js';
+/**
+ * Context used to determine which modules to include
+ */
+export interface SystemPromptContext {
+    /** Is the current directory a git repository? */
+    hasGit?: boolean;
+    /** Current workflow mode */
+    mode?: 'flexible' | 'guided' | 'plan';
+    /** Is there an active project? */
+    hasProject?: boolean;
+    /** Are meta-tools enabled? */
+    enableMetaTools?: boolean;
+    /** Does the agent have a role-specific identity? (team agents) */
+    hasRoleIdentity?: boolean;
+    /** Active project name (for explicit identification) */
+    projectName?: string;
+    /** Project context from COMPILR.md (appended at end) */
+    projectContext?: string;
+    /** Guided mode context (appended at end) */
+    guidedModeContext?: string;
+    /** Plan mode context (appended at end) */
+    planModeContext?: string;
+    /** Meta-tools index (appended at end) */
+    metaToolsIndex?: string;
+    /** Working directory override (defaults to process.cwd()) */
+    cwd?: string;
+    /** Git user.name override (skips execSync detection) */
+    gitUserName?: string;
+    /** Git user.email override (skips execSync detection) */
+    gitUserEmail?: string;
+}
+/**
+ * Build result with metadata for debugging
+ */
+export interface BuildResult {
+    /** The assembled system prompt */
+    prompt: string;
+    /** Modules that were included */
+    includedModules: string[];
+    /** Modules that were excluded (with reasons) */
+    excludedModules: Array<{
+        id: string;
+        reason: string;
+    }>;
+    /** Estimated token count */
+    estimatedTokens: number;
+}
+/**
+ * Detect if a directory is a git repository.
+ * Uses execSync when available; returns false in non-Node environments.
+ */
+export declare function detectGitRepository(cwd?: string): boolean;
+/**
+ * SystemPromptBuilder - assembles modular system prompts
+ */
+export declare class SystemPromptBuilder {
+    private context;
+    private readonly modules;
+    constructor(context?: SystemPromptContext, modules?: SystemPromptModule[]);
+    /**
+     * Update context (e.g., when mode changes)
+     */
+    setContext(context: Partial<SystemPromptContext>): void;
+    /**
+     * Get current context
+     */
+    getContext(): SystemPromptContext;
+    /**
+     * Build the system prompt based on current context
+     */
+    build(): BuildResult;
+    /**
+     * Build and return just the prompt string
+     */
+    buildPrompt(): string;
+    /**
+     * Get estimated token count for current context
+     */
+    getEstimatedTokens(): number;
+    /**
+     * Get a summary of what modules will be included/excluded
+     */
+    getSummary(): {
+        included: string[];
+        excluded: Array<{
+            id: string;
+            reason: string;
+        }>;
+        estimatedTokens: number;
+    };
+}
+/**
+ * Convenience function to build a system prompt
+ */
+export declare function buildSystemPrompt(context?: SystemPromptContext): string;
+/**
+ * Get module stats for debugging
+ */
+export declare function getModuleStats(): {
+    totalModules: number;
+    conditionalModules: number;
+    alwaysIncludedModules: number;
+    maxTokens: number;
+    minTokens: number;
+};

package/dist/system-prompt/builder.js

@@ -0,0 +1,255 @@
+/**
+ * System Prompt Builder
+ *
+ * Assembles system prompt from modules based on current context.
+ * Provides ~50% token reduction by only including relevant modules.
+ *
+ * Git/CWD detection is injectable via SystemPromptContext for non-Node environments.
+ * Falls back to execSync detection in Node.js when not provided.
+ */
+import { ALL_MODULES, shouldIncludeModule, getEstimatedTokensForConditions, } from './modules.js';
+/**
+ * Get git configuration (user.name and user.email).
+ * Returns provided overrides, or auto-detects via execSync in Node.js.
+ */
+function getGitConfig(context) {
+    // Use injected values if provided
+    if (context.gitUserName !== undefined && context.gitUserEmail !== undefined) {
+        return { userName: context.gitUserName, userEmail: context.gitUserEmail };
+    }
+    let userName = context.gitUserName ?? '(not set - commits will fail)';
+    let userEmail = context.gitUserEmail ?? '(not set - commits will fail)';
+    try {
+        // Dynamic import to avoid bundler issues in non-Node environments
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { execSync } = require('child_process');
+        if (context.gitUserName === undefined) {
+            try {
+                const name = execSync('git config --global user.name', {
+                    encoding: 'utf8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                }).trim();
+                if (name)
+                    userName = name;
+            }
+            catch {
+                // Not configured
+            }
+        }
+        if (context.gitUserEmail === undefined) {
+            try {
+                const email = execSync('git config --global user.email', {
+                    encoding: 'utf8',
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                }).trim();
+                if (email)
+                    userEmail = email;
+            }
+            catch {
+                // Not configured
+            }
+        }
+    }
+    catch {
+        // child_process not available (browser/edge runtime)
+    }
+    return { userName, userEmail };
+}
+/**
+ * Detect if a directory is a git repository.
+ * Uses execSync when available; returns false in non-Node environments.
+ */
+export function detectGitRepository(cwd) {
+    try {
+        // Dynamic import to avoid bundler issues in non-Node environments
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { execSync } = require('child_process');
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { existsSync } = require('fs');
+        const dir = cwd ?? process.cwd();
+        // Check for .git directory
+        if (existsSync(`${dir}/.git`)) {
+            return true;
+        }
+        // Also check via git command (handles worktrees, etc.)
+        execSync('git rev-parse --is-inside-work-tree', {
+            cwd: dir,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Replace placeholders in module content
+ */
+function replacePlaceholders(content, context) {
+    const gitConfig = getGitConfig(context);
+    let cwd;
+    try {
+        cwd = context.cwd ?? process.cwd();
+    }
+    catch {
+        cwd = context.cwd ?? '(unknown)';
+    }
+    return content
+        .replace('{{CWD}}', cwd)
+        .replace('{{GIT_USER_NAME}}', gitConfig.userName)
+        .replace('{{GIT_USER_EMAIL}}', gitConfig.userEmail);
+}
+/**
+ * SystemPromptBuilder - assembles modular system prompts
+ */
+export class SystemPromptBuilder {
+    context;
+    modules;
+    constructor(context = {}, modules) {
+        // Auto-detect git if not specified
+        this.context = {
+            ...context,
+            hasGit: context.hasGit ?? detectGitRepository(context.cwd),
+        };
+        this.modules = modules ?? ALL_MODULES;
+    }
+    /**
+     * Update context (e.g., when mode changes)
+     */
+    setContext(context) {
+        this.context = { ...this.context, ...context };
+    }
+    /**
+     * Get current context
+     */
+    getContext() {
+        return { ...this.context };
+    }
+    /**
+     * Build the system prompt based on current context
+     */
+    build() {
+        const includedModules = [];
+        const excludedModules = [];
+        const parts = [];
+        // Process each module
+        for (const module of this.modules) {
+            if (shouldIncludeModule(module, this.context)) {
+                includedModules.push(module.id);
+                parts.push(replacePlaceholders(module.content, this.context));
+            }
+            else {
+                // Determine reason for exclusion
+                let reason = 'Unknown';
+                if (module.conditions?.hasGit && !this.context.hasGit) {
+                    reason = 'Not a git repository';
+                }
+                else if (module.conditions?.enableMetaTools && !this.context.enableMetaTools) {
+                    reason = 'Meta-tools not enabled';
+                }
+                else if (module.conditions?.modes && this.context.mode) {
+                    reason = `Mode is ${this.context.mode}, requires ${module.conditions.modes.join('/')}`;
+                }
+                else if (module.conditions?.hasProject && !this.context.hasProject) {
+                    reason = 'No active project';
+                }
+                excludedModules.push({ id: module.id, reason });
+            }
+        }
+        // Join modules with separators
+        let prompt = parts.join('\n\n---\n\n');
+        // Append meta-tools index if provided
+        if (this.context.metaToolsIndex) {
+            prompt += `\n\n---\n\n${this.context.metaToolsIndex}`;
+        }
+        // Append project context if provided
+        if (this.context.projectContext) {
+            const projectHeader = this.context.projectName
+                ? `## Project Context (${this.context.projectName})`
+                : '## Project Context';
+            prompt += `\n\n---\n\n${projectHeader}\n\nThe following is project-specific context loaded from COMPILR.md:\n\n${this.context.projectContext}`;
+        }
+        else if (this.context.projectName) {
+            prompt += `\n\n---\n\n## Active Project\n\nThe current project is: **${this.context.projectName}**`;
+        }
+        // Append guided mode context if provided
+        if (this.context.guidedModeContext) {
+            prompt += `\n\n---\n\n${this.context.guidedModeContext}`;
+        }
+        // Append plan mode context if provided
+        if (this.context.planModeContext) {
+            prompt += `\n\n---\n\n${this.context.planModeContext}`;
+        }
+        // Calculate estimated tokens
+        const baseTokens = getEstimatedTokensForConditions(this.context);
+        // Rough estimate for appended contexts (4 chars ≈ 1 token)
+        const appendedTokens = Math.ceil(((this.context.projectContext?.length ?? 0) +
+            (this.context.guidedModeContext?.length ?? 0) +
+            (this.context.planModeContext?.length ?? 0) +
+            (this.context.metaToolsIndex?.length ?? 0)) /
+            4);
+        return {
+            prompt,
+            includedModules,
+            excludedModules,
+            estimatedTokens: baseTokens + appendedTokens,
+        };
+    }
+    /**
+     * Build and return just the prompt string
+     */
+    buildPrompt() {
+        return this.build().prompt;
+    }
+    /**
+     * Get estimated token count for current context
+     */
+    getEstimatedTokens() {
+        return this.build().estimatedTokens;
+    }
+    /**
+     * Get a summary of what modules will be included/excluded
+     */
+    getSummary() {
+        const result = this.build();
+        return {
+            included: result.includedModules,
+            excluded: result.excludedModules,
+            estimatedTokens: result.estimatedTokens,
+        };
+    }
+}
+/**
+ * Convenience function to build a system prompt
+ */
+export function buildSystemPrompt(context = {}) {
+    const builder = new SystemPromptBuilder(context);
+    return builder.buildPrompt();
+}
+/**
+ * Get module stats for debugging
+ */
+export function getModuleStats() {
+    const conditional = ALL_MODULES.filter((m) => m.conditions);
+    const always = ALL_MODULES.filter((m) => !m.conditions);
+    // Max: all modules
+    const maxTokens = getEstimatedTokensForConditions({
+        hasGit: true,
+        enableMetaTools: true,
+        hasProject: true,
+    });
+    // Min: no conditional modules
+    const minTokens = getEstimatedTokensForConditions({
+        hasGit: false,
+        enableMetaTools: false,
+        hasProject: false,
+    });
+    return {
+        totalModules: ALL_MODULES.length,
+        conditionalModules: conditional.length,
+        alwaysIncludedModules: always.length,
+        maxTokens,
+        minTokens,
+    };
+}

package/dist/system-prompt/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Modular System Prompt
+ *
+ * Token-optimized system prompt that only includes relevant modules
+ * based on current context (git repo, mode, project, etc.).
+ *
+ * Usage:
+ * ```typescript
+ * import { SystemPromptBuilder, buildSystemPrompt } from '@compilr-dev/sdk';
+ *
+ * // Simple usage
+ * const prompt = buildSystemPrompt({ hasGit: true, enableMetaTools: true });
+ *
+ * // Builder pattern for more control
+ * const builder = new SystemPromptBuilder({ hasGit: true });
+ * builder.setContext({ enableMetaTools: true, projectContext: '...' });
+ * const result = builder.build();
+ * console.log(`Included: ${result.includedModules.join(', ')}`);
+ * console.log(`Est. tokens: ${result.estimatedTokens}`);
+ *
+ * // Injectable context (for non-Node environments)
+ * const prompt2 = buildSystemPrompt({
+ *   hasGit: true,
+ *   cwd: '/app',
+ *   gitUserName: 'Alice',
+ *   gitUserEmail: 'alice@example.com',
+ * });
+ *
+ * // Custom modules
+ * const builder2 = new SystemPromptBuilder({}, [STYLE_MODULE, TASK_EXECUTION_MODULE]);
+ * ```
+ */
+export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, type SystemPromptContext, type BuildResult, } from './builder.js';
+export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, type SystemPromptModule, type ModuleConditions, } from './modules.js';

package/dist/system-prompt/index.js

@@ -0,0 +1,34 @@
+/**
+ * Modular System Prompt
+ *
+ * Token-optimized system prompt that only includes relevant modules
+ * based on current context (git repo, mode, project, etc.).
+ *
+ * Usage:
+ * ```typescript
+ * import { SystemPromptBuilder, buildSystemPrompt } from '@compilr-dev/sdk';
+ *
+ * // Simple usage
+ * const prompt = buildSystemPrompt({ hasGit: true, enableMetaTools: true });
+ *
+ * // Builder pattern for more control
+ * const builder = new SystemPromptBuilder({ hasGit: true });
+ * builder.setContext({ enableMetaTools: true, projectContext: '...' });
+ * const result = builder.build();
+ * console.log(`Included: ${result.includedModules.join(', ')}`);
+ * console.log(`Est. tokens: ${result.estimatedTokens}`);
+ *
+ * // Injectable context (for non-Node environments)
+ * const prompt2 = buildSystemPrompt({
+ *   hasGit: true,
+ *   cwd: '/app',
+ *   gitUserName: 'Alice',
+ *   gitUserEmail: 'alice@example.com',
+ * });
+ *
+ * // Custom modules
+ * const builder2 = new SystemPromptBuilder({}, [STYLE_MODULE, TASK_EXECUTION_MODULE]);
+ * ```
+ */
+export { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, } from './builder.js';
+export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_META_MODULE, DELEGATION_MODULE, GIT_SAFETY_MODULE, SUGGEST_MODULE, IMPORTANT_RULES_MODULE, ENVIRONMENT_MODULE, shouldIncludeModule, getEstimatedTokensForConditions, getTotalEstimatedTokens, } from './modules.js';

package/dist/system-prompt/modules.d.ts

@@ -0,0 +1,124 @@
+/**
+ * System Prompt Modules
+ *
+ * Modular system prompt for token optimization.
+ * Each module has content and optional conditions for inclusion.
+ *
+ * Token savings: ~50% reduction on average by only including relevant modules.
+ */
+/**
+ * Conditions that determine if a module should be included
+ */
+export interface ModuleConditions {
+    /** Include only if in a git repository */
+    hasGit?: boolean;
+    /** Include only in these workflow modes */
+    modes?: ('flexible' | 'guided' | 'plan')[];
+    /** Include only if there's an active project */
+    hasProject?: boolean;
+    /** Include only if meta-tools are enabled */
+    enableMetaTools?: boolean;
+    /** Include only if NO role identity is specified (for default identity module) */
+    noRoleIdentity?: boolean;
+}
+/**
+ * A system prompt module
+ */
+export interface SystemPromptModule {
+    /** Unique identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** The actual prompt content */
+    content: string;
+    /** Conditions for inclusion (empty = always include) */
+    conditions?: ModuleConditions;
+    /** Estimated token count (for debugging/optimization) */
+    estimatedTokens: number;
+}
+/**
+ * Default identity module - only included when NO role is specified
+ * When a specialized role (pm, arch, qa, etc.) is used, this is skipped
+ * and the role's identity is prepended instead.
+ */
+export declare const IDENTITY_MODULE: SystemPromptModule;
+/**
+ * Style module - always included
+ * Defines tone, style, and behavioral guidelines that apply to ALL agents
+ */
+export declare const STYLE_MODULE: SystemPromptModule;
+/**
+ * Task execution module - always included
+ * Defines how to approach coding tasks
+ */
+export declare const TASK_EXECUTION_MODULE: SystemPromptModule;
+/**
+ * Todo management module - always included
+ * Defines how to use the todo_write tool
+ */
+export declare const TODO_MANAGEMENT_MODULE: SystemPromptModule;
+/**
+ * Tool usage module (direct tools) - always included
+ * Lists tools that are always available
+ */
+export declare const TOOL_USAGE_DIRECT_MODULE: SystemPromptModule;
+/**
+ * Tool usage module (meta-tools) - only if enableMetaTools=true
+ * Explains how to use specialized tools via meta-tools
+ */
+export declare const TOOL_USAGE_META_MODULE: SystemPromptModule;
+/**
+ * Token delegation module - always included
+ * CRITICAL for token efficiency - teaches agent to use sub-agents
+ */
+export declare const DELEGATION_MODULE: SystemPromptModule;
+/**
+ * Git safety module - only if hasGit=true
+ * Defines safety rules for git operations
+ */
+export declare const GIT_SAFETY_MODULE: SystemPromptModule;
+/**
+ * Suggest module - always included
+ * Defines how to use the suggest tool
+ */
+export declare const SUGGEST_MODULE: SystemPromptModule;
+/**
+ * Important rules module - always included
+ * Summary of critical rules
+ */
+export declare const IMPORTANT_RULES_MODULE: SystemPromptModule;
+/**
+ * Environment module - always included
+ * Current working directory and git config
+ * Note: {{PLACEHOLDERS}} are replaced at runtime
+ */
+export declare const ENVIRONMENT_MODULE: SystemPromptModule;
+/**
+ * All modules in the order they should appear in the prompt.
+ * Modules without conditions are always included.
+ */
+export declare const ALL_MODULES: SystemPromptModule[];
+/**
+ * Get total estimated tokens for all modules
+ */
+export declare function getTotalEstimatedTokens(): number;
+/**
+ * Get estimated tokens for modules that match given conditions
+ */
+export declare function getEstimatedTokensForConditions(conditions: {
+    hasGit?: boolean;
+    enableMetaTools?: boolean;
+    mode?: 'flexible' | 'guided' | 'plan';
+    hasProject?: boolean;
+    hasRoleIdentity?: boolean;
+}): number;
+/**
+ * Check if a module should be included based on conditions
+ */
+export declare function shouldIncludeModule(module: SystemPromptModule, context: {
+    hasGit?: boolean;
+    enableMetaTools?: boolean;
+    mode?: 'flexible' | 'guided' | 'plan';
+    hasProject?: boolean;
+    hasRoleIdentity?: boolean;
+}): boolean;

package/dist/system-prompt/modules.js

@@ -0,0 +1,356 @@
+/**
+ * System Prompt Modules
+ *
+ * Modular system prompt for token optimization.
+ * Each module has content and optional conditions for inclusion.
+ *
+ * Token savings: ~50% reduction on average by only including relevant modules.
+ */
+// =============================================================================
+// MODULE DEFINITIONS
+// =============================================================================
+/**
+ * Default identity module - only included when NO role is specified
+ * When a specialized role (pm, arch, qa, etc.) is used, this is skipped
+ * and the role's identity is prepended instead.
+ */
+export const IDENTITY_MODULE = {
+    id: 'identity',
+    name: 'Default Identity',
+    estimatedTokens: 50,
+    conditions: {
+        noRoleIdentity: true, // Only include if no role identity is specified
+    },
+    content: `You are a coding assistant running in a terminal CLI.
+
+You help users with software engineering tasks: writing code, debugging, refactoring, explaining concepts, managing projects, and more.`,
+};
+/**
+ * Style module - always included
+ * Defines tone, style, and behavioral guidelines that apply to ALL agents
+ */
+export const STYLE_MODULE = {
+    id: 'style',
+    name: 'Tone and Style',
+    estimatedTokens: 150,
+    content: `## Tone and Style
+
+- Your output displays in a terminal. Keep responses short and concise.
+- Use GitHub-flavored markdown for formatting.
+- Only use emojis if the user explicitly requests them.
+- Output text to communicate. Never use tools (like bash echo) to communicate.
+- NEVER create files unless absolutely necessary. Always prefer editing existing files.
+- When referencing code, include file path and line number: src/utils.ts:42
+
+## Professional Objectivity
+
+Prioritize technical accuracy over validating the user's beliefs. Provide direct, objective technical info without unnecessary praise or emotional validation. Disagree when necessary - objective guidance is more valuable than false agreement.
+
+Avoid phrases like "You're absolutely right!" or "Great question!" - just answer directly.
+
+## No Time Estimates
+
+Never predict how long tasks will take. Avoid phrases like "this will take a few minutes" or "quick fix". Focus on what needs to be done, not duration.`,
+};
+/**
+ * Task execution module - always included
+ * Defines how to approach coding tasks
+ */
+export const TASK_EXECUTION_MODULE = {
+    id: 'task-execution',
+    name: 'Task Execution',
+    estimatedTokens: 150,
+    content: `## Doing Tasks
+
+When the user requests software engineering work:
+
+1. **Read before modifying**: NEVER propose changes to code you haven't read. Always read files first.
+2. **Use todo_write for complex tasks**: Track progress on multi-step work (3+ steps).
+3. **Avoid over-engineering**:
+   - Only make changes that are directly requested
+   - Don't add features beyond what was asked
+   - Don't add error handling for scenarios that can't happen
+   - Don't create abstractions for one-time operations
+   - Three similar lines is better than a premature abstraction
+4. **Security awareness**: Don't introduce vulnerabilities (injection, XSS, SQL injection). If you notice insecure code, fix it immediately.
+5. **Clean up completely**: If something is unused, delete it. No backwards-compatibility hacks.`,
+};
+/**
+ * Todo management module - always included
+ * Defines how to use the todo_write tool
+ */
+export const TODO_MANAGEMENT_MODULE = {
+    id: 'todo-management',
+    name: 'Todo Management',
+    estimatedTokens: 250,
+    content: `## Task Management (todo_write)
+
+Use todo_write to track progress on multi-step tasks.
+
+When to use:
+- Tasks with 3+ distinct steps
+- User provides multiple tasks
+- Complex work requiring planning
+
+When NOT to use:
+- Single, trivial tasks
+- Purely informational questions
+- Tasks completable in 1-2 steps
+
+### Task Dependencies (blockedBy)
+
+Use the \`blockedBy\` field to declare dependencies between tasks. Values are 1-based task positions in the array.
+When a task cannot start until another finishes, set blockedBy to indicate the dependency. This helps track execution order.
+
+Example: Task #3 depends on #1 and #2:
+\`\`\`
+{ content: "Run tests", status: "pending", blockedBy: [1, 2] }
+\`\`\`
+Completed tasks automatically move to the bottom of the displayed list.
+
+### Example: When to use todo_write
+
+User: Fix the type errors and run the tests
+Assistant: I'll track this multi-step task:
+[Uses todo_write: "Fix type errors", "Run tests" (blockedBy: [1])]
+[Marks "Fix type errors" as in_progress]
+[Reads files, fixes errors]
+[Marks "Fix type errors" complete, "Run tests" in_progress]
+[Runs tests]
+[Marks "Run tests" complete]
+
+### Example: When NOT to use todo_write
+
+User: What does this function do?
+Assistant: [Reads the file and explains directly - no todo needed for a simple question]`,
+};
+/**
+ * Tool usage module (direct tools) - always included
+ * Lists tools that are always available
+ */
+export const TOOL_USAGE_DIRECT_MODULE = {
+    id: 'tool-usage-direct',
+    name: 'Tool Usage (Direct)',
+    estimatedTokens: 100,
+    content: `## Tool Usage
+
+IMPORTANT: Tool names are lowercase with underscores.
+
+### Direct Tools (always available)
+- **File operations**: read_file, write_file, edit, glob, grep
+- **Shell**: bash (use run_in_background=true for long-running), bash_output, kill_shell
+- **Task management**: todo_write, todo_read
+- **User interaction**: ask_user, ask_user_simple
+- **Sub-agents**: task (types: explore, code-review, plan, debug, test-runner, refactor, security-audit, general)`,
+};
+/**
+ * Tool usage module (meta-tools) - only if enableMetaTools=true
+ * Explains how to use specialized tools via meta-tools
+ */
+export const TOOL_USAGE_META_MODULE = {
+    id: 'tool-usage-meta',
+    name: 'Tool Usage (Meta)',
+    estimatedTokens: 250,
+    conditions: { enableMetaTools: true },
+    content: `### Specialized Tools
+
+These are **CLI system tools** — they operate on the Compilr CLI's internal database, NOT on the user's application. Never confuse them with the user's project backend (e.g., localhost servers).
+
+Key categories:
+- **Git**: git_status, git_diff, git_log, git_commit, git_branch
+- **Project Management**: project_get, project_list, project_create, project_update
+- **Work Items**: workitem_query, workitem_add, workitem_update, workitem_next
+- **Documents**: project_document_add, project_document_get, project_document_list
+- **Planning**: plan_create, plan_get, plan_list
+- **Runners**: run_tests, run_lint
+- **Anchors**: anchor_add, anchor_list, anchor_remove
+
+### Document Storage (CRITICAL)
+
+Project documents (PRD, architecture, design, notes) are stored in the **database**, not the filesystem.
+- **Read**: \`project_document_get({ doc_type: "prd" })\` or \`project_document_list()\`
+- **Write**: \`project_document_add({ doc_type: "prd", title: "...", content: "..." })\`
+- Do NOT use write_file or edit for project documents — always use these database tools
+- Valid doc_types: prd, architecture, design, notes, session-note`,
+};
+/**
+ * Token delegation module - always included
+ * CRITICAL for token efficiency - teaches agent to use sub-agents
+ */
+export const DELEGATION_MODULE = {
+    id: 'delegation',
+    name: 'Token Efficiency & Delegation',
+    estimatedTokens: 200,
+    content: `## Token Efficiency & Delegation
+
+Use the **task** tool (sub-agent) for:
+- **File exploration**: "find files", "what's in this directory", "explore codebase"
+- **Code search**: "where is X defined", "find usages of Y"
+- **Analysis**: "analyze module", "understand architecture", "review code"
+- **Multi-file operations**: Tasks touching 5+ files
+
+### Rules
+1. Exploration/search questions → task(explore)
+2. Code review → task(code-review)
+3. Planning → task(plan)
+4. Simple answers (no file access) → respond directly
+5. Code edits → do it yourself (never delegate edits)`,
+};
+/**
+ * Git safety module - only if hasGit=true
+ * Defines safety rules for git operations
+ */
+export const GIT_SAFETY_MODULE = {
+    id: 'git-safety',
+    name: 'Git Safety Protocol',
+    estimatedTokens: 300,
+    conditions: { hasGit: true },
+    content: `## Git Safety Protocol
+
+When working with git:
+
+1. **Never update git config** without explicit user request
+2. **Never force push** to main/master - warn if requested
+3. **Never use --amend** unless:
+   - User explicitly requested it, AND
+   - Commit was created by you in this session, AND
+   - Commit has NOT been pushed to remote
+4. **Check before destructive operations**:
+   - git reset --hard (loses uncommitted changes)
+   - git checkout -- file (discards local changes)
+   - git clean (deletes untracked files)
+5. **Only commit when asked** - don't commit proactively
+
+### Commit Workflow
+1. Run git_status to see changes
+2. Run git_diff to review what will be committed
+3. Check recent git_log for commit message style
+4. Create focused commit with clear message
+5. Never commit files with secrets (.env, credentials.json)`,
+};
+/**
+ * Suggest module - always included
+ * Defines how to use the suggest tool
+ */
+export const SUGGEST_MODULE = {
+    id: 'suggest',
+    name: 'Next Action Suggestions',
+    estimatedTokens: 100,
+    content: `## Next Action Suggestions
+
+After completing a task, call the suggest tool to recommend the next action.
+
+Good suggestions are short commands or actions:
+- "run npm test"
+- "commit the changes"
+- "check the error log"
+
+CALL the suggest tool - never write "suggest: ..." as text.`,
+};
+/**
+ * Important rules module - always included
+ * Summary of critical rules
+ */
+export const IMPORTANT_RULES_MODULE = {
+    id: 'important-rules',
+    name: 'Important Rules',
+    estimatedTokens: 200,
+    content: `## IMPORTANT RULES (read carefully)
+
+1. Tool names are lowercase with underscores - use exactly as shown
+2. ALWAYS read files before proposing changes to them
+3. After calling a tool, respond with the result - never end silently
+4. Use todo_write for multi-step tasks (3+ steps)
+5. Don't over-engineer - implement exactly what was asked
+6. Check for security issues - fix insecure code immediately
+7. **DELEGATE exploration to sub-agents** - use task(explore) for file searches, code navigation, and analysis. NEVER accumulate exploration results in your own context.
+8. Call suggest tool after completing tasks (don't write "suggest:" as text)
+9. When user asks "what files...", "where is...", "find..." - ALWAYS use task(explore), not direct tool calls`,
+};
+/**
+ * Environment module - always included
+ * Current working directory and git config
+ * Note: {{PLACEHOLDERS}} are replaced at runtime
+ */
+export const ENVIRONMENT_MODULE = {
+    id: 'environment',
+    name: 'Environment Info',
+    estimatedTokens: 50,
+    content: `Current working directory: {{CWD}}
+Git configuration:
+- user.name: {{GIT_USER_NAME}}
+- user.email: {{GIT_USER_EMAIL}}`,
+};
+// =============================================================================
+// ALL MODULES (in order)
+// =============================================================================
+/**
+ * All modules in the order they should appear in the prompt.
+ * Modules without conditions are always included.
+ */
+export const ALL_MODULES = [
+    IDENTITY_MODULE, // Conditional: only when no role identity
+    STYLE_MODULE,
+    TASK_EXECUTION_MODULE,
+    TODO_MANAGEMENT_MODULE,
+    TOOL_USAGE_DIRECT_MODULE,
+    TOOL_USAGE_META_MODULE, // Conditional: enableMetaTools
+    DELEGATION_MODULE,
+    GIT_SAFETY_MODULE, // Conditional: hasGit
+    SUGGEST_MODULE,
+    IMPORTANT_RULES_MODULE,
+    ENVIRONMENT_MODULE,
+];
+/**
+ * Get total estimated tokens for all modules
+ */
+export function getTotalEstimatedTokens() {
+    return ALL_MODULES.reduce((sum, m) => sum + m.estimatedTokens, 0);
+}
+/**
+ * Get estimated tokens for modules that match given conditions
+ */
+export function getEstimatedTokensForConditions(conditions) {
+    let total = 0;
+    for (const module of ALL_MODULES) {
+        if (shouldIncludeModule(module, conditions)) {
+            total += module.estimatedTokens;
+        }
+    }
+    return total;
+}
+/**
+ * Check if a module should be included based on conditions
+ */
+export function shouldIncludeModule(module, context) {
+    // No conditions = always include
+    if (!module.conditions) {
+        return true;
+    }
+    const { conditions } = module;
+    // Check noRoleIdentity condition - only include if NO role identity is specified
+    // This allows team agents to define their own identity without conflict
+    if (conditions.noRoleIdentity && context.hasRoleIdentity) {
+        return false;
+    }
+    // Check hasGit condition
+    if (conditions.hasGit !== undefined && conditions.hasGit !== context.hasGit) {
+        return false;
+    }
+    // Check enableMetaTools condition
+    if (conditions.enableMetaTools !== undefined &&
+        conditions.enableMetaTools !== context.enableMetaTools) {
+        return false;
+    }
+    // Check modes condition
+    if (conditions.modes && context.mode) {
+        if (!conditions.modes.includes(context.mode)) {
+            return false;
+        }
+    }
+    // Check hasProject condition
+    if (conditions.hasProject !== undefined && conditions.hasProject !== context.hasProject) {
+        return false;
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",