Add AGENTS.md files for AI coding agents#57
Conversation
📝 WalkthroughWalkthroughThis pull request introduces AGENTS.md documentation files across the monorepo that define the purpose, scope, boundaries, and development workflows for the MDCMS project, its applications (CLI and server), and its packages (SDK, shared contracts, and Studio component). Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Poem
🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 74264e1902
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| The command-line interface for syncing content between local files and the MDCMS server. The core mental model: content lives in the database, but developers pull it to local `.md`/`.mdx` files, edit with their preferred tools, and push changes back. The CLI handles change detection, conflict resolution, and schema synchronization. | ||
|
|
||
| Commands: `init`, `login`, `logout`, `push`, `pull`, `schema sync`, `status`, `migrate`. Auth uses a browser-based device flow that exchanges a challenge for an API key stored locally. |
There was a problem hiding this comment.
migrate from documented CLI commands
This AGENTS guide lists migrate as an available CLI command, but the command registry only wires init, login, logout, pull, push, schema sync, and status (apps/cli/src/lib/framework.ts DEFAULT_COMMANDS, lines 100-108). Because these files are operational instructions for agents/contributors, documenting an unavailable command will send automation and users down a failing path when they try migration workflows.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
packages/sdk/AGENTS.md (1)
14-14: Tighten dependency wording on Line 14 (“runtime” vs “types”).“Runtime except
@mdcms/sharedfor types” is internally inconsistent. Suggest splitting into: runtime dependency policy + type-level dependency policy.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/sdk/AGENTS.md` at line 14, Split the single sentence that now reads "Does not depend on any other MDCMS package at runtime except `@mdcms/shared` for types" into two clear policies: one stating the runtime dependency rule (e.g., "This package must not have runtime dependencies on other MDCMS packages.") and one stating the type-only dependency rule (e.g., "Type-only dependencies such as `@mdcms/shared` are allowed for typings and should be marked as devDependency or peerDependency as appropriate."); update the AGENTS.md wording accordingly so runtime vs type-level dependency policies are unambiguous.AGENTS.md (1)
32-35: Use clickable Markdown links for specs/ADRs instead of code literals.On Line 32 and Line 34, paths are currently plain code spans, so “link resolution” can’t be directly validated from the doc UI. Prefer
[label](relative/path.md)links.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@AGENTS.md` around lines 32 - 35, Replace the plain code-span mentions of docs/adrs/ and docs/specs/ with clickable Markdown links so link resolution can be validated in the doc UI; specifically update the text containing `docs/adrs/` and `docs/specs/` to use the form [ADRs](docs/adrs/) and [specs](docs/specs/) (or similar descriptive labels) where those two literals appear in the AGENTS.md snippet.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@apps/cli/AGENTS.md`:
- Line 13: Update the sentence in AGENTS.md that currently reads "Does not run
the server. It connects to a running MDCMS server via HTTP." to clarify that the
CLI does not start the MDCMS backend but may create a temporary local HTTP
listener for authentication callbacks; e.g., replace it with "Does not run the
MDCMS backend server; it only connects to a running MDCMS server via HTTP (the
CLI may create a temporary localhost HTTP listener for auth callbacks — see
apps/cli/src/lib/login.ts)." This makes it clear the CLI doesn't run the backend
while acknowledging the auth callback listener behavior found in
apps/cli/src/lib/login.ts.
---
Nitpick comments:
In `@AGENTS.md`:
- Around line 32-35: Replace the plain code-span mentions of docs/adrs/ and
docs/specs/ with clickable Markdown links so link resolution can be validated in
the doc UI; specifically update the text containing `docs/adrs/` and
`docs/specs/` to use the form [ADRs](docs/adrs/) and [specs](docs/specs/) (or
similar descriptive labels) where those two literals appear in the AGENTS.md
snippet.
In `@packages/sdk/AGENTS.md`:
- Line 14: Split the single sentence that now reads "Does not depend on any
other MDCMS package at runtime except `@mdcms/shared` for types" into two clear
policies: one stating the runtime dependency rule (e.g., "This package must not
have runtime dependencies on other MDCMS packages.") and one stating the
type-only dependency rule (e.g., "Type-only dependencies such as `@mdcms/shared`
are allowed for typings and should be marked as devDependency or peerDependency
as appropriate."); update the AGENTS.md wording accordingly so runtime vs
type-level dependency policies are unambiguous.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: bf225f17-c303-47b9-9fa4-4b4a5da31329
📒 Files selected for processing (6)
AGENTS.mdapps/cli/AGENTS.mdapps/server/AGENTS.mdpackages/sdk/AGENTS.mdpackages/shared/AGENTS.mdpackages/studio/AGENTS.md
|
|
||
| - Does not render or serve content. That's the SDK's job. | ||
| - Does not provide a visual editing interface. That's Studio. | ||
| - Does not run the server. It connects to a running MDCMS server via HTTP. |
There was a problem hiding this comment.
Clarify “does not run the server” to avoid contradiction with login callback listener.
Line 13 currently reads absolute, but apps/cli/src/lib/login.ts (Line 140-180 in provided snippet) creates a temporary localhost HTTP listener for auth callback. Consider wording like: “Does not run the MDCMS backend server; it only connects to a running MDCMS server via HTTP.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@apps/cli/AGENTS.md` at line 13, Update the sentence in AGENTS.md that
currently reads "Does not run the server. It connects to a running MDCMS server
via HTTP." to clarify that the CLI does not start the MDCMS backend but may
create a temporary local HTTP listener for authentication callbacks; e.g.,
replace it with "Does not run the MDCMS backend server; it only connects to a
running MDCMS server via HTTP (the CLI may create a temporary localhost HTTP
listener for auth callbacks — see apps/cli/src/lib/login.ts)." This makes it
clear the CLI doesn't run the backend while acknowledging the auth callback
listener behavior found in apps/cli/src/lib/login.ts.
3 participants
Summary
Adds orientation files for AI coding agents (Claude Code, Codex, etc.) contributing to the codebase.
AGENTS.mdwith project vision, direction, repo layout, and pointers to specs/ADRsTest plan
Summary by CodeRabbit