AGENTS.md ยท diff
git:20260503.cba5627 to git:20260711.35ed150
10 added, 9 removed. Audit A to A.
<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
# AI DevOps Framework - Developer Guide
<!-- AI-CONTEXT-START -->
## Quick Reference
- **User Guide**: `.agents/AGENTS.md` (deployed to `~/.aidevops/agents/`)
- **Commands**: `./setup.sh` (deploy) | `.agents/scripts/linters-local.sh` (quality) | `.agents/scripts/version-manager.sh release [major|minor|patch]`
- - **Config**: Runtime-specific (see `.agents/AGENTS.md` "Runtime-Specific References")
+ - **Config**: Runtime-specific (see `.agents/AGENTS.md` "Runtime References")
- **Quality**: `.agents/AGENTS.md` "Framework Rules"
**File Structure**: `TODO.md` (tasks), `todo/` (plans, PRDs), `.agents/` (agents, tools, services, workflows, scripts).
**Before extending**: Read `.agents/aidevops/architecture.md` (design patterns, conventions, extension guide).
<!-- AI-CONTEXT-END -->
## Two AGENTS.md Files
| File | Purpose | Audience |
|------|---------|----------|
| `~/Git/aidevops/AGENTS.md` | Development guide | Contributors |
| `~/Git/aidevops/.agents/AGENTS.md` | User guide | Users of aidevops |
The `.agents/AGENTS.md` is copied to `~/.aidevops/agents/AGENTS.md` by `setup.sh`.
## Development Lifecycle
- See `.agents/AGENTS.md` "Development Lifecycle" for the full lifecycle.
- Completion self-check: see `.agents/AGENTS.md` "Framework Rules > Completion and quality discipline".
+ See `.agents/AGENTS.md` "Operational Routines" for code-change routing and
+ `.agents/AGENTS.md` "Git Workflow" for the full lifecycle.
+ Completion self-check: see `.agents/AGENTS.md` "Framework Rules > Task and completion discipline".
## Contributing
See `.agents/aidevops/` (architecture, setup) and `.agents/tools/` (agent/MCP authoring) for framework development guidance:
| File | Purpose |
|------|---------|
| `.agents/tools/build-agent/build-agent.md` | Composing efficient agents |
| `.agents/tools/build-agent/agent-review.md` | Reviewing and improving agents |
| `.agents/tools/build-mcp/build-mcp.md` | MCP server development |
| `.agents/tools/mcp-toolkit/mcporter.md` | MCP runtime toolkit (discover, call, generate CLIs) |
| `.agents/aidevops/architecture.md` | Framework structure |
| `.agents/aidevops/setup.md` | AI guide to setup.sh |
## Agent Design Principles
- From `tools/build-agent/build-agent.md`:
+ From `.agents/tools/build-agent/build-agent.md`:
- 1. **Instruction budget**: ~50-100 max in root AGENTS.md
+ 1. **Instruction budget**: ~50-100 per agent is a maintainability heuristic; investigate overages, but do not cut solely to hit the count
2. **Universal applicability**: Every instruction relevant to >80% of tasks
3. **Progressive disclosure**: Pointers to subagents, not inline content
- 4. **Code examples**: Only when authoritative (use `file:line` refs otherwise)
+ 4. **Code examples**: Only when authoritative; otherwise use stable `rg "pattern"` search references or section headings
5. **Self-assessment**: Flag issues with evidence, complete task first
Contributor rule: changes that add or expand always-loaded guidance (`AGENTS.md`,
- `.agents/AGENTS.md`, `prompts/build.txt`) must prefer a short pointer plus a
+ `.agents/AGENTS.md`, `.agents/prompts/build.txt`) must prefer a short pointer plus a
reference/workflow document, keep `.agents/AGENTS.md` under the CI size ratchet,
and justify any intentional baseline increase in the PR body.
## Security
- Security rules: see `.agents/AGENTS.md` "Framework Rules > Security Rules". Additional contributor rule:
+ Security rules: see `.agents/AGENTS.md` "Framework Rules > Security and external content". Additional contributor rule:
- Use placeholders in examples, note secure storage location
## Quality Workflow
```bash
# Before committing
.agents/scripts/linters-local.sh
# ShellCheck all scripts
find .agents/scripts/ -name "*.sh" -exec shellcheck {} \;
# Release new version
.agents/scripts/version-manager.sh release [major|minor|patch]
```
## Self-Assessment Protocol
- From `tools/build-agent/build-agent.md`:
+ From `.agents/tools/build-agent/build-agent.md`:
- **Triggers**: Observable failure, user correction, contradiction, staleness
- **Process**: Complete task, cite evidence, check duplicates, propose fix
- **Duplicates**: Always `rg "pattern" .agents/` before adding instructions