Agent Context Profiles
Relevant source files
The following files were used as context for generating this wiki page:
Agent Context Profiles define the behavioral boundaries and operational permissions for AI agents working within the flext-quality repository. These profiles regulate how agents use the Beads (bd) issue tracking system and govern their authority to perform git operations, run quality gates, and sync data.
The project uses these profiles to maintain strict coordination between human operators and AI agents, ensuring that automated actions align with specific project needs and safety requirements. The profiles are subordinate to explicit instructions from users or orchestrators.
Sources: CLAUDE.md:36-39, AGENTS.md:143-146
Profile Definitions
The system provides three standard profiles that dictate agent behavior during task tracking and session completion.
| Profile | Task Tracking Usage | Git & Sync Policy | Quality Gate Policy |
|---|---|---|---|
| Conservative (Default) | Uses bd for tracking. | No git commits, pushes, or Dolt syncs unless explicitly asked. | Reports changed files and validation results at handoff. |
| Minimal | Uses bd via bd prime pointers. | Follows Conservative git policy unless active instructions differ. | Focuses on instruction pointers. |
| Team-maintainer | Uses bd for tracking. | May close beads, commit, and push during session close if opted-in. | Runs quality gates as part of the session close protocol. |
Sources: CLAUDE.md:41-47, AGENTS.md:148-154
Selection Logic
Agents select a profile based on repository settings or explicit user requests. If no specific profile is defined, the agent defaults to the Conservative profile. A "do not commit" or "do not push" instruction always overrides the permissions of the Team-maintainer profile.
Sources: CLAUDE.md:46-47, AGENTS.md:153-154
Session Completion Protocol
The session completion protocol defines the steps an agent must take when ending a workflow. The specific execution of step 4 depends on the active Agent Context Profile.
The diagram shows the branching logic in the session completion protocol based on the assigned profile.
Step 4 Execution Details
- Conservative/Minimal: The agent runs
git status, reports proposed commands, and waits for user approval. - Team-maintainer: The agent executes
git pull --rebase,bd dolt push(orgit push), andgit statusautomatically.
Sources: CLAUDE.md:49-65, AGENTS.md:156-173
Technical Integration
MCP Tools and Context
Agents interact with the project context through Model Context Protocol (MCP) tools. These tools allow agents to search project memory and codebases to ensure their actions conform to the defined profiles and existing project knowledge.
search_memory: Searches cross-session memory viaclaude-mem.search_code: Performs semantic code search viaclaude-context.execute_hook: Manually triggers registered project hooks.
Sources: src/flext_quality/mcp/tools.py:23-85, AGENTS.md:25-27
Execution Contracts
The ExecutionRequest and ExecutionResult models define how agents request script execution within the environment. These contracts ensure that agent actions stay within the timeouts and runtimes (e.g., Python, Ruff, Basedpyright) allowed by the active profile.
class ExecutionRequest(_WebModels.ManagedModel):
script_path: Path
runtime: str # e.g. python, ruff, basedpyright
args: t.StrSequence = ()
timeout_ms: int
Sources: src/flext_quality/_models/flextqualitymodels_part_02.py:408-422
Summary
Agent Context Profiles serve as the governance layer for AI interactions within flext-quality. By distinguishing between Conservative, Minimal, and Team-maintainer roles, the system ensures that agents only perform high-impact operations like git pushes and issue closures when specifically authorized, while maintaining consistent task tracking through the Beads system.