Skip to content

Consolidate agent documentation into AGENTS.md, skills, and docs - #654

Merged
dennisdoomen merged 7 commits into
developfrom
dennisdoomen-consolidate-agent-docs
Aug 24, 2026
Merged

Consolidate agent documentation into AGENTS.md, skills, and docs#654
dennisdoomen merged 7 commits into
developfrom
dennisdoomen-consolidate-agent-docs

Conversation

@dennisdoomen

@dennisdoomendennisdoomen commented Aug 23, 2026•
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

This PR depends on #653 (the GitFlow/versioning reversion) and should merge after it.

The repo had three always-on instruction files: AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md. It also had a docs/agents/ reference folder. These overlapped. They had already drifted apart. They cost context on every session, no matter the task.

.github/copilot-instructions.md was especially stale and wrong. It said every source file needs a license header. AGENTS.md rule 6 says the opposite.

This PR splits the content into three layers. Each layer has one job:

  • AGENTS.md — always-on rules. Cut from about 9 KB to about 110 lines. Contains a documentation-map section, a short versioning table, one-line critical rules, a repository map, and a routing table.
  • .agents/skills/<skill>/SKILL.md — on-demand procedures. Loaded only when the task matches. Seven skills: creating-a-pr, adding-a-tool-wrapper, marking-experimental-apis, editing-ci-workflows, cutting-a-release, adding-a-migration-step (for fallout-migrate step recipes; not named in the original plan, but it fits the same pattern as the other named skills), and plain-english (the writing-style rules, vendored so every contributor and tool gets them, not just one person's machine). Copilot CLI finds this folder on its own. Claude Code does not, so CLAUDE.md now lists each skill by its path.
  • docs/ and docs/adr/ — reference material and maintainer runbooks. Unchanged in kind, just repointed where needed.

docs/agents/ and .github/copilot-instructions.md are deleted. Nothing is lost. Every rule that lived there now has exactly one new home, listed below.

Where things moved

  • docs/agents/release-and-versioning.md moved into creating-a-pr and cutting-a-release. docs/branching-and-release.md also gained the branch-protection profile and the nuget.org first-publish gotcha from it.
  • docs/agents/conventions.md split into adding-a-tool-wrapper, marking-experimental-apis, editing-ci-workflows, AGENTS.md, and CONTRIBUTING.md (test-writing conventions). The glossary moved to a new docs/glossary.md. General "what not to do" rules (don't reintroduce source/, don't bypass Directory.Packages.props, and so on) moved into docs/architecture.md's existing build-conventions section. We did not put them in a new file, since that would just create the same problem again under a different name.
  • docs/agents/repository-layout.md — the layout table moved directly into AGENTS.md. It is short and useful in every session.
  • docs/agents/issue-and-pr-style.md moved into the creating-a-pr skill's reference files.

Also fixed

  • The stale docs/agents/repository-layout.md link in Fallout.Persistence.Solution.csproj that started this whole review.
  • 11 more old links to docs/agents/, found by searching the whole repo: all five ADRs' References sections, docs/dependencies.md, docs/experimental-apis.md, docs/obsolete_apis.md, CONTRIBUTING.md, .claude/agents/story-writer.md, .claude/commands/new-issue.md, .claude/skills/restructure-pr-commits/SKILL.md, .github/PULL_REQUEST_TEMPLATE.md, and .github/release.yml.
  • A new plain-English writing rule in AGENTS.md (critical rule 8). Many contributors read English as a second language. The rule asks for plain words, one idea per sentence, no idioms, glossed cross-references, and jargon linked to the glossary. The full rules now live in the plain-english skill; AGENTS.md and creating-a-pr both link to it instead of repeating it.
  • An ADR index bug from Revert to classic GitFlow; stay on semver 10.x until a breaking change is needed #653 (the GitFlow/versioning PR): the GitFlow ADR was labeled "0005" instead of "0009" in one table row.

The ADRs' own "Documentation churn" lines are left as they are. Those describe past churn. They are history, not live links.

Not in scope here

Whether csharp-guidelines (another personal skill) should also live in the repo. That is an open question for later, not this PR.

Verification

  • ./build.ps1 Compile succeeds in this worktree.
  • A repo-wide search for docs/agents/ finds nothing left, except one ADR historical note we left on purpose.
  • docs/agents/ and .github/copilot-instructions.md no longer exist.

🤖 Generated with Claude Code

@dennisdoomendennisdoomen added documentation Improvements or additions to documentation target/vCurrent Targets the current version labels Aug 23, 2026
@dennisdoomen
dennisdoomen marked this pull request as ready for review August 23, 2026 19:25
@dennisdoomen
dennisdoomen requested a review from a team as a code ownerAugust 23, 2026 19:25
@dennisdoomen
dennisdoomenforce-pushed the dennisdoomen-consolidate-agent-docs branch from b4ea14a to 82d5bfbCompareAugust 23, 2026 19:25
ChrisonSimtian
ChrisonSimtian approved these changes Aug 23, 2026
View reviewed changes

@ChrisonSimtianChrisonSimtian left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see comment about writing style

Comment thread.agents/skills/adding-a-migration-step/SKILL.md
Comment thread.claude/agents/story-writer.md Outdated
Base automatically changed from dennisdoomen-gitflow-adoption-impact to mainAugust 24, 2026 05:51
@dennisdoomen@claude
Add .agents/skills/ tree and docs/glossary.md
4601ca8
On-demand procedures for the five tasks the plan calls out (creating a
PR, adding a tool wrapper, marking an API experimental or obsolete,
editing CI workflows, cutting a release) plus a sixth for the
fallout-migrate step recipe, which the plan's skill list didn't name
but is the same kind of narrow, infrequent procedure.
Each SKILL.md stays short, with a references/ folder for anything
longer (the full PR-creation policy, the CI-trigger invariant list,
the writing-style guide).
The glossary of repo jargon (shim, sentinel, canonical type, ...) moves
to its own docs/glossary.md - it's reference material, not a rule or a
procedure, so it doesn't fit AGENTS.md or a skill.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@dennisdoomen
dennisdoomenforce-pushed the dennisdoomen-consolidate-agent-docs branch from 82d5bfb to 7541d30CompareAugust 24, 2026 08:13
dennisdoomenand others added 4 commits August 24, 2026 10:28
@dennisdoomen@claude
Rewrite AGENTS.md around the new skills tree and add a plain-English …
c1ebe4a
…rule
Cuts AGENTS.md from ~9 KB of always-on prose to a short brief: a
documentation-map contract (ADR = decision, docs/ = reference and
runbooks, .agents/skills/ = on-demand procedure, this file = the
always-on rules), one line per critical rule with the rationale moved
to the linked skill or doc, the repository-layout table lifted in from
the now-deleted docs/agents/repository-layout.md, and a routing table
replacing the old 'Where to look next' prose dump.
Adds a new critical rule requiring plain, terse English in chat
responses, commit messages, PR/issue descriptions, and code comments
alike - not just at PR-creation time, since it's foundational to how
any AI should write in this repo. The longer version with more
PR-writing examples lives in the creating-a-pr skill's
references/writing-style.md and matches this rule; neither should
drift from the other.
CLAUDE.md now lists each skill under .agents/skills/ by path, since
Claude Code doesn't auto-discover that folder the way Copilot CLI does.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@dennisdoomen@claude
Delete docs/agents/ now that its content has a new home
f746a95
Its four files are folded into AGENTS.md, the new .agents/skills/
tree, and docs/branching-and-release.md / docs/glossary.md - see the
prior two commits. Nothing here duplicated content that survives
elsewhere unchanged; every rule ends up in exactly one place.
.github/copilot-instructions.md, the other stale always-on file the
plan calls out, was already absent from this branch.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@dennisdoomen@claude
Repoint stray docs/agents references and absorb their leftover content
ec47125
Fixes every remaining inbound link to the deleted docs/agents/ folder:
ADRs' References sections, docs/dependencies.md, docs/experimental-apis.md,
docs/obsolete_apis.md, CONTRIBUTING.md, the .claude/ agent/command/skill
files, .github/PULL_REQUEST_TEMPLATE.md, .github/release.yml, and the
Fallout.Persistence.Solution.csproj comment that pointed at a
'persistence-ring layering' section repository-layout.md never had
(the stale reference the plan's evidence called out).
'Documentation churn' lines inside ADR bodies are left untouched - the
plan treats those as historical record, not live links.
Also merges docs/agents/release-and-versioning.md's content that
wasn't already duplicated elsewhere into its one new home:
- The detailed branch-protection profile (required checks, linear
history, CODEOWNER review, ...) and the first-publish-to-nuget.org
gotcha move into docs/branching-and-release.md, alongside the
GitVersion transitional-helper note.
- docs/architecture.md's Build conventions gain the 'don't reintroduce
source/ or images/' and 'don't bypass Directory.Packages.props /
Directory.Build.targets' rules that used to live in
docs/agents/conventions.md's what-not-to-do list.
- CONTRIBUTING.md's testing bullet gains the AV1600 naming, Specs
suffix, AAA-comment, and disk-fixture conventions from the same
file's 'conventions worth respecting' list, and its Tool wrappers
section is replaced by a pointer to the adding-a-tool-wrapper skill
(which now owns that recipe).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@dennisdoomen
Vendor the plain-english skill into the repo
dc8df69
This resolves the open question from the PR description: the
plain-english skill now lives in the repo, not only on one person's
machine, so every contributor and AI tool gets it.
- New .agents/skills/plain-english/SKILL.md, adapted to link this
repo's docs/glossary.md directly.
- AGENTS.md rule 8 and the routing table now point to it as the
source of the writing-style rule.
- creating-a-pr/references/writing-style.md no longer repeats the
same rules inline -- it links to plain-english instead and keeps
only the PR/issue-shape content that's specific to it.
- CLAUDE.md lists the new skill by path, like the other six.
@dennisdoomen
dennisdoomenforce-pushed the dennisdoomen-consolidate-agent-docs branch from 7541d30 to dc8df69CompareAugust 24, 2026 08:28
@dennisdoomen
Fold issue/PR writing-style guidance into the plain-english skill
14b33ba
writing-style.md duplicated principles already covered by the
plain-english skill (terse, lead with the point, cut filler) and lived
under creating-a-pr even though its actual topic is writing style, not
PR-creation mechanics. Per the docs map's one-topic-one-home rule, folds
its guidance directly into plain-english/SKILL.md as one document: the
existing rules, then an 'Extra rules for issues and PRs' section with
the Problem/Outcome/Acceptance-criteria and PR templates and the
anti-patterns table.
Updates every reference to the old file: creating-a-pr/SKILL.md,
AGENTS.md, the PR template, the new-issue command, and the
story-writer agent.
@dennisdoomen
dennisdoomenforce-pushed the dennisdoomen-consolidate-agent-docs branch from ef7ecc8 to 14b33baCompareAugust 24, 2026 08:38
@dennisdoomen
Fold the repo-jargon glossary into the plain-english skill
61c6828
docs/glossary.md only existed to back the plain-english skill's
jargon-glossing rule (rule 6) and had no other consumer. Moves its
term table into plain-english/SKILL.md as a Glossary section instead
of a separate doc, and repoints rule 6 and the two AGENTS.md
references at it.
@dennisdoomen
dennisdoomen merged commit 611075a into mainAug 24, 2026
8 checks passed
@dennisdoomen
dennisdoomen deleted the dennisdoomen-consolidate-agent-docs branch August 24, 2026 09:01
@dennisdoomendennisdoomen mentioned this pull request Aug 25, 2026
Open
phmatray added a commit to Atypical-Consulting/Fallout that referenced this pull request Sep 3, 2026
@phmatray@claude
Merge upstream/main into main
d76b4cd
Sync the fork with Fallout-build/Fallout. The two lines had diverged in
both directions: 80 commits here, 41 upstream, 35 of ours already
patch-equivalent there.
All 14 conflicts resolved in upstream's favour, because upstream had
already absorbed this fork's work and carried it forward:
- docs/agents/*.md consolidated into AGENTS.md and .agents/skills (Fallout-build#654);
the four files are deleted here.
- The docs site moved to docs/website/, and docs/migration to
docs/Migration. docs/badge.md dropped as an identical, unreferenced
duplicate of docs/website/badge.md.
- Calendar versioning is reverted to classic GitFlow on semver 10.x
(ADR-0009 replaces ADR-0004): develop is the trunk and preview lane,
version.json moves to 10.5.0-preview.{height}, and release.yml,
CONTRIBUTING.md and the publish/prune workflows follow.
- prune-preview-packages.yml takes upstream's copy, which is this fork's
workflow already updated for ADR-0009.
The resulting tree is identical to upstream/main.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VyD69qYha8hBMuja7opyj2
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ChrisonSimtianChrisonSimtianChrisonSimtian approved these changes

Assignees

No one assigned

Labels

documentationImprovements or additions to documentationtarget/vCurrentTargets the current version

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@dennisdoomen@ChrisonSimtian