YPE-1006: Update AGENTS.md & CLAUDE.md files so that AI agents can better work with this repo #90

cameronapak · 2026-01-06T18:38:25Z

Because people, including myself, will be using AI agents to interact with and to create and work with this repository, I wanted to make sure that AI has the right guidance that it needs so that when it produces code, it produces code in line with the desires and the standards that we have set forth.

This is the second attempt to make the agent's files better so that AI can be a better assistant and helper as we create and do what God's called us to do

Important

This does not include a changeset because it doesn't change any features that an end-user interacts with.

One important piece of information is that the AGENTS.md file is compatible with a ton of AI agents such as people who use OpenCode or if they use Aider or if they use Kilo code or Cursor. However, AGENTS.md is not. They are all incompatible with Claude, which is why I do a symlink and create a CLAUDE.md file for each of the agent files that just points directly to the AGENTS.md file.

https://agents.md sets the tone for overarching idea and simple application of how AGENTS.md works.

Jira ticket: https://lifechurch.atlassian.net/browse/YPE-1006

context

instructions

changeset-bot · 2026-01-06T18:38:29Z

⚠️ No Changeset found

Latest commit: 343b408

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

chatgpt-codex-connector · 2026-01-06T18:38:30Z

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

greptile-apps · 2026-01-06T18:41:35Z

Greptile Summary

This PR restructures AI agent documentation to improve how AI coding assistants interact with the repository.

Refactored root AGENTS.md from 236 lines to 75 lines, focusing on essential patterns, commands, and anti-patterns
Extracted comprehensive review guidelines to new docs/review-guidelines.md (109 lines covering security, performance, accessibility, etc.)
Added new greptile.json configuration for AI-powered code review automation
Created package-specific AGENTS.md files for core, hooks, and ui packages with targeted documentation
Added CLAUDE.md symlinks in each package pointing to AGENTS.md for Claude-specific compatibility

The documentation accurately describes the monorepo structure, build tools, and development workflow. Minor count discrepancies exist in test file and component counts.

Confidence Score: 5/5

This PR only adds/modifies documentation files with no code changes - safe to merge
All changes are documentation-only (markdown files, JSON config, symlinks). No executable code is modified. The documentation accurately reflects the existing codebase structure with only minor count discrepancies that don't affect functionality.
No files require special attention - all changes are non-functional documentation updates

Important Files Changed

Filename	Overview
AGENTS.md	Refactored from verbose 236-line documentation to a more concise 75-line format. Review guidelines moved to separate docs/review-guidelines.md file.
docs/review-guidelines.md	New file containing comprehensive AI code review guidelines extracted from the previous AGENTS.md, covering code standards, security, performance, React/TypeScript best practices, accessibility, and more.
greptile.json	New Greptile configuration file defining comment types, project-specific rules, and references to review guidelines for AI code review automation.
packages/core/AGENTS.md	New package-specific AI documentation for core package. Minor inaccuracy: claims 12 test files but only 10 exist.
packages/hooks/AGENTS.md	New package-specific AI documentation for hooks package. Minor inaccuracy: claims 9 test files but 11 actually exist.
packages/ui/AGENTS.md	New package-specific AI documentation for UI package. Minor inaccuracy: mentions BibleTextView component which doesn't exist (appears to be verse.tsx), and claims 7 components but lists 8.

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant AI as AI Agent
    participant Root as AGENTS.md (root)
    participant Pkg as Package AGENTS.md
    participant Guide as review-guidelines.md
    participant Greptile as greptile.json

    Dev->>AI: Request code assistance
    AI->>Root: Read monorepo overview
    Root-->>AI: Structure, patterns, commands, anti-patterns
    AI->>Pkg: Read package-specific docs
    Pkg-->>AI: Package structure, API, conventions
    
    Dev->>AI: Request code review
    AI->>Greptile: Load review configuration
    Greptile-->>AI: Comment types, rules, file references
    AI->>Guide: Load review checklist
    Guide-->>AI: Security, performance, accessibility checks
    AI-->>Dev: Provide targeted review feedback

greptile-apps

_{9 files reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

packages/core/AGENTS.md

packages/hooks/AGENTS.md

packages/ui/AGENTS.md

Updated the wording to say "many" versus having very specific numbers that would have to be updated on every PR. This simplifies it so that AI gets the information it needs and we don't have to update this.

cameronapak · 2026-01-06T18:46:29Z

Hey @bmanquen , this PR is ready for review. I'll create a ticket in JIRA so that this does get tracked. This is very important for us as we create and if we use AI tools to create on this repo, this makes things easier. And I hope that it helps your development workflow as well

cameronapak · 2026-01-06T18:53:37Z

@greptileai, I've made some changes. Let me know if this is good to you. Also, I want to hear what you think about the greptile.json file.

greptile-apps

Looking at your changes, I think this is a significant improvement for AI agents working with this repo. Here's my assessment:

What Works Really Well

AGENTS.md transformation: The move from verbose documentation to concise, actionable reference is excellent. The new format with:

Clear structure overview
Key patterns and anti-patterns
Critical gotchas section
Command reference

This is much more useful for AI agents than the previous wall of text.

Separation of concerns: Moving the detailed review guidelines to docs/review-guidelines.md keeps the main AGENTS.md focused while preserving the comprehensive checklist.

Package-specific AGENTS.md files: These provide focused context for each package, which is perfect for when AI agents are working on specific parts of the monorepo.

The greptile.json File - This is Clever

I really like what you've done here. The greptile.json configuration is smart because it:

Enforces architectural patterns - The dependency order rule (core → hooks → ui) is critical for this monorepo
Captures React patterns - The forwardRef requirement is a good UI consistency rule
Prevents common mistakes - The workspace protocol rule will save headaches
References comprehensive guidelines - Pointing to docs/review-guidelines.md gives AI the full context when needed

The rules are specific and actionable, which is exactly what AI agents need.

Minor Suggestions

In the main AGENTS.md, you might add a note about the minimum Node.js version requirement (20.0.0+)
Consider adding a rule in greptile.json about the unified versioning pattern since that's such a critical aspect of this monorepo

Overall, this is a thoughtful approach that balances conciseness with completeness. AI agents should be much more effective with these changes. The greptile.json file in particular shows you're thinking strategically about how to guide AI behavior through tooling configuration.

davidfedor · 2026-01-07T21:33:10Z

packages/hooks/AGENTS.md

+- `utility/` - Helper functions (useDebounce, extractTextFromHTML, extractVersesFromHTML)
+
+## PUBLIC API
+- 20+ data fetching hooks for YouVersion API resources


would it be good to give a few examples on this line? so they can be found or guessed based on the naming convention it would see

davidfedor · 2026-01-07T21:36:35Z

packages/core/AGENTS.md

@@ -0,0 +1,36 @@
+## OVERVIEW
+Foundation package providing pure TypeScript API clients for YouVersion services with zero React dependencies.


Would it be helpful to mention here the other two packages and when they should be used instead of this? Cross-linking, basically, so agents which guessed about one of them would know if they should be using a different one.

davidfedor · 2026-01-07T21:36:53Z

packages/hooks/AGENTS.md

+# @youversion/platform-react-hooks
+
+## OVERVIEW
+React integration layer providing 20+ data fetching hooks and 3 core providers.


Ditto the cross-linking idea

davidfedor · 2026-01-07T21:37:13Z

packages/ui/AGENTS.md

+# AGENTS.md
+
+## OVERVIEW
+Complete UI layer with many Bible components: BibleTextView, VerseOfTheDay, BibleReader, BibleChapterPicker, BibleVersionPicker, YouVersionAuthButton, BibleWidgetView, BibleAppLogoLockup


ditto the cross-linking idea

davidfedor · 2026-01-07T21:38:17Z

packages/ui/AGENTS.md

+- Radix UI primitives for accessibility
+- Tailwind CSS via @tailwindcss/cli 4.1.15
+- tsup for bundling, tsc for type declarations
+


Would it be good to have very simple example code in this file? Same sample code as we have in the documentation, showing the basic usage patterns of the top components.

bmanquen

Great work just some comments that will hopefully help improve a couple areas.

bmanquen · 2026-01-08T04:22:24Z

greptile.json

+    "rules": [
+      {
+        "scope": ["src/**/*.ts", "src/**/*.tsx", "packages/**/*.ts", "packages/**/*.tsx"],
+        "rule": "All components must use React.forwardRef and accept standard HTML attributes"


I don't know if all components need to use forwardRef, I think only the components that users might need to interact with child components need refs.

bmanquen · 2026-01-08T04:38:28Z

packages/hooks/AGENTS.md

+- TypeScript declarations generated separately (no bundling)
+- Build: tsc only
+
+## TESTING


Should we also mention testing with mocks and ensuring that the tests are utilizing MSW?

bmanquen · 2026-01-08T04:41:28Z

packages/ui/AGENTS.md

+- Tailwind CSS via @tailwindcss/cli 4.1.15
+- tsup for bundling, tsc for type declarations
+
+## STYLING


Should we mention that styles must be prefixed with yv:, they must be within a parent that has data-yv-sdk, and that theme is set with data-yv-theme={currentTheme}?

bmanquen · 2026-01-08T04:43:48Z

packages/ui/AGENTS.md

+- Built Tailwind CSS: `dist/tailwind.css` → injected as JS string at build time
+- Light/dark mode via CSS variables (`[data-yv-sdk]`)
+
+## TESTING


Testing should be done within Storybook if possible utilizing the play function.

All Storybook tests with a play function need to have a tags: ['integration'],.

To run all Storybook integration tests run pnpm test:integration

Do these things need to be added?

bmanquen · 2026-01-08T04:45:27Z

packages/ui/AGENTS.md

+
+## TESTING
+- Vitest + jsdom for unit tests (`*.test.tsx`)
+- Playwright for Storybook integration tests (`vitest run --project storybook`)


I believe you can just run pnpm test:integration as long as they have the tags: ['integration'] on the story.

cameronapak added 2 commits January 6, 2026 12:28

feat: add AGENTS.md and CLAUDE.md files for better AI and developer

3bd6e63

context

feat: add Michael Martin's review guidelines for AI agents with greptile

4196ce8

instructions

cameronapak self-assigned this Jan 6, 2026

greptile-apps bot reviewed Jan 6, 2026

View reviewed changes

packages/core/AGENTS.md Outdated Show resolved Hide resolved

packages/hooks/AGENTS.md Outdated Show resolved Hide resolved

packages/ui/AGENTS.md Outdated Show resolved Hide resolved

docs(agents): update wording to "many" to avoid per-PR updates

6e715a9

Updated the wording to say "many" versus having very specific numbers that would have to be updated on every PR. This simplifies it so that AI gets the information it needs and we don't have to update this.

cameronapak requested a review from bmanquen January 6, 2026 18:45

cameronapak changed the title ~~Update AGENTS.md & CLAUDE.md files so that AI agents can better work with this repo~~ YPE-1006: Update AGENTS.md & CLAUDE.md files so that AI agents can better work with this repo Jan 6, 2026

greptile-apps bot reviewed Jan 6, 2026

View reviewed changes

docs: add updates based on feedback from Greptile's AI agent review

343b408

cameronapak mentioned this pull request Jan 6, 2026

YPE-1000 - Fix verse of the day component error loading verses in Storybook #92

Closed

cameronapak requested a review from davidfedor January 7, 2026 15:35

davidfedor reviewed Jan 7, 2026

View reviewed changes

bmanquen reviewed Jan 8, 2026

View reviewed changes

		@@ -0,0 +1,36 @@
		## OVERVIEW
		Foundation package providing pure TypeScript API clients for YouVersion services with zero React dependencies.

YPE-1006: Update AGENTS.md & CLAUDE.md files so that AI agents can better work with this repo #90

Are you sure you want to change the base?

YPE-1006: Update AGENTS.md & CLAUDE.md files so that AI agents can better work with this repo #90

Uh oh!

Conversation

cameronapak commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

chatgpt-codex-connector bot commented Jan 6, 2026

Uh oh!

greptile-apps bot commented Jan 6, 2026

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cameronapak commented Jan 6, 2026

Uh oh!

cameronapak commented Jan 6, 2026

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

What Works Really Well

The greptile.json File - This is Clever

Minor Suggestions

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bmanquen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cameronapak commented Jan 6, 2026 •

edited

Loading

changeset-bot bot commented Jan 6, 2026 •

edited

Loading