System Prompts & Context
Relevant source files
The following files were used as context for generating this wiki page:
System prompts and context management form the foundational intelligence layer of QQcode. This system is responsible for aggregating environment data, project structure, user instructions, and specialized operational modes into a cohesive set of instructions that guide the AI agent's behavior. It ensures the LLM understands its role as a CLI coding assistant, the limitations of its current environment (such as OS-specific command rules), and the specific state of the local codebase it is interacting with.
The system utilizes a modular approach, combining static templates with dynamic content generated at runtime, such as directory trees, git statuses, and active skill definitions. This context-aware architecture allows the agent to provide technically accurate responses and execute tool calls effectively across different platforms and project states.
Core Prompt Architecture
The universal system prompt is constructed by concatenating several distinct sections based on the current configuration and execution state. This process is primarily orchestrated by the get_universal_system_prompt function.
The diagram above shows how different metadata and environmental factors are aggregated into a single prompt string.
Sources: vibe/core/system_prompt.py:270-345, vibe/core/config.py:328-340
Universal Prompt Components
The prompt is built from the following sequence of components:
- Base Identity: The core identity defined in
system_prompt_id(defaulting tocli.md). - Commit Signature: Mandatory co-authoring information for git commits.
- Model Information: Identifying the active model name.
- Operational Modes: Special instructions for modes like "plan" or conversation "compacting".
- Environment Detail: OS platform name and default shell rules (e.g., Windows compatibility).
- Tool & Skill Instructions: Dynamic usage hints from active tools and discovered skills.
- Project Context: The directory tree and git repository state.
Sources: vibe/core/system_prompt.py:279-315, vibe/core/prompts/cli.md:1-15
Project Context Provider
The ProjectContextProvider class is the primary component for gathering local repository metadata. It handles filesystem traversal while respecting .gitignore patterns and enforcing resource limits to prevent context window overflow.
Directory Structure Generation
The system builds an iterative tree representation of the project. It uses a recursive-like generator with depth and file count limits to ensure the prompt remains manageable.
| Configuration Field | Description | Default Value |
|---|---|---|
max_depth | Maximum recursion depth for directory traversal | 3 |
max_files | Total number of file entries to include in the tree | 1000 |
max_chars | Maximum character length for the entire project context | 40,000 |
timeout_seconds | Time limit for generating the directory structure | 2.0s |
Sources: vibe/core/config.py:126-134, vibe/core/system_prompt.py:44-140
Git Integration
The provider executes shell commands to retrieve repository status. This includes the current branch, the main branch name (e.g., main vs master), and a summary of recent commits.
- Git Status: Summarizes changes as
(clean)or listing the number of modified files. - Recent Log: Fetches the last $N$ commits (default 5) with decorations.
Sources: vibe/core/system_prompt.py:175-236
Specialized Operational Modes
Plan Mode
When the agent enters plan mode, the system prompt is appended with restrictive instructions that disable write-access tools. The agent is forced to use a specific workflow involving read_file, grep, and bash (read-only) before calling submit_plan.
Compaction Mode
To handle long-running conversations, the compact.md template instructs the LLM to generate a structured summary of goals, technical decisions, and pending tasks. This summary serves as the "complete context" for future turns to preserve token space.
Sources: vibe/core/prompts/compact.md:1-35
Skill & Tool Context
Dynamic Skill Discovery
The SkillManager scans ./.qqcode/skills/ and ~/.qqcode/skills/ for SKILL.md files. These skills are converted into an XML block within the system prompt to inform the agent of available domain-specific expertise.
# vibe/core/skills/manager.py:202-214
def get_skills_prompt_section(self) -> str:
if not self._skills:
return ""
lines = ["<available_skills>"]
for skill in self._skills.values():
lines.append(f"- name: {skill.name}")
lines.append(f" description: {skill.description}")
lines.append("</available_skills>")
return "\n".join(lines)
Sources: vibe/core/skills/manager.py:58-75, vibe/core/skills/manager.py:202-214
Platform-Specific Rules
The system prompt adapts to the underlying OS. For example, on Windows, it explicitly injects rules forbidding Unix-style commands (ls, grep) and mandating Windows equivalents (dir, where) and backslash paths.
Sources: vibe/core/system_prompt.py:246-267
Summary
The System Prompts & Context module ensures that the QQcode agent is never "blind" to its environment. By combining core identity files (like cli.md) with real-time data from the ProjectContextProvider and SkillManager, the system creates a high-fidelity operational environment. This allows the AI to transition between modes—such as from analysis in Plan Mode to execution in Interactive Mode—while maintaining a consistent understanding of project constraints and platform requirements.
Sources: vibe/core/system_prompt.py:270-345, vibe/core/prompts/cli.md:1-20