Skip to content

feat: support AGENTS.md standard by splitting CLAUDE.md#231

Draft
ryzizub wants to merge 4 commits into
mainfrom
claude/wingspan-issue-225-8ff4a6
Draft

feat: support AGENTS.md standard by splitting CLAUDE.md#231
ryzizub wants to merge 4 commits into
mainfrom
claude/wingspan-issue-225-8ff4a6

Conversation

@ryzizub

@ryzizub ryzizub commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

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.md that tier-2 harnesses (Codex, Gemini CLI, OpenCode) read directly. CLAUDE.md becomes a single @AGENTS.md import followed only by the Claude-Code-specific ## Hooks section, so Claude Code receives the same conventions with nothing duplicated.

Why this approach: Claude Code does not read AGENTS.md natively (mid-2026), but CLAUDE.md supports @path imports. 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:

  • Repository Structure section added to AGENTS.md — a commented directory tree covering agents/, hooks/, config/, and skills/, mirroring the Flutter plugin's layout overview.
  • Light-touch neutralization so the portable file does not overpromise tier-2 behavior: the auto-recommendation sentence is scoped to Claude Code, the clear-context handoff no longer names /clear, and a note clarifies the /name forms are canonical skill names whose invocation varies per harness.
  • markdownlint MD041 exemption for CLAUDE.md: its first line must be the @AGENTS.md import 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

  • New feature (feat)
  • Bug fix (fix)
  • Code refactor (refactor)
  • Documentation (docs)
  • CI change (ci)
  • Chore (chore)

Test plan

  • Structural gate passes: AGENTS.md exists; CLAUDE.md's first line is exactly @AGENTS.md; the Hooks section stays in CLAUDE.md; no agnostic section is duplicated across the two files; the moved sections are present in AGENTS.md; no hook mechanics leaked into AGENTS.md.
  • markdownlint-cli2 and cspell pass on both files with the repo config (CI green).
  • Manual: launch a fresh Claude Code session at the repo root, confirm no unresolved-import warning for @AGENTS.md, and confirm the imported conventions (e.g. Key Conventions) appear in context.
  • Tier-2 (Codex / Gemini CLI / OpenCode) support is structurally verified, not behaviorally tested — no runner is available in this environment.

Follow-ups (out of scope here)

  • Import guardrail: add a small CI/shell assertion that AGENTS.md exists and CLAUDE.md's first line is @AGENTS.md. A rename or typo would otherwise silently empty Claude Code's context while claude plugin validate stays green.
  • Epic feat: Phase 0 portability prep for open-standard support #228 ripple: the ~18 agent/skill references that read "the project's CLAUDE.md" of a downstream repo were intentionally left unchanged. As a side effect, running /review on Wingspan itself now reads a slim CLAUDE.md through the Read tool, since the Read tool does not expand the @AGENTS.md import. Teaching those agents to also read a target repo's AGENTS.md belongs to feat: Phase 0 portability prep for open-standard support #228.
  • Narrative consistency (under feat: add support for other AI platforms other than Claude Code #66): README.md and CONTRIBUTING.md still frame Wingspan as a Claude Code plugin and do not mention the memory-file import. A later pass should align them.

Closes #225.

ryzizub and others added 3 commits July 24, 2026 15:13
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>
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
ryzizub marked this pull request as ready for review July 24, 2026 15:33
@ryzizub
ryzizub requested a review from a team as a code owner July 24, 2026 15:33
@ryzizub ryzizub changed the title feat: support AGENTS.md standard feat: support AGENTS.md standard by splitting CLAUDE.md Jul 24, 2026
@ryzizub
ryzizub marked this pull request as draft July 24, 2026 15:36
@ryzizub
ryzizub marked this pull request as ready for review July 24, 2026 15:38
@ryzizub
ryzizub marked this pull request as draft July 27, 2026 09:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: support AGENTS standard

2 participants