docs: refresh per-plugin AGENTS.md for monorepo context#128
Merged
Conversation
Tracks issue #125. PRD specifies a uniform eight-section AGENTS.md template for every Claude Code Plugin, with CLAUDE.md as a symlink so the agent-guidance file is discoverable under either name. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Rewrites the agent-guidance file for every Claude Code Plugin in the monorepo voice. Each Plugin gets an AGENTS.md (canonical) plus a CLAUDE.md symlink, mirroring the root convention. - All four files share the eight-section template from the PRD: What this Plugin is / Where to start / Commands / Layout / Plugin doctrines / External dependencies / Do not add / Plugin ADRs. - Root-mirroring content (pnpm scripts, SemVer policy, Conventional Commits scope, tag scheme, generic code conventions, cross-platform requirement) is dropped — the root AGENTS.md owns it. - Obsolete identifiers removed: unic-claude-code-format, unic-claude-code-<service>, spec-NN scopes, the bare "spec 02" reference. - unic-archon-dlc gets its first AGENTS.md — Setup idempotence, Slug-scoped Sessions, triage-owned HANDOFF.md/ROADMAP.md, the marker-managed Agent skills block, and the dogfooding note all live in the new file. - CLAUDE.md is a relative symlink to AGENTS.md in every Plugin. Tracks #125. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR implements issue #125 by refreshing per-plugin agent guidance so each Claude Code plugin directory has monorepo-accurate, plugin-scoped instructions (with AGENTS.md as canonical guidance and CLAUDE.md intended as a symlink for compatibility).
Changes:
- Adds a PRD describing a uniform 8-section template and symlink convention for plugin agent-guidance docs.
- Introduces new per-plugin
AGENTS.mdfiles forauto-format,pr-review,unic-confluence, andunic-archon-dlcfollowing that template. - Documents plugin-specific doctrines, layout, commands, and ADR links while removing root-mirroring guidance from plugin-level docs.
Reviewed changes
Copilot reviewed 9 out of 12 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/issues/plugin-claude-md-monorepo-refresh/PRD.md | Adds the PRD/spec for the per-plugin guidance refresh and file naming/template decisions. |
| apps/claude-code/auto-format/AGENTS.md | Adds plugin-scoped agent guidance for auto-format aligned to the new template. |
| apps/claude-code/pr-review/AGENTS.md | Adds plugin-scoped agent guidance for pr-review aligned to the new template. |
| apps/claude-code/unic-confluence/AGENTS.md | Adds plugin-scoped agent guidance for unic-confluence aligned to the new template. |
| apps/claude-code/unic-archon-dlc/AGENTS.md | Adds first-time plugin-scoped agent guidance for unic-archon-dlc aligned to the new template. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Address Copilot feedback on PR #128: - Fix `pnpm tag` description in all four plugin AGENTS.md to reflect the real `<plugin-name>@<version>` tag scheme (not `v<version>`). - Remove `pnpm typecheck` from `pr-review/AGENTS.md` — no such script in package.json and no tsconfig in the plugin. - Add the missing `pnpm confluence` wrapper to `unic-confluence/AGENTS.md` and move `pnpm test`/`pnpm typecheck` into its plugin-specific list for consistency with the other plugins. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Address three accuracy issues surfaced by the post-Copilot multi-agent review of PR #128: - pr-review/AGENTS.md: the four-state Review Thread classification was listed as `addressed, unaddressed, outdated, new-finding`. Real taxonomy per ADR-0005 and CONTEXT.md is `addressed, disputed, pending, obsolete`. - unic-confluence/AGENTS.md: External dependencies omitted `marked`, the only runtime npm dep. ADR-0010 (already cited) exists precisely because of this dep, so the omission was self-contradictory. - unic-archon-dlc/AGENTS.md: Layout omitted `.archon/` (referenced by the doctrines section as the install target for workflow YAMLs) and `CONTEXT.md` (the file the description points readers at). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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.
Summary
Implements #125. Rewrites the agent-guidance file for every Claude Code Plugin in the monorepo voice, so a contributor opening a plugin directory gets context that matches the post-migration reality.
AGENTS.md(canonical) + aCLAUDE.mdrelative symlink, mirroring the root pattern.unic-archon-dlcgets its first agent-guidance file. Its Setup-as-sole-entry-point, Slug-scoped Sessions, triage-ownedHANDOFF.md/ROADMAP.md, marker-managed## Agent skillsblock, and dogfooding note all live in the new file.unic-claude-code-format,unic-claude-code-<service>,spec-NNscopes, the bare "spec 02" reference inpr-review.No code changes; no
plugin.jsontouched; no version bumps.verify:changelogis PR-only and skips docs-only PRs by design (ADR-0017).Why this PR
The per-plugin
CLAUDE.mdfiles predated the monorepo migration and still opened with "This file provides guidance to Claude Code when working in this repository" — duplicating root content and leaving stale, sometimes contradictory guidance behind. The backlog item indocs/plans/README.mdto refresh them was deferred during the plugin-migration specs and not picked back up until this PRD.Test plan
AGENTS.mdfiles follows the eight-section template.apps/claude-code/<plugin>/CLAUDE.mdis a symlink (120000mode in the diff), not a regular file.unic-claude-code-format,unic-claude-code-<service>, orspec-NN.docs/adr/.pnpm checkandpnpm formatpass (verified locally).🤖 Generated with Claude Code