t1023: Reduce AGENTS.md instruction count from 67 to <50#1331
t1023: Reduce AGENTS.md instruction count from 67 to <50#1331marcusquinn merged 6 commits intomainfrom
Conversation
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
WalkthroughThese changes consolidate and restructure AI agent documentation by simplifying AGENTS.md into a concise reference, distributing detailed operational guidance across specialized workflow files (headless-dispatch.md, git-workflow.md, plans.md), and establishing explicit safety frameworks for worktree ownership and task ID allocation. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts (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 |
marcusquinn
force-pushed
the
feature/t1023
branch
from
6951229 to
01c5eb1
Compare
🔍 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: Fri Feb 13 00:25:09 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: 3
🤖 Fix all issues with AI agents
In @.agents/workflows/git-workflow.md:
- Around line 671-683: The docs show commands using worktree-helper.sh without a
path; update this block to either use the canonical script path
(~/.aidevops/agents/scripts/worktree-helper.sh) for all examples (e.g.,
~/.aidevops/agents/scripts/worktree-helper.sh registry list, ... remove, ...
clean) or add a one-line note above the commands saying "Ensure
~/.aidevops/agents/scripts is on your PATH or use the full path to
worktree-helper.sh" so that calls to worktree-helper.sh (registry list, remove,
clean) are unambiguous and not PATH-dependent.
- Around line 661-691: The "Worktree Ownership" block duplicated in
git-workflow.md (the section with the "Worktree Ownership" heading and commands
like worktree-helper.sh registry list / worktree-helper.sh remove /
worktree-helper.sh clean) must be removed from git-workflow.md and replaced with
a single cross-reference to the canonical .agents/workflows/worktree.md, or
alternatively consolidate by moving any unique content into
.agents/workflows/worktree.md and then update AGENTS.md and git-workflow.md to
point to that canonical file; ensure you keep the ownership rules and helper
command references exclusively in .agents/workflows/worktree.md and update
AGENTS.md and git-workflow.md to reference that file so guidance isn’t split
across sources.
In @.agents/workflows/plans.md:
- Around line 52-57: Update the output format line so TASK_REF is
platform-neutral instead of hardcoded to GH; replace the example
`TASK_REF=GH#NNN` with a neutral representation (e.g.,
`TASK_REF=GH#NNN|GL#NNN|NONE` or document both `GH#NNN` and `GL#NNN` and the
offline `NONE` case), and mention that TASK_OFFLINE=true/false controls when
TASK_REF may be NONE; update the description of Online (`t(N+1)`) and Offline
fallback (`t(N+100)`) examples to show both GH and GL or NONE variants so
downstream tooling won't assume only GitHub.
🧹 Nitpick comments (1)
.agents/tools/ai-assistants/headless-dispatch.md (1)
100-100: Minor: Clarify auto-detection outcome mapping.Line 100 states:
Use /save-todo after planning. Auto-detects complexity (simple → TODO.md only, complex → PLANS.md + TODO.md reference).The phrasing "PLANS.md + TODO.md reference" could be clearer. Consider:
complex → PLANS.md entry + TODO.md referenceto explicitly indicate a new entry in PLANS.md is created.Suggested clarification
-Use `/save-todo` after planning. Auto-detects complexity (simple → TODO.md only, complex → PLANS.md + TODO.md reference). +Use `/save-todo` after planning. Auto-detects complexity (simple → TODO.md only, complex → PLANS.md entry + TODO.md reference).
| ### Worktree Ownership | ||
|
|
||
| **CRITICAL**: NEVER remove a worktree unless you meet ALL of these conditions: | ||
|
|
||
| 1. **You created it in this session**, OR | ||
| 2. **It belongs to a task in your active batch** AND the task is deployed/complete, OR | ||
| 3. **The user explicitly asks** | ||
|
|
||
| **Why this matters**: Worktrees may belong to parallel sessions. Removing them destroys another agent's working directory mid-work. | ||
|
|
||
| **Safe cleanup workflow**: | ||
|
|
||
| ```bash | ||
| # 1. Check ownership registry | ||
| worktree-helper.sh registry list | ||
|
|
||
| # 2. Only remove worktrees you personally merged | ||
| # The registry tracks which PID owns each worktree | ||
|
|
||
| # 3. Use helper commands (they enforce ownership checks) | ||
| worktree-helper.sh remove feature/my-feature # Refuses if owned by another live process | ||
| worktree-helper.sh clean # Only removes worktrees you own | ||
| ``` | ||
|
|
||
| **What NOT to do**: | ||
|
|
||
| - NEVER assume unrecognized worktrees are safe to remove | ||
| - NEVER use `git worktree remove` directly (bypasses ownership checks) | ||
| - NEVER remove worktrees for tasks you didn't personally merge | ||
|
|
||
| **Ownership registry**: `worktree-helper.sh registry list` shows which PID owns each worktree. The `remove` and `clean` commands automatically refuse to touch worktrees owned by other live processes. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for potential duplicates of Worktree Ownership guidance across .agents/
echo "=== Searching for Worktree Ownership related patterns ==="
rg -n --glob '.agents/**/*.md' "Worktree Ownership|ownership registry|worktree-helper\.sh (remove|clean|registry list)"
echo ""
echo "=== Broader search for worktree cleanup guidance ==="
rg -n --glob '.agents/**/*.md' -i "worktree.*clean|worktree.*remov|git worktree" | head -30Repository: marcusquinn/aidevops
Length of output: 4727
Consolidate Worktree Ownership guidance—it already exists in .agents/workflows/worktree.md.
The rg scan confirms duplication: worktree ownership, registry patterns, and safe cleanup workflows are already comprehensively documented in .agents/workflows/worktree.md (lines 387–392+). The content added to git-workflow.md:661–691 replicates this existing guidance. Per framework standards, maintain operational guidance in a single authoritative location. Either:
- Remove the new section from
git-workflow.mdand keep the reference inAGENTS.md:227pointing toworktree.mdas the primary source, or - Consolidate into
.agents/workflows/worktree.mdif this is now the canonical reference, then updateAGENTS.mdandgit-workflow.mdto cross-reference it.
Ensure the final structure avoids split ownership guidance across files.
🤖 Prompt for AI Agents
In @.agents/workflows/git-workflow.md around lines 661 - 691, The "Worktree
Ownership" block duplicated in git-workflow.md (the section with the "Worktree
Ownership" heading and commands like worktree-helper.sh registry list /
worktree-helper.sh remove / worktree-helper.sh clean) must be removed from
git-workflow.md and replaced with a single cross-reference to the canonical
.agents/workflows/worktree.md, or alternatively consolidate by moving any unique
content into .agents/workflows/worktree.md and then update AGENTS.md and
git-workflow.md to point to that canonical file; ensure you keep the ownership
rules and helper command references exclusively in .agents/workflows/worktree.md
and update AGENTS.md and git-workflow.md to reference that file so guidance
isn’t split across sources.
| **Safe cleanup workflow**: | ||
|
|
||
| ```bash | ||
| # 1. Check ownership registry | ||
| worktree-helper.sh registry list | ||
|
|
||
| # 2. Only remove worktrees you personally merged | ||
| # The registry tracks which PID owns each worktree | ||
|
|
||
| # 3. Use helper commands (they enforce ownership checks) | ||
| worktree-helper.sh remove feature/my-feature # Refuses if owned by another live process | ||
| worktree-helper.sh clean # Only removes worktrees you own | ||
| ``` |
There was a problem hiding this comment.
Clarify helper script path to avoid PATH-dependent failures.
Earlier examples use the full ~/.aidevops/agents/scripts/... path, but this block assumes worktree-helper.sh is on PATH. Please align with the canonical path or explicitly state it must be on PATH to prevent confusion in safety-critical cleanup steps.
🔧 Suggested doc tweak
-# 1. Check ownership registry
-worktree-helper.sh registry list
+# 1. Check ownership registry
+~/.aidevops/agents/scripts/worktree-helper.sh registry list
...
-worktree-helper.sh remove feature/my-feature # Refuses if owned by another live process
-worktree-helper.sh clean # Only removes worktrees you own
+~/.aidevops/agents/scripts/worktree-helper.sh remove feature/my-feature # Refuses if owned by another live process
+~/.aidevops/agents/scripts/worktree-helper.sh clean # Only removes worktrees you own🤖 Prompt for AI Agents
In @.agents/workflows/git-workflow.md around lines 671 - 683, The docs show
commands using worktree-helper.sh without a path; update this block to either
use the canonical script path (~/.aidevops/agents/scripts/worktree-helper.sh)
for all examples (e.g., ~/.aidevops/agents/scripts/worktree-helper.sh registry
list, ... remove, ... clean) or add a one-line note above the commands saying
"Ensure ~/.aidevops/agents/scripts is on your PATH or use the full path to
worktree-helper.sh" so that calls to worktree-helper.sh (registry list, remove,
clean) are unambiguous and not PATH-dependent.
| **Online mode**: Creates a GitHub/GitLab issue as a distributed lock, then allocates `t(N+1)`. | ||
|
|
||
| **Offline fallback**: Allocates `t(N+100)` to avoid collisions (reconcile when back online). | ||
|
|
||
| **Output format**: `TASK_ID=tNNN TASK_REF=GH#NNN TASK_OFFLINE=false` | ||
|
|
There was a problem hiding this comment.
Make TASK_REF format platform-neutral (GitHub vs GitLab/offline).
The output format hardcodes TASK_REF=GH#NNN, but online mode can be GitHub or GitLab and offline mode may have no issue number. Consider specifying a neutral format (e.g., TASK_REF=GH#NNN|GL#NNN|NONE) or documenting the GitLab equivalent to prevent downstream tooling assumptions.
✏️ Possible wording update
-**Output format**: `TASK_ID=tNNN TASK_REF=GH#NNN TASK_OFFLINE=false`
+**Output format**: `TASK_ID=tNNN TASK_REF=GH#NNN|GL#NNN|NONE TASK_OFFLINE=false`📝 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.
| **Online mode**: Creates a GitHub/GitLab issue as a distributed lock, then allocates `t(N+1)`. | |
| **Offline fallback**: Allocates `t(N+100)` to avoid collisions (reconcile when back online). | |
| **Output format**: `TASK_ID=tNNN TASK_REF=GH#NNN TASK_OFFLINE=false` | |
| **Online mode**: Creates a GitHub/GitLab issue as a distributed lock, then allocates `t(N+1)`. | |
| **Offline fallback**: Allocates `t(N+100)` to avoid collisions (reconcile when back online). | |
| **Output format**: `TASK_ID=tNNN TASK_REF=GH#NNN|GL#NNN|NONE TASK_OFFLINE=false` |
🤖 Prompt for AI Agents
In @.agents/workflows/plans.md around lines 52 - 57, Update the output format
line so TASK_REF is platform-neutral instead of hardcoded to GH; replace the
example `TASK_REF=GH#NNN` with a neutral representation (e.g.,
`TASK_REF=GH#NNN|GL#NNN|NONE` or document both `GH#NNN` and `GL#NNN` and the
offline `NONE` case), and mention that TASK_OFFLINE=true/false controls when
TASK_REF may be NONE; update the description of Online (`t(N+1)`) and Offline
fallback (`t(N+100)`) examples to show both GH and GL or NONE variants so
downstream tooling won't assume only GitHub.
…)" This reverts commit c343c25.
2 participants
Summary
Reduced AGENTS.md instruction count from 67 to 49 by offloading detail to existing subagents.
Changes
workflows/plans.md(consolidated 10 bullets to 3 + pointer)workflows/plans.md(consolidated 8 lines to 2 + pointer)workflows/git-workflow.md(consolidated 5 sentences to 1 + pointer)tools/ai-assistants/headless-dispatch.md(moved 20-line code block to new section)Verification
Ref #1327
Summary by CodeRabbit