Rewrite AGENTS.md as an architecture guide and add CLAUDE.md - #401
Open
jasonleenaylor wants to merge 2 commits into
Open
Rewrite AGENTS.md as an architecture guide and add CLAUDE.md#401jasonleenaylor wants to merge 2 commits into
jasonleenaylor wants to merge 2 commits into
Conversation
Replaces the onboarding log with guidance an agent can act on. The old file recorded that dotnet build and dotnet test had FAILED and attributed both to GitVersion, which sent readers down a dead end; it also inventoried the repo root and top-level directories, which the repository already states. What the file now carries that could not be discovered cheaply: - Editing a Generated*.cs file does not fail. Regeneration is skipped while the file is newer than MasterLCModel.xml, so the edit compiles locally and the tests pass while CI builds different code from the XML. The files are gitignored, so it can never be committed. A fresh worktree has none of them until the first build, and a stale one left by a branch switch is compiled as it stands. - Per-rule consequences instead of one blanket claim, since rule 1 neither breaks the build nor corrupts data. - The FLEx Bridge metadata cache obligation from WARNING 4. - Worktrees need a named branch, because GitVersion cannot version a detached HEAD, and removal needs the directory left first. - ParallelizeAssembly=false is required because ICU and the writing system subsystems hold shared state. - Windows builds need the C++ tools whether or not the IDE is used, because code generation preprocesses the IDL with cl.exe. Corrects the IOC description: the container is Microsoft.Extensions.DependencyInjection since #393, not StructureMap. Drops the transcribed SDK version, target frameworks and CI command list in favour of pointing at global.json, the csproj files and ci-cd.yml, which is where they are actually defined. The -m:1 rule and the instruction to report failing instructions are carried forward unchanged. CLAUDE.md imports AGENTS.md and points Claude-only procedures at .claude/skills/, matching FieldWorks and interlinearizer-extension. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The rewrite dropped five accurate statements about GitVersion.MsBuild: that every project uses it, that it needs real git metadata, that CI checks out with fetch-depth 0, that GitVersion.yml configures it, and the error string it fails with. Those were correct and worth keeping. Restores them as a Versioning section, with the part the original lacked: the two checkouts that break it. A shallow clone reports that it cannot find the commit and asks for git fetch --unshallow; a detached HEAD reports that it cannot determine a version without a branch name. Both arrive through MSBuild as MSB3073 with gitversion.dll exiting 1, so the error alone does not distinguish them. Verified by cloning this repository with --depth 1 and running gitversion against it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
jasonleenaylor
force-pushed
the
piece3/agent-skills
branch
from
August 31, 2026 16:06
ca63ca1 to
925a3a7
Compare
jasonleenaylor
force-pushed
the
piece2/agents-md
branch
from
August 31, 2026 16:06
49b0c68 to
65b9ffc
Compare
jasonleenaylor
marked this pull request as ready for review
August 31, 2026 22:20
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.
Rewrites
AGENTS.mdas an architecture guide and addsCLAUDE.md.Stacked on #400, which is stacked on #364. Review those first; this PR targets #400's branch.
Why rewrite rather than amend
The old file was an onboarding log rather than guidance. It inventoried the repository root
and the top-level directories, which the repository already states, and it transcribed the
SDK version, the target frameworks and the CI command sequence, which then drifted from
global.json, the.csprojfiles andci-cd.yml. The architecture — the generationpipeline, the model schema, the persistence design — was not described at all.
What the file now carries that cannot be discovered cheaply
Generated*.csfile does not fail. Regeneration is skipped while the file isnewer than
MasterLCModel.xml, so the edit compiles into the local build and the testspass, while CI generates from the XML into a fresh tree and builds different code. The files
are gitignored, so the edit can never be committed. A fresh clone or worktree has none of
them until the first build, and a stale one left by a branch switch is compiled as it stands.
rule 4 breaks the build; rule 1 does neither, which is what makes it dangerous.
WARNING 4.plain
git worktree removerefuses.-p:ParallelizeAssembly=falseis not optional: ICU and the writing system subsystemshold shared state.
generation preprocesses the IDL with
cl.exe, located viavswhere..csfile from another branch produceserrors that look like your change broke something.
Corrections
The IOC section described StructureMap. Since #393 the container is
Microsoft.Extensions.DependencyInjection, wrapped inMicrosoftServiceLocatorsoGetInstance<T>()still works.Facts now pointed at rather than copied
The SDK floor, target frameworks and CI sequence point at
global.json, the.csprojfilesand
.github/workflows/ci-cd.yml. The transcriptions are what went stale; the definitionscannot.
The
-m:1rule from #364 and the instruction to report failing instructions are carriedforward unchanged. The existing GitVersion guidance is also carried forward, with the two
checkouts that break it named alongside it.
Checked against source
The flid arithmetic (
LexSenseTags.kflidDefinitionis5016005),LexDbatomic underLangProject,Stylesas anStStylecollection, all sevenOverrides*.csnames, the ninegenerated files,
CheckWinFormsin three projects, and every path in the layout tree.CLAUDE.mdimportsAGENTS.mdand points Claude-only procedures at.claude/skills/,matching FieldWorks and interlinearizer-extension.
Docs only, so no build or test run is claimed.
This change is