chore(repo): symlink agents to claude

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[railway-app]

🚅 Deployed to the rivet-pr-4117 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-cloud	❌ Build Failed (View Logs)	Web	Feb 4, 2026 at 9:49 pm
website	🕒 Building (View Logs)	Web	Feb 4, 2026 at 9:49 pm
frontend-inspector	🕒 Building (View Logs)	Web	Feb 4, 2026 at 9:49 pm
mcp-hub	🕒 Building (View Logs)	Web	Feb 4, 2026 at 9:49 pm

[NathanFlurry]

• chore(repo): symlink agents to claude #4117 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[graphite-app]

Merge activity

• Feb 4, 9:49 PM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Feb 4, 9:49 PM UTC: CI is running for this pull request on a draft pull request (#4118) due to your merge queue CI optimization settings.
• Feb 4, 9:50 PM UTC: Merged by the Graphite merge queue via draft PR: #4118.

[claude]

PR Review: Symlink AGENTS.md to CLAUDE.md

Summary

This PR creates symlinks from AGENTS.md to CLAUDE.md in three subdirectories:

• rivetkit-swift/
• rivetkit-typescript/packages/workflow-engine/
• website/

Code Quality: ✅ APPROVED

Strengths:

1. Consistency - This change follows the existing pattern already established in the root directory and examples/ folder, where AGENTS.md -> CLAUDE.md symlinks already exist
2. Simplicity - The approach is minimal and straightforward
3. Context-aware - Each directory has its own specific CLAUDE.md with relevant guidance (Swift SDK guidelines, workflow engine schema sync, website code block requirements)

Verification

I verified that all three directories already have their own CLAUDE.md files with domain-specific content:

• rivetkit-swift/CLAUDE.md (147 lines) - Swift SDK guidelines, platform support, API surface conventions
• workflow-engine/CLAUDE.md (14 lines) - Persist schema sync instructions
• website/CLAUDE.md (14 lines) - Documentation code block type-checking requirements

The symlinks correctly point to their respective local CLAUDE.md files (relative path).

Potential Concerns: ⚠️ MINOR

1. No documentation - The PR description doesn't explain what AGENTS.md is for or why this symlink pattern is used. Consider adding a brief comment in the root README.md or a .agents/README.md explaining this convention.

2. Incomplete coverage? - Are there other subdirectories that should also have this symlink? The pattern seems to be applied selectively. Consider documenting the criteria for when a directory should have this symlink.

Security: ✅ NO CONCERNS

Symlinks pose no security risk in this context.

Performance: ✅ NO IMPACT

Symlinks have negligible performance impact.

Test Coverage: ⚠️ N/A

This is a documentation/tooling change that doesn't require tests, but it would be helpful to verify:

• The symlinks work correctly on different platforms (Windows, macOS, Linux)
• Any tooling that reads AGENTS.md can follow symlinks properly

Recommendation: ✅ APPROVE WITH SUGGESTIONS

This is a safe, straightforward change that improves consistency. The minor suggestions above are optional improvements, not blockers.

Optional follow-up:

• Document the purpose of the AGENTS.md symlink pattern
• Consider whether other directories need this symlink for completeness

[claude]

PR Review: Symlink AGENTS.md to CLAUDE.md

Summary

This PR creates symlinks from AGENTS.md to CLAUDE.md in three subdirectories:

• rivetkit-swift/
• rivetkit-typescript/packages/workflow-engine/
• website/

Overall Assessment

✅ APPROVED - This is a clean, low-risk organizational change.

---

Code Quality

✅ Good - The implementation is straightforward and follows existing patterns.

Observations:

• The PR follows the existing pattern already established in the root directory and examples/, where AGENTS.md -> CLAUDE.md symlinks already exist
• This creates consistency across the monorepo by ensuring all subdirectories with their own CLAUDE.md files also have AGENTS.md symlinks

---

Potential Issues

⚠️ Minor Concerns:

1. Symlink Resolution Across Platforms: Symlinks work well on Unix-like systems (Linux, macOS), but may have issues on Windows systems without proper Git configuration. Consider documenting this if Windows development is supported.

2. Git Configuration: Ensure that .gitattributes or Git configuration properly handles symlinks if not already configured. On Windows, users need core.symlinks=true.

3. Missing Context: The PR description is empty (uses default template). While the commit message chore(repo): symlink agents to claude is clear, it would be helpful to explain why these symlinks are needed. Is AGENTS.md a convention expected by tooling, CI/CD, or agent frameworks?

---

Testing Considerations

✅ Low Risk - No functional changes

Suggested verification:

# Verify symlinks are created correctly
ls -la rivetkit-swift/AGENTS.md
ls -la rivetkit-typescript/packages/workflow-engine/AGENTS.md
ls -la website/AGENTS.md

# Verify they resolve to the correct target
readlink -f rivetkit-swift/AGENTS.md
readlink -f rivetkit-typescript/packages/workflow-engine/AGENTS.md
readlink -f website/AGENTS.md

# Test that content is accessible
cat rivetkit-swift/AGENTS.md | head -5

---

Performance Considerations

✅ No Impact - Symlinks have negligible performance overhead

---

Security Concerns

✅ No Security Issues

• Symlinks point to files within the same repository
• No external references or potential for directory traversal

---

Recommendations

1. Documentation: Add a brief explanation to the PR description about why AGENTS.md symlinks are being created (e.g., "Agent tooling expects AGENTS.md files" or "For compatibility with CI/CD workflows").

2. Consistency Check: Verify if other subdirectories with CLAUDE.md files also need AGENTS.md symlinks:

   find . -name "CLAUDE.md" -type f

   If there are other CLAUDE.md files without corresponding AGENTS.md symlinks, consider adding them for consistency.

3. Windows Support (if applicable): Document any Git configuration requirements for Windows developers in the repository's contributing guide.

---

Conclusion

This is a clean, well-scoped change that improves consistency across the monorepo. No blocking issues identified. ✅

[claude]

PR Review: Symlink AGENTS.md to CLAUDE.md

Overview

This PR creates symlinks from AGENTS.md to CLAUDE.md in three subdirectories:

• rivetkit-swift/
• rivetkit-typescript/packages/workflow-engine/
• website/

✅ Positive Aspects

1. Good Architecture: Using symlinks to avoid duplication is the right approach - maintains a single source of truth while making context available in subdirectories.

2. Symlinks Are Correct: All three symlinks use relative paths (CLAUDE.md) which will correctly resolve to the local CLAUDE.md file in each directory.

3. Files Exist: Verified that all target CLAUDE.md files exist:

   • rivetkit-swift/CLAUDE.md (4,943 bytes)
   • rivetkit-typescript/packages/workflow-engine/CLAUDE.md (470 bytes)
   • website/CLAUDE.md (436 bytes)

4. Consistent Pattern: All symlinks follow the same pattern, making the codebase more predictable.

⚠️ Considerations & Questions

1. Missing Context in PR Description: The PR body uses the default template without explaining:

   • What is AGENTS.md and how does Claude Code use it?
   • Why are these specific three directories chosen?
   • Are there other subdirectories that should also have this symlink?

2. Incomplete Coverage?: The root directory already has AGENTS.md (seen in git status). Should other major subdirectories also have this symlink for consistency? For example:

   • examples/ subdirectories?
   • Other packages in rivetkit-typescript/packages/?
   • Rust workspace packages?

3. Documentation Gap: There's no documentation explaining:

   • The AGENTS.md mechanism itself
   • When/why to add these symlinks to new directories
   • How Claude Code discovers and uses these files

4. Git Symlink Portability: While git handles symlinks well on Unix-like systems, Windows users cloning the repo may need special git configuration (core.symlinks=true) or may get text files with symlink target paths instead. This is usually fine but worth noting for Windows contributors.

🔍 Code Quality Assessment

• No bugs detected: The symlinks are correctly formed
• No security concerns: Symlinks point to local files in the same directory
• No performance impact: Symlinks are resolved at filesystem level
• No test coverage needed: This is infrastructure configuration

📋 Recommendations

1. Update PR Description: Add a brief explanation of what AGENTS.md does and why these three directories need it.

2. Consider Documentation: Add a note to the root CLAUDE.md or create a brief doc explaining the AGENTS.md mechanism and when to use it in subdirectories.

3. Audit for Completeness: Consider whether other directories with CLAUDE.md files should also have AGENTS.md symlinks for consistency.

✅ Approval

This PR is ready to merge as-is. The implementation is correct and safe. The recommendations above are suggestions for improving documentation and completeness, but are not blocking issues.

The symlinks work correctly, point to existing files, and follow a sensible pattern for making context-specific guidelines discoverable by Claude Code when working in subdirectories.