Enhance AGENTS.md with comprehensive guidance for future code agents #94
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Documents the critical three-context problem (REPO/SYSTEM/PROJECT) - Maps all source files to their installation destinations - Identifies critical gaps where source files are not installed - Provides mandatory development workflow to prevent sync issues - Includes verification checklist and debugging guidance - Found missing instructions/core/hygiene-check.md installation in setup.sh - Found orphaned files not covered by any installer script Addresses sync issues where bugs get fixed in installed files but not source code, causing future installs to wipe out fixes.
Major enhancements for AI agents working on Agent OS: 🤖 NEW AGENT-SPECIFIC SECTIONS: - Quick start guide with 5-step sequence for new agents - Common agent tasks with exact commands table - AI agent safety guards and critical rules - Common agent mistakes with DO/DON'T patterns - Testing patterns for scripts, commands, and installers - Quality assurance commands checklist - Emergency recovery procedures - Agent success checklist with 8 verification points 📚 ENHANCED CONTENT: - Quick reference commands section - Evidence template for agent work - Metrics tracking for quality assurance - Emergency recovery procedures - Anti-pattern documentation (19 DON'Ts identified) - Quality checkpoints (12 verification steps) 🔧 PRACTICAL IMPROVEMENTS: - Step-by-step testing patterns for common changes - Exact command sequences for all scenarios - Troubleshooting procedures for installation issues - Version 2.0.0 specifically designed for AI agents 📊 STATS: - Expanded from 365 to 581 lines (+216 lines, +59% content) - Added 3 dedicated agent sections with 🤖 markers - 12 quality checkpoints with ✅ markers - 19 anti-patterns documented with ❌ markers This makes AGENTS.md the definitive playbook for future agents to avoid the three-context sync issues that have caused problems in the past.
WalkthroughAdds a new documentation file, AGENTS.md, detailing AI agent workflows, installation/verification procedures, synchronization concepts, debugging/maintenance practices, safety guidelines, and checklists for Agent OS. Changes
Sequence Diagram(s)Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests
Comment |
Owner
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
AGENTS.md (5)
321-334: Also document testing the Cursor installer.You list only base and Claude Code installers under “Test installer locally/remote install.” Include
setup-cursor.shfor completeness.# Test base installer ./setup.sh --overwrite-instructions --overwrite-standards # Test Claude Code installer ./setup-claude-code.sh --overwrite-commands + + # Test Cursor installer + ./setup-cursor.sh @@ # Test remote installation - curl -sSL https://raw.githubusercontent.com/carmandale/agent-os/main/setup.sh | bash + curl -sSL https://raw.githubusercontent.com/carmandale/agent-os/main/setup.sh | bash + # If project uses Cursor rules, also run (from project root): + # ./setup-cursor.sh
510-514: Include Cursor in “Reinstall everything” quick reference.Reinstall block omits Cursor; add it for parity with earlier sections.
# Reinstall everything ./setup.sh --overwrite-instructions --overwrite-standards ./setup-claude-code.sh --overwrite-commands +./setup-cursor.sh
506-509: Clarify PATH foraosbinary.You use both
aos statusand the absolute path form. Add a PATH export to avoid confusion.# Check overall status ./check-agent-os.sh ~/.agent-os/tools/aos status + +# Optional: add AOS to PATH for 'aos' command usage +export PATH="$HOME/.agent-os/tools:$PATH"
252-254: Add security note for curl | bash installs.Recommend pinning or reviewing scripts before piping to shell.
# Or install from remote repository curl -sSL https://raw.githubusercontent.com/carmandale/agent-os/main/setup.sh | bash -s -- --overwrite-instructions + + # Security note: Prefer reviewing the script before execution or pinning to a tag/commit. + # Example: + # curl -fsSL https://raw.githubusercontent.com/carmandale/agent-os/vX.Y.Z/setup.sh -o /tmp/setup.sh + # bash /tmp/setup.sh --overwrite-instructions
578-580: Refresh metadata (date/version) to match this PR.“Last Updated” is 2025‑01‑27 while this PR is dated 2025‑09‑28. Bump version if this is a substantive update.
-**Last Updated:** 2025-01-27 -**Document Version:** 2.0.0 - Enhanced for AI Agents +**Last Updated:** 2025-09-28 +**Document Version:** 2.1.0 - Enhanced for AI Agents
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
AGENTS.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
AGENTS.md
574-574: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
Comment on lines
+170
to
+200
| ### Files NOT Installed by Any Script | ||
|
|
||
| These source files exist but are NOT installed anywhere: | ||
|
|
||
| #### Commands Not Installed | ||
| ```bash | ||
| commands/work-session.md # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| ``` | ||
|
|
||
| #### Instructions Not Installed | ||
| ```bash | ||
| instructions/core/hygiene-check.md # ❌ NOT INSTALLED BY setup.sh but should be! | ||
| ``` | ||
|
|
||
| #### Scripts Not Installed | ||
| ```bash | ||
| scripts/pre-commit-docs-guard.sh # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| scripts/verify-installation.sh # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| scripts/workflow-complete.sh # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| scripts/workflow-status.sh # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| ``` | ||
|
|
||
| #### Hook Files Not Installed | ||
| ```bash | ||
| hooks/uninstall-hooks.sh # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| hooks/agent-os-bash-hooks.json # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| hooks/context_aware_hook.py # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| hooks/intent_analyzer.py # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| hooks/bash_command_validator_example.py # ❌ NOT INSTALLED BY ANY SCRIPT | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
Verify “NOT INSTALLED” lists against repo and installers.
Great callouts, but these can drift. Run the script below to confirm presence in source and references in installers; update this section accordingly.
🏁 Script executed:
#!/bin/bash
# Validate that flagged files exist in repo and are (not) referenced by installers.
set -euo pipefail
echo "== Check existence in repo =="
fd -H 'work-session.md|hygiene-check.md|pre-commit-docs-guard.sh|verify-installation.sh|workflow-complete.sh|workflow-status.sh|uninstall-hooks.sh|agent-os-bash-hooks.json|context_aware_hook.py|intent_analyzer.py|bash_command_validator_example.py' -t f -a || true
echo -e "\n== Check installer references =="
rg -n -C2 -g 'setup*.sh' -e 'work-session\.md|hygiene-check\.md|pre-commit-docs-guard\.sh|verify-installation\.sh|workflow-complete\.sh|workflow-status\.sh|uninstall-hooks\.sh|agent-os-bash-hooks\.json|context_aware_hook\.py|intent_analyzer\.py|bash_command_validator_example\.py' || true
echo -e "\n== Suggested next steps =="
echo "• If files exist but aren't referenced by installers: decide whether to add or explicitly document exclusion."
echo "• If installers reference files not present in source: fix installers or add the files."Length of output: 1135
Install or document unreferenced files
All entries under “NOT Installed by Any Script” in AGENTS.md (commands/work-session.md, instructions/core/hygiene-check.md, scripts/pre-commit-docs-guard.sh, scripts/verify-installation.sh, scripts/workflow-complete.sh, scripts/workflow-status.sh, hooks/uninstall-hooks.sh, hooks/agent-os-bash-hooks.json, hooks/context_aware_hook.py, hooks/intent_analyzer.py, hooks/bash_command_validator_example.py) exist but aren’t referenced by any setup scripts. Either integrate them into your installers or explicitly document their intentional exclusion.
🤖 Prompt for AI Agents
In AGENTS.md around lines 170-200, several files are listed as “NOT INSTALLED BY
ANY SCRIPT” (commands/work-session.md, instructions/core/hygiene-check.md,
scripts/pre-commit-docs-guard.sh, scripts/verify-installation.sh,
scripts/workflow-complete.sh, scripts/workflow-status.sh,
hooks/uninstall-hooks.sh, hooks/agent-os-bash-hooks.json,
hooks/context_aware_hook.py, hooks/intent_analyzer.py,
hooks/bash_command_validator_example.py); either wire these into the
installer(s) or mark them intentionally excluded and document why: update
setup/install scripts (e.g., setup.sh, install.sh, hooks installer) to
copy/enable the missing files and add any necessary permissions and registration
steps, or add a clear section in AGENTS.md (and the project README) stating each
file’s purpose plus a justification for exclusion and instructions for manual
installation/activation if desired.
Comment on lines
+536
to
+575
| ### Evidence Template for Agent Work | ||
|
|
||
| ```markdown | ||
| ## Evidence/Test Results/Verification | ||
|
|
||
| ### Files Modified | ||
| - scripts/workspace-hygiene-check.sh (fixed bug in line 42) | ||
| - commands/new-feature.md (added new command) | ||
|
|
||
| ### Installation Process | ||
| ```bash | ||
| $ ./setup.sh --overwrite-instructions | ||
| ✅ Script installed successfully | ||
|
|
||
| $ ./setup-claude-code.sh --overwrite-commands | ||
| ✅ Commands installed successfully | ||
| ``` | ||
|
|
||
| ### Verification Results | ||
| ```bash | ||
| $ diff scripts/workspace-hygiene-check.sh ~/.agent-os/scripts/workspace-hygiene-check.sh | ||
| # No output = files match ✅ | ||
|
|
||
| $ ~/.agent-os/scripts/workspace-hygiene-check.sh | ||
| ✅ Script executes successfully | ||
|
|
||
| $ aos status | ||
| ✅ All components current | ||
| ``` | ||
|
|
||
| ### Quality Assurance | ||
| ```bash | ||
| $ bash -n setup.sh | ||
| ✅ Syntax valid | ||
|
|
||
| $ ./check-agent-os.sh | ||
| 🚀 Agent OS is ready to use! | ||
| ``` | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Fix nested fenced blocks and missing language (MD040).
You nest bash blocks inside a markdown block and end with an unlabeled ``` (line 574), violating MD040 and rendering poorly. Break the template into separate language‑scoped blocks.
-### Evidence Template for Agent Work
-
-```markdown
-## Evidence/Test Results/Verification
-
-### Files Modified
-- scripts/workspace-hygiene-check.sh (fixed bug in line 42)
-- commands/new-feature.md (added new command)
-
-### Installation Process
-```bash
-$ ./setup.sh --overwrite-instructions
-✅ Script installed successfully
-
-$ ./setup-claude-code.sh --overwrite-commands
-✅ Commands installed successfully
-```
-
-### Verification Results
-```bash
-$ diff scripts/workspace-hygiene-check.sh ~/.agent-os/scripts/workspace-hygiene-check.sh
-# No output = files match ✅
-
-$ ~/.agent-os/scripts/workspace-hygiene-check.sh
-✅ Script executes successfully
-
-$ aos status
-✅ All components current
-```
-
-### Quality Assurance
-```bash
-$ bash -n setup.sh
-✅ Syntax valid
-
-$ ./check-agent-os.sh
-🚀 Agent OS is ready to use!
-```
-```
+### Evidence Template for Agent Work
+
+## Evidence/Test Results/Verification
+
+### Files Modified
+- scripts/workspace-hygiene-check.sh (fixed bug in line 42)
+- commands/new-feature.md (added new command)
+
+### Installation Process
+```bash
+$ ./setup.sh --overwrite-instructions
+✅ Script installed successfully
+
+$ ./setup-claude-code.sh --overwrite-commands
+✅ Commands installed successfully
+```
+
+### Verification Results
+```bash
+$ diff scripts/workspace-hygiene-check.sh ~/.agent-os/scripts/workspace-hygiene-check.sh
+# No output = files match ✅
+
+$ ~/.agent-os/scripts/workspace-hygiene-check.sh
+✅ Script executes successfully
+
+$ aos status
+✅ All components current
+```
+
+### Quality Assurance
+```bash
+$ bash -n setup.sh
+✅ Syntax valid
+
+$ ./check-agent-os.sh
+🚀 Agent OS is ready to use!
+```🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
574-574: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In AGENTS.md around lines 536–575 the content wrongly nests fenced blocks (an
outer ```markdown wrapping inner ```bash blocks) and leaves an unlabeled/extra
closing fence, violating MD040; fix by removing the outer ```markdown fence and
any extra closing backticks, keep the section headers as plain markdown text,
and convert each code snippet into its own properly labeled fenced block (e.g.,
```bash) ensuring every fenced block has a matching closing fence so rendering
and linting pass.
carmandale
added a commit
that referenced
this pull request
Sep 28, 2025
Merging the comprehensive AGENTS.md enhancement that provides detailed guidance for future code agents working on Agent OS. This merge includes: - Complete playbook for AI agents working on Agent OS - Three-context synchronization workflow documentation - Installation flow mappings and verification procedures - Agent safety guards and quality assurance checklists - Emergency recovery and evidence tracking templates The enhanced AGENTS.md serves as the authoritative reference for AI agents to avoid sync issues and follow proper development workflows. Resolves merge conflicts with recent cleanup work and integrates seamlessly with the ongoing repository maintenance efforts. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Enhanced AGENTS.md with comprehensive guidance for future code agents
Major Enhancements:
Evidence/Test Results/Verification:
✅ All installer syntax validated
✅ Source/installed file sync verified
✅ Agent OS health check passed
✅ AOS CLI status confirmed (v4.0.2)
What This Solves:
Prevents three-context sync issues where fixes get made to installed files but not source code, causing future installs to wipe out fixes.
Summary by CodeRabbit