docs: Add AGENTS.md files for OpenAI Codex compatibility - #86
Conversation
Add root AGENTS.md as symlink to CLAUDE.md and create package-specific AGENTS.md files with concise development notes for each package.
Each package now has a Learnings section for documenting failures and their solutions. This prevents repeated mistakes across agent runs.
Consistent with package AGENTS.md files.
📝 WalkthroughSummary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughAdds multiple AGENTS.md documentation files (root and per-package), updates CLAUDE.md Learnings to require documenting failures in a specific format, and relaxes a floating-point test assertion to use epsilon tolerance. Most edits are documentation; one test change. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
🔇 Additional comments (1)
Comment |
Code ReviewSummaryThis PR adds AGENTS.md files across the monorepo to support OpenAI Codex/agent compatibility. The changes are well-structured and provide useful package-specific guidance. Overall quality is good with some minor suggestions. ✅ Strengths
📝 Suggestions1. Symlink Compatibility ConcernThe root AGENTS.md is a symlink to CLAUDE.md. This works on Unix systems but may cause issues:
Recommendation: Consider using a regular file with a note pointing to CLAUDE.md, or add a CI check to ensure symlink integrity. 2. Missing Context on "OpenAI Codex Compatibility"The PR title mentions "OpenAI Codex compatibility" but:
Recommendation: Add a comment in root AGENTS.md explaining the dual naming convention (CLAUDE.md for Claude Code, AGENTS.md for OpenAI Codex). 3. Minor Content Issuespackages/create-app/AGENTS.md:39 - Generated projects use npm (not pnpm) to avoid workspace conflictsThis is listed under "Common Mistakes" but seems like intended behavior, not a mistake. Should be in a "Design Decisions" or "Notes" section. packages/ui/AGENTS.md:49 --->
+-->4. Consistency with CLAUDE.mdThe CLAUDE.md update changes the Learnings section comment: -<!-- Add specific lessons learned during development. Format: what happened → what to do instead -->
+<!-- MANDATORY: Document failures here to prevent repeated mistakes -->
+<!-- Format: what went wrong → what to do instead -->This makes the tone stronger ("MANDATORY") and format clearer. Good improvement. All package AGENTS.md files already use this improved format. 🔒 SecurityNo security concerns - documentation only. ⚡ PerformanceNo performance impact - documentation only. 🧪 Test CoverageNot applicable - this PR adds documentation files only. No tests needed. ✅ Meets Project Standards
🎯 RecommendationApprove with minor suggestions. The symlink concern should be evaluated based on your team's platform requirements. If you have Windows developers, consider using a regular file instead. Reviewed according to /home/runner/work/mcp-apps-kit/mcp-apps-kit/CLAUDE.md guidelines |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In @AGENTS.md:
- Line 1: The file AGENTS.md currently contains "CLAUDE.md" but fails Prettier
due to missing trailing newline; edit AGENTS.md to add a newline (trailing empty
line) at the end of the file so the file ends with a proper newline character.
In @packages/core/AGENTS.md:
- Around line 1-50: Update the "Patterns" section to correct the architecture
note: replace the incorrect claim that there are "no barrel files in
subdirectories" with a statement that exports are centralized through
src/index.ts which re-exports from barrel files (index.ts) in subdirectories
such as adapters/, debug/, events/, middleware/, plugins/, server/, and
server/oauth/; mention to prefer using defineTool and defineUI for type
inference and that subdirectory barrel files are used only as local re-exports
routed through src/index.ts.
In @packages/create-app/AGENTS.md:
- Line 1: The file @mcp-apps-kit/create-app (AGENTS.md) is missing a trailing
newline causing Prettier to fail; open the AGENTS.md file and add a single
newline character at the end of the file (ensure the file ends with an empty
line/line break after the last content) then save to fix the formatting check.
In @packages/ui-react-builder/AGENTS.md:
- Line 1: The file AGENTS.md is missing a trailing newline causing Prettier to
fail; open packages/ui-react-builder/AGENTS.md and add a single newline
character at the end of the file (i.e., ensure there is an empty line after the
current last line, add a newline after line 54) then save and re-run
formatting/CI.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
AGENTS.mdCLAUDE.mdpackages/core/AGENTS.mdpackages/create-app/AGENTS.mdpackages/testing/AGENTS.mdpackages/ui-react-builder/AGENTS.mdpackages/ui-react/AGENTS.mdpackages/ui/AGENTS.md
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2026-01-11T02:21:51.116Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-11T02:21:51.116Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Use `defineTool` and `defineUI` (or `defineReactUI` for React components) for type inference instead of manual definitions
Applied to files:
packages/ui-react/AGENTS.mdpackages/ui-react-builder/AGENTS.md
📚 Learning: 2026-01-11T02:21:51.116Z
Learnt from: CR
Repo: AndurilCode/mcp-apps-kit PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-11T02:21:51.116Z
Learning: Run `pnpm build && pnpm test && pnpm lint && pnpm typecheck` before finishing any task - all four must pass without exceptions
Applied to files:
CLAUDE.md
🪛 GitHub Actions: PR Check
packages/create-app/AGENTS.md
[error] 1-1: Prettier formatting check failed. Run 'prettier --write' to fix code style issues in AGENTS.md.
packages/ui-react/AGENTS.md
[error] 1-1: Prettier formatting check failed. Run 'prettier --write' to fix code style issues in AGENTS.md.
AGENTS.md
[error] 1-1: Prettier formatting check failed. Run 'prettier --write' to fix code style issues in AGENTS.md.
[error] 1-1: Prettier formatting check failed. Run 'prettier --write' to fix code style issues in AGENTS.md.
🔇 Additional comments (7)
packages/create-app/AGENTS.md (1)
1-51: Excellent documentation structure and content.The package documentation is well-organized with clear sections for quick commands, key exports, templates, dependencies, and common mistakes. The mandatory Learnings section with format guidance is a helpful addition to encourage documentation of failures and solutions across agent runs.
packages/ui-react-builder/AGENTS.md (2)
22-30: High-quality usage example.The TypeScript code example clearly demonstrates the intended pattern for defineReactUI with buildAndTransform. This is helpful for developers onboarding to the package.
1-54: Well-structured documentation with clear organization.Package documentation effectively covers quick commands, key exports, usage patterns, dependencies, and common pitfalls. The Learnings section is well-positioned to capture failures and solutions to prevent repeated mistakes in future agent runs, aligning with the PR's intent.
CLAUDE.md (1)
63-71: Well-structured Learnings section.The updated mandatory format with clear examples ("what went wrong → what to do instead") provides helpful guidance for future learnings entries. This sets a good precedent for the package-specific AGENTS.md files.
packages/ui/AGENTS.md (1)
1-49: Excellent documentation structure.The packages/ui/AGENTS.md file provides clear onboarding guidance with practical quick commands, concrete code examples, and a well-formatted Learnings section. The documentation is comprehensive without being verbose.
packages/ui-react/AGENTS.md (1)
1-56: Prettier formatting claim cannot be verified in sandbox environment.The file exists and its content appears well-formatted with proper markdown structure, but Prettier is not available in the sandbox to verify the claimed formatting failure. The review comment asserts a pipeline failure as fact but provides no specific details about which formatting rules are violated. Manual verification using local Prettier would be needed to confirm whether this file actually requires formatting corrections.
packages/testing/AGENTS.md (1)
1-52: Well-structured documentation for the testing package.This AGENTS.md file provides clear guidance for developers using the MCP testing library. The structure is comprehensive: quick commands for common tasks, key exports with descriptions, practical patterns with working code examples, dependency information, and documented common mistakes.
The Learnings section template with MANDATORY comment is appropriately formatted to guide future documentation of failures and solutions. The example in the template is helpful for showing the expected format.
One suggestion: when the Learnings section is populated, consider ensuring the format stays consistent (e.g., always "Problem → Solution" format) and that entries reference specific PR numbers or issue links where applicable for traceability. However, this can be addressed during future updates.
| @@ -0,0 +1 @@ | |||
| CLAUDE.md No newline at end of file | |||
There was a problem hiding this comment.
Fix Prettier formatting error (likely missing trailing newline).
The Prettier check is failing on the formatting. Since this file should reference CLAUDE.md, ensure there's a proper newline at the end of the file.
🔧 Proposed fix
-CLAUDE.md
+CLAUDE.md(Add newline at end of file)
📝 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.
| CLAUDE.md | |
| CLAUDE.md |
🧰 Tools
🪛 GitHub Actions: PR Check
[error] 1-1: Prettier formatting check failed. Run 'prettier --write' to fix code style issues in AGENTS.md.
[error] 1-1: Prettier formatting check failed. Run 'prettier --write' to fix code style issues in AGENTS.md.
🤖 Prompt for AI Agents
In @AGENTS.md at line 1, The file AGENTS.md currently contains "CLAUDE.md" but
fails Prettier due to missing trailing newline; edit AGENTS.md to add a newline
(trailing empty line) at the end of the file so the file ends with a proper
newline character.
| @@ -0,0 +1,54 @@ | |||
| # @mcp-apps-kit/ui-react-builder | |||
There was a problem hiding this comment.
Fix Prettier formatting error (likely missing trailing newline).
The Prettier check is failing. Ensure proper line ending and newline at EOF.
🔧 Proposed fix
Add a newline at the end of the file after line 54:
<!-- Example:
- Build succeeded but component didn't render → Check if all imports are included in bundle
- esbuild error about JSX → Ensure .tsx extension and jsx: 'automatic' in config
--->
+-->
🤖 Prompt for AI Agents
In @packages/ui-react-builder/AGENTS.md at line 1, The file AGENTS.md is missing
a trailing newline causing Prettier to fail; open
packages/ui-react-builder/AGENTS.md and add a single newline character at the
end of the file (i.e., ensure there is an empty line after the current last
line, add a newline after line 54) then save and re-run formatting/CI.
PR Review: Add AGENTS.md filesOverviewThis PR adds package-specific AGENTS.md documentation files and a symlink from root AGENTS.md to CLAUDE.md. Strengths
Critical Issues1. Misleading PR Title 2. Missing Context Minor Issues3. Windows Compatibility 4. Empty Learnings Sections 5. Formatting Check 6. Common Mistakes Quality Impact Assessment
RecommendationApprove with minor changes requested. Main concern is the outdated Codex reference in the title. Review based on CLAUDE.md conventions. |
Update Patterns section to accurately describe how exports are centralized through src/index.ts with re-exports from subdirectory barrel files.
Symlinks can be problematic on Windows (require admin/developer mode). Use a regular file instead that mirrors CLAUDE.md content.
Code Review: AGENTS.md DocumentationSummaryThis PR adds package-specific AGENTS.md documentation files for OpenAI Codex compatibility, along with a symlink at the root level pointing to CLAUDE.md. The documentation is well-structured and provides clear, concise development guidance for each package. ✅ Strengths
🔍 Observations & Minor Considerations1. Symlink Compatibility (Low Priority)The root Consideration: If Windows compatibility is important for contributors, you might want to document this or test it. However, given this is a developer-focused monorepo, the symlink approach is likely fine. 2. Documentation ConsistencyThe CLAUDE.md update ( to: This is an improvement (more direct, action-oriented language) and is consistently applied across all package AGENTS.md files. 3. Missing Package ReferenceAccording to
Good coverage! 🎯 Quality Checks
📝 Recommendations
✅ Final VerdictApproved with enthusiasm! This PR is well-executed, provides immediate value for AI agents working with the codebase, and maintains consistency with the existing CLAUDE.md conventions. The documentation is clear, practical, and well-organized. The changes are:
No blocking issues identified. Great work @gabrypavanello! 🎉 Note: I did not run the build/test suite since this is a documentation-only change with no code modifications. The symlink and markdown files are correctly formatted. |
PR Review: Documentation for OpenAI Codex CompatibilitySummaryThis PR adds ✅ Positive Aspects1. Clear Documentation Structure
2. Practical Developer Guidance
3. Accurate Technical Content
4. Root-Level Duplication Strategy
|
The float generator test was flaky due to floating point precision issues in fast-check. Added small epsilon tolerance for comparison.
PR Review: docs: Add AGENTS.md files for OpenAI Codex compatibilitySummaryThis PR adds AGENTS.md files across the codebase for OpenAI Codex compatibility, duplicating CLAUDE.md at the root and creating package-specific documentation. It also includes a test fix for floating-point precision issues. ✅ Positive Aspects
🔍 Code Quality & Best PracticesDocumentation Duplication ConcernIssue: The root AGENTS.md is a complete duplicate of CLAUDE.md (74 lines), differing only by a 3-line header comment. This violates the DRY principle and creates a maintenance burden. Recommendation: Instead of duplicating content, consider one of these approaches:
The commit message at 9afb1ec mentions symlinks are "problematic on Windows", but modern Windows 10+ supports symlinks with developer mode. A build script could handle this cross-platform. 🐛 Potential Issues1. Inconsistent Export DocumentationLocation: packages/core/AGENTS.md:25-26 Issue: The barrel file architecture description may be confusing:
This is technically accurate but verbose. The original CLAUDE.md says it more simply: "Exports only through index.ts" Recommendation: Simplify to match the clarity of CLAUDE.md, or add a concrete example showing the pattern. 2. Test Fix AnalysisLocation: packages/testing/tests/unit/eval/generators.test.ts:265-267 Current Code: const epsilon = 1e-10;
expect(samples.every((n) => n >= 0 - epsilon && n <= 1 + epsilon)).toBe(true);Analysis:
Recommendation: Consider using a slightly larger epsilon (e.g., const epsilon = 1e-6;
expect(samples.every((n) => n >= -epsilon && n <= 1 + epsilon)).toBe(true);🔒 Security ConcernsNo security issues identified. This PR only adds documentation and fixes a test. ⚡ Performance ConsiderationsNo performance impact - documentation changes only. 🧪 Test CoverageMissing Coverage:
Example Test:// In a root-level test file
it('should keep AGENTS.md and CLAUDE.md in sync', async () => {
const claudeMd = await fs.readFile('CLAUDE.md', 'utf-8');
const agentsMd = await fs.readFile('AGENTS.md', 'utf-8');
const claudeContent = claudeMd.trim();
const agentsContent = agentsMd
.replace(/^<!-- .* -->\n/gm, '') // Remove comment lines
.trim();
expect(agentsContent).toBe(claudeContent);
});📋 Recommendations SummaryHigh Priority:
Medium Priority:
Low Priority:
✅ Approval StatusThe PR is functional and doesn't introduce bugs, but the documentation duplication is a maintenance concern. I recommend addressing the duplication issue before merging to prevent divergence over time. Suggested Action: Refactor AGENTS.md to reference CLAUDE.md rather than duplicating it, or add automated sync verification. |
Remove duplication - AGENTS.md now just points to CLAUDE.md as the canonical source for project instructions.
Code ReviewSummaryThis PR adds AGENTS.md files for OpenAI Codex compatibility across all packages. The overall structure is good and follows a consistent pattern. Here's my detailed feedback: ✅ Strengths
🔍 Issues & Concerns1. Test Change Needs Review (
|
| Category | Rating | Notes |
|---|---|---|
| Documentation Quality | ⭐⭐⭐⭐☆ | Clear, concise, practical |
| Consistency | ⭐⭐⭐⭐☆ | Uniform structure, minor content gaps |
| Completeness | ⭐⭐⭐☆☆ | Missing external links, test change rationale |
| Maintainability | ⭐⭐⭐⭐☆ | Easy to update, follows template |
🔒 Security & Performance
- ✅ No security concerns
- ✅ No performance impact (documentation only)
- ✅ No runtime code changes except test fix
🧪 Test Coverage
The PR includes one test modification but no new tests. Since this is primarily a documentation change, that's acceptable. However:
Action Required: Verify the floating-point test change doesn't mask a real bug in the generator.
📝 Recommendations
Must Fix
- Clarify the test change rationale - Is epsilon tolerance correct, or does it hide a generator bug?
- Fix Common Mistakes classification - Move runtime npm version fetching to "How it Works" section
Should Fix
- Add Zod 4 migration guidance - Link or document breaking changes
- Clarify export patterns - Make subdirectory barrel file usage explicit
Nice to Have
- Add cross-references - Link between AGENTS.md files where packages depend on each other
- Expand framework adapter guidance - When to use vitest vs jest adapters
- Document template versioning - How to keep all AGENTS.md files in sync when template changes
✅ Approval Status
Conditional Approval - Approve after addressing the test change rationale and Common Mistakes classification fix.
The documentation structure is excellent and will be valuable for both human developers and AI coding assistants. Great work on maintaining consistency across all packages!
Testing Checklist
- Verify
pnpm build && pnpm test && pnpm lint && pnpm typecheckpasses (per CLAUDE.md line 8) - Confirm floating-point test still validates generator correctness
- Check that no existing CI checks are broken
Reviewed with Claude Code following CLAUDE.md conventions
Code ReviewSummaryThis PR adds AGENTS.md documentation files across the monorepo to improve AI agent compatibility (OpenAI Codex). The changes include:
Strengths
Observations and Minor Suggestions1. Root AGENTS.md ApproachThe root AGENTS.md redirects to CLAUDE.md. This is simple and prevents duplication, though it might be slightly confusing that AGENTS.md and CLAUDE.md are not identical. Consider:
2. Package Documentation ConsistencyAll package AGENTS.md files follow the same excellent structure. Minor observation:
3. Test Coverage for AGENTS.md FilesSince these are documentation files, no automated tests are needed. However, consider:
Potential IssuesNone found. The changes are low-risk documentation additions with one legitimate bug fix. Security ConsiderationsNo security concerns. These are documentation files only. Test CoverageThe test fix (generators.test.ts) improves test reliability by properly handling floating-point precision. The epsilon approach is textbook correct. No additional test coverage needed for documentation. Performance ConsiderationsNo performance impact. Documentation files are not loaded at runtime. RecommendationAPPROVE - This is a high-quality documentation PR that adds value for AI agents and developers. The changes are:
The only minor item is the semicolon in the JSX example, which is stylistic and not worth blocking on. Before merging: Verify that all CI checks pass (pnpm build, test, lint, typecheck as per CLAUDE.md requirements). CI appears to still be running. Great work! |
2 participants
Add root AGENTS.md as symlink to CLAUDE.md and create package-specific
AGENTS.md files with concise development notes for each package.