Unify agent docs: merge CLAUDE.md into AGENTS.md, symlink the rest#425
Conversation
…the rest CLAUDE.md (codebase map, build/test, conventions) and AGENTS.md (command/usage tour) were two separate, non-overlapping docs that both had to be kept in sync by hand. Fold CLAUDE.md's unique content into AGENTS.md as a new "Working on fledge's own codebase" section, then replace CLAUDE.md with a symlink → AGENTS.md so there's a single source of truth. AGENTS.md is the cross-tool standard name; Claude Code resolves the symlink transparently. Refreshed while merging: `src/spec/` now lists `engine`; the spec-check convention notes the new specsync delegation; dropped the stale `Formula/` line. Note: git stores CLAUDE.md as a symlink (mode 120000). Windows clones need core.symlinks=true (+ Developer Mode) to materialize it as a link rather than a text file; macOS/Linux are unaffected. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request restructures the project's documentation by moving the development guidelines, build/test instructions, and architecture source map from the main README (which was deleted) into AGENTS.md, and introduces a CLAUDE.md file. The review feedback correctly points out that development commands, such as running lanes or checking specs, should be executed using the local development version via cargo run -- instead of the globally installed fledge binary to ensure local changes are tested.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| cargo fmt --check | ||
| ``` | ||
|
|
||
| Or via fledge's own lanes: `fledge lanes run pre-commit` (fmt + lint + test + spec-check). |
There was a problem hiding this comment.
When working on fledge's own codebase, running the globally installed fledge binary will not use your local changes to the CLI or runner. It is safer to run the local development version using cargo run --.
Suggested change:
Or via fledge's own lanes: `cargo run -- lanes run pre-commit` (fmt + lint + test + spec-check).| ### Conventions | ||
|
|
||
| - Specs are the source of truth — read before modifying code | ||
| - Run `fledge spec check` before committing. It delegates to the `specsync` binary when installed (matching CI's export-coverage validation) and falls back to a structural check otherwise |
There was a problem hiding this comment.
Using the globally installed fledge binary to run spec check will execute the installed version rather than your local changes. When modifying fledge itself, you should run the local development version via cargo run --.
Suggested change:
- Run `cargo run -- spec check` before committing. It delegates to the `specsync` binary when installed (matching CI's export-coverage validation) and falls back to a structural check otherwise1 participant
Summary
CLAUDE.mdandAGENTS.mdwere two separate, non-overlapping docs that both had to be hand-maintained:CLAUDE.md— codebase map (src/module layout), build/test commands, repo conventionsAGENTS.md— the agent command/usage tour (--jsonsurface, workflows, AI providers)This folds
CLAUDE.md's unique content intoAGENTS.mdunder a new "Working on fledge's own codebase" section, then replacesCLAUDE.mdwith a symlink → AGENTS.md. One source of truth;AGENTS.mdis the emerging cross-tool standard name and Claude Code resolves the symlink transparently.Refreshed while merging:
src/spec/source map now lists the newenginesubmodulespecsyncdelegation (from Delegatefledge spec checkto the real specsync binary for CI parity #424)Formula/lineCaveat — Windows symlinks
git stores
CLAUDE.mdas a symlink (mode120000). Windows clones needcore.symlinks=true(+ Developer Mode) to materialize it as a real link rather than a 1-line text file containingAGENTS.md. macOS/Linux are unaffected. Flagging since this repo haswindows-latestCI and Windows users.Test Plan
CLAUDE.mdresolves to mergedAGENTS.mdcontent (verifiedhead/grepthrough the link)CLAUDE.mdas symlink (mode120000), not a regular blobsrc/untouched🤖 Generated with Claude Code