GeoAssets
CLAUDE.md2 starsChanged 18 days agoMITView on GitHub
GeoAssets operates under a Tri-Planar Dual-Loop Architecture backed by a Deterministic Oracle Substrate and Git Worktree Isolation: When ./scripts/verify-agent-worktree.sh returns a non-zero exit code, intercept the structured output and execute up to 3 self-healing iterations before escalating to the orchestrator:
In this repository12 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- code-gen-dagSkill
- outer-loop-dag-orchestratorSkill
- plan-gen-dagSkill
- solid-code-synthesizerSkill
- csharp-conventionsSkill
- jira-conventionsSkill
- observability-conventionsSkill
- outer-loop-dag-orchestratorSkill
- solid-code-synthesizerSkill
- ui-ux-pro-maxSkill
- solid-code-synthesizerSkill
The file
We split this CLAUDE.md into the rules it gives an agent
10 rules. About 0 are common, 4 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Never modify the root checkout directly during orchestrated runs, and never branch from, checkout, merge into, or rebase main.
- Very specific: line 17
Never run git commit or report task completion until the deterministic gatekeeper script passes with exit code 0:
- Very specific: line 23
Never bypass Directory.Build.props or BannedSymbols.txt by inserting #pragma warning disable, [SuppressMessage], or <NoWarn>.
- Very specific: line 27
When ./scripts/verify-agent-worktree.sh returns a non-zero exit code, intercept the structured output and execute up to 3 self-healing …
- Very specific: line 158
When an Agent (Claude Code Action or otherwise) opens a PR implementing a Jira ticket, the PR title must be prefixed with that ticket's …
- Distinctive: line 159
If a PR's changes span multiple tickets, prefix with the primary/parent ticket key
- Very specific: line 160
Commit subjects implementing a ticket end with (TICKET-KEY), e.g.
- Distinctive: line 164
All geometry follows RFC 7946 GeoJSON ([longitude, latitude] order)
- Distinctive: line 169
Do not add features, refactor, or clean up code beyond what is asked
- Distinctive: line 170
Do not add comments or docstrings to code you did not change
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
GeoAssets — Claude Instructions
Tri-Planar Multi-Agent Architecture & Operational Contract
GeoAssets operates under a Tri-Planar Dual-Loop Architecture backed by a Deterministic Oracle Substrate and Git Worktree Isolation:
- Outer Loop — Google Antigravity (DAG Orchestrator): Decomposes epics/tickets into a dependency-aware DAG, provisions isolated Git Worktrees via
scripts/agent-sandbox.sh, dispatches parallel work to inner-loop agents, runs the deterministic gatekeeper (scripts/verify-agent-worktree.sh), manages the self-healing retry loop (up to 3 cycles), and coordinates rebase/merge preparation. - Inner Loop (Deep Reasoning) — Claude Code (Specialist): Owns complex domain modeling, cross-cutting architectural refactoring, spatial/topology algorithms (NetTopologySuite / PostGIS), state-machine rules (
GeoAssets.Workflow), concurrency/observability propagation, and self-healing diagnostic resolution. - Inner Loop (Mechanical / QA) — GitHub Copilot (Worker): Owns high-velocity mechanical implementation, DTO/mapper scaffolding, xUnit test suites, mock/builder generation, and formatting compliance.
Mandatory Execution Rules for Claude Code
- Strict Git Worktree Isolation:
- Execute all file reads, edits, builds, and tests exclusively inside the assigned Git Worktree (
../worktrees/<task-id>provisioned byscripts/agent-sandbox.shor.claude/worktrees/<id>). - Never modify the root checkout directly during orchestrated runs, and never branch from, checkout, merge into, or rebase
main. Every worktree branch must originate fromorigin/develop.
- Execute all file reads, edits, builds, and tests exclusively inside the assigned Git Worktree (
- No Unverified Commits:
- Never run
git commitor report task completion until the deterministic gatekeeper script passes with exit code0:./scripts/verify-agent-worktree.sh - In interactive
/implement-ticketflows, leave changes unstaged and uncommitted after verification so the human reviewer can inspect the verified diff.
- Never run
- Zero Tolerance for Analyzer Suppression:
- Never bypass
Directory.Build.propsorBannedSymbols.txtby inserting#pragma warning disable,[SuppressMessage], or<NoWarn>. Fix the underlying architectural or code defect.
- Never bypass
Deterministic Self-Healing Loop (Compiler & Oracle Diagnostics)
When ./scripts/verify-agent-worktree.sh returns a non-zero exit code, intercept the structured output and execute up to 3 self-healing iterations before escalating to the orchestrator:
| Exit Code | Gate Stage | Typical Diagnostics | Required Self-Healing Resolution |
10 | dotnet format --verify-no-changes | WHITESPACE, IDE0055 | Run dotnet format GeoAssets.sln inside the worktree and re-verify that no unintended semantic changes were introduced. |
20 | dotnet build --no-incremental /warnaserror | AsyncFixer01–04, RS0030, MA*, CA* | Parse the diagnostic code and resolve without breaking domain invariants (see table below). |
30 | dotnet test --no-build (NetArchTest / Domain) | Onion layer violation or broken domain invariant | Refactor misplaced infrastructure dependencies back behind core/ interfaces (IAssetProvider, IServiceOrderRepository, etc.) and re-run. |
Common Analyzer Diagnostic Resolutions (Exit Code 20)
AsyncFixer01(Unnecessaryasync/await): Remove theasync/awaitstate-machine wrapper and return the underlyingTaskdirectly, unless theawaitis inside ausingblock,try/catch/finallyblock, or activeActivityspan scope (in which case elidingasyncwould dispose the resource or end the span before the task completes — restructure the scope instead).AsyncFixer02(Long-running or blocking operation insideasyncmethod): Replace synchronous blocking calls (.Result,.Wait(),.GetAwaiter().GetResult(),Thread.Sleep, synchronous EF Core/IO methods) with their true asynchronous counterparts (await ...ConfigureAwait(false)orawait Task.Delay(..., timeProvider, cancellationToken)).AsyncFixer03(async voidfire-and-forget): Convertasync voidmethods toasync Task(except framework-mandated Blazor/MAUI UI event handlers, which must wrap their body in an explicittry/catcherror boundary).RS0030(Banned Symbol fromBannedSymbols.txt):DateTime.Now/DateTime.UtcNow/DateTimeOffset.Now→ InjectSystem.TimeProvidervia primary/constructor DI and calltimeProvider.GetUtcNow().Task.Wait/Task.Result/Thread.Sleep→ Convert to non-blockingawaitwithCancellationToken.
MA0004/MA0040(Meziantou Concurrency & CancellationToken): Forward the caller'sCancellationTokento all downstream async calls and apply.ConfigureAwait(false)in non-UI library layers (core/,providers/,workflow/).
Stack
- .NET 10 / Blazor WebAssembly (Web) + MAUI (mobile/desktop)
- Razor Class Library:
GeoAssets.Shared(components, CSS, JS) - Core library:
GeoAssets.Core(models, services, interfaces) - Provider:
GeoAssets.Provider.PostgreSQL(EF Core + Npgsql + PostGIS — server-side only) - Map: Leaflet.js 1.9.4 + Leaflet-Geoman 2.18.3 (via CDN)
- Spatial: NetTopologySuite 2.5.0 + NTS.IO.GeoJSON4STJ 4.0.0
- Storage: Blazored.LocalStorage (Web), MAUI file APIs (MAUI)
Folder Structure
apps/— Blazor Web, ASP.NET Core Server, MAUI, Shared RCL, Identity EFCore, Commands Builtincore/— Core, Commands, Workflow, Identity, IpBilling, Infrastructure.Observabilityproviders/— PostgreSQL, Rest, Shapefile, WFS, WMS, Xlsxplugins/commands/— Plugin.Hydrology, Plugin.GeoJsonImportworkflow/— EFCore, Rest, Messaging.Kafka, Messaging.ServiceBus, Agentsipbilling/— IpBilling.EFCoreprojects/— Projects.EFCore, Projects.Restdeploy/— Docker Compose stacks (web,server,otel)docs/— Performance baselines and technical reportstools/— Benchmarks and developer tooling (GeoAssets.Bench.GetPageAsync)examples/— Console examples (Spatial, Topology, Workflow, MultiAgent)
Key File Paths
| Purpose | Path |
| Main page | apps/GeoAssets.Shared/Pages/Index.razor |
| Nav menu | apps/GeoAssets.Shared/Components/Layout/NavMenu.razor |
| Top bar | apps/GeoAssets.Shared/Components/Layout/TopBar.razor |
| Map component | apps/GeoAssets.Shared/Components/Map/MapContainer.razor |
| Context menu | apps/GeoAssets.Shared/Components/Map/MapContextMenu.razor |
| Draw toolbar | apps/GeoAssets.Shared/Components/Map/DrawToolbar.razor |
| Asset form | apps/GeoAssets.Shared/Components/Assets/AssetForm.razor |
| Asset list | apps/GeoAssets.Shared/Components/Assets/AssetList.razor |
| JS interop | apps/GeoAssets.Shared/wwwroot/js/geoassets.js |
| CSS | apps/GeoAssets.Shared/wwwroot/css/geoassets.css |
| Geometry models | core/GeoAssets.Core/Models/Geometry/ |
| Provider contract | core/GeoAssets.Core/Interfaces/IAssetProvider.cs |
| Active provider proxy | core/GeoAssets.Core/Providers/ActiveAssetProvider.cs |
| Provider pool | core/GeoAssets.Core/Services/ProviderPool.cs |
| Map interop interface | apps/GeoAssets.Shared/Interfaces/IMapInterop.cs |
| Map interop impl | apps/GeoAssets.Shared/Services/MapInteropService.cs |
| Web app | apps/GeoAssets.Web/ |
| Server app | apps/GeoAssets.Server/ |
| MAUI app | apps/GeoAssets.MAUI/ |
Architecture
- State:
IAssetProvider(ActiveAssetProviderproxying the active entry inIProviderPool) as source of truth; C# events (FeatureAdded/Updated/Deleted/CollectionChanged) as pub/sub - JS↔C# bridge:
DotNetObjectReference<object>stored in JS_maps[divId].dotNetRef; C# calls JS viaIJSRuntime.InvokeVoidAsync("GeoAssets.*") - JS→C# callbacks (all
[JSInvokable]onMapContainer):OnFeatureDrawnFromJs,OnFeatureEditedFromJs,OnFeatureClickedFromJs,OnFeatureContextMenuFromJs,OnViewportChangedFromJs - Auto-save:
AssetServicedebounces 500ms onCollectionChanged→IStorageService.SaveAsync
Geometry (NTS Integration)
GeoGeometrybase: abstractNtsGeometryproperty,GetBoundingBox()via NTS envelope, spatial predicates (Contains,Intersects,Within, etc.), measurements (Area,Length,Distance), derived geometries (Buffer,ConvexHull,Union, etc.),Centroid,FromNts()static factoryGeoPoint,GeoLineString,GeoPolygon: each builds NTS geometry lazily from coordinate arrays (SRID 4326, X=lon, Y=lat)- Serialization: coordinate arrays are the JSON source of truth — do not change this
- Spatial queries on
IAssetProvider:GetWithinAsync,GetIntersectingAsync,GetNearbyAsync,GetInBoundsAsync
Topology (directed graph)
TopoEdgemodel (Models/TopoEdge.cs):TargetId,Kind,Weight,Metadata; serialized as"topology"array on eachGeoFeatureGeoFeature.Topology:List<TopoEdge>(outgoing edges, persisted in JSON)TopoGraphstatic service (Services/TopoGraph.cs):GetNeighbors,GetDescendants,GetAncestors,TopologicalSort(Kahn's),FindPath(BFS),FindShortestPath(Dijkstra),GetConnectedComponents,HasCycles
PostgreSQL Provider
- Register with
builder.Services.AddGeoAssetsPostgres()(server-side hosts only — not Blazor WASM) IExternalProviderFactory(Core) — discoverable;ProviderPoolPanelrenders entries managed inIProviderPool- NTS bridge: write
feature.Geometry?.NtsGeometry→GeoEntityRow.Geom; readGeoGeometry.FromNts(row.Geom)→GeoFeature.Geometry - Key files:
Data/GeoAssetsDbContext.cs,Entities/GeoEntityRow.cs,Repositories/PostgresAssetProvider.cs,PostgresProviderFactory.cs
Context Menu
- Right-click on any map feature →
contextmenuingeoassets.js→OnFeatureContextMenuFromJs(id, clientX, clientY) MapContextMenu.razor:position:fixedat click coords, z-1500; backdrop div z-1400 closes on outside click<MapContextMenu>and<ConfirmDialog>rendered outside.map-areainIndex.razorsoposition:fixedworks correctly
CSS Design System (Catppuccin Mocha / Latte)
Dark (Mocha) Light (Latte)
--panel-bg: #1e1e2e --accent: #89b4fa --panel-bg: #eff1f5 --accent: #1e66f5
--panel-border: #313244 --danger: #f38ba8 --panel-border: #ccd0da --danger: #d20f39
--text-primary: #cdd6f4 --success: #a6e3a1 --text-primary: #4c4f69 --success: #40a02b
--text-secondary: #6c7086 --warning: #f9e2af --text-secondary: #6c6f85 --warning: #df8e1dLayout: sidebar (340px fixed) + content-column (flex:1, topbar + map-area). Overlays use position:absolute z-1000. Dialogs use position:fixed z-2000.
Bootstrap 5.3 (vendored at apps/GeoAssets.Shared/wwwroot/lib/bootstrap/, served to both hosts as _content/GeoAssets.Shared/lib/bootstrap/dist/css/bootstrap.min.css) is loaded before geoassets.css in both index.html files. geoassets.css re-maps Bootstrap's --bs-* custom properties under [data-bs-theme="dark"]/[data-bs-theme="light"] to the tokens above (--bs-primary → --accent, --bs-tertiary-bg/--bs-secondary-bg → --panel-bg, --bs-border-color → --panel-border, --bs-secondary-color → --text-secondary, --bs-success/--bs-danger → --success/--danger) so Bootstrap components render in-brand. Note: Bootstrap's own per-component vars (e.g. --bs-btn-bg, --bs-nav-pills-link-active-bg) are hardcoded in the stock CSS rather than derived from --bs-primary, so components that rely on Bootstrap's primary color (buttons, active nav-pills, dropdowns) still need a small scoped override when they're built — the token bridge only covers the base/reboot layer.
Also theme-scoped: --on-accent (text/icon color for content on top of --accent/--danger/--success — near-black in Mocha since those are light pastels, near-white in Latte since they're saturated) and --surface-tint-weak/--surface-tint/--surface-tint-strong (hover/subtle-background tints — white-alpha in Mocha, black-alpha in Latte). Use these instead of hardcoding a color that only looks right in one theme.
Theming (dark / light / system)
IThemeService(core/GeoAssets.Core/Theming/) +BlazorThemeService(apps/GeoAssets.Shared/Theming/) — same interface-in-Core/implementation-in-Shared split asICultureService/BlazorCultureService.Modeis the user's selection (ThemeMode.Light/Dark/System);SetModeAsyncpersists tolocalStorage["geoassets.theme"]and appliesdata-bs-themeon<html>via JS interop.- Flash prevention: a small inline
<script>in the<head>of bothindex.htmlfiles resolves the same stored-preference-or-prefers-color-schemelogic synchronously, before first paint — this is what actually prevents the flash, since Blazor WASM's boot is too slow to rely onApp.razor'sOnInitializedAsync. Keep that script's logic in sync withBlazorThemeService.ResolveThemeif either changes. App.razorcallsThemeService.InitAsync()(mirroringCultureService.InitAsync()) to sync the C#Mode/ResolvedThemestate to whatever the inline script already applied — it's a no-op re-application of the same value, not a second source of truth.- The topbar's theme toggle (
TopBar.razor) is a 3-button Bootstrapbtn-group(Light/System/Dark). - Only wired into
GeoAssets.Web(Program.cs+App.razor) —GeoAssets.MAUI'sMauiProgram.cs/WebApp.razordon't registerIThemeServiceorICultureService(MAUI's DI for these two remains a pre-existing gap;ICurrentUserAccessor/IAuthNavigationServicewere closed for MAUI by XD01-52's MSAL.NET wiring — seeEntraCiamMauiAuthenticationProvider). The FOUC-prevention inline script is duplicated into MAUI'sindex.htmlanyway since it's plain JS with no DI dependency.
Branching & Release Policy
developis the sole integration branch for all agent work — manual ticket implementation,/implement-ticket,/ship-ticket, and/orchestrate-ticketsalike. Every new branch must be created fromorigin/developexplicitly (fetch it, branch from it) — never from whatever branch happens to already be checked out, since this repo's working directory is sometimes shared across concurrent sessions and the current branch is not a reliable signal of intent.mainmust never be branched from, merged into, merged from, or rebased by any agent or orchestration workflow, under any circumstance — including when resolving a conflict, "catching main up," or any other seemingly-helpful cleanup. The only waymainchanges is the user explicitly instructing it in an interactive session, by name, in that session. No skill or command in this repo should referencemainas a base or target branch; if one is found to, that's a bug in the skill, not a precedent to follow.
Pull Requests & Commits
- When an Agent (Claude Code Action or otherwise) opens a PR implementing a Jira ticket, the PR title must be prefixed with that ticket's key, e.g.
XD01-8: Add REST-backed IServiceOrderRepository client - If a PR's changes span multiple tickets, prefix with the primary/parent ticket key
- Commit subjects implementing a ticket end with
(TICKET-KEY), e.g.feat(workflow): round-trip a concurrency version token through IServiceOrderRepository (XD01-26)— the GitHub for Atlassian app (connected to this repo) scans commits/branches/PR titles for this pattern to auto-link them under the ticket's Development panel; it also makesgit log --grepreliable for human traceability
Conventions
- All geometry follows RFC 7946 GeoJSON ([longitude, latitude] order)
- Razor components:
EventCallback<T>up,[Parameter]down - Every Razor component/page ships as a markup-only
.razorfile plus a.razor.cscode-behind partial class, regardless of the component's size — seeapps/GeoAssets.MAUI/WebApp.razor/WebApp.razor.csfor the target shape (tracked by XD01-101). Exception:apps/GeoAssets.MAUI/Pages/MauiLogin.razorstays single-file.GeoAssets.MAUI's Razor toolchain (Sdk="Microsoft.NET.Sdk"+UseMaui=true, viaMicrosoft.AspNetCore.Components.WebView.Maui) doesn't reliably wire markup that reads a.razor.cs-declared field back to that field — confirmed by a field used only in markup (disabled="@_signingIn") triggering a false "unused" warning once moved to code-behind, a warning that does not reproduce with the identical pattern inGeoAssets.Shared(Microsoft.NET.Sdk.Razor) orGeoAssets.Web(Microsoft.NET.Sdk.BlazorWebAssembly) — evidence of degraded codegen specific to this project, not a Roslyn quirk. A[Inject]-in-code-behind workaround does fix the@inject-property-visibility half of the problem, but the markup-binding warning persists and couldn't be runtime-verified (no MAUI simulator/device in this environment), so the split was not applied rather than risk a silent regression in an auth-critical flow. See XD01-121 for the investigation. - Bootstrap is allowed and is the base for component styling in
GeoAssets.Shared(used by both Web and MAUI); layer bespoke CSS ingeoassets.csson top for anything Bootstrap doesn't cover — don't hand-roll styles Bootstrap already provides - The only loaded JS file is
geoassets.js(IIFE);mapInterop.jsanddrawInterop.jsare legacy drafts — do not reference them - Do not add features, refactor, or clean up code beyond what is asked
- Do not add comments or docstrings to code you did not change
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

