Agent context file

[gabrypavanello]

Refactor AGENTS.md to serve as a high-signal, low-noise system prompt extension for coding agents.

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[claude]

Code Review

Summary

This PR refactors AGENTS.md from a simple redirect to CLAUDE.md into a comprehensive agent-oriented system prompt. The new structure uses semantic section markers (@context, @stack, @knowledge Graph, etc.) to organize information for AI coding agents.

---

✅ Strengths

1. Well-structured information architecture: The @-prefixed sections (@context, @stack, @knowledge Graph, @Map, @workflow, @rules, @memory) create clear mental models for agents to understand the codebase.

2. Comprehensive coverage: The new content consolidates critical information from CLAUDE.md and extends it with additional context (Node.js versions, TypeScript config specifics, testing framework details).

3. Good cross-referencing: The @knowledge Graph section provides a clear map of where to find detailed information, preventing duplication while maintaining discoverability.

4. Self-correction loop: The @memory section encourages iterative improvement, which aligns with the "Learnings" section pattern already present in CLAUDE.md and package-level AGENTS.md files.

---

⚠️ Issues & Recommendations

1. Potential Confusion with CLAUDE.md

Issue: The repository now has TWO authoritative agent instruction files (CLAUDE.md and AGENTS.md) with overlapping content but different structures. This creates ambiguity about which file is the source of truth.

Evidence:

• Both files specify the same build command requirement
• Both files document Zod 4, Express 5, strict TypeScript, and middleware patterns
• CLAUDE.md is referenced in system prompts
• The new AGENTS.md references CLAUDE.md in @knowledge Graph but doesn't explain their relationship

Recommendation:

• Option A (Recommended): Merge the best of both into CLAUDE.md and make AGENTS.md a brief introduction that points to CLAUDE.md, similar to the original approach but with a table of contents
• Option B: Clearly document the distinction (e.g., "CLAUDE.md = human-friendly guide, AGENTS.md = agent-optimized prompt extension") and ensure they don't conflict
• Option C: Deprecate one in favor of the other

---

2. Inconsistency with Package-Level AGENTS.md Pattern

Issue: The root AGENTS.md now uses a different format (@context, @stack, etc.) than the package-level AGENTS.md files (which use: Quick Commands, Key Exports, Patterns, Dependencies, Common Mistakes, Learnings).

Evidence: Compare the new root AGENTS.md with packages/core/AGENTS.md and packages/ui-react/AGENTS.md

Recommendation: Either:

1. Standardize all AGENTS.md files to use the same format, OR
2. Document that root-level uses @-sections while package-level uses traditional sections

---

3. Node.js Version Discrepancy

Issue: The @stack section states "monorepo dev requires >= 20; runtime packages may support >= 18" but this needs verification.

Current state:

• CONTRIBUTING.md specifies Node.js >= 20
• No mention of runtime vs. dev distinction elsewhere

Recommendation: Verify this claim or remove the "runtime packages may support >= 18" clause if it's not accurate. If true, document which packages support Node 18 vs 20.

---

4. Missing Test Coverage Context

Issue: The @stack section mentions "50% lines/functions/branches/statements" but doesn't explain this is repo-level enforcement (not per-package).

Evidence: CLAUDE.md states "CI fails below this"

Recommendation: Clarify: "repo-level coverage thresholds enforced at 50%" to match the precision in CLAUDE.md.

---

5. Minor: Verbose @knowledge Graph

Issue: The @knowledge Graph section lists packages/*/AGENTS.md which may not exist for all packages.

Recommendation: Be specific: "Package-specific agent notes (where present)" or list only packages that have AGENTS.md.

---

📊 Testing & Quality

Strengths:

• This is a documentation-only change (no code changes)
• No test updates needed
• No build/lint issues expected

Missing:

• No verification that all referenced files exist (e.g., ./docs/quickstart.md, ./eslint.config.js, ./vitest.config.ts)

Recommendation: Verify all file paths in @knowledge Graph section actually exist in the repository.

---

🔒 Security & Performance

No concerns: This is documentation only, no security or performance implications.

---

🎯 Final Verdict

Conditional Approval: The refactor significantly improves agent-oriented documentation structure, but the relationship with CLAUDE.md needs clarification to avoid confusion.

Required before merge:

1. Resolve CLAUDE.md vs AGENTS.md relationship (see Issue Add Claude Code GitHub Workflow #1)
2. Verify all file paths in @knowledge Graph exist

Nice to have:
3. Standardize format across root and package-level AGENTS.md files
4. Clarify Node.js version requirements
5. Verify coverage threshold description accuracy

---

📝 Suggested Next Steps

1. Discuss with team: Should AGENTS.md replace CLAUDE.md, complement it, or point to it?
2. Run file existence validation
3. Consider updating package-level AGENTS.md files to match new format (separate PR)
4. Update system prompts/tooling that reference CLAUDE.md to also reference AGENTS.md (if applicable)

Great work on improving agent-facing documentation! The @-section structure is a solid pattern for AI context files.

[gabrypavanello]

@cursor replace the content in CLAUDE.md referencing only the AGENTS.md instructing to read it before starting

[cursor]

Updated CLAUDE.md to only reference AGENTS.md and instruct agents to read it before starting:

# CLAUDE.md

This repository’s primary agent instructions live in `AGENTS.md`.

**Before starting any work, read `./AGENTS.md` and follow it as the single source of truth.**

This is committed and pushed on cursor/agent-context-file-51a8, and pnpm build && pnpm test && pnpm lint && pnpm typecheck all pass.

---

 

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Expanded agent guidelines into structured sections covering mission, technical stack, knowledge graph, map, workflow, rules, and memory/self-correction processes.
  • Centralized guidance by making the main reference the single source of truth and condensing secondary guidance to point to it.
  • Removed redundant task-oriented content from the secondary doc and streamlined onboarding/usage instructions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Restructures documentation: expands AGENTS.md into a structured agent guide (mission, stack, knowledge graph, map, workflow, rules, memory) and replaces CLAUDE.md with a minimal pointer directing readers to AGENTS.md. No code or public API changes.

Changes

Cohort / File(s)	Summary
Documentation: agent guide AGENTS.md	Rewritten and expanded into multiple structured sections: Context (Mission), Stack (Technical DNA), Knowledge Graph (Context Links), Map (File Structure), Workflow (How To Work Here), Rules (Dos & Don’ts), Memory (Self-Correction Loop).
Documentation: pointer CLAUDE.md	Condensed to a single directive instructing readers to follow AGENTS.md as the single source of truth; previous extensive guidance removed.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• docs: comprehensive update to CLAUDE.md for AI assistants #49 — Edits CLAUDE.md; may conflict by expanding CLAUDE.md while this PR condenses it to point at AGENTS.md.
• Agent context file #100 — Makes similar documentation changes: expands AGENTS.md and updates CLAUDE.md to reference it.
• docs: Add AGENTS.md files for OpenAI Codex compatibility #86 — Also modifies AGENTS.md and CLAUDE.md, aligning documentation restructuring.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is vague and generic, using a non-descriptive term 'Agent context file' that doesn't convey the primary change of refactoring AGENTS.md into a system prompt extension.	Consider a more specific title like 'Refactor AGENTS.md as system prompt for coding agents' to better reflect the primary intent and change.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly relates to the changeset by explaining the refactoring of AGENTS.md to serve as a system prompt extension for coding agents.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cd6b58b and cbc7a63.

📒 Files selected for processing (2)

• AGENTS.md
• CLAUDE.md

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Pull Request Review: Agent Context File Refactoring

Summary

This PR refactors the agent instruction files by consolidating detailed project context into AGENTS.md and simplifying CLAUDE.md to be a simple pointer. The goal is to provide a more structured, high-signal context for coding agents.

---

✅ Strengths

1. Excellent Structure and Organization

   • The new AGENTS.md uses clear semantic sections (@context, @stack, @Map, @workflow, @rules, @memory)
   • Information is hierarchically organized and easy to scan
   • The knowledge graph section provides clear pointers to related documentation

2. Comprehensive Technical Guidance

   • Critical version requirements are explicit (Zod v4, Express v5, Node >= 20)
   • Coverage thresholds and testing requirements are clearly stated
   • Common pitfalls are documented in @rules section

3. Self-Correction Loop

   • The @memory section is excellent - it creates a feedback mechanism for continuous improvement
   • This pattern encourages agents to document failures for future reference

4. Clean Separation of Concerns

   • CLAUDE.md now has a single, clear purpose: redirect to AGENTS.md
   • Reduces maintenance burden and eliminates duplicate information

---

📋 Observations & Suggestions

1. Documentation Completeness

The old CLAUDE.md had a "Learnings" section for documenting failures. While the new AGENTS.md has the @memory section serving this purpose, you might want to:

• Consider migrating any existing learnings from the old CLAUDE.md if they existed
• Add a comment or example in @memory showing the expected format

Suggestion:

## @Memory (Self-Correction Loop)

If you encounter repeated errors [...] you MUST update this file.

<!-- Example entries:
- ❌ Used `pnpm test` in single package without build → ✅ Always `pnpm build` first or use `pnpm -C packages/<pkg> test` with fresh install
- ❌ Import from 'src/internal/foo' across packages → ✅ All imports must go through package's index.ts
-->

2. Consistency Check

The PR description mentions this is optimized for coding agents, particularly as a "system prompt extension." Consider:

• Are there other agent context files in the repo that should reference this pattern?
• Should package-specific AGENTS.md files follow a similar structure?

3. Testing Implications

This is a documentation-only change, so traditional testing doesn't apply. However:

• Consider how agents will discover this file (is there documentation pointing to it?)
• Is the filename AGENTS.md a standard convention in your workflow, or should it be documented elsewhere?

---

🔍 Code Quality Assessment

Best Practices: ✅ Excellent

• Clear, concise writing
• Logical information architecture
• Actionable guidance

Potential Bugs: ✅ None

• This is documentation only, no code changes

Performance: ✅ N/A

• Documentation has no runtime performance impact

Security: ✅ N/A

• No security implications

Test Coverage: ⚠️ N/A

• Documentation changes don't require tests
• Consider: Do you want to add a test that validates the structure/format of AGENTS.md? (e.g., ensuring required sections exist)

---

🎯 Final Recommendation

Approve with minor suggestions.

This is a high-quality refactoring that improves maintainability and provides clearer guidance for coding agents. The structure is well-thought-out and follows good technical writing practices.

Before merging:

1. ✅ Verify no valuable content from old CLAUDE.md was lost
2. 💡 Consider adding example entries to the @memory section
3. 💡 Document this pattern in CONTRIBUTING.md if it's not already there

Note: The commit messages follow good conventional commit style ("docs: refactor AGENTS.md for coding agents"), which is great for changelog generation.

---

Great work on improving the developer experience for both human and AI contributors! 🚀

[claude]

Code Review: Agent Context File Refactor

Summary

This PR refactors the agent instruction files by consolidating all substantive guidance into AGENTS.md and converting CLAUDE.md to a simple pointer. This is a documentation restructuring with no code changes.

---

✅ Strengths

1. Improved Information Architecture

The new AGENTS.md structure is excellent:

• Clear sections with semantic headers (@context, @stack, @Map, etc.) make it scannable
• Knowledge Graph provides direct navigation to relevant documentation
• Centralized rules eliminate ambiguity about where to find project conventions
• Self-correction loop (@memory section) is a great pattern for evolving best practices

2. Better Signal-to-Noise Ratio

• The old CLAUDE.md had redundant sections ("Before Finishing Any Task" duplicated in both files)
• New structure consolidates everything into a single source of truth
• More structured format (bullet points, bold emphasis) vs. prose makes it easier to parse

3. Consistency with Monorepo Pattern

• The reference to package-specific AGENTS.md files shows good architectural thinking
• Follows the principle of keeping global guidance at root and package-specific details local

---

⚠️ Issues & Recommendations

1. Breaking Change for CI Workflows ⚠️ CRITICAL

Problem: Two GitHub Actions workflows still reference CLAUDE.md:

File: .github/workflows/claude-code-review.yml:50

Use the repository's CLAUDE.md for guidance on style and conventions.

File: .github/workflows/claude-kaizen.yml:71

CRITICAL: Read CLAUDE.md before starting.

Impact: These workflows will continue instructing the agent to read CLAUDE.md, which now just says "read AGENTS.md". While this creates an extra redirection hop (which works), it's inconsistent with the PR's goal of making AGENTS.md the primary source.

Recommendation: Update both workflow files to reference AGENTS.md directly:

# claude-code-review.yml
- Use the repository's CLAUDE.md for guidance on style and conventions.
+ Use the repository's AGENTS.md for guidance on style and conventions.

# claude-kaizen.yml  
- CRITICAL: Read CLAUDE.md before starting.
+ CRITICAL: Read AGENTS.md before starting.

2. Content Loss: Missing "Learnings" Section

Problem: The old CLAUDE.md had a "Learnings" section for documenting mistakes:

## Learnings
<!-- MANDATORY: Document failures here to prevent repeated mistakes -->

The new AGENTS.md has an @memory section that serves a similar purpose but with different framing:

• Old: "Document what went wrong → what to do instead"
• New: "Update this file when you encounter repeated errors"

Impact: The new framing is actually better (proactive vs. reactive), but the explicit template with examples is lost.

Recommendation: Consider adding a concrete example in the @memory section to maintain the pattern:

## @Memory (Self-Correction Loop)

If you encounter repeated errors... you MUST update this file.

<!-- Example format:
- ❌ Forgot to rebuild ui package before testing ui-react 
  ✅ Always `pnpm build` from root before cross-package testing
-->

3. Minor: "External Docs" Section Removed

Problem: The old CLAUDE.md linked to:

• MCP Spec
• OpenAI Apps SDK

These are now missing from the new AGENTS.md.

Impact: Low - agents can find these via web search, but having them pre-linked reduces friction.

Recommendation: Add to @knowledge Graph:

- [MCP Protocol specification]: https://modelcontextprotocol.io/specification/2025-11-25
- [OpenAI Apps SDK documentation]: https://developers.openai.com/apps-sdk

4. Consistency: Quick Commands Missing

Problem: Old CLAUDE.md included quick commands like:

pnpm -C packages/core test     # Faster iteration
pnpm release:version:patch

The new AGENTS.md mentions pnpm -C in @workflow but without the "faster iteration" context.

Impact: Low - information is preserved but less explicit.

Recommendation: Keep as-is (it's documented in @workflow), but consider adding a note in @workflow:

- Test: `pnpm test` (or faster: `pnpm -C packages/<pkg> test` for single-package iteration)

---

📊 Test Coverage

Status: N/A (documentation-only change)

No tests needed, but the workflow references should be tested once updated.

---

🔒 Security

Status: ✅ No concerns

No code changes, no security impact.

---

🎯 Performance

Status: ✅ No impact

Documentation changes only.

---

📋 Overall Assessment

Rating: ⚠️ Approve with Changes Required

This is a well-thought-out refactor that improves the agent instruction architecture. However, the CI workflow references must be updated to avoid confusion and maintain consistency with the PR's intent.

Required Changes:

1. ✅ MUST FIX: Update .github/workflows/claude-code-review.yml:50 and .github/workflows/claude-kaizen.yml:71 to reference AGENTS.md

Suggested Improvements:

2. Consider adding example to @memory section (low priority)
3. Consider adding external docs to @knowledge Graph (low priority)

Once the workflow files are updated, this PR will be ready to merge. The new structure is a clear improvement over the old one.

---

Reviewed by: Claude Sonnet 4.5
Review Date: 2026-01-16

[memory]

dear @claude -- @memory is an actual github userID, specfically mine. Any time you use that string in a code review or comment, I get an alert. please stop that.

[stack]

dear @claude -- @memory is an actual github userID, specfically mine. Any time you use that string in a code review or comment, I get an alert. please stop that.

Imagine having the username @stack.

[memory]

@stack LOL. For what it's worth I have managed to track down a contact inside Anthropic; we'll see they can get Claude to stop doing this. (Alerts from humans misunderstanding how github usernames work, alas, we are probably stuck with forever.)