agentleFS
matt82198matt82198/aesop/ui/CLAUDE.md

aesop / ui

CLAUDE.md2 starsChanged 31 days agoMITView on GitHub

A fresh scaffold has empty state, so a stranger sees a dead shell. --demo serves a seeded, self-identifying fleet snapshot instead — no API key, no gh auth, no prior runs needed: The page carries a fixed DEMO DATA banner and /api/state returns "demo": true — seeded data can never be mistaken for a live fleet (honesty is the project's brand). Default mode (no flag) is byte-identical to before. serve.py (~65 lines): Composition layer. Calls config.reload(), csrf.init(), sse.reset_state(), re-exports their…

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Write: All tracker CRUD routes through state_store.write_api.WriteAPI, which appends events to SQLite and renders views atomically via …

    line 120
  2. Very specific:

    Read: load_tracker() reads the materialized tracker.json (git-ignored, gitignored, rebuildable — NOT committed).

    line 121
  3. Very specific:

    Chart accessibility (FINDING 2): All SVG charts already had role="img" + aria-label naming.

    line 169
  4. Very specific:

    All routes resolve to identical handlers with same status/headers/body.

    line 205

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

ui/ — Web dashboard (self-contained domain guide)

Purpose: Local observability dashboard. Python backend serves a React+Vite frontend on a configurable port via Server-Sent Events (realtime updates), with CSRF + session protection and event-sourced state. All file I/O uses explicit encoding="utf-8".

Try it in 30 seconds (no API key)

A fresh scaffold has empty state, so a stranger sees a dead shell. --demo serves a seeded, self-identifying fleet snapshot instead — no API key, no gh auth, no prior runs needed:

git clone https://github.com/matt82198/aesop.git && cd aesop
python ui/serve.py --demo        # then open http://127.0.0.1:8770
# or via the CLI: npx @matt82198/aesop dash --demo

The page carries a fixed DEMO DATA banner and /api/state returns "demo": true — seeded data can never be mistaken for a live fleet (honesty is the project's brand). Default mode (no flag) is byte-identical to before.

Universal rules (every domain)

  • Feature branch only, never main; every push gated by python tools/secret_scan.py --staged exit 0.
  • Tests never pollute cwd or global git config; temp dirs only; dummy secrets are runtime-concatenated, never literal.
  • In worktrees use ABSOLUTE paths under the worktree for every write.
  • Domain docs stay minimal-but-complete; update this file in the same PR as code it describes.

Backend Python modules (stdlib-only)

serve.py (~65 lines): Composition layer. Calls config.reload(), csrf.init(), sse.reset_state(), re-exports their symbols for test suite.

config.py (call-time config, load-bearing rule):

  • Path/env/aesop.config.json resolution; reload() recomputes all paths from current environment. A state_root starting with ~ is expanded to the home dir before the absolute/relative check (SEM-1; test tests/test_state_root_expanduser.py).
  • RULE: Every other module reads config.X at call time (import config), NEVER from config import <path>. Frozen imports go stale after reload() (breaks test fixture isolation).
  • Exports: PORT, AESOP_ROOT, CONFIG_FILE, STATE_DIR, TRANSCRIPTS_ROOT, WEB_DIST, WATCHDOG_HEARTBEAT, MONITOR_HEARTBEAT, REPOS_JSON, ALERTS_LOG, INBOX_FILE, AUDIT_BACKLOG_FILE, UI_SESSION_TOKEN_FILE, TRACKER_FILE, ORCH_STATUS_FILE, LEDGER_FILE, QUEUE_STATE_DIR (env AESOP_QUEUE_STATE, default state/merge-queue), COLLECTOR_INTERVAL, SSE_KEEPALIVE_SECONDS, SSE_MAX_CLIENTS.

csrf.py: Session-token generation (atomic O_EXCL 0600 mode) + validate_csrf_request() (Origin/Referer check + X-Aesop-Token header). init() sets SESSION_TOKEN (43-char URL-safe base64). Token persisted to state/.ui-session-token (readable only by owner).

collectors.py: Read-only data collectors (heartbeats, repos, events, alerts, messages, backlog parse), tracker CRUD via WriteAPI, queue status (exceptions.jsonl + heartbeat age), and SSE section snapshots. Functions: _snapshot_data, _snapshot_tracker, _snapshot_orchestrator_status, drain_tracker_inbox, get_alerts, get_heartbeat_status(clock=) (injectable epoch clock for the 3s age buckets), get_queue_status (Q5 merge-queue operator panel), get_agent_lifecycle_events (wave-29), etc. Inc 1 (2026-07-30): Tracker CRUD routes through state_store.write_api.WriteAPI (atomic append + render). load_tracker() reads tracker.json cache. Slow-create diagnostics: create_tracker_item times its migrate, append and render stages and writes one stderr line tracker-create slow: total= migrate= append= render= state_dir= only when the create exceeds AESOP_TRACKER_SLOW_SECONDS (default 1.0).

agents.py: Agent transcript reading (get_fleet_agents, extract_agent_dispatch_prompt, get_agent_detail), path-traversal-safe agent-id handling via _AGENT_ID_FORBIDDEN.

sse.py (Server-Sent Events): Client registry, bounded broadcast, hash-gated _maybe_emit(), background collector_loop() thread. reset_state() restores per-import collector isolation (cached module across test re-imports). Sections emitted (in order): "data", "backlog", "agents", "tracker", "status", "cost" (wave-14 addition). Keepalive comment-line (: keepalive) every ~15s.

render.py: Renders ui/web/dist/index.html with CSRF token substituted via unique sentinel __AESOP_CSRF_SENTINEL__ (no .format() — Vite build passes it through verbatim). Requires template_path parameter; legacy fallback removed.

handler.py (HTTP routing + GET/POST endpoints):

  • DashboardHandler class (extends http.server.BaseHTTPRequestHandler).
  • run_server(host, port, app_handler_fn) — ThreadingHTTPServer required (SSE holds one connection per client).
  • Reads config.X / csrf.SESSION_TOKEN at call time. Tracker delete splits the path from the query before item_id (else archive 404s).
  • serve_api_state (GET /api/state): a cached section that is empty counts as not-yet-snapshotted and is recomputed inline. The "data" source seeds {} and is mtime-gated, so a quiet collector leaves that default cached; testing only for None let {} through and produced an empty first paint.

cost.py: Parser for state/ledger/OUTCOMES-LEDGER.md (markdown table); returns per-model + per-day aggregates, verdict scorecards, optional dollar estimates (if aesop.config.json supplies pricing map).

state_query_panel.py — Time-travel state query API: GET /api/state/events (temporal/stream/type filters) and GET /api/state/streams (aggregate view). Wraps state_store.StateAPI; gracefully degrades if DB missing.

wave_prs.py — Wave PR board: get_wave_prs() gathers open PRs + PR-less feat/* branches, rolls CI checks into passing/failing/pending/none, derives top blocker, caches ~5s. Degrades to {available:false, error} when gh missing/un-authed. Subprocess reads use encoding='utf-8', errors='replace'. Override gh binary: AESOP_GH_BIN env var.

wave_telemetry.py — Wave telemetry: get_wave_telemetry() extracts current phase (from orchestrator-status when fresh, STATE.md ## Phase: fallback), top blocker (from AUDIT-BACKLOG.md), cost metrics (from ledger). Reads state at call time (no cache); degrades gracefully on missing files. get_wave_telemetry(now=) and _read_orchestrator_status(now=) take an injectable freshness clock (tests pin it; default is the wall clock).

wave_dispatch.py — Wave dispatch (per-agent visibility): reads agent transcripts, infers phase (dispatch/thinking/tool-use/stall/done, else unknown) from structured tail fields only (record type, message.stop_reason, content block types, API-error marker; free text never inspected), estimates tokens from file size, computes activity age from mtime. Returns per-agent rows with phase badge, age, warnings (inactive >5min, stalled >10min). Degrades {available:false}. Polled 2-3s.

wave_failure.py — Wave PR failure drill-down: get_wave_failure(pr_number) shells gh run view --json jobs for jobs on PR branch, then gh api .../jobs/{id}/logs for failing jobs; extracts ~100-line log tails. Caches ~5s per PR; degrades to {available:false, error} when gh missing/un-authed. Override gh binary: AESOP_GH_BIN env var.

demo.py — Zero-key demo mode (--demo or AESOP_DEMO=1). Seeds throwaway state root with fabricated data, redirects all env vars to it; shell-out collectors use get_demo_agents()/get_demo_wave_prs(). Daemon refresher (~45s) keeps timestamps fresh. AESOP_ROOT stays real (dist must resolve). Honesty: BANNER_HTML + "demo": true in /api/state. No-op in default mode. Optional AESOP_DEMO_ROOT (tests). _write_ledger()'s most-recent row uses hours_ago=0.0 (not a small positive offset) — it must equal now exactly, otherwise a run within minutes of UTC midnight lands every row on the prior UTC date and test_seeded_ledger_uses_current_dates fails (observed on PR #878, proved via a mocked datetime.now at 00:01Z).

bench_panel.py: Benchmark API routes (/api/bench, /api/bench/compare). Reads bench_results_cache at call time.

tooling_panel.py — Tooling dashboard panel: GET /api/tooling/summary aggregates results from repo analysis tools (todo_tracker, test_coverage_gaps, dead_code_check, import_cycle_check, encoding_lint). Runs tools via subprocess (30s timeout), caches 60s, gracefully degrades to null for missing tools. ?force=1 bypasses cache. Exit code handling (findings-aware linters): Some tools signal “findings detected” with exit code 1, not an error — _is_acceptable_exit_code() distinguishes: dead_code_check.py, import_cycle_check.py, encoding_lint.py exit with 0 (clean) or 1 (findings found, both valid) or 2+ (error); other tools only accept 0. This allows accurate reporting of findings without masking them as errors.

quality_scorecard.py — Quality scorecard API: spec-sharpness and per-wave quality metrics.

wave_audit_tail.py — Wave audit tail: streams recent audit findings for live dashboard display.

wave_gantt.py — Wave Gantt chart data: per-agent timeline for wave execution visualization. Timestamps are RFC 3339 Z only; duration is end minus start, or null (unknown) when start is missing, never idle age. The frontend GanttTimeline.tsx renders a null duration as unknown (never nulls), pinned by a test in GanttTimeline.test.tsx.

wave_reasoning_tail.py — Wave reasoning tail: streams orchestrator reasoning for live display.

wave_context.py — Wave context file listing: files touched by wave agents for context display.

api/init.py, api/tracker.py, api/submit.py: Mutation handlers (tracker CRUD, inbox append).

Frontend (React 18 + Vite + TypeScript)

ui/web/src/:

  • main.tsx: Vite entry point; renders <App /> to #root.
  • App.tsx: App shell; hash-routed views (/#/, /#/work, /#/activity, /#/cost, /#/prs).
  • styles/tokens.css + global.css: Design tokens (light/dark palettes, spacing, typography).
  • views/: Overview, Work, Activity, Cost, WavePRBoard (with SSE bindings). 5 views total: /#/ (Overview), /#/work (Work), /#/activity (Activity), /#/cost (Cost), /#/prs (PR Board). WavePRBoard polls /api/wave/prs every 5s; drills down to FailureDrilldown on click.
  • components/: HealthHeader (always-visible mission-control status header), AgentsPanel, TrackerBoard, Timeline, CostChart, CostAnalyticsPanel, FailureDrilldown, BenchmarkPanel, etc.
    • HealthHeader: Mission-control status header (D4, always visible). Three-zone layout: (1) fleet orchestrator phase + agent counts/status breakdown from live agents array, (2) system health (watchdog/monitor/alerts/SSE/data freshness), (3) controls (cost snapshot, theme toggle, manual refresh). Color-coded freshness indicator dot. All metrics bound to real SSE state; nothing invented. Clickable cells jump to corresponding views. No local state beyond focus/hover. Props from App.tsx.
    • BenchmarkPanel: Results table (model/accuracy/tokens/latency/cost/timestamp) + model comparison cards; fetches /api/bench and /api/bench/compare; dark/light theme, responsive grid.
    • CostAnalyticsPanel (wave-29 UX): info-dense operator view with (a) spend per wave (bar chart), (b) model efficiency vs Opus counterfactual, (c) burn rate + end-of-wave projection with ceiling alert; graceful DATA-UNAVAILABLE states when ledger/ceiling missing.
    • FailureDrilldown: drawer showing CI job list + ~100-line log excerpts on expand; fetches /api/wave/failure?pr=N.
    • ToolingPanel: compact card grid showing repo tooling health (TODO count, coverage, dead code, import cycles, encoding issues); fetches /api/tooling/summary; green/yellow/red severity coding; refresh button; responsive grid.
  • lib/api.ts: Typed fetch helpers + CSRF header injection + /api/session fallback for dev server.
  • lib/useSSE.ts: EventSource hook with reconnect logic, per-section state, connection status. Cleanup clears the EventSource ref so a same-instance re-run (StrictMode double effect) opens a fresh source; covered by lib/useSSE.test.tsx.
  • lib/types.ts: TypeScript types for all API payloads (backend contract).
  • lib/sanitizeUrl.ts: XSS-safe URL parsing (inerts PR links on bad schemes).
  • vite.config.ts: Vite config with API proxy to :8770.
  • dist/: Built static files (committed to git; served by Python handler). Content-hashed by Vite; rebuilt with vite build on every ui/web dependency bump and committed with the bump (asset hash changes).

testids-in-fixtures pattern (both Python + React): Test components with data-testid attributes. React tests use getByTestId() (via @testing-library/react). Python tests use fixtures to set testids for integration proofs. Fixtures use repository-agnostic paths (<REPO>/ placeholders instead of hardcoded personal paths) for portability across repos/machines.

API Routes

Read-only: / (HTML+CSRF), /data, /assets/*, /api/state (first-paint snapshot), /api/session (dev token), /api/cost, /api/queue (merge-queue operator: depth/batch/heartbeat-age/exceptions), /api/backlog, /api/agents, /api/agent?id=, /api/tracker (?status/priority), /api/state/events (?stream/type/after/before/limit), /api/state/streams, /api/wave/prs (CI rollup, 5s cache), /api/wave/telemetry, /api/wave/dispatch (2-3s poll), /api/wave/failure?pr=N, /api/wave/gantt, /api/wave/audit-tail, /api/wave/reasoning-tail, /api/wave/quality-scorecards, /api/context/files, /api/quality/spec-sharpness, /api/bench, /api/bench/compare, /api/tooling/summary (60s cache, ?force=1), /events (SSE, 6 sections, 15s keepalive), /favicon.ico (204). All /api/wave/* honor AESOP_GH_BIN.

Mutations (CSRF-gated): POST /submit (inbox), POST /api/tracker (create), POST /api/tracker/<id> (?action=update|delete).

CSRF & Session Protection

43-char URL-safe base64 token, persisted to state/.ui-session-token (0600), regenerated if missing. Mutations require Origin/Referer local check + X-Aesop-Token header match (both fail-closed). CLI reads token from file; browser gets it injected into HTML template. CSRF trusts only the bound loopback port by default; AESOP_DASH_DEV_ORIGINS opts in exact loopback origins with an explicit port (e.g. Vite http://localhost:5173), and any local process on an opted-in port can read the session token.

SSE Contract

Realtime via GET /events (ThreadingHTTPServer required). 6 sections (data/backlog/agents/tracker/status/cost) emitted on content-hash change. Keepalive ~15s. Background collector thread polls every COLLECTOR_INTERVAL (1s default), mtime-gated, fail-open on crash.

State Store Integration

Inc 1 consolidation (2026-07-30):

  • Write: All tracker CRUD routes through state_store.write_api.WriteAPI, which appends events to SQLite and renders views atomically via state_store.materialize.
  • Read: load_tracker() reads the materialized tracker.json (git-ignored, gitignored, rebuildable — NOT committed). tracker.json is a derived view of the event store, kept current by WriteAPI.
  • Canonical render path: materialize_tracker() (one pure function) — all callers use this, not independent render logic.
  • Recovery: python tools/state_rebuild.py --all rebuilds views from event store with zero data loss.

Configuration

Precedence: env vars > aesop.config.json > built-in defaults. Key env vars: PORT (8770), AESOP_ROOT, AESOP_STATE_ROOT, AESOP_TRANSCRIPTS_ROOT, AESOP_UI_COLLECT_INTERVAL (1.0s), AESOP_GH_BIN, AESOP_AUDIT_BACKLOG, AESOP_DEMO/AESOP_DEMO_ROOT. Config keys: state_root, transcripts_root, aesop_root, pricing.

Build & Test

cd ui/web && npm run build before serving (dist always required, no fallback). Dev: npm run dev (Vite proxies API to :8770). Python tests: python -m unittest discover -s tests. React: cd ui/web && npm test. Playwright: npx playwright test.

Invariants

Stdlib-only backend (ThreadingHTTPServer for SSE). Collector fail-open. Config: import config; config.X (never from config import X). Dist always required (hard 500 if missing). Map of all domains: /CLAUDE.md

Tracker event-log migration (collectors.py)

_ensure_tracker_migrated() backfills the event log from tracker.json: migration_started claims an attempt, migration_completed only after a full backfill (skip requires both). An unreadable file (missing/malformed/permission) records migration_failed with the reason, never migration_completed, so a repaired tracker.json is backfilled on the next run.

It reconciles in BOTH directions. Items missing from the log are backfilled from disk; and where disk holds a status the log never recorded (historical closes were written straight to the projection without emitting events), an item_updated event is emitted so replay cannot resurrect them. The reconcile skips any item that already carries an explicit item_updated event -- that item is owned by the log, and overwriting it from a stale projection would revert a real update.

Refactoring (complexity reduction): _ensure_tracker_migrated() refactored from radon E(39) → C(19) via extraction of _backfill_missing_items() (A, cyclomatic 5) and _reconcile_status_updates() (C, cyclomatic 17). Per-record error handling preserved: one item's failure doesn't prevent others from backfilling/reconciling. Behavior byte-identical (invariant confirmed: no duplicate backfills, missing items backfilled, stale statuses reconciled, closed items not resurrected in projection).

Cost view: absent vs empty → three distinct states

RESOLVED (wave-31 audit findings):

Cost.tsx now receives both cost prop AND connectionStatus to distinguish three states:

  1. Loading (cost=null and connectionStatus.status='live'): shows "Loading cost metrics..." with explanatory hint.
  2. Error (cost=null and connectionStatus.status != 'live'): shows error callout with connection error message + retry button.
  3. Empty (cost has total_runs=0): shows "No cost data yet" with explanation (fresh install case).

Old behavior: null ambiguously covered both loading and error, rendering both as a slow-connection alarm. New behavior: loads three distinct callout styles with honest messaging, preserving retry affordance.

Chart accessibility (FINDING 2): All SVG charts already had role="img" + aria-label naming; added tests to verify screen readers can announce chart content:

  • CostChart.tsx: "Daily token usage by model"
  • ModelMixTrendChart.tsx: "Daily model usage distribution"
  • CostAnalyticsPanel.tsx WaveSpendChart: "Spend per wave" Bar segments include <title> elements for tooltips. Tests verify presence and correctness.

SSE Collector Loop Refactoring (wave-32: sse.py complexity reduction)

Refactored ui/sse.py:collector_loop() from radon F(43) → B(6) via CollectorSource abstraction. Each of 9 sources (data, backlog, agents, tracker, status, cost, collector_health + heartbeat) now declares its:

  • File path(s) to monitor
  • Change detection strategy (mtime+size tuple, multi-file mtime, fingerprint, always-update)
  • Snapshot builder function
  • Error tracking (per-source 5-error rolling buffer)

Implementation: Base CollectorSource class + three detection strategies (MtimeSizeGatedSource, MultiFileMtimeGatedSource, FingerprintGatedSource) + 7 concrete sources. Main loop reduced to 48 lines iterating over source list; all extracted methods grade A-B (≤ 7 cyclomatic). Behavior preserved: event names, payload keys, field order, mtime-cache semantics, error handling, emission order all byte-identical (captured SSE streams verified).

Testing: AST parse OK, encoding_lint OK, behavioral SSE proof (baseline vs refactored identical payloads), server runs with --demo. No changes to collectors.py, config.py, handlers.py, or React frontend.

HTTP handler route table (wave-32)

Refactored ui/handler.py:do_GET and do_POST from if/elif chains to route table lookup:

DashboardHandler now dispatches requests via two route tables per method:

  • _GET_EXACT_ROUTES (dict): 19 exact-match GET paths (checked first).
  • _GET_PREFIX_ROUTES (list): 9 prefix-match patterns, order-dependent for precedence preservation.
  • _POST_EXACT_ROUTES (dict): 2 exact-match POST paths.
  • _POST_PREFIX_ROUTES (list): 1 prefix-match pattern.

_route_get() / _route_post() matchers: check exact dict first, then prefix list in order; 404 if no match.

Complexity reduction:

  • do_GET: D(30) → A(2) (if/elif chain eliminated).
  • do_POST: A(5) → A(2) (if/elif chain eliminated).
  • _route_get() / _route_post(): A(4) each (linear scan with early exit).

Behavior preserved:

  • All routes resolve to identical handlers with same status/headers/body.
  • Prefix precedence: exact matches before patterns; within patterns, list order matters (first match wins).
  • 404/405 fallthrough unchanged.
  • Security checks (Host-header DNS-rebinding mitigation, path-traversal containment on /assets/*, CSRF gating on mutations) untouched.
  • Hard 500 on missing ui/web/dist is intentional fail-closed behaviour (preserved).

Testing: 24 unit tests PASS (Host header validation, DNS-rebinding defence, route resolution). No regression.

CostSummaryDrawer component

New: ui/web/src/components/CostSummaryDrawer.tsx — right-edge collapsible drawer (40px collapsed, ~180px expanded) showing spend/rate/model-mix metrics. Bound to SSE cost+connectionStatus props; handles loading/error/empty/loaded states. Toggle button + panel with role="status", aria-label accessibility. 31 unit tests (vitest, all states + keyboard/pricing + stale-after-disconnect + model-mix proportions). Integrated into App.tsx. CSS uses design tokens. Cost.tsx:63 comment fixed (was "live/reconnecting", now "live"). Contract fixes (drawer P1s): connection status wins over cached data — useSSE retains the last cost when the EventSource errors, so anything gated on !cost is unreachable after the first payload and the always-visible drawer showed stale spend indefinitely; isError is now connectionStatus.status !== 'live' ALONE, precedence error (retained payload rendered under an explicit cost-summary-stale label, never as current) > loading > empty > loaded. Model-mix shares are each model's fraction of the all-time token total, both sides from summary.models (daily_totals has no model dimension) — same window, so shares sum to 100%, the window is labelled in the UI, and the 0.1% rounding happens once so label and bar width cannot disagree (the old denominator mixed windows, exceeded 100%, saturated every bar). tools/verify_cost_summary_drawer.py carries a falsifiability contract: every docstring claim is an assert and each [PASS] print sits after the assert earning it — an unassertable claim is deleted from the docstring, never downgraded to [WARN]/[INFO]. Pyflakes cleanup (2026-10-06, G15): removed unused imports/locals across serve.py/handler.py/agents.py/collectors.py/etc (see tools/pyflakes_gate.py); serve.py's re-export surface kept, # noqa'd with reasons. CostForecast addition: ui/web/src/components/CostForecast.tsx (+ .test.tsx + .css) — linear regression trend over daily_totals; end-of-wave projection with confidence bands; ceiling alerts. 24 unit tests. Wired into CostAnalyticsPanel. GanttTimeline frozen fixture: test imports src/components/__fixtures__/gantt-sample.json (decoupled from stats.json refreshes).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.