Prompt Management
Relevant source files
The following files were used as context for generating this wiki page:
Prompt Management in Linux Archductor is a centralized system for defining, organizing, and injecting instructions into AI agent sessions. It ensures that agents have the necessary context and behavioral guidelines for specific tasks such as code review, pull request creation, and merge conflict resolution. The system utilizes a combination of shared repository settings, local overrides, and "Prompt Packs" to provide a flexible and robust instruction layer.
The architecture is built around first-class instruction fields within the project settings, allowing users to iterate on prompts as part of their daily workflow. These prompts are automatically injected during various lifecycle events, such as workspace initialization or when staging context for an agent session.
Sources: README.md:144-158, progress.md:118-121
Core Components and Data Structures
PromptSettings
The primary data structure for instructions is the PromptSettings struct, which contains specific fields for different workflow stages.
| Field | Purpose |
|---|---|
new_workspace | Instructions for planning in a new workspace. |
general | Default context used for all agent work in the repository. |
continue_work | Guidance for resuming work from a current state. |
summarize_session | Template for end-of-session summaries. |
handoff | Guidance for leaving context for other agents or users. |
code_review | Specific instructions for code review tasks. |
create_pr | Template for generating pull request content. |
fix_errors | Guidance for fixing CI failures or broken builds. |
resolve_merge_conflicts | Instructions for handling Git conflicts. |
setup_script | Guidance for inferring or updating setup scripts. |
Sources: crates/core/src/settings.rs:43-59, crates/gtk-app/src/settings.rs:242-288
Prompt Packs
Prompt Packs allow for modular sets of instructions. They are stored in .archductor/prompt-packs/ and are referenced in the main settings file. This allows teams to switch between different behavioral profiles (e.g., strict-review, docs-heavy).
Sources: crates/core/src/settings.rs:61-65, crates/core/src/settings.rs:1145-1153, README.md:156-157
Prompt Layering and Resolution
The system resolves prompts through a multi-layer hierarchy. This allows for team-wide defaults to be set in the repository while individuals can maintain private overrides.
The resolution logic merges these layers, where Local Overrides take the highest precedence. If a Prompt Pack is active, its values serve as the base before shared repository settings are applied.
Sources: crates/core/src/settings.rs:136-160, crates/core/src/settings.rs:188-210
Instruction Injection Workflows
Staged Review Prompts
Instructions can be dynamically generated based on the current workspace state. For example, open review comments or failing PR checks can be converted into a "staged review prompt."
- Selection: The user selects review comments or checks in the GTK UI.
- Generation: The system assembles a prompt using the relevant
PromptSettingsfield and the specific context (e.g., the text of the failing check). - Staging: The prompt is set in the
AppStateas astaged_review_prompt. - Injection: When the user sends a message to an agent, the staged prompt is prepended to the input.
Sources: crates/gtk-app/src/workspace_command_center.rs:1594-1620, crates/gtk-app/src/session_surface.rs:320-330
Automated Pull Request Generation
The create_pr prompt is utilized when a user triggers the pull request workflow. The system combines the repository-specific PR instructions with a "context brief" derived from the workspace history.
Sources: crates/gtk-app/src/workspace_command_center.rs:1096-1120
Configuration and Management UI
The GTK application provides a dedicated "Settings" page and "Projects" settings panel for managing these instructions.
Editor Fields
Prompt editors in the UI use dedicated TextView widgets with monospace fonts to facilitate multi-line instruction editing. The UI ensures that settings are saved to the correct layer (Shared vs. Local).
Sources: crates/gtk-app/src/settings.rs:242-290, crates/gtk-app/src/settings.rs:821-831
Prompt Preview
Before launching an agent session, if prompts.general is defined, the application can display a modal preview. This allows the user to verify the instructions that will be injected into the PTY-backed harness.
Sources: crates/gtk-app/src/workspace_command_center.rs:849-880
Technical Implementation Details
Serialization and Formatting
Prompts are stored as strings within TOML tables. The RawPromptSettings struct handles the serialization/deserialization between the disk format and the application's internal model.
#[derive(Debug, Clone, Default, Deserialize, Serialize)]
struct RawPromptSettings {
#[serde(skip_serializing_if = "Option::is_none")]
new_workspace: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
general: Option<String>,
// ... other fields
}
Sources: crates/core/src/settings.rs:445-470
Validation
The system validates prompt-related settings to ensure consistency, such as verifying that prompt_pack.path points to a valid file within the designated directory and that no NUL bytes are present in command strings.
Sources: crates/core/src/settings.rs:395-415
Default Seeding
On repository initialization, the system seeds a default.toml prompt pack. This ensures that agents have a baseline of "sane defaults" for common operations like conventional commit generation and small, reviewable change preferences.
Sources: crates/core/src/settings.rs:1145-1153, crates/core/src/settings.rs:334-360
Summary
Prompt Management provides the instructional infrastructure for Linux Archductor's parallel agent model. By leveraging a layered configuration system and integrating instructions directly into the workspace lifecycle, it enables precise control over agent behavior while maintaining flexibility for individual developer preferences.