AGENTS.md

1<!-- SPDX-License-Identifier: MIT -->
2<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
3 
4# AI DevOps Framework - Developer Guide
5 
6<!-- AI-CONTEXT-START -->
7 
8## Quick Reference
9 
10- **User Guide**: `.agents/AGENTS.md` (deployed to `~/.aidevops/agents/`)
11- **Commands**: `./setup.sh` (deploy) | `.agents/scripts/linters-local.sh` (quality) | `.agents/scripts/version-manager.sh release [major|minor|patch]`
12- **Config**: Runtime-specific (see `.agents/AGENTS.md` "Runtime References")
13- **Quality**: `.agents/AGENTS.md` "Framework Rules"
14 
15**File Structure**: `TODO.md` (tasks), `todo/` (plans, PRDs), `.agents/` (agents, tools, services, workflows, scripts).
16 
17**Before extending**: Read `.agents/aidevops/architecture.md` (design patterns, conventions, extension guide).
18 
19<!-- AI-CONTEXT-END -->
20 
21## Two AGENTS.md Files
22 
23| File | Purpose | Audience |
24|------|---------|----------|
25| `~/Git/aidevops/AGENTS.md` | Development guide | Contributors |
26| `~/Git/aidevops/.agents/AGENTS.md` | User guide | Users of aidevops |
27 
28The `.agents/AGENTS.md` is copied to `~/.aidevops/agents/AGENTS.md` by `setup.sh`.
29 
30## Development Lifecycle
31 
32See `.agents/AGENTS.md` "Operational Routines" for code-change routing and
33`.agents/AGENTS.md` "Git Workflow" for the full lifecycle.
34Completion self-check: see `.agents/AGENTS.md` "Framework Rules > Task and completion discipline".
35 
36## Contributing
37 
38See `.agents/aidevops/` (architecture, setup) and `.agents/tools/` (agent/MCP authoring) for framework development guidance:
39 
40| File | Purpose |
41|------|---------|
42| `.agents/tools/build-agent/build-agent.md` | Composing efficient agents |
43| `.agents/tools/build-agent/agent-review.md` | Reviewing and improving agents |
44| `.agents/tools/build-mcp/build-mcp.md` | MCP server development |
45| `.agents/tools/mcp-toolkit/mcporter.md` | MCP runtime toolkit (discover, call, generate CLIs) |
46| `.agents/aidevops/architecture.md` | Framework structure |
47| `.agents/aidevops/setup.md` | AI guide to setup.sh |
48 
49## Agent Design Principles
50 
51From `.agents/tools/build-agent/build-agent.md`:
52 
531. **Instruction budget**: ~50-100 per agent is a maintainability heuristic; investigate overages, but do not cut solely to hit the count
542. **Universal applicability**: Every instruction relevant to >80% of tasks
553. **Progressive disclosure**: Pointers to subagents, not inline content
564. **Code examples**: Only when authoritative; otherwise use stable `rg "pattern"` search references or section headings
575. **Self-assessment**: Flag issues with evidence, complete task first
58 
59Contributor rule: changes that add or expand always-loaded guidance (`AGENTS.md`,
60`.agents/AGENTS.md`, `.agents/prompts/build.txt`) must prefer a short pointer plus a
61reference/workflow document, keep `.agents/AGENTS.md` under the CI size ratchet,
62and justify any intentional baseline increase in the PR body.
63 
64## Security
65 
66Security rules: see `.agents/AGENTS.md` "Framework Rules > Security and external content". Additional contributor rule:
67- Use placeholders in examples, note secure storage location
68 
69## Quality Workflow
70 
71```bash
72# Before committing
73.agents/scripts/linters-local.sh
74 
75# ShellCheck all scripts
76find .agents/scripts/ -name &quot;*.sh&quot; -exec shellcheck {} \;
77 
78# Release new version
79.agents/scripts/version-manager.sh release [major|minor|patch]
80```
81 
82## Self-Assessment Protocol
83 
84From `.agents/tools/build-agent/build-agent.md`:
85 
86- **Triggers**: Observable failure, user correction, contradiction, staleness
87- **Process**: Complete task, cite evidence, check duplicates, propose fix
88- **Duplicates**: Always `rg "pattern" .agents/` before adding instructions
89