khabotcli 1.0.0

package/.OLD/STEP-1/RESEARCH-RESULTS/Deep Research: Context Engineering for AI Agent Runtimes.md

@@ -0,0 +1,197 @@
+# **Context Engineering for AI Agent Runtimes: A Systematic Analysis of Context Window Management and State Persistence**
+
+The transition from simple conversational large language models to autonomous agentic systems represents a fundamental shift in the information production function of artificial intelligence. In this new paradigm, the primary engineering challenge is no longer the raw capability of the model, but rather the configuration of context most likely to generate the desired behavioral outputs.1 As agents operate over extended temporal horizons—ranging from multi-hour coding sessions to thousands of turn-based actions in gaming environments—the volume of data generated during the reasoning, action, and observation loop creates a significant architectural burden.1 This phenomenon, often termed context rot, occurs when accuracy and recall degrade as the context window fills, a direct consequence of the mathematical properties of transformer-based attention mechanisms.3
+
+## **The Theoretical Framework of Context Rot and Information Decay**
+
+To architect a robust agent runtime, such as KhaBotCLI, one must first address the physics of the transformer architecture. The attention mechanisms that power modern large language models operate on a finite budget where every token competes for influence over the model's next prediction.6 The relationship between tokens is characterized by an ![][image1] complexity in pairwise relationships, meaning that as context grows, the computational noise increases exponentially.3 Research indicates that as context windows expand beyond approximately 32,000 tokens, accuracy drops significantly even in models claiming million-token limits.5
+
+The degradation manifests in several distinct failure modes that define the boundaries of context engineering. Context poisoning occurs when a hallucination or an error becomes embedded in the conversation history and is subsequently referenced in later turns, leading to a compounding cycle of failure.5 Context distraction arises when the volume of accumulated history causes the agent to over-focus on past actions rather than synthesizing novel plans based on its underlying training.5 Furthermore, context confusion and context clash describe scenarios where overlapping or contradictory instructions within the window lead to tool misuse or reasoning loops.5 These failures are exacerbated by the "lost in the middle" phenomenon, where information positioned in the center of a long context is systematically neglected in favor of the most recent or earliest tokens.8
+
+The economic implications of these architectural realities are profound. In unmanaged agentic workloads, costs can more than double as the context window accumulates thousands of tokens with every turn.2 Anthropic, for example, implements premium pricing structures for requests exceeding specific token thresholds, effectively charging a 2x rate for input and 1.5x for output in high-volume scenarios.9 Consequently, managing the context window is not merely a performance optimization but an economic necessity for industrial-scale deployment.2
+
+## **Compaction Strategies and Summarization Heuristics**
+
+The primary defense against context window saturation is compaction, a process of summarizing and reinitializing the conversation history to preserve signal while discarding noise.1 Production-level agents like Claude Code and OpenCode have pioneered distinct approaches to this challenge, balancing the trade-offs between technical resolution and token efficiency.
+
+### **Comparative Analysis of Production Compaction Systems**
+
+Claude Code implements a sophisticated "Recent Message Summarization" agent that performs a chronological analysis of recent interactions.12 This system is designed to preserve architectural decisions, unresolved bugs, and specific code patterns while discarding redundant tool outputs.1 The compaction prompt used by Claude Code instructs the model to identify user intents, technical concepts, file names, and full code snippets that are critical for the next phase of work.12 In contrast, OpenCode utilizes a hard-threshold trigger based on the specific model's context limit.11 When usage reaches approximately 95% of the context window, OpenCode creates a new session where the history is replaced by a summary explicitly marked as "summary" in the message metadata.11
+
+| Feature | Claude Code | OpenCode | Cursor |
+| :---- | :---- | :---- | :---- |
+| **Auto-Compact Threshold** | ~95% (Configurable to 85%) | 95% (effective_context_window_percent) | Triggered when context fills or via manual user command |
+| **Trigger Mechanism** | Real-time token monitoring via /context | isOverflow() check (tokens > limit - output) | Continuous monitoring and user-initiated /summarize |
+| **Preservation Focus** | Architectural decisions, TODOs, file paths, specific feedback | What was accomplished, WIP, modified files, next steps | Task state, current goals, critical file references |
+| **Discarding Policy** | Tool outputs, redundant reasoning turns, resolved issues | Raw tool data, broad exploratory logs | Long tool responses (turned into files instead) |
+| **Summarization Type** | Chronological analysis with specific code snippets | Detailed but concise summary for session handoff | "Lossy" compression supplemented by chat history files |
+
+11
+
+### **The Efficacy of Observation Masking**
+
+While LLM-driven summarization is a standard approach, research from JetBrains suggests that "Observation Masking" may be more efficient for software engineering agents.2 In this strategy, the agent’s reasoning and actions are preserved in full resolution, but the environment observations—such as verbose test logs or large file reads—are replaced with placeholders once they fall outside a rolling window, typically of the last ten turns.19 This method addresses the "stopping problem" where summaries might smooth over failure signals, causing an agent to run 13-15% longer without reaching a solution.19 Observation masking has been found to be 52% cheaper than unmanaged context while maintaining, and sometimes exceeding, the solve rate of complex summarization strategies.19
+
+### **Tuning for Recall vs. Precision in Compaction**
+
+The optimal threshold for triggering compaction remains a subject of debate among practitioners. While production defaults often sit at 95%, many advanced users recommend manual compaction at 70-80%.11 A model operating at 90% capacity suffers from a reduced "reasoning budget," becoming slower and less precise.17 To maximize recall, the compaction prompt must explicitly instruct the agent to analyze the conversation chronologically and identify critical data like function signatures and specific user feedback.12 Precision is then improved by filtering out redundant messages and tool results that are no longer necessary for the current task.1
+
+## **Semantic Pruning and Tool Result Clearing**
+
+The lightest and often most cost-effective form of context management is tool result clearing. Anthropic recommends this as a first-line optimization, where raw outputs from tools called deep in the message history are removed while the reasoning that led to the call is preserved.3
+
+### **Server-Side Context Editing and Cache Management**
+
+The Claude Developer Platform has institutionalized this through "context editing" features, which allow server-side management of tool results and thinking blocks.22 Tool result clearing specifically targets agentic workflows where old data is no longer needed but would otherwise bloat the prompt.23 However, this process invalidates cached prompt prefixes, incurring cache write costs each time content is cleared.23 To mitigate this, developers use a clear_at_least parameter to ensure that the number of tokens cleared is significant enough to justify the cache invalidation.23
+
+Cursor takes a different approach by turning long tool responses into files rather than truncating them or clearing them entirely.16 When a shell command or MCP call returns a large volume of data, Cursor writes the output to the filesystem and gives the agent a reference to read it using tools like tail or grep.16 This dynamic context discovery prevents context bloat while ensuring that no critical data is lost during the compression phase.16
+
+### **Thinking Block Management**
+
+Models with extended thinking capabilities generate internal reasoning chains that can be substantial in length.4 In multi-turn tool use, these thinking blocks are not typically carried forward as input tokens for subsequent turns unless configured otherwise.4 Managing these blocks is a balancing act: keeping them preserves reasoning continuity and maximizes prompt cache hits, while clearing them reclaims context window space but invalidates the cache.23
+
+## **Structured Note-Taking and Externalized Persistence**
+
+For tasks that exceed even the most generous context windows, agents must rely on externalized memory systems. This involves the agent writing its own persistent notes to files outside the conversational history.1
+
+### **The Role of Persistent Markdown Artifacts**
+
+In production coding environments, this manifests as files like CLAUDE.md, NOTES.md, and TODO.md.24 CLAUDE.md typically contains static project-level context, such as build instructions and naming conventions, which are dropped into the context window at the start of every session.1 NOTES.md and TODO.md serve as a "scratchpad" for the agent to track progress and critical dependencies.1 This persistent note-taking mechanism allows for cross-session learning, ensuring that the agent does not repeat dead-end strategies or invalid actions.24
+
+### **Case Study: Long-Horizon Reasoning in Pokémon**
+
+The "Claude playing Pokémon" experiment provides the most rigorous test case for structured note-taking.3 Across 170,000 game steps, the agent maintained precise tallies of its training progress, such as tracking a Pokémon's level gain over thousands of steps (e.g., "Pikachu gained 8 levels toward target of 10").1 This system allowed the agent to resume multi-hour sequences seamlessly after context resets.1 However, the experiment also highlighted the limitations of current vision-to-text distillation; the agent’s struggle with navigating complex maps was often a failure of spatial memory and the lack of a robust text-based representation of the environment.28
+
+## **Sub-Agent Context Isolation and Multi-Agent Orchestration**
+
+The use of sub-agents represents a paradigm of "sharding" context to maintain reasoning resolution. Instead of a single model attempting to manage thousands of lines of code, an orchestrator spawns specialized agents for focused tasks.1
+
+### **Orchestrator-Worker Architecture**
+
+In this model, the main agent maintains the high-level plan and coordination.1 When a deep technical task is required, it spawns a sub-agent with a clean context window containing only the specific task description, necessary files, and relevant tools.1 This isolation prevents the "noise" of technical exploration from polluting the main orchestrator's history.3 Anthropic recommends that sub-agents return a condensed summary of approximately 1,000 to 2,000 tokens upon completion.1
+
+### **Coordination and Conflict Management**
+
+Cursor enables the simultaneous execution of up to eight agents, each working in an isolated environment.32 This parallelization requires a robust interface to manage coordination and prevent merge conflicts across the codebase.32 The effectiveness of this approach is driven by the "return contract": the quality of the summary provided by the sub-agent determines whether the orchestrator can accurately integrate the work into the master plan.16
+
+## **Token Budgeting and Economic Resource Management**
+
+A disciplined token budget is essential for preventing the performance degradation associated with "baggage-heavy" sessions.17 Simply starting a session in a modern coding agent can consume 17,000 tokens for system prompts and tool definitions.33
+
+### **Resource Allocation Framework**
+
+To maximize the "reasoning budget," an agent runtime must treat context as a finite, tiered resource.
+
+| Layer | Priority | Recommended Budget % | Management Strategy |
+| :---- | :---- | :---- | :---- |
+| **Priming Documents (.cursorrules, CLAUDE.md)** | High | 5% - 10% | Static injection; heavily cached. |
+| **Tool/MCP Metadata** | Medium | 10% - 20% | On-demand tool search; disable idle servers. |
+| **Conversation History** | Variable | 40% - 60% | Aggressive /compact or /clear; observation masking. |
+| **Active Working Set (Files/Task)** | Critical | 20% - 30% | Just-in-time retrieval; selective file tagging. |
+
+6
+
+### **Cost and Latency Benchmarks**
+
+The average cost for a developer using Claude Code is approximately $6 per day, though this can scale significantly with codebase size and query complexity.31 Latency also increases linearly with context size; more tokens require more GPU memory bandwidth and longer processing times during the prefill phase.9 Caching is the primary lever for cost reduction, with savings scaling from 10% at 500 tokens to nearly 89% at 50,000 tokens.36
+
+## **Progressive Summarization and Multi-Turn Optimization**
+
+For conversations spanning over 100 turns, agents must transition from a continuous history to a structured state management model.36
+
+### **Strategic Session Hygiene**
+
+The "default sequence" for managing long-running sessions involves regular use of /clear and /compact. /clear should be used between unrelated tasks—such as switching from a feature implementation to a bug fix—because stale context full of failed approaches actively distracts the model.17 For work requiring continuity, progressive summarization (compacting every ![][image2] turns) preserves the "story state" without dragging the noise of every exploratory command.21
+
+### **Decision Tree: Context Management Mode Selection**
+
+When the runtime detects that context usage has exceeded the efficiency threshold (typically 70%), it should evaluate the following logic to select the management strategy:
+
+1. **Is the current task a direct continuation of the previous turn?**  
+   * No: Execute /clear. Re-read the CLAUDE.md and start fresh.  
+   * Yes: Proceed.  
+2. **Does the history contain repetitive tool outputs (e.g., failed builds, long logs)?**  
+   * Yes: Apply **Observation Masking** to prior turns.  
+   * No: Proceed.  
+3. **Is the complexity of the current task high (multi-file, architectural)?**  
+   * Yes: Spawn a **Sub-Agent** with a focused context shard.  
+   * No: Execute **Compaction** and preserve only the last 5 turns.
+
+1
+
+## **Implementation Blueprint for KhaBotCLI**
+
+A production-ready implementation of an auto-compaction system for an agent runtime must integrate real-time token monitoring with a tiered response strategy.
+
+### **Recommended Compaction Prompt Template**
+
+The following prompt is derived from the "Recent Message Summarization" logic used in high-performance coding agents.12
+
+Your task is to create a detailed summary of the RECENT portion of the conversation.
+
+The earlier messages are being kept intact; focus only on what was discussed and
+
+accomplished in the recent messages.
+
+In your analysis process:
+
+1. Identify the user's explicit requests and intents.  
+2. Document key technical concepts, technologies, and code patterns discussed.  
+3. Enumerate specific files and code sections modified, including important snippets.  
+4. List errors encountered and how they were fixed.  
+5. Outline pending tasks and the precise state of work immediately before this summary.
+
+Structure your response with:
+
+* Primary Request and Intent  
+* Key Technical Concepts  
+* Files and Code Sections (with summaries of importance)  
+* Errors and Fixes  
+* Current Work and Optional Next Step
+
+### **Auto-Compaction Logic Pseudocode**
+
+This Go-based logic illustrates the integration of the isOverflow check with a multi-tier pruning mechanism.9
+
+```go
+const (
+    CONTEXT_LIMIT   = 200000
+    PRUNE_PROTECT   = 40000 // Protect recent 40k tokens
+    PRUNE_MINIMUM   = 20000 // Minimum tokens to justify pruning
+    COMPACT_TRIGGER = 0.85  // 85% threshold
+)
+
+func (r *Runtime) EvaluateContextPressure(session *Session) {
+    currentTokens := session.GetTotalTokens()
+    
+    // Check for critical overflow
+    if float64(currentTokens) > float64(CONTEXT_LIMIT) * COMPACT_TRIGGER {
+        if r.config.AutoCompact {
+            r.TriggerCompaction(session)
+        } else {
+            session.WarnUser("Context at 85% capacity. Recommend /compact.")
+        }
+    }
+
+    // Background pruning of tool outputs
+    if currentTokens > PRUNE_PROTECT + PRUNE_MINIMUM {
+        r.PruneDeepHistory(session, "half") // Keep 75% of messages
+    }
+}
+
+func (r *Runtime) TriggerCompaction(session *Session) {
+    // 1. Generate summary using the Recent Message Summarization agent
+    summary := r.Summarizer.Generate(session.RecentHistory)
+    
+    // 2. Archive current history to SQLite for /resume capabilities
+    r.DB.ArchiveSession(session.ID, session.History)
+    
+    // 3. Reinitialize session with summary as "hidden context"
+    session.ResetWithSummary(summary)
+    session.AppendUserMessage("Continue if you have next steps.")
+}
+```
+
+## **Conclusion: The Cognitive Architecture of Agentic Runtimes**
+
+Context engineering has evolved from a simple prompt-length optimization into a complex discipline of state management. By treating the context window as a tiered, dynamic resource—rather than a passive accumulator of history—agents can overcome the inherent limitations of transformer-based reasoning. The integration of observation masking to reduce verbosity, structured note-taking to ensure long-term persistence, and sub-agent isolation to maintain technical resolution forms the triad of a modern agentic architecture. As models move toward native context awareness, the ability of a runtime to intelligently shard, prune, and persist information will remain the primary determinant of agentic success in real-world environments.

package/.OLD/STEP-1/RESEARCH-RESULTS/Deep Research: System Prompt Architecture for AI Agent Runtimes.md

@@ -0,0 +1,283 @@
+# **Architectural Paradigms for Modular System Prompts in Agentic Runtimes: A Comprehensive Analysis of Claude Code, OpenCode, and Cursor Implementation Strategies**
+
+The engineering of autonomous agents has transitioned from basic prompt engineering toward a sophisticated discipline defined as context engineering. As large language models (LLMs) are integrated into terminal-based runtimes and integrated development environments (IDEs), the structural requirements for directing their behavior have become increasingly complex. Modern agentic runtimes like Claude Code, OpenCode, and Cursor do not rely on monolithic instructions; instead, they utilize modular architectures that dynamically assemble system prompts from a registry of specialized fragments. This report investigates the design patterns, taxonomy, and technical specifications of these systems to provide a definitive blueprint for the KhaBotCLI modular system prompt architecture.
+
+## **Foundations of Modern System Prompt Architectures**
+
+The shift toward modularity in system prompts is driven by the necessity to balance instructional specificity with the finite attentional budget of the model. Research into the phenomenon of context rot suggests that as the total token count in a context window increases, the model's adherence to specific instructions can diminish.1 To combat this, production agents utilize a "just-in-time" assembly logic, injecting only the instructional fragments relevant to the current environmental state, available tools, and active sub-agent role.1
+
+In the context of the Claude Agent SDK and Claude Code, this is realized through a system of over 110 discrete prompt strings.3 These strings represent an evolution from "personality" definitions to "operational policies" that dictate how the agent interacts with the filesystem, handles errors, and manages its own cognitive state.4 The goal of such an architecture is to maintain the "Goldilocks zone" or the "right altitude"—providing instructions specific enough to guide behavior but flexible enough to allow for the model's inherent reasoning capabilities.1
+
+## **Taxonomic Analysis of the Claude Code Prompt Registry**
+
+Claude Code v2.1.62 serves as the primary case study for a highly fragmented system prompt architecture. The system does not treat the system prompt as a static string but as an array of components orchestrated by the runtime. The registry is categorized by function, allowing the orchestrator to pull specific fragments based on session telemetry.3
+
+### **Classification of System Prompt Categories**
+
+The strings extracted from the Claude Code source reveal a sophisticated taxonomy. This organization allows the runtime to manage different operational modes without reloading the entire instructional set, thereby optimizing for prompt caching and latency.7
+
+| Category | Primary Function | Examples and Token Counts |
+| :---- | :---- | :---- |
+| **Base System Prompt** | Establishes the core identity as an interactive CLI tool and aligns it with safety protocols. | "Main system prompt" (269 tks), "Identity and safety" (300 tks).3 |
+| **Task Fragments** | Operational guidelines for code modification and repository interaction. | "Avoid over-engineering," "Read before modifying," "No premature abstractions".3 |
+| **Tool Descriptions** | Detailed instructions and schemas for individual tools in the registry. | 18+ tools including Bash, Write, Grep, Glob, Task.3 |
+| **Agent Blueprints** | Specialized system prompts for sub-agents spawned via the Task tool. | "Explore" (400 tks), "Plan" (1,200 tks), "Compaction" (278 tks).3 |
+| **Utility Prompts** | Logic for background tasks such as title generation and memory management. | "Session Search" (439 tks), "Title generation" (184 tks), "Memory update" (756 tks).3 |
+| **System Reminders** | Mid-conversation injections to correct drift or enforce specific styles. | "No flattery," "No emojis," "Objectivity".3 |
+
+The assembly of these fragments is handled by modules such as system.ts and instruction.ts, which gather environmental data like the current directory, OS, and platform to populate templates before they are passed to the LLM.6
+
+### **Logic for "Doing Tasks" Fragments**
+
+A subset of the Claude Code registry, referred to as "Doing Tasks" fragments, is critical for maintaining high-quality code output. These instructions are typically always included when the agent is in a mode capable of modification.3 They specify behavioral heuristics that prevent common LLM pitfalls in software engineering:
+
+* **Avoiding Over-engineering**: Instructions explicitly command the model to solve the immediate problem without adding unnecessary complexity or future-proofing.3  
+* **Reading Before Modifying**: A strict rule that requires the agent to read the contents or a relevant section of a file before applying an edit, ensuring context-aware changes.14  
+* **Instruction Hierarchy**: Explicit orders to prioritize CLAUDE.md and user-specific rules over general system defaults, ensuring the agent adheres to repository-specific norms.10
+
+## **OpenCode and the Configuration-Driven Architecture**
+
+While Claude Code uses a more integrated assembly logic, OpenCode provides a transparent, configuration-driven approach. OpenCode allows developers to define agents and their associated prompts through a hierarchical set of JSON and Markdown files.17
+
+### **File-Based Prompting and Reference Syntax**
+
+A defining feature of the OpenCode architecture is the use of file-based references within the configuration. Instead of embedding large strings in JSON, developers use the {file:./prompts/filename.txt} syntax.18 This separation of concerns allows for:
+
+* **Version Control**: Prompts can be versioned independently of the agent logic.18  
+* **Modularity**: Different agents can reference the same instructional fragments, such as a shared "safety protocol" or "code style guide".18  
+* **Dynamic Path Resolution**: Paths are resolved relative to the configuration file, allowing for project-specific overrides of global prompts.18
+
+### **Precedence Hierarchy in OpenCode**
+
+The OpenCode runtime evaluates prompts based on a strict priority system. This ensures that organizational or repository-specific rules are never overshadowed by generic global defaults.17
+
+| Priority | Location | Usage Scenario |
+| :---- | :---- | :---- |
+| **Highest** | .opencode/agents/*.md | Project-specific overrides for a particular feature or module.18 |
+| **High** | opencode.json (Project Root) | Repository-wide settings and tool permissions.17 |
+| **Medium** | ~/.config/opencode/agents/ | User-defined global agents for specialized tasks like security auditing.17 |
+| **Low** | Organization Defaults | Remote configuration fetched via .well-known/opencode endpoint.17 |
+| **Lowest** | Bundled System Prompts | Internal defaults provided with the OpenCode installation.22 |
+
+This hierarchy allows a "Security Auditor" agent to have a system prompt that focuses entirely on input validation and vulnerability detection, while disabling any tools that might commit code, such as write or patch.18
+
+## **Specialization through Sub-Agent Architectures**
+
+Both Claude Code and OpenCode utilize sub-agents to bypass the context window limitations and prevent information overload. This is accomplished by spawning specialized agents with restricted toolsets and tailored system prompts via the Task tool.1
+
+### **Functional Divergence in Sub-Agent Prompts**
+
+The system prompt for the lead agent (the "Orchestrator") differs significantly from those of its sub-agents. The lead agent is prompted to think holistically, managing high-level goals and synthesizing information returned from sub-tasks.1 In contrast, sub-agents are designed for narrow execution.
+
+1. **Explore Agent**: Focused on read-only navigation. Its system prompt emphasizes rapid pattern matching and directory traversal using Read, Glob, and Grep.11  
+2. **Plan Agent**: Operates in "metacognition" mode. The prompt instructs it to analyze the architecture and draft a PLAN.md before any implementation occurs. It is often restricted from using execution tools to prevent premature coding.11  
+3. **Compaction Agent**: A utility agent whose system prompt provides instructions for summarizing a long conversation into a lossless state representation. It is instructed on what to preserve (architectural decisions, unsolved bugs) and what to discard (raw terminal output).1
+
+When a sub-agent completes its task, it returns a summary of approximately 1,000–2,000 tokens to the lead agent, effectively performing "manual" context compression and preserving the lead agent's attention budget.1
+
+## **Conditional Fragment Inclusion: Situation-Aware Prompting**
+
+A robust agent runtime must programmatically alter its system prompt based on the environmental context. This ensures the model is aware of the tools and constraints specific to its current workspace.2
+
+### **Environmental Signal Integration**
+
+The orchestrator within the runtime performs a series of environment checks to determine which instructional blocks should be injected into the final system message.6
+
+* **Git Awareness**: If a .git directory is detected, the orchestrator includes fragments regarding git status, branch conventions, and commit requirements.25  
+* **LSP Diagnostics**: If a Language Server Protocol (LSP) server is active, instructions are added telling the model to prioritize LSP diagnostics for error detection and go-to-definition for context.6  
+* **Hook Protocols**: When project-specific hooks are defined (e.g., in .claude/hooks/), the prompt is updated to mandate their execution after any file modification.11  
+* **MCP Connectivity**: The inclusion of Model Context Protocol (MCP) tool descriptions is conditional on whether the relevant MCP servers are connected and authenticated.3
+
+This conditional logic prevents the agent from attempting to use tools like git commit in a non-repository directory or from relying on outdated grep results when live LSP diagnostics are available.6
+
+## **System Reminders and Mid-Conversation Interventions**
+
+The "system reminder" pattern involves injecting small instructional blocks directly into the conversation history at specific intervals. This is a critical mechanism for preventing "instructional drift" during long sessions.3
+
+### **Trigger Mechanisms and Content**
+
+Claude Code utilizes approximately 40 different system reminders. These are not static parts of the system prompt but are dynamically triggered by the runtime.3
+
+| Trigger Type | Mechanism | Reminder Content Example |
+| :---- | :---- | :---- |
+| **Token Threshold** | Injected when context exceeds 15,000–20,000 tokens.13 | "Maintain objectivity; avoid flattery; do not use emojis; be critical and honest".13 |
+| **Stall Detection** | Injected after a series of failing or repetitive tool calls.5 | "Step back and re-evaluate your plan; check the TODO list; verify if you are stuck in a loop".18 |
+| **Tool Usage Rules** | Injected alongside tool results for high-risk tools like Bash.5 | "NEVER create files unless absolutely necessary; ALWAYS prefer editing existing files".5 |
+| **Style Adherence** | Injected when the active output style (e.g., Learning, Explanatory) is toggled.33 | "Provide educational 'Insights' between tasks; ask the user to contribute code".33 |
+
+Research indicates that these reminders are highly effective at forcing the model to adhere to stylistic and safety constraints, even when the initial system prompt has been pushed deep into the model's history.5 However, they consume additional tokens and can sometimes cause "bitterness" in the model's tone if the instructions are perceived as overly restrictive.13
+
+## **Token Budgeting and Context Management Strategies**
+
+The size of the system prompt has a direct impact on the model's performance and the cost of the session. A typical Claude Code system prompt, when including all tool descriptions and environmental context, is reported to reach approximately 24,000 tokens.7
+
+### **Optimization Techniques for System Prompt Size**
+
+To manage such large prompts without degrading response quality, runtimes employ several strategies:
+
+1. **Prompt Caching**: By structuring the system prompt as a static, pre-cached block, runtimes can significantly reduce the cost of repeated interactions. The caching allows the system prompt tokens to be billed at a lower rate and processed faster.7  
+2. **Lazy Loading (Progressive Disclosure)**: Tools like "Tool Search" allow the agent to only load the full description and schema of a tool when it is deemed relevant to the task.35  
+3. **Hierarchical Selection**: Instead of loading every sub-agent prompt, only the "Main" agent is loaded until the model invokes the Task tool, at which point the specialized sub-agent prompt is loaded into a fresh context.1  
+4. **Auto-Compaction**: When the context window approaches its limit (e.g., 200,000 tokens), the runtime uses a utility agent to summarize the conversation, discarding redundant terminal outputs while retaining critical state.1
+
+The effective context usage ![][image1] can be represented as:
+
+![][image2]  
+where ![][image3] is the system prompt, ![][image4] are conversation turns, and ![][image5] is the new user input. Minimizing ![][image3] or utilizing lazy loading ensures more room for ![][image4] before compaction is required.7
+
+## **User-Customizable Prompts and Project-Level Instructions**
+
+Modern agents must allow users to inject their own rules without breaking the core system logic. This is typically achieved through CLAUDE.md (for Claude Code) or .cursorrules (for Cursor).16
+
+### **The Role of CLAUDE.md and AGENT.md**
+
+These files act as "persistent memory" for a specific repository. When an agent starts, it reads these files and appends them to its context.16
+
+* **Priority Hierarchy**: In most runtimes, user-defined rules in CLAUDE.md are given higher priority than general system instructions. If the system prompt says "use tabs" but CLAUDE.md says "use spaces," the agent is instructed to follow the project-specific rule.10  
+* **Merging Logic**: Runtimes often inject these instructions as a "pseudo-user message" at the start of the session or append them to the system prompt block.33  
+* **Creation Assistants**: Tools like Claude Code provide assistants to help users generate high-quality CLAUDE.md files by analyzing the existing codebase and extracting patterns.3
+
+### **Agent Skills vs. Rules**
+
+The evolution of these systems has led to "Agent Skills"—an open standard for portable, versioned capabilities. Unlike rules, which are always active, skills are only loaded when the agent determines they are relevant based on a short description.35 This "progressive loading" is a key strategy for maintaining a lean system prompt while providing vast functional expertise.38
+
+## **Design Specification for KhaBotCLI System Prompt Architecture**
+
+Based on the preceding analysis of industry standards, the KhaBotCLI architecture should be built on a modular, file-based registry that supports dynamic assembly and mid-conversation reminders.
+
+### **Complete Taxonomy of System Prompt Categories**
+
+| Category | Filename Prefix | Inclusion Logic |
+| :---- | :---- | :---- |
+| **Base Core** | core_* | Always included; contains identity, safety, and core safety guardrails. |
+| **Task Heuristics** | task_* | Included when modification tools are active; guidelines like "no over-engineering." |
+| **Tool Registry** | tool_* | Conditional; only loaded for tools available in the current environment. |
+| **Sub-Agents** | agent_* | Specialized; one agent prompt per Task invocation (Explore, Plan, Execute, Compact). |
+| **Environment** | env_* | Template-based; populated with Git status, LSP health, and OS details at runtime. |
+| **Reminders** | rem_* | Dynamic; injected mid-turn based on token count or stall detection. |
+| **User Rules** | user_* | External; read from AGENT.md or .khabot/rules.md in the project root. |
+
+### **Template for KhaBotCLI Main Agent**
+
+# **KhaBotCLI Main Agent: System Identity**
+
+You are KhaBotCLI, an advanced autonomous terminal agent designed for high-precision software engineering and systems administration.
+
+Current Working Directory: {{cwd}}
+
+Platform: {{os_platform}}
+
+Git Status: {{git_status}}
+
+## **Core Operational Policies**
+
+1. **Holistic Planning**: Before any modification, use 'Explore' to understand dependencies and 'Plan' to draft a trajectory.  
+2. **Context Hygiene**: Prefer targeted file reads (e.g., line ranges) over full file loads to conserve tokens.  
+3. **Correctness First**: Prioritize architectural integrity and project-specific rules in AGENT.md over speed.  
+4. **Tool Safety**: Verify all Bash commands before execution; never execute 'rm' or 'nuke' commands without explicit user confirmation.
+
+## **Instruction Priority**
+
+1. Immediate User Message  
+2. Project-level AGENT.md  
+3. Global user settings  
+4. This system prompt
+
+### **Sub-Agent Template Specifications**
+
+#### **1. Explore Agent (Specialist)**
+
+* **Focus**: Rapid codebase navigation and pattern discovery.  
+* **Constraints**: Read-only access; no modification tools.  
+* **Instruction**: "Find all occurrences of [pattern]; identify architectural entry points; do not propose fixes, only report findings."
+
+#### **2. Plan Agent (Architect)**
+
+* **Focus**: Analytical reasoning and implementation strategy.  
+* **Constraints**: Limited toolset (Read, Glob, Grep); access to WritePlan tool.  
+* **Instruction**: "Analyze the requirement; evaluate 3 possible solutions; output a step-by-step implementation guide in PLAN.md."
+
+#### **3. Execute Agent (Implementer)**
+
+* **Focus**: Atomic task completion.  
+* **Constraints**: Full tool access; scoped to specific files identified by the Plan agent.  
+* **Instruction**: "Follow the provided PLAN.md; implement changes; run tests; report success or failure; do not stray from the scope."
+
+#### **4. Compact Agent (Maintenance)**
+
+* **Focus**: Lossless context compression.  
+* **Constraints**: Internal utility; no external tool access.  
+* **Instruction**: "Summarize the architectural decisions, current state of the TODO list, and unresolved bugs; discard raw terminal logs."
+
+### **Conditional Fragment Inclusion Rules**
+
+The KhaBotCLI orchestrator should apply the following inclusion logic based on environmental triggers:
+
+| Trigger | Fragment to Include | Rationale |
+| :---- | :---- | :---- |
+| directory_has_git | env_git_protocol.txt | Ensures commits follow repository conventions and uses git status for state tracking.25 |
+| lsp_server_active | env_lsp_support.txt | Directs the model to use LSP diagnostics for real-time error feedback during edit calls.6 |
+| has_agent_md | user_project_rules.txt | Injects repo-specific standards to override general defaults.16 |
+| mcp_active_servers | tool_mcp_registry.txt | Dynamically appends tool definitions for connected MCP services.30 |
+| is_vision_model | env_vision_guide.txt | Provides instructions for interpreting screenshot and diagram attachments.3 |
+
+### **System Reminder Specification for KhaBotCLI**
+
+Reminders should be injected as <system-reminder> blocks within the conversation flow to maintain focus without replacing the system prompt.
+
+1. **Stall Reminder** (Trigger: 3 failed tool calls): "You have failed to execute this task three times. Please use 'Read' to re-verify the file content or 'Explore' to find alternative patterns."  
+2. **Long Session Reminder** (Trigger: >20,000 tokens): "Warning: Context window is filling. Avoid flattery and conversational filler. Be direct and objective. Focus strictly on the technical task."  
+3. **Safe-Edit Reminder** (Trigger: Prior to Write or Edit call): "Reminder: Always read the lines surrounding your target edit area to ensure whitespace and indentation alignment."  
+4. **Plan Adherence** (Trigger: Mid-task check): "Are you following the approved PLAN.md? If the plan is no longer valid, use 'ExitPlanMode' to request a revision."
+
+### **Token Budget Recommendation per Category**
+
+| Category | Recommended Budget (Tokens) | Management Strategy |
+| :---- | :---- | :---- |
+| **Base Core** | 500 | Static; cached for the entire session. |
+| **Task Heuristics** | 400 | Included only in 'Build' or 'Execute' modes. |
+| **Tool Registry** | 5,000 | Use progressive disclosure for non-essential tools. |
+| **Sub-Agents** | 1,000 | Only one sub-agent prompt is loaded at a time. |
+| **Env & User Rules** | 1,500 | Variable based on AGENT.md size; cap AGENT.md at 800 tokens. |
+| **Total Target** | **~8,400** | Optimize for speed and minimal context rot. |
+
+### **Proposed File Structure for ./system-prompts/**
+
+A modular directory structure ensures that the runtime can easily manage and update individual fragments without affecting the core orchestrator logic.
+
+./system-prompts/
+
+├── core/
+│ ├── identity.txt # KhaBotCLI personality
+│ ├── safety.txt # Refusal styles and guardrails
+│ └── hierarchy.txt # Instruction priority logic
+├── agents/
+│ ├── orchestrator.md # Main agent logic
+│ ├── explore.md # Read-only exploration agent
+│ ├── plan.md # Architectural planning agent
+│ ├── execute.md # Atomic task execution agent
+│ └── compact.md # Context compaction utility
+├── environment/
+│ ├── git_aware.txt # Protocols for git repositories
+│ ├── lsp_aware.txt # Protocols for LSP-enabled workspaces
+│ ├── hooks_aware.txt # Protocols for project hooks
+│ └── vision_aware.txt # Instructions for image analysis
+├── tools/
+│ ├── schemas/ # JSON schemas for each tool
+│ │ ├── bash.json
+│ │ ├── read.json
+│ │ └── task.json
+│ └── usage_rules.txt # General tool usage heuristics
+├── reminders/
+│ ├── token_drift.txt # Long conversation correction
+│ ├── stall_recovery.txt # Logic for looping agents
+│ └── style_correction.txt # Formatting and tone reminders
+└── metadata.json # Mapping of fragments to triggers
+
+## **Insights into Context Maintenance and Evolution**
+
+The transition from static prompts to modular runtimes represents a broader trend in AI toward "Agentic Memory." Systems like Claude Code are increasingly using external files (e.g., claude-progress.txt and features_list.json) to store state that would otherwise clutter the system prompt.1 This allows the system prompt to remain focused on *policy* (the "how") while external files handle *state* (the "what").
+
+The inclusion of "liberation prompts" in the developer community highlights a growing tension between safety-oriented system reminders and the technical utility of the agent.31 A high-performance architecture like KhaBotCLI must therefore be designed with "tunable objectivity," allowing the orchestrator to adjust the intensity of system reminders based on the user's expertise level and the complexity of the task.
+
+The architectural success of Claude Code and OpenCode demonstrates that the most effective agents are not those with the longest instructions, but those with the most *relevant* instructions. By utilizing a modular taxonomy, conditional inclusion, and mid-conversation reminders, the KhaBotCLI runtime will be positioned to handle massive codebases and complex multi-step tasks with a level of reliability and precision that matches or exceeds current industry standards. This architecture ensures that as models evolve and context windows expand, the system can scale its instructional density without sacrificing the focus or intelligence of the underlying model.