@compilr-dev/sdk 0.1.11 → 0.1.12

package/dist/index.d.ts

@@ -45,7 +45,7 @@ export { type ModelTier, type TierInfo, type ProviderModelMap, MODEL_TIERS, TIER
 export { assembleTools, deduplicateTools } from './tools.js';
 export { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX, } from './meta-tools/index.js';
 export type { MetaToolStats, MetaTools } from './meta-tools/index.js';
-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 { SystemPromptBuilder, buildSystemPrompt, detectGitRepository, getModuleStats, ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_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 type { ProjectType, ProjectStatus, RepoPattern, WorkflowMode, LifecycleState, WorkItemType, WorkItemStatus, WorkItemPriority, GuidedStep, DocumentType, PlanStatus, Project, WorkItem, ProjectDocument, Plan, PlanSummary, PlanWithWorkItem, HistoryEntry, CreateProjectInput, UpdateProjectInput, ProjectListOptions, CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, CreateDocumentInput, UpdateDocumentInput, CreatePlanInput, UpdatePlanInput, ListPlansOptions, WorkItemQueryResult, ProjectListResult, BulkCreateItem, IProjectRepository, IWorkItemRepository, IDocumentRepository, IPlanRepository, IAnchorService, IArtifactService, IEpisodeService, AnchorData, ArtifactType, ArtifactData, ArtifactSummaryData, WorkEpisode, ProjectWorkSummary, PlatformContext, PlatformToolsConfig, PlatformHooks, StepCriteria, } from './platform/index.js';
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, } from './platform/index.js';

package/dist/index.js

@@ -71,7 +71,7 @@ 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, 
+ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_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';
 // =============================================================================

package/dist/platform/types.d.ts

@@ -19,7 +19,7 @@ export type WorkItemType = 'feature' | 'bug' | 'tech-debt' | 'chore';
 export type WorkItemStatus = 'backlog' | 'in_progress' | 'completed' | 'skipped';
 export type WorkItemPriority = 'critical' | 'high' | 'medium' | 'low';
 export type GuidedStep = 'plan' | 'implement' | 'test' | 'commit' | 'review';
-export type DocumentType = 'prd' | 'architecture' | 'design' | 'notes' | 'plan';
+export type DocumentType = 'prd' | 'architecture' | 'design' | 'notes' | 'plan' | 'app-model';
 export type PlanStatus = 'draft' | 'approved' | 'in_progress' | 'completed' | 'abandoned';
 export interface Project {
     id: number;

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

@@ -31,4 +31,4 @@
  * ```
  */
 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';
+export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_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

@@ -31,4 +31,4 @@
  * ```
  */
 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';
+export { ALL_MODULES, IDENTITY_MODULE, STYLE_MODULE, TASK_EXECUTION_MODULE, TODO_MANAGEMENT_MODULE, TOOL_USAGE_DIRECT_MODULE, TOOL_USAGE_HINTS_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

@@ -62,6 +62,13 @@ export declare const TODO_MANAGEMENT_MODULE: SystemPromptModule;
  * Lists tools that are always available
  */
 export declare const TOOL_USAGE_DIRECT_MODULE: SystemPromptModule;
+/**
+ * Tool usage hints module - always included
+ * Behavioral guidance removed from tool descriptions (Phase 1a optimization).
+ * These hints are load-bearing: bash background workflow, todo/backlog
+ * disambiguation, file pagination, edit matching, suggest quality.
+ */
+export declare const TOOL_USAGE_HINTS_MODULE: SystemPromptModule;
 /**
  * Tool usage module (meta-tools) - only if enableMetaTools=true
  * Explains how to use specialized tools via meta-tools

package/dist/system-prompt/modules.js

@@ -143,6 +143,24 @@ IMPORTANT: Tool names are lowercase with underscores.
 - **User interaction**: ask_user, ask_user_simple
 - **Sub-agents**: task (types: explore, code-review, plan, debug, test-runner, refactor, security-audit, general)`,
 };
+/**
+ * Tool usage hints module - always included
+ * Behavioral guidance removed from tool descriptions (Phase 1a optimization).
+ * These hints are load-bearing: bash background workflow, todo/backlog
+ * disambiguation, file pagination, edit matching, suggest quality.
+ */
+export const TOOL_USAGE_HINTS_MODULE = {
+    id: 'tool-usage-hints',
+    name: 'Tool Usage Hints',
+    estimatedTokens: 120,
+    content: `## Tool Usage Hints
+
+- **bash background:** For long-running commands (builds, servers, watchers), set \`run_in_background: true\` and poll with \`bash_output\`. Never wait indefinitely.
+- **todo vs backlog:** \`todo_write\` is for ephemeral session tasks (lost on exit). For persistent project backlog, use \`workitem_*\` tools.
+- **Large files:** When reading files >500 lines, use \`maxLines\`/\`startLine\` to paginate. Avoid loading entire large files into context.
+- **edit matching:** \`edit\` uses exact string matching. Provide enough surrounding context to make the match unique. If the match fails, read the file first to get the exact text.
+- **suggest quality:** Suggestions should be specific and actionable (e.g., "run npm test" not "continue working").`,
+};
 /**
  * Tool usage module (meta-tools) - only if enableMetaTools=true
  * Explains how to use specialized tools via meta-tools
@@ -294,6 +312,7 @@ export const ALL_MODULES = [
     TASK_EXECUTION_MODULE,
     TODO_MANAGEMENT_MODULE,
     TOOL_USAGE_DIRECT_MODULE,
+    TOOL_USAGE_HINTS_MODULE,
     TOOL_USAGE_META_MODULE, // Conditional: enableMetaTools
     DELEGATION_MODULE,
     GIT_SAFETY_MODULE, // Conditional: hasGit

package/package.json

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