feat: support AGENTS.md standard by splitting CLAUDE.md#231
Draft
ryzizub wants to merge 4 commits into
Draft
Conversation
Move platform-agnostic conventions to AGENTS.md; CLAUDE.md now imports it via @AGENTS.md and keeps only the Claude-specific Hooks section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Neutralize Claude-specific language in AGENTS.md (recommendation hook scoped to Claude Code, clear-context handoff no longer names /clear) and drop the redundant other-harnesses sentence. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
markdownlint MD041 requires an H1 as the first line, but CLAUDE.md must lead with the @AGENTS.md import for the memory import to resolve. Disable MD041 for the file, matching the repo's PR-template precedent. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Draft
6 tasks
Mirror the Flutter plugin's layout overview with a commented directory tree covering agents, hooks, config, and skills. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
ryzizub
marked this pull request as ready for review
July 24, 2026 15:33
ryzizub
marked this pull request as draft
July 24, 2026 15:36
ryzizub
marked this pull request as ready for review
July 24, 2026 15:38
ryzizub
marked this pull request as draft
July 27, 2026 09:04
marcossevilla
approved these changes
Jul 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adopt the AGENTS.md open standard (part of multi-harness epic #66).
Platform-agnostic conventions — philosophy, repository structure, tech-agnostic design, workflow, output directories, key conventions, and guidance — now live in a new root
AGENTS.mdthat tier-2 harnesses (Codex, Gemini CLI, OpenCode) read directly.CLAUDE.mdbecomes a single@AGENTS.mdimport followed only by the Claude-Code-specific## Hookssection, so Claude Code receives the same conventions with nothing duplicated.Why this approach: Claude Code does not read
AGENTS.mdnatively (mid-2026), butCLAUDE.mdsupports@pathimports. This is Anthropic's documented pattern for the split: single source of truth, zero drift, cross-platform (no symlink, so no Windows admin requirement). Only the Hooks section is Claude-Code-specific and stays behind; everything else moved intact.Also in this PR:
AGENTS.md— a commented directory tree coveringagents/,hooks/,config/, andskills/, mirroring the Flutter plugin's layout overview./clear, and a note clarifies the/nameforms are canonical skill names whose invocation varies per harness.CLAUDE.md: its first line must be the@AGENTS.mdimport rather than an H1 heading, so MD041 is disabled for the file via an inline directive, matching the repo's PR-template precedent.Type of Change
feat)fix)refactor)docs)ci)chore)Test plan
AGENTS.mdexists;CLAUDE.md's first line is exactly@AGENTS.md; the Hooks section stays inCLAUDE.md; no agnostic section is duplicated across the two files; the moved sections are present inAGENTS.md; no hook mechanics leaked intoAGENTS.md.markdownlint-cli2andcspellpass on both files with the repo config (CI green).@AGENTS.md, and confirm the imported conventions (e.g. Key Conventions) appear in context.Follow-ups (out of scope here)
AGENTS.mdexists andCLAUDE.md's first line is@AGENTS.md. A rename or typo would otherwise silently empty Claude Code's context whileclaude plugin validatestays green./reviewon Wingspan itself now reads a slimCLAUDE.mdthrough the Read tool, since the Read tool does not expand the@AGENTS.mdimport. Teaching those agents to also read a target repo'sAGENTS.mdbelongs to feat: Phase 0 portability prep for open-standard support #228.README.mdandCONTRIBUTING.mdstill frame Wingspan as a Claude Code plugin and do not mention the memory-file import. A later pass should align them.Closes #225.