t1282: Tier AGENTS.md into slim core + on-demand reference files#2046
t1282: Tier AGENTS.md into slim core + on-demand reference files#2046marcusquinn merged 2 commits intomainfrom
Conversation
… (t1282) Split 36KB always-loaded AGENTS.md into: - Slim core (8.4KB, -76.6%) with all routing pointers preserved - reference/planning-detail.md (7.1KB) - task dispatch, completion rules, atomic counter - reference/orchestration.md (6.2KB) - supervisor, model routing, pattern tracking - reference/services.md (8.0KB) - memory, mailbox, MCP, skills, auto-update, repo-sync - reference/session.md (5.7KB) - session mgmt, git detail, browser, localhost, quality All 26 original section headings preserved. All 41 domain index entries retained. Byte conservation: 35,514 of 36,080 bytes (98.4%, delta 1.6%). Every session saves ~27KB of context that is now loaded on-demand.
WalkthroughThis PR restructures agent framework documentation by substantially rewriting Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request refactors the core documentation for the AI DevOps framework by modularizing the extensive Highlights
Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sat Feb 21 01:09:36 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request effectively tiers the AGENTS.md file into a slimmer core and several on-demand reference files, significantly reducing the always-loaded context. The changes are well-structured and the new reference files (orchestration.md, planning-detail.md, services.md, session.md) seem to correctly house the extracted content. The summary and verification steps in the PR description are clear and demonstrate a thorough approach to this refactoring. Overall, this is a positive change for improving efficiency and context management.
.agents/AGENTS.md
Outdated
| **Supported tools:** [OpenCode](https://opencode.ai/) (TUI, Desktop, Extension for Zed/VSCode). The `opencode` CLI handles headless dispatch and orchestration. | ||
|
|
||
| **Mission**: Maximise dev-ops efficiency and ROI — maximum value for the user's time and money. Self-heal, self-improve, and grow capabilities through highest-leverage tooling. See `prompts/build.txt` for the full mission statement. | ||
| **Runtime identity**: AI DevOps agent powered by aidevops. Use app name from version check output — do not guess. MCP tools are auxiliary integrations, not your identity. |
There was a problem hiding this comment.
The instruction "Use app name from version check output — do not guess" is a good clarification. However, the original text "MCP tools are auxiliary integrations, not your identity" was also valuable context for understanding the agent's identity. Consider re-integrating this part to maintain clarity on what constitutes the agent's core identity versus auxiliary tools.
There was a problem hiding this comment.
Fixed: restored MCP auxiliary integration clarification and expanded intent detection modes (deliberation vs execution) with examples.
.agents/AGENTS.md
Outdated
| **Runtime identity**: AI DevOps agent powered by aidevops. Use app name from version check output — do not guess. MCP tools are auxiliary integrations, not your identity. | ||
|
|
||
| **Runtime identity**: You are an AI DevOps agent powered by the aidevops framework. When asked about your identity, use the app name from the version check output (e.g., "running in OpenCode") - do not guess or assume based on system prompt content. MCP tools like `claude-code-mcp` are auxiliary integrations, not your identity. | ||
| **Primary agent**: Build+ — unified coding agent. Detects intent: deliberation ("What do you think...") vs execution ("Implement X"). Ambiguous → ask. |
There was a problem hiding this comment.
The condensed description for "Primary agent" is good for brevity, but the original breakdown of intent detection ("Deliberation mode" vs "Execution mode") provided more specific guidance. It might be beneficial to retain a brief mention or a pointer to where this detailed explanation can be found, as it's crucial for understanding how the agent operates.
There was a problem hiding this comment.
Fixed: restored the deliberation/execution mode breakdown with specific trigger examples in the slim core.
.agents/AGENTS.md
Outdated
| Pre-edit check rules: see `prompts/build.txt`. Full details: `workflows/pre-edit.md`. Additional restrictions below: | ||
|
|
||
| **Subagent write restrictions**: Subagents invoked via the Task tool cannot run `pre-edit-check.sh` (many lack `bash: true`). When on `main`/`master`, subagents with `write: true` may ONLY write to: `README.md`, `TODO.md`, `todo/PLANS.md`, `todo/tasks/*`. All other writes must be returned as proposed edits for the calling agent to apply in a worktree. | ||
| Pre-edit check rules: see `prompts/build.txt`. Full details: `workflows/pre-edit.md`. |
There was a problem hiding this comment.
The removal of "Additional restrictions below" is appropriate given the content has been moved. However, ensure that any critical restrictions previously mentioned here are now clearly and explicitly covered in workflows/pre-edit.md or reference/planning-detail.md to avoid loss of important operational rules.
There was a problem hiding this comment.
Fixed: restored 'Additional restrictions below' text and added technical reason (many lack bash: true) to the subagent write restrictions.
.agents/AGENTS.md
Outdated
| Pre-edit check rules: see `prompts/build.txt`. Full details: `workflows/pre-edit.md`. | ||
|
|
||
| **Worker TODO.md restriction**: Workers must NEVER edit TODO.md. See `workflows/plans.md` "Worker TODO.md Restriction". | ||
| **Subagent write restrictions**: Subagents via Task tool cannot run `pre-edit-check.sh`. On `main`/`master`, subagents with `write: true` may ONLY write to: `README.md`, `TODO.md`, `todo/PLANS.md`, `todo/tasks/*`. All other writes → proposed edits for calling agent in a worktree. |
There was a problem hiding this comment.
The rephrasing of "Subagent write restrictions" is more concise. However, the original text explicitly stated that many subagents lack bash: true, which is a key technical constraint. This detail helps explain why subagents cannot run pre-edit-check.sh. Consider adding a brief note about this technical limitation back into the description or linking to a document that explains it.
There was a problem hiding this comment.
Fixed: restored the technical constraint explanation (many lack bash: true) in the subagent write restrictions.
.agents/AGENTS.md
Outdated
| - **Subagent Index**: `subagent-index.toon` (agents, subagents, workflows, scripts) | ||
|
|
||
| **Critical Rules**: See `prompts/build.txt` for file operations, security, file discovery, and quality standards. Additional AGENTS.md-specific rule: blank lines around code blocks (MD031). | ||
| - **Secrets**: `aidevops secret` (gopass) or `~/.config/aidevops/credentials.sh` (fallback) |
There was a problem hiding this comment.
The credentials.sh is described as a "plaintext fallback" here, which is accurate. However, the Repository Style Guide (line 31) mentions credentials.sh (600 permissions) as an alternative for secrets. It would be beneficial to explicitly state the security implications of using a plaintext fallback and emphasize the preference for gopass where possible, aligning with the security focus of the style guide.
References
- The style guide emphasizes using
gopassorcredentials.shwith 600 permissions for secrets. Whilecredentials.shis mentioned as a fallback, it's important to highlight the security implications of plaintext storage and prefergopass. (link)
There was a problem hiding this comment.
Fixed: added explicit security emphasis — 'gopass, preferred' and 'plaintext fallback, 600 permissions — use gopass where possible' to both Quick Reference and Security sections.
| **Cross-tool**: Claude marketplace plugin, Agent Skills (SKILL.md), Claude Code agents, manual AGENTS.md reference. | ||
|
|
||
| **Skill persistence**: Imported skills are stored in `~/.aidevops/agents/` and tracked in `configs/skill-sources.json`. The daily auto-update skill refresh (see Auto-Update below) keeps them current from upstream. Note: `aidevops update` overwrites shared agent files — only `custom/` and `draft/` survive. Re-import skills after an update, or place them in `custom/` for persistence. | ||
|
|
There was a problem hiding this comment.
The "Skill persistence" section is important. The original AGENTS.md explicitly stated that aidevops update overwrites shared agent files and that only custom/ and draft/ survive. This detail is crucial for users to understand how to manage their skills across updates. Consider re-emphasizing this point for clarity.
There was a problem hiding this comment.
Acknowledged. The detail referenced is already present in the reference file — this was the intent of the tiered architecture (slim core + full-detail reference files). No change needed.
| **Daily skill refresh**: Each auto-update check also runs a 24h-gated skill freshness check. If >24h have passed since the last check, `skill-update-helper.sh --auto-update --quiet` pulls upstream changes for all imported skills. State is tracked in `~/.aidevops/cache/auto-update-state.json` (`last_skill_check`, `skill_updates_applied`). Disable with `AIDEVOPS_SKILL_AUTO_UPDATE=false`; adjust frequency with `AIDEVOPS_SKILL_FRESHNESS_HOURS=<hours>` (default: 24). View skill check status with `aidevops auto-update status`. | ||
|
|
||
| **Repo version wins on update**: When `aidevops update` runs, shared agents in `~/.aidevops/agents/` are overwritten by the repo version. Only `custom/` and `draft/` directories are preserved. Imported skills stored outside these directories will be overwritten. To keep a skill across updates, either re-import it after each update or move it to `custom/`. | ||
|
|
There was a problem hiding this comment.
The "Repo version wins on update" section is critical for understanding skill management. The original AGENTS.md explicitly stated that aidevops update overwrites shared agents and that only custom/ and draft/ are preserved. This detail is crucial for users to understand how to manage their skills across updates. Consider re-emphasizing this point for clarity.
There was a problem hiding this comment.
Acknowledged. The detail referenced is already present in the reference file — this was the intent of the tiered architecture (slim core + full-detail reference files). No change needed.
| ## Git Workflow Detail | ||
|
|
||
| **Before edits**: Run pre-edit check (see AGENTS.md top). | ||
|
|
||
| **After branch creation**: | ||
| 1. Check TODO.md for matching tasks, record `started:` timestamp | ||
| 2. Call `session-rename_sync_branch` tool | ||
| 3. Read `workflows/git-workflow.md` for full guidance |
There was a problem hiding this comment.
The "Git Workflow Detail" section is concise. The original AGENTS.md included a specific note about "After switching to a worktree: Re-read any file at its worktree path before editing. The Edit tool tracks reads by exact absolute path — a read from the main repo path does NOT satisfy the worktree path." This explanation of why re-reading is necessary is valuable context for avoiding issues.
There was a problem hiding this comment.
Acknowledged. The detail referenced is already present in the reference file — this was the intent of the tiered architecture (slim core + full-detail reference files). No change needed.
|
|
||
| **Worktree ownership** (CRITICAL): NEVER remove a worktree unless (a) you created it in this session, (b) it belongs to a task in your active batch, AND the task is deployed/complete, or (c) the user explicitly asks. Worktrees may belong to parallel sessions — removing them destroys another agent's working directory mid-work. When cleaning up, only touch worktrees for tasks you personally merged. Use `git worktree list` to see all worktrees but do NOT assume unrecognized ones are safe to remove. The ownership registry (`worktree-helper.sh registry list`) tracks which PID owns each worktree — `remove` and `clean` commands automatically refuse to touch worktrees owned by other live processes. | ||
|
|
||
| **Safety hooks** (Claude Code only): Destructive commands (`git reset --hard`, `rm -rf`, etc.) are blocked by a PreToolUse hook. Run `install-hooks.sh --test` to verify. See `workflows/git-workflow.md` "Destructive Command Safety Hooks" section. |
There was a problem hiding this comment.
The "Worktree ownership" section is critical. The original AGENTS.md provided more detail on why removing others' worktrees is dangerous (destroying another agent's working directory mid-work) and how the ownership registry prevents this. This context is important for understanding the severity of the rule. Consider adding a brief summary of this critical aspect back.
There was a problem hiding this comment.
Acknowledged. The detail referenced is already present in the reference file — this was the intent of the tiered architecture (slim core + full-detail reference files). No change needed.
| **Agent tiers** (user-created agents survive `aidevops update`): | ||
|
|
||
| | Tier | Location | Purpose | | ||
| |------|----------|---------| | ||
| | **Draft** | `~/.aidevops/agents/draft/` | R&D, experimental, auto-created by orchestration tasks | | ||
| | **Custom** | `~/.aidevops/agents/custom/` | User's permanent private agents | | ||
| | **Shared** | `.agents/` in repo | Open-source, distributed to all users | | ||
|
|
There was a problem hiding this comment.
The "Agent tiers" section is concise. The original AGENTS.md provided more detailed descriptions for each tier, such as draft/ being for "R&D, experimental, auto-created by orchestration tasks." While the current version is brief, some of this descriptive detail might be useful to retain for clarity, perhaps by linking to a more comprehensive document on agent directory structure.
There was a problem hiding this comment.
Acknowledged. The detail referenced is already present in the reference file — this was the intent of the tiered architecture (slim core + full-detail reference files). No change needed.
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sat Feb 21 01:37:43 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (1)
.agents/reference/services.md (1)
48-48:mail-helper.sh prunenaming is counterintuitive for a "show storage report" operation.
pruneconventionally implies deletion, but without--forceit only displays a report. An agent following documented patterns would expectpruneto actually prune. Consider calling the report operationstorageorreportto avoid confusion, or at minimum add a clarifying comment in the docs.📝 Proposed clarity fix
-**Storage**: `mail-helper.sh prune` shows storage report. Use `--force` to delete old archived messages. +**Storage**: `mail-helper.sh prune` shows storage report (dry-run); `mail-helper.sh prune --force` deletes old archived messages.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.agents/reference/services.md at line 48, The doc entry for the mail-helper command is misleading because mail-helper.sh prune only shows a storage report unless run with --force, so update the documentation in the services.md entry referencing mail-helper.sh prune to either rename the documented subcommand to a clearer name (e.g., mail-helper.sh storage or mail-helper.sh report) or at minimum add a clarifying sentence that "prune" only displays a report by default and requires --force to perform deletions; ensure the change references the exact command string mail-helper.sh prune and clearly states the behavior and the need for --force.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.agents/AGENTS.md:
- Line 66: Update the sentence containing "go direct to main" in AGENTS.md to
correct the grammar to "go directly to main"; locate the exact phrase in the
document (the line that reads "Planning files (TODO.md, todo/) go direct to
main.") and replace it with "Planning files (TODO.md, todo/) go directly to
main." to preserve meaning and punctuation.
- Around line 102-111: Remove the duplicated entry for
services/email/email-testing.md from the "Email" row in .agents/AGENTS.md so it
only appears under the more specific "Email testing" row; locate the table rows
containing the "Email" and "Email testing" headings and delete the
services/email/email-testing.md reference from the Email row while leaving the
Email testing row unchanged.
In @.agents/reference/orchestration.md:
- Around line 78-83: Update the example invocation of budget-tracker-helper.sh
to make the currency explicit by adding the --unit usd flag (or annotate the
--allowance 200 as "USD") so the --allowance default unit is clear; also correct
the script name casing by replacing "Dispatch.sh" with the lowercase
"dispatch.sh" to match the actual script and conventional shell naming (ensure
references to dispatch.sh match the real script name used by the supervisor).
In @.agents/reference/services.md:
- Around line 127-129: Update the services.md example and text to note that the
git_parent_dirs JSON entry {"git_parent_dirs": ["~/Git", "~/Projects"]} uses "~"
which is not expanded by JSON parsers; explicitly state that "~" requires shell
expansion by the caller (e.g., the aidevops repo-sync wrapper) or show an
alternative with absolute paths (e.g., /home/username/Git) so tools reading
repos.json directly receive expanded paths.
In @.agents/reference/session.md:
- Around line 90-112: The "Shared" agent path is inconsistent between the
"Agents & Subagents" table (`.agents/` in repo) and the "Working Directories"
section (`~/.aidevops/agents/`); update the text to clarify the distinction by
adding a short note that `.agents/` refers to the repository source path (shared
agents committed and distributed via the repo) while `~/.aidevops/agents/` is
the deployed/installed location on a user's machine (overwritten on update), and
adjust the table row or the Working Directories bullet to include this explicit
clarification so a reader at runtime understands which path is source vs
deployed.
---
Nitpick comments:
In @.agents/reference/services.md:
- Line 48: The doc entry for the mail-helper command is misleading because
mail-helper.sh prune only shows a storage report unless run with --force, so
update the documentation in the services.md entry referencing mail-helper.sh
prune to either rename the documented subcommand to a clearer name (e.g.,
mail-helper.sh storage or mail-helper.sh report) or at minimum add a clarifying
sentence that "prune" only displays a report by default and requires --force to
perform deletions; ensure the change references the exact command string
mail-helper.sh prune and clearly states the behavior and the need for --force.
| Task completion: NEVER mark `[x]` without merged PR (`pr:#NNN`) or `verified:YYYY-MM-DD`. Use `task-complete-helper.sh`. False completions cascade into closed GitHub issues. | ||
|
|
||
| ## Memory | ||
| Planning files (TODO.md, todo/) go direct to main. Code changes need worktree + PR. NEVER `git checkout -b` in main repo. |
There was a problem hiding this comment.
Grammar nit: "go direct to main" → "go directly to main".
📝 Proposed fix
-Planning files (TODO.md, todo/) go direct to main.
+Planning files (TODO.md, todo/) go directly to main.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Planning files (TODO.md, todo/) go direct to main. Code changes need worktree + PR. NEVER `git checkout -b` in main repo. | |
| Planning files (TODO.md, todo/) go directly to main. Code changes need worktree + PR. NEVER `git checkout -b` in main repo. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/AGENTS.md at line 66, Update the sentence containing "go direct to
main" in AGENTS.md to correct the grammar to "go directly to main"; locate the
exact phrase in the document (the line that reads "Planning files (TODO.md,
todo/) go direct to main.") and replace it with "Planning files (TODO.md, todo/)
go directly to main." to preserve meaning and punctuation.
| | Email | `tools/ui/react-email.md`, `services/email/email-testing.md` | | ||
| | WordPress | `tools/wordpress/wp-dev.md`, `tools/wordpress/mainwp.md` | | ||
| | SEO | `seo/dataforseo.md`, `seo/google-search-console.md` | | ||
| | Content | `content.md` (orchestrator), `content/research.md`, `content/story.md`, `content/production/`, `content/distribution/`, `content/optimization.md` | | ||
| | Video | `tools/video/video-prompt-design.md`, `tools/video/remotion.md`, `tools/video/higgsfield.md`, `tools/video/runway.md`, `tools/video/wavespeed.md` (200+ models), `wavespeed-helper.sh`, `tools/video/muapi.md` (multimodal: image/video/audio/VFX/workflows/agents), `muapi-helper.sh`, `tools/video/real-video-enhancer.md` (upscale/interpolate/denoise), `real-video-enhancer-helper.sh` | | ||
| | YouTube | `content/distribution/youtube/` (migrated from root, see content.md) | | ||
| | Vision | `tools/vision/overview.md` (decision tree, then `image-generation.md`, `image-understanding.md`, `image-editing.md`) | | ||
| | ComfyUI | `tools/ai-generation/comfy-cli.md`, `comfy-cli-helper.sh` | | ||
| | Voice | `tools/voice/speech-to-speech.md`, `voice-helper.sh talk` (voice bridge) | | ||
| | Email testing | `services/email/email-testing.md` (overview), `services/email/email-design-test.md`, `services/email/email-delivery-test.md`, `email-test-suite-helper.sh` | | ||
| | Multi-org | `services/database/multi-org-isolation.md` (schema, RLS, context model), `multi-org-helper.sh` | | ||
| | Encryption | `tools/credentials/encryption-stack.md` (decision tree), `tools/credentials/sops.md`, `tools/credentials/gocryptfs.md`, `tools/credentials/gopass.md` | | ||
| | Security | `tools/security/tirith.md` (terminal guard), `tools/security/shannon.md` (pentesting), `tools/security/ip-reputation.md` (IP reputation), `tools/security/cdn-origin-ip.md` (CDN origin leak), `/ip-check <ip>`, `aidevops ip-check` | | ||
| | Content | `content.md` (orchestrator + subagents) | | ||
| | Video | `tools/video/video-prompt-design.md`, `tools/video/remotion.md`, `tools/video/wavespeed.md`, `tools/video/muapi.md`, `tools/video/real-video-enhancer.md` | | ||
| | YouTube | `content/distribution/youtube/` | | ||
| | Vision | `tools/vision/overview.md` | | ||
| | ComfyUI | `tools/ai-generation/comfy-cli.md` | | ||
| | Voice | `tools/voice/speech-to-speech.md` | | ||
| | Email testing | `services/email/email-testing.md`, `services/email/email-design-test.md`, `services/email/email-delivery-test.md` | |
There was a problem hiding this comment.
services/email/email-testing.md duplicated in Domain Index.
services/email/email-testing.md is listed in both the Email row (line 102) and the Email testing row (line 111). An agent querying the index for email testing would find it in either row, but having it in both adds noise. Consider removing it from the Email row and keeping only the more granular entry under Email testing.
📝 Proposed fix
-| Email | `tools/ui/react-email.md`, `services/email/email-testing.md` |
+| Email | `tools/ui/react-email.md` |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Email | `tools/ui/react-email.md`, `services/email/email-testing.md` | | |
| | WordPress | `tools/wordpress/wp-dev.md`, `tools/wordpress/mainwp.md` | | |
| | SEO | `seo/dataforseo.md`, `seo/google-search-console.md` | | |
| | Content | `content.md` (orchestrator), `content/research.md`, `content/story.md`, `content/production/`, `content/distribution/`, `content/optimization.md` | | |
| | Video | `tools/video/video-prompt-design.md`, `tools/video/remotion.md`, `tools/video/higgsfield.md`, `tools/video/runway.md`, `tools/video/wavespeed.md` (200+ models), `wavespeed-helper.sh`, `tools/video/muapi.md` (multimodal: image/video/audio/VFX/workflows/agents), `muapi-helper.sh`, `tools/video/real-video-enhancer.md` (upscale/interpolate/denoise), `real-video-enhancer-helper.sh` | | |
| | YouTube | `content/distribution/youtube/` (migrated from root, see content.md) | | |
| | Vision | `tools/vision/overview.md` (decision tree, then `image-generation.md`, `image-understanding.md`, `image-editing.md`) | | |
| | ComfyUI | `tools/ai-generation/comfy-cli.md`, `comfy-cli-helper.sh` | | |
| | Voice | `tools/voice/speech-to-speech.md`, `voice-helper.sh talk` (voice bridge) | | |
| | Email testing | `services/email/email-testing.md` (overview), `services/email/email-design-test.md`, `services/email/email-delivery-test.md`, `email-test-suite-helper.sh` | | |
| | Multi-org | `services/database/multi-org-isolation.md` (schema, RLS, context model), `multi-org-helper.sh` | | |
| | Encryption | `tools/credentials/encryption-stack.md` (decision tree), `tools/credentials/sops.md`, `tools/credentials/gocryptfs.md`, `tools/credentials/gopass.md` | | |
| | Security | `tools/security/tirith.md` (terminal guard), `tools/security/shannon.md` (pentesting), `tools/security/ip-reputation.md` (IP reputation), `tools/security/cdn-origin-ip.md` (CDN origin leak), `/ip-check <ip>`, `aidevops ip-check` | | |
| | Content | `content.md` (orchestrator + subagents) | | |
| | Video | `tools/video/video-prompt-design.md`, `tools/video/remotion.md`, `tools/video/wavespeed.md`, `tools/video/muapi.md`, `tools/video/real-video-enhancer.md` | | |
| | YouTube | `content/distribution/youtube/` | | |
| | Vision | `tools/vision/overview.md` | | |
| | ComfyUI | `tools/ai-generation/comfy-cli.md` | | |
| | Voice | `tools/voice/speech-to-speech.md` | | |
| | Email testing | `services/email/email-testing.md`, `services/email/email-design-test.md`, `services/email/email-delivery-test.md` | | |
| | Email | `tools/ui/react-email.md` | | |
| | WordPress | `tools/wordpress/wp-dev.md`, `tools/wordpress/mainwp.md` | | |
| | SEO | `seo/dataforseo.md`, `seo/google-search-console.md` | | |
| | Content | `content.md` (orchestrator + subagents) | | |
| | Video | `tools/video/video-prompt-design.md`, `tools/video/remotion.md`, `tools/video/wavespeed.md`, `tools/video/muapi.md`, `tools/video/real-video-enhancer.md` | | |
| | YouTube | `content/distribution/youtube/` | | |
| | Vision | `tools/vision/overview.md` | | |
| | ComfyUI | `tools/ai-generation/comfy-cli.md` | | |
| | Voice | `tools/voice/speech-to-speech.md` | | |
| | Email testing | `services/email/email-testing.md`, `services/email/email-design-test.md`, `services/email/email-delivery-test.md` | |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~103-~103: The official name of this content management system is spelled with a capital “P”.
Context: ...email/email-testing.md| | WordPress |tools/wordpress/wp-dev.md, tools/wordpress/mainwp.md`...
(WORDPRESS)
[uncategorized] ~103-~103: The official name of this content management system is spelled with a capital “P”.
Context: ...ordPress | tools/wordpress/wp-dev.md, tools/wordpress/mainwp.md | | SEO | `seo/dataforseo.md...
(WORDPRESS)
[uncategorized] ~107-~107: The official name of this popular video platform is spelled with a capital “T”.
Context: ...o/real-video-enhancer.md| | YouTube |content/distribution/youtube/| | Vision |tools/vision/overview.m...
(YOUTUBE)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/AGENTS.md around lines 102 - 111, Remove the duplicated entry for
services/email/email-testing.md from the "Email" row in .agents/AGENTS.md so it
only appears under the more specific "Email testing" row; locate the table rows
containing the "Email" and "Email testing" headings and delete the
services/email/email-testing.md reference from the Email row while leaving the
Email testing row unchanged.
| # Configure OpenCode as subscription with monthly allowance | ||
| budget-tracker-helper.sh configure opencode --billing-type subscription | ||
| budget-tracker-helper.sh configure-period opencode --start 2026-02-01 --end 2026-03-01 --allowance 200 | ||
| ``` | ||
|
|
||
| **Integration**: Dispatch.sh checks budget state before model selection. Spend is recorded automatically after each worker evaluation. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Search for dispatch.sh with various casings
find . -type f -name "*dispatch*" 2>/dev/null | head -20Repository: marcusquinn/aidevops
Length of output: 277
🏁 Script executed:
# Search for budget-tracker-helper.sh and check --allowance documentation
find . -type f -name "budget-tracker-helper.sh" -o -name "*budget-tracker*" 2>/dev/nullRepository: marcusquinn/aidevops
Length of output: 106
🏁 Script executed:
# Read the orchestration.md file to get full context
cat -n ".agents/reference/orchestration.md" | head -100Repository: marcusquinn/aidevops
Length of output: 6915
🏁 Script executed:
# Search for --allowance usage in the repo
rg '\-\-allowance' -n --max-count 20Repository: marcusquinn/aidevops
Length of output: 716
🏁 Script executed:
# Read the configure-period function in budget-tracker-helper.sh
sed -n '920,1000p' .agents/scripts/budget-tracker-helper.sh | cat -nRepository: marcusquinn/aidevops
Length of output: 2599
🏁 Script executed:
# Search for the default unit logic or comments about allowance
rg 'allowance|unit' .agents/scripts/budget-tracker-helper.sh -B 2 -A 2 -n | head -50Repository: marcusquinn/aidevops
Length of output: 2128
Fix two documentation issues: clarify --allowance default unit and correct script filename casing.
-
Line 80: The
--allowance 200example omits the unit. The default is USD, but to maintain documentation clarity and follow DevOps best practices, add--unit usdto the example or annotate inline. -
Line 83:
Dispatch.shshould bedispatch.sh. The actual script is./.agents/scripts/supervisor/dispatch.sh(lowercase). Shell scripts conventionally use lowercase filenames; mismatched casing in docs prevents accurate lookup.
📝 Proposed fixes
-budget-tracker-helper.sh configure-period opencode --start 2026-02-01 --end 2026-03-01 --allowance 200
+budget-tracker-helper.sh configure-period opencode --start 2026-02-01 --end 2026-03-01 --allowance 200 --unit usd-**Integration**: Dispatch.sh checks budget state before model selection.
+**Integration**: `dispatch.sh` checks budget state before model selection.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Configure OpenCode as subscription with monthly allowance | |
| budget-tracker-helper.sh configure opencode --billing-type subscription | |
| budget-tracker-helper.sh configure-period opencode --start 2026-02-01 --end 2026-03-01 --allowance 200 | |
| ``` | |
| **Integration**: Dispatch.sh checks budget state before model selection. Spend is recorded automatically after each worker evaluation. | |
| # Configure OpenCode as subscription with monthly allowance | |
| budget-tracker-helper.sh configure opencode --billing-type subscription | |
| budget-tracker-helper.sh configure-period opencode --start 2026-02-01 --end 2026-03-01 --allowance 200 --unit usd |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/reference/orchestration.md around lines 78 - 83, Update the example
invocation of budget-tracker-helper.sh to make the currency explicit by adding
the --unit usd flag (or annotate the --allowance 200 as "USD") so the
--allowance default unit is clear; also correct the script name casing by
replacing "Dispatch.sh" with the lowercase "dispatch.sh" to match the actual
script and conventional shell naming (ensure references to dispatch.sh match the
real script name used by the supervisor).
| ```json | ||
| {"git_parent_dirs": ["~/Git", "~/Projects"]} | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# First, find the file and check its content
echo "=== Locating and checking .agents/reference/services.md ==="
if [ -f ".agents/reference/services.md" ]; then
echo "File found. Checking lines 127-129 context:"
sed -n '120,135p' .agents/reference/services.md
else
echo "File not found at .agents/reference/services.md"
find . -name "services.md" -o -name "repos.json" | head -20
fiRepository: marcusquinn/aidevops
Length of output: 630
🏁 Script executed:
#!/bin/bash
# Search for how git_parent_dirs and repos.json are used
echo "=== Searching for git_parent_dirs usage ==="
rg -n 'git_parent_dirs' --type-list | head -10
echo -e "\n=== Searching for repos.json references ==="
rg -n 'repos\.json' -A 3 -B 3 | head -40
echo -e "\n=== Searching for repo-sync implementation ==="
find . -type f \( -name "*.sh" -o -name "*.bash" -o -name "*.zsh" \) | xargs grep -l 'repo-sync' | head -5Repository: marcusquinn/aidevops
Length of output: 3283
🏁 Script executed:
#!/bin/bash
# Search for path expansion or tilde handling
echo "=== Searching for tilde expansion or path handling ==="
rg -n 'expand|HOME|~' --type sh --type bash | grep -i 'tilde\|expand\|git_parent' | head -30
echo -e "\n=== Checking if code uses JSON parsing libraries ==="
rg -n 'jq|json\.parse|JSON\.parse' | grep -B 3 -A 3 'repos\|git_parent'Repository: marcusquinn/aidevops
Length of output: 23524
Document that ~/ in JSON requires shell expansion, or provide absolute path alternative.
The example {"git_parent_dirs": ["~/Git", "~/Projects"]} shows ~ which jq treats as a literal string, not a home directory reference. While the shell layer in aidevops repo-sync handles expansion when these paths are used, custom tooling that reads repos.json directly with a JSON parser would receive literal ~/Git instead of the expanded path. Clarify that ~ requires shell interpretation, or show the absolute path format as a documented alternative.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/reference/services.md around lines 127 - 129, Update the services.md
example and text to note that the git_parent_dirs JSON entry {"git_parent_dirs":
["~/Git", "~/Projects"]} uses "~" which is not expanded by JSON parsers;
explicitly state that "~" requires shell expansion by the caller (e.g., the
aidevops repo-sync wrapper) or show an alternative with absolute paths (e.g.,
/home/username/Git) so tools reading repos.json directly receive expanded paths.
| | Tier | Location | Purpose | | ||
| |------|----------|---------| | ||
| | **Draft** | `~/.aidevops/agents/draft/` | R&D, experimental, auto-created by orchestration tasks | | ||
| | **Custom** | `~/.aidevops/agents/custom/` | User's permanent private agents | | ||
| | **Shared** | `.agents/` in repo | Open-source, distributed to all users | | ||
|
|
||
| Orchestration agents can create drafts in `draft/` for reusable parallel processing context. See `tools/build-agent/build-agent.md` for the full lifecycle and promotion workflow. | ||
|
|
||
| ## Security Detail | ||
|
|
||
| Security rules: see `prompts/build.txt`. Additional details: | ||
|
|
||
| - Config templates: `configs/*.json.txt` (committed), working: `configs/*.json` (gitignored) | ||
|
|
||
| **Full docs**: `tools/credentials/gopass.md`, `tools/credentials/api-key-setup.md` | ||
|
|
||
| ## Working Directories | ||
|
|
||
| Working directory tree: see `prompts/build.txt`. Agent file locations: | ||
|
|
||
| - `~/.aidevops/agents/custom/` — User's permanent private agents (survives updates) | ||
| - `~/.aidevops/agents/draft/` — R&D, experimental agents (survives updates) | ||
| - `~/.aidevops/agents/` — Shared agents (deployed from repo, overwritten on update) |
There was a problem hiding this comment.
Internal contradiction: Shared agent path differs between the two sections of this file.
The Agents & Subagents table (line 94) gives the Shared tier location as .agents/ in repo, while the Working Directories section (line 112) gives it as ~/.aidevops/agents/. Both are technically true for different purposes (source vs deployed), but an agent consulting this file at runtime will see two different answers for the same question.
Add a clarifying note to distinguish the two paths:
📝 Proposed fix
-| **Shared** | `.agents/` in repo | Open-source, distributed to all users |
+| **Shared** | `~/.aidevops/agents/` (deployed) / `.agents/` (source repo) | Open-source, distributed to all users |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.agents/reference/session.md around lines 90 - 112, The "Shared" agent path
is inconsistent between the "Agents & Subagents" table (`.agents/` in repo) and
the "Working Directories" section (`~/.aidevops/agents/`); update the text to
clarify the distinction by adding a short note that `.agents/` refers to the
repository source path (shared agents committed and distributed via the repo)
while `~/.aidevops/agents/` is the deployed/installed location on a user's
machine (overwritten on update), and adjust the table row or the Working
Directories bullet to include this explicit clarification so a reader at runtime
understands which path is source vs deployed.
1 participant
Summary
.agents/AGENTS.md(36KB) into slim core (8.4KB) + 4 on-demand reference filesReference Files Created
reference/planning-detail.mdreference/orchestration.mdreference/services.mdreference/session.mdVerification
Ref #2041
Summary by CodeRabbit