AI Prompts and Guards
Relevant source files
The following files were used as context for generating this wiki page:
AI Prompts and Guards define the instructions, constraints, and safety boundaries for AI agents operating within the Opificia software factory. These components ensure that agents follow specific workflows, respect repository policies, and operate within the security parameters defined by the operator.
The system uses a combination of structured system prompts, task-specific implementation prompts, and rigorous guardrails to prevent unauthorized actions. This architecture supports the project's Sovereignty Commitments by ensuring humans remain in control and data access is strictly regulated.
Sources: README.md:5-10, SOVEREIGNTY.md:12-20
AI Agent Workflow and Prompts
The interaction with AI agents, specifically through the Claude harness, follows a structured multi-stage process: planning, implementation, and self-review. Each stage uses specific prompt templates to guide the agent's behavior.
Execution Phases
The following diagram illustrates the data flow between the harness and the AI agent across different task phases.
The diagram shows the sequential progression from task ingestion to the final pull request generation.
Sources: plugins/harness-claude/src/prompts.ts:77-124
Prompt Templates
The project defines specific functions to generate structured Markdown prompts for different tasks.
| Function | Purpose | Key Content |
|---|---|---|
planPrompt | Requests a high-level implementation strategy. | Issue details, relevant code, summary, changes, tests, and risks. |
implementPrompt | Instructs the agent to execute code changes. | Approved plan, coding instructions, and PR description format. |
REVIEW_PROMPT | Triggers a self-audit by the agent before submission. | git diff check, bug identification, and test verification. |
Sources: plugins/harness-claude/src/prompts.ts:91-131
System Constraints and Network Rules
System prompts append specific rules to the AI agent's core instructions. These rules enforce repository hygiene and security boundaries.
Forbidden Actions
Agents are explicitly blocked from modifying critical configuration and policy files. Attempts to change the following files cause the run to fail:
- CI workflows and scripts
CODEOWNERSandMAINTAINERS.mdAGENTS.mdandCLAUDE.md.mcp.jsonor.claude/directories
Sources: plugins/harness-claude/src/prompts.ts:50-55
Network Access Levels
The system prompt dynamically adjusts instructions based on the NetworkLevel configured for the runner.
| Level | Prompt Instruction |
|---|---|
none | No internet access; prohibits installing packages or downloading files. |
registries | Allows HTTPS access to package registries through a configured proxy. |
open | Allows HTTPS access to most hosts; every request is logged. |
Sources: plugins/harness-claude/src/prompts.ts:6-14
Sovereignty and Safety Guards
Guards are enforced through both prompt instructions and architectural commitments to ensure operational sovereignty.
Human-in-the-Loop Guards
The system prompt strictly forbids agents from performing certain Git operations. The harness enforces these rules:
- No Sign-offs: Agents must never add a
Signed-off-byline. - No Commits: Agents are instructed to make changes but never execute
git commit. Opificia or a human maintainer handles the commit process. - Human Approval: By default, no agent can merge or deploy without recorded human approval.
Sources: plugins/harness-claude/src/prompts.ts:58-59, AGENTS.md:32-35, SOVEREIGNTY.md:65-70
Content Processing Guards
The system includes utilities to clean and structure agent output to ensure it meets repository standards.
// plugins/harness-claude/src/prompts.ts:32-39
export function withoutAttribution(text: string): string {
return text
.split("\n")
.filter((line) => !/^\s*(?:\W{0,3}\s*)?Generated with \[?Claude Code/i.test(line) && !/^\s*Co-Authored-By:/i.test(line))
.join("\n")
.trim();
}
This function removes automated attribution lines (e.g., "Generated with Claude Code") to keep pull request descriptions clean.
Sources: [plugins/harness-claude/src/prompts.ts:32-39](https://github.com/opificia/factory/blob/305b9540fcbe8e50df12415c83237a9684062103/?Claude Code/i.test(line) && !/^\s*Co-Authored-By:/i.test(line))
.join("\n")
.trim();
}
This function removes automated attribution lines (e.g., "Generated with Claude Code") to keep pull request descriptions clean.
Sources: [plugins/harness-claude/src/prompts.ts:32-39), [plugins/harness-claude/src/prompts.test.ts:17-21](https://github.com/opificia/factory/blob/305b9540fcbe8e50df12415c83237a9684062103/plugins/harness-claude/src/prompts.test.ts#L17-L21)
## Formatting Requirements
The `DESCRIPTION_FORMAT` constant defines a strict structure for agent replies. This ensures that the generated pull requests follow the [Conventional Commits](https://www.conventionalcommits.org/) standard.
- **Title Line:** Must start with `Title: <type>(<scope>): <summary>`.
- **Description Body:** Must use Markdown with "What changed" and "Tests" sections.
- **Validation:** The harness uses `splitTitle` to extract the commit title and description from the raw agent reply.
Sources: [plugins/harness-claude/src/prompts.ts:15-30](https://github.com/opificia/factory/blob/305b9540fcbe8e50df12415c83237a9684062103/plugins/harness-claude/src/prompts.ts#L15-L30), [plugins/harness-claude/src/prompts.ts:133-149](https://github.com/opificia/factory/blob/305b9540fcbe8e50df12415c83237a9684062103/plugins/harness-claude/src/prompts.ts#L133-L149)
## Summary
AI Prompts and Guards in Opificia establish a controlled environment where AI agents can safely contribute to codebase development. By partitioning tasks into phases, enforcing network and file-level restrictions, and maintaining a strict "human-in-the-loop" requirement, the system ensures that AI assistance does not compromise project sovereignty or security.