| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 12 | 9 | 0% |
| Commands | 0 | 0 | 0 | — |
| Section tags | 1 | 3 | 3 | 14% |
What each file covers
Sections
0 shared · 12 only in A · 9 only in B- − AI DevOps Framework - Developer Guide
- − Quick Reference
- − Two AGENTS.md Files
- − Development Lifecycle
- − Contributing
- − Agent Design Principles
- − Security
- − Quality Workflow
- − Before committing
- − ShellCheck all scripts
- − Release new version
- − Self-Assessment Protocol
- + Codacy Rules
- + CRITICAL: After ANY successful `edit_file` or `reapply` operation
- + When you tried to run the `codacy_cli_analyze` tool and the Codacy CLI is not installed
- + After every response
- + When there are no Codacy MCP Server tools available, or the MCP Server is not reachable
- + Trying to call a tool that needs a rootPath as a parameter
- + CRITICAL: Dependencies and Security Checks
- + General
- + Whenever a call to a Codacy tool that uses `repository` or `organization` as a parameter returns a 404 error
Commands
neither file has anySection tags
1 shared · 3 only in A · 3 only in B- − code-style
- − deployment
- − agent-behaviour
- + setup
- + dependencies
- + do-not
- security
Line diff
marcusquinn/aidevops · AGENTS.md
@@ −1 @@
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 "*.sh" -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
marcusquinn/aidevops · .github/instructions/codacy.instructions.md
@@ +1 @@
1---
2description: Configuration for AI behavior when interacting with Codacy's MCP Server
3applyTo: '**'
4---
5
6<!-- SPDX-License-Identifier: MIT -->
7<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
8
9# Codacy Rules
10
11Configuration for AI behavior when interacting with Codacy's MCP Server
12
13## CRITICAL: After ANY successful `edit_file` or `reapply` operation
14
15- YOU MUST IMMEDIATELY run the `codacy_cli_analyze` tool from Codacy's MCP Server for each file that was edited, with:
16- `rootPath`: set to the workspace path
17- `file`: set to the path of the edited file
18- `tool`: leave empty or unset
19- If any issues are found in the new edits, propose and apply fixes for them.
20- > NOTE: Failure to follow this rule is considered a critical error.
21
22## When you tried to run the `codacy_cli_analyze` tool and the Codacy CLI is not installed
23
24- Ask the user 'Codacy CLI is not installed. Would you like me to install it now?'
25- If the user responds with "yes", run the `codacy_cli_install` tool and then continue with the original task
26- If the user responds with "no", instruct the user that they can disable automatic analysis in the extension settings
27- Wait for the user to respond before proceeding with any other actions
28
29## After every response
30
31- If you made any file edits in this conversation, verify you ran `codacy_cli_analyze` tool from Codacy's MCP Server
32
33## When there are no Codacy MCP Server tools available, or the MCP Server is not reachable
34
35- Suggest the user the following troubleshooting steps:
36- Try to reset the MCP on the extension
37- If the user is using VSCode, suggest them to review their Copilot > MCP settings in Github, under their organization or personal account. Refer them to Settings > Copilot > Enable MCP servers in Copilot. Suggested URL (https://github.com/settings/copilot/features) or https://github.com/organizations/{organization-name}/settings/copilot/features (This can only be done by their organization admins / owners)
38- If none of the above steps work, suggest the user to contact Codacy support
39
40## Trying to call a tool that needs a rootPath as a parameter
41
42- Always use the standard, non-URL-encoded file system path
43
44## CRITICAL: Dependencies and Security Checks
45
46- IMMEDIATELY after ANY of these actions:
47- Running npm/yarn/pnpm install
48- Adding dependencies to package.json
49- Adding requirements to requirements.txt
50- Adding dependencies to pom.xml
51- Adding dependencies to build.gradle
52- Any other package manager operations
53- You MUST run the `codacy_cli_analyze` tool with:
54- `rootPath`: set to the workspace path
55- `tool`: set to "trivy"
56- `file`: leave empty or unset
57- If any vulnerabilities are found because of the newly added packages:
58- Stop all other operations
59- Propose and apply fixes for the security issues
60- Only continue with the original task after security issues are resolved
61- EXAMPLE:
62- After: npm install react-markdown
63- Do: Run codacy_cli_analyze with trivy
64- Before: Continuing with any other tasks
65
66## General
67
68- Repeat the relevant steps for each modified file.
69- "Propose fixes" means to both suggest and, if possible, automatically apply the fixes.
70- You MUST NOT wait for the user to ask for analysis or remind you to run the tool.
71- Do not run `codacy_cli_analyze` looking for changes in duplicated code or code complexity metrics.
72- Complexity metrics are different from complexity issues. When trying to fix complexity in a repository or file, focus on solving the complexity issues and ignore the complexity metric.
73- Do not run `codacy_cli_analyze` looking for changes in code coverage.
74- Do not try to manually install Codacy CLI using either brew, npm, npx, or any other package manager.
75- If the Codacy CLI is not installed, just run the `codacy_cli_analyze` tool from Codacy's MCP Server.
76- When calling `codacy_cli_analyze`, only send provider, organization and repository if the project is a git repository.
77
78## Whenever a call to a Codacy tool that uses `repository` or `organization` as a parameter returns a 404 error
79
80- Offer to run the `codacy_setup_repository` tool to add the repository to Codacy
81- If the user accepts, run the `codacy_setup_repository` tool
82- Do not ever try to run the `codacy_setup_repository` tool on your own
83- After setup, immediately retry the action that failed (only retry once)
84
@@ −1 +1 @@
1+---
2+description: Configuration for AI behavior when interacting with Codacy's MCP Server
3+applyTo: '**'
4+---
5+
16 <!-- SPDX-License-Identifier: MIT -->
27 <!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
38
4−# AI DevOps Framework - Developer Guide
9+# Codacy Rules
510
6−<!-- AI-CONTEXT-START -->
11+Configuration for AI behavior when interacting with Codacy's MCP Server
712
8−## Quick Reference
13+## CRITICAL: After ANY successful `edit_file` or `reapply` operation
914
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"
15+- YOU MUST IMMEDIATELY run the `codacy_cli_analyze` tool from Codacy's MCP Server for each file that was edited, with:
16+- `rootPath`: set to the workspace path
17+- `file`: set to the path of the edited file
18+- `tool`: leave empty or unset
19+- If any issues are found in the new edits, propose and apply fixes for them.
20+- > NOTE: Failure to follow this rule is considered a critical error.
1421
15−**File Structure**: `TODO.md` (tasks), `todo/` (plans, PRDs), `.agents/` (agents, tools, services, workflows, scripts).
22+## When you tried to run the `codacy_cli_analyze` tool and the Codacy CLI is not installed
1623
17−**Before extending**: Read `.agents/aidevops/architecture.md` (design patterns, conventions, extension guide).
24+- Ask the user 'Codacy CLI is not installed. Would you like me to install it now?'
25+- If the user responds with "yes", run the `codacy_cli_install` tool and then continue with the original task
26+- If the user responds with "no", instruct the user that they can disable automatic analysis in the extension settings
27+- Wait for the user to respond before proceeding with any other actions
1828
19−<!-- AI-CONTEXT-END -->
29+## After every response
2030
21−## Two AGENTS.md Files
31+- If you made any file edits in this conversation, verify you ran `codacy_cli_analyze` tool from Codacy's MCP Server
2232
23−| File | Purpose | Audience |
24−|------|---------|----------|
25−| `~/Git/aidevops/AGENTS.md` | Development guide | Contributors |
26−| `~/Git/aidevops/.agents/AGENTS.md` | User guide | Users of aidevops |
33+## When there are no Codacy MCP Server tools available, or the MCP Server is not reachable
2734
28−The `.agents/AGENTS.md` is copied to `~/.aidevops/agents/AGENTS.md` by `setup.sh`.
35+- Suggest the user the following troubleshooting steps:
36+- Try to reset the MCP on the extension
37+- If the user is using VSCode, suggest them to review their Copilot > MCP settings in Github, under their organization or personal account. Refer them to Settings > Copilot > Enable MCP servers in Copilot. Suggested URL (https://github.com/settings/copilot/features) or https://github.com/organizations/{organization-name}/settings/copilot/features (This can only be done by their organization admins / owners)
38+- If none of the above steps work, suggest the user to contact Codacy support
2939
30−## Development Lifecycle
40+## Trying to call a tool that needs a rootPath as a parameter
3141
32−See `.agents/AGENTS.md` "Operational Routines" for code-change routing and
33−`.agents/AGENTS.md` "Git Workflow" for the full lifecycle.
34−Completion self-check: see `.agents/AGENTS.md` "Framework Rules > Task and completion discipline".
42+- Always use the standard, non-URL-encoded file system path
3543
36−## Contributing
44+## CRITICAL: Dependencies and Security Checks
3745
38−See `.agents/aidevops/` (architecture, setup) and `.agents/tools/` (agent/MCP authoring) for framework development guidance:
46+- IMMEDIATELY after ANY of these actions:
47+- Running npm/yarn/pnpm install
48+- Adding dependencies to package.json
49+- Adding requirements to requirements.txt
50+- Adding dependencies to pom.xml
51+- Adding dependencies to build.gradle
52+- Any other package manager operations
53+- You MUST run the `codacy_cli_analyze` tool with:
54+- `rootPath`: set to the workspace path
55+- `tool`: set to "trivy"
56+- `file`: leave empty or unset
57+- If any vulnerabilities are found because of the newly added packages:
58+- Stop all other operations
59+- Propose and apply fixes for the security issues
60+- Only continue with the original task after security issues are resolved
61+- EXAMPLE:
62+- After: npm install react-markdown
63+- Do: Run codacy_cli_analyze with trivy
64+- Before: Continuing with any other tasks
3965
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 |
66+## General
4867
49−## Agent Design Principles
68+- Repeat the relevant steps for each modified file.
69+- "Propose fixes" means to both suggest and, if possible, automatically apply the fixes.
70+- You MUST NOT wait for the user to ask for analysis or remind you to run the tool.
71+- Do not run `codacy_cli_analyze` looking for changes in duplicated code or code complexity metrics.
72+- Complexity metrics are different from complexity issues. When trying to fix complexity in a repository or file, focus on solving the complexity issues and ignore the complexity metric.
73+- Do not run `codacy_cli_analyze` looking for changes in code coverage.
74+- Do not try to manually install Codacy CLI using either brew, npm, npx, or any other package manager.
75+- If the Codacy CLI is not installed, just run the `codacy_cli_analyze` tool from Codacy's MCP Server.
76+- When calling `codacy_cli_analyze`, only send provider, organization and repository if the project is a git repository.
5077
51−From `.agents/tools/build-agent/build-agent.md`:
78+## Whenever a call to a Codacy tool that uses `repository` or `organization` as a parameter returns a 404 error
5279
53−1. **Instruction budget**: ~50-100 per agent is a maintainability heuristic; investigate overages, but do not cut solely to hit the count
54−2. **Universal applicability**: Every instruction relevant to >80% of tasks
55−3. **Progressive disclosure**: Pointers to subagents, not inline content
56−4. **Code examples**: Only when authoritative; otherwise use stable `rg "pattern"` search references or section headings
57−5. **Self-assessment**: Flag issues with evidence, complete task first
58−
59−Contributor 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
61−reference/workflow document, keep `.agents/AGENTS.md` under the CI size ratchet,
62−and justify any intentional baseline increase in the PR body.
63−
64−## Security
65−
66−Security 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
76−find .agents/scripts/ -name "*.sh" -exec shellcheck {} \;
77−
78−# Release new version
79−.agents/scripts/version-manager.sh release [major|minor|patch]
80−```
81−
82−## Self-Assessment Protocol
83−
84−From `.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
80+- Offer to run the `codacy_setup_repository` tool to add the repository to Codacy
81+- If the user accepts, run the `codacy_setup_repository` tool
82+- Do not ever try to run the `codacy_setup_repository` tool on your own
83+- After setup, immediately retry the action that failed (only retry once)
8984
