System Prompts & Directives

Relevant source files

The following files were used as context for generating this wiki page:

• src/agent/prompt.ts
• src/agent/setup.ts
• src/agent/events.ts
• src/main.ts
• skills/claude-code/SKILL.md

The System Prompts & Directives module in pi-digby is responsible for constructing the operational identity, constraints, and contextual awareness of the agent. It serves as the foundational instruction set for the LLM (Claude), defining how it should interact with users across different platforms (Slack and Linear), manage memory, execute tools, and handle asynchronous events.

The system prompt is not static; it is dynamically rebuilt for every execution cycle to incorporate the latest environment state, including workspace layouts, available skills, active events, and persisted memory. This ensures the agent maintains strict adherence to platform-specific formatting and operational boundaries.

Prompt Construction Architecture

The system prompt is generated by the buildSystemPrompt function, which aggregates multiple data sources into a structured Markdown-based directive.

The diagram above shows the flow of data into the prompt builder, illustrating how platform-specific logic and environmental context are merged into the final instruction set.

Core Directive Components

Component	Description	Source File
Identity	Defines the agent as "digby" and sets a concise, emoji-free tone.	src/agent/prompt.ts:40-42
Formatting	Enforces mrkdwn for Slack or standard Markdown for Linear.	src/agent/prompt.ts:44-58
Workspace	Maps the file system structure (MEMORY.md, skills, logs).	src/agent/prompt.ts:72-81
Event System	Provides instructions for creating and managing cron/one-shot events.	src/agent/prompt.ts:98-146
Memory	Injects global and channel-specific persisted context.	src/agent/prompt.ts:151-158

Sources: src/agent/prompt.ts:32-160, src/agent/setup.ts:182-192

Platform Specific Directives

The system distinguishes between Slack and Linear environments, providing tailored directives for each to ensure correct message rendering and user interaction.

Slack Directives

When operating as a Slack bot, the prompt explicitly forbids standard Markdown links and double-asterisk bolding, requiring mrkdwn syntax (e.g., *bold*, _italic_, and <url|text>). It also provides a mapping of internal IDs to human-readable names for channels and users to facilitate accurate mentions using the <@username> format.
Sources: src/agent/prompt.ts:49-58

Linear Directives

For Linear, the prompt instructs the agent to use standard Markdown. It sets the expectation that responses will be posted as agent activities on specific issues.
Sources: src/agent/prompt.ts:44-47

Operational Constraints and Logic

Silent Completion

A critical directive is the [SILENT] marker. If an agent determines there is nothing actionable to report (especially during periodic event checks), it is instructed to respond with [SILENT]. The harness intercepts this to delete status messages and avoid channel spam.
Sources: src/agent/prompt.ts:140-142, src/agent/setup.ts:289-293

Event Management Logic

The prompt contains detailed "how-to" guides for the agent to manage its own lifecycle via the file system. It describes:

• Immediate Events: Signaling external activities (e.g., GitHub webhooks).
• One-shot Events: Future reminders using ISO timestamps.
• Periodic Events: Recurring tasks defined by standard cron syntax.
• Debouncing: Instructions to prevent event storms from high-frequency triggers.

The sequence above illustrates the interaction between the agent's directives for creating events and the system's execution of those events.
Sources: src/agent/prompt.ts:98-146, src/main.ts:192-208

Skills and Tooling Integration

The system prompt dynamically lists all "Skills" available to the agent. These are structured as custom CLI tools stored in specific workspace directories. Each skill includes a SKILL.md file with YAML frontmatter that the prompt builder parses to explain capabilities to the LLM.

Example: Claude Code Skill

A primary directive for complex implementation tasks is the claude-code skill. The instructions within the prompt (derived from the skill definition) guide the agent on how to:

1. Initialize a task worktree.
2. Clone or pull a repository using gh.
3. Execute claude in --print mode with specific budget constraints.
4. Report structured JSON results back to the user.

Sources: skills/claude-code/SKILL.md:1-55, src/agent/prompt.ts:83-96

Runtime Prompt Rebuilding

The prompt is rebuilt during the run method of the ChannelRunner. This ensures that any changes to the environment—such as new skills created by the agent, updated memory files, or changes in MCP (Model Context Protocol) configurations—are immediately reflected in the next interaction.

// src/agent/setup.ts:182-192
const memory = loadMemory(channelDir);
const skills = loadSkills(channelDir, workingDir);
systemPrompt = buildSystemPrompt({
    workspacePath: workingDir,
    channelId,
    memory,
    channels,
    users,
    skills,
    source: event.source,
});

Sources: src/agent/setup.ts:182-192, src/agent/setup.ts:194-211

Conclusion

The System Prompts & Directives module acts as the "brain's configuration," ensuring pi-digby operates safely within its host environment while maintaining high-context awareness. By dynamically merging file-based memory, skill definitions, and platform-specific formatting rules, the system provides a robust framework for autonomous agent behavior across diverse communication surfaces.