flightdeck
CLAUDE.md30 starsChanged yesterdayApache-2.0View on GitHub
These rules exist because something went wrong or almost went wrong without them. Follow them without exception. If a rule conflicts with a task instruction, raise the conflict with the maintainer before proceeding. "The maintainer" means the person directing this session. Component-specific rules live in dashboard/CLAUDE.md (frontend + E2E discipline) and sensor/CLAUDE.md (sensor + framework coverage). They load automatically when working on files under those directories. 1. Read ARCHITECTURE.md in full. Not a skim. Every section. The architecture is the…
- Deletes or force-pushes
- Commits and pushes
In this repository3 other files it gives its agents.
- dashboard/CLAUDE.mdCLAUDE.md
- sensor/CLAUDE.mdCLAUDE.md
- docs/llms.txtllms.txt
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
47 rules. About 0 are common, 40 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈40
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 16
Read ARCHITECTURE.md in full: Not a skim. Every section.
- Distinctive: line 18
Read the DECISIONS.md entries (and DECISIONS-ARCHIVE.md for D001-D213) for the area you touch, so a rejected alternative is not proposed …
- Distinctive: line 39
Scope tasks tightly: If a task touches more than 5-8 files, split it into separate PRs where the pieces stand alone.
- Distinctive: line 43
State your assumptions: If the task is ambiguous, list your assumptions in the plan.
- Distinctive: line 50
Tests are not optional: Every task that produces code must also produce tests.
- Distinctive: line 53
Never break existing tests: If your change breaks a test you did not touch, fix it before reporting back.
- Distinctive: line 74
If you find code that stores content when capture is off, it is a bug.
- Very specific: line 83
Preserve provider terminology: Never normalize Anthropic's system + messages into OpenAI's messages-only format or vice versa.
- Distinctive: line 103
If you implement a chart that ignores the global time range, it is wrong.
- Distinctive: line 107
Do not create separate endpoints per chart.
- Very specific: line 149
All database schema changes must use golang-migrate: Create a new numbered migration pair in storage/migrations/postgres/ and one with the …
- Distinctive: line 177
Validate all event payloads at the ingestion API boundary: Do not pass invalid events to NATS.
- Distinctive: line 188
Every file created or modified
- Distinctive: line 189
Every decision made not explicitly covered in ARCHITECTURE.md
- Distinctive: line 190
Test count before and after (must increase)
- Distinctive: line 218
Does NOT apply to:
- Distinctive: line 223
If a live-run is genuinely not feasible (requires production credentials, or the dev stack can't exercise the path), flag explicitly in the …
- Distinctive: line 227
Not verified against live stack because <reason>.
- Distinctive: line 230
Never silently claim verification that wasn't done.
- Very specific: line 284
NOT reflect your edits: run make dev-restart after a Go or a dashboard change.
- Very specific: line 323
Does NOT apply to: docs-only commits with no source-file changes.
- Distinctive: line 331
When implementation reveals that a planned approach is wrong, impractical, or superseded by a better idea, update the document to reflect …
- Distinctive: line 360
Never merge code that contradicts the architecture docs.
- Distinctive: line 372
Phase plan changes must be approved by the maintainer: If a task reveals that a planned deliverable is wrong in scope, sequencing, or …
- Distinctive: line 378
Acceptance criteria can be revised if they are wrong: If a criterion turns out to be untestable, overconstrained, or based on a wrong …
- Distinctive: line 386
Never commit directly to main: All changes go through a branch.
- Distinctive: line 407
When you would have filed a KI, instead:
- Distinctive: line 408
If it's a bug that needs fixing now: fix it in this commit or the next release.
- Distinctive: line 410
If it's a legitimate architectural trade-off: document the decision in the PR body, or in DECISIONS.md when rule 43 applies (with a …
- Very specific: line 414
If it's a post-launch follow-up that might matter to users but has no concrete owner yet: open or update a roadmap issue.
- Distinctive: line 416
If it's outside scope entirely (feature creep, hypothetical): decline in the PR or commit body with reason.
- Distinctive: line 430
When any new endpoint is added to ingestion or api:
- Distinctive: line 431
Add swaggo annotations to the handler before the task is considered complete
- Very specific: line 438
Commit the regenerated docs/ directory
- Distinctive: line 441
Every endpoint listed in ARCHITECTURE.md has a Swagger annotation in the handler
- Distinctive: line 447
No endpoint exists in the code that is absent from the Swagger spec
- Distinctive: line 449
If any endpoint is undocumented, the phase audit fails.
- Distinctive: line 456
No-defer discipline: When methodology or scope gaps surface mid-phase that fit the phase's intent, they land in the current PR.
- Distinctive: line 489
Do not implement without explicit maintainer instruction:
- Distinctive: line 523
If any of these feels necessary, stop and write a plan describing:
- Distinctive: line 545
Before beginning any task, fetch from origin, fast-forward main to origin/main, and create a new feature branch from there.
- Distinctive: line 558
If the working tree is dirty, stop and ask the maintainer before proceeding.
- Distinctive: line 570
When main moves forward and the feature branch needs updates:
- Very specific: line 574
If not fast-forwardable, report the situation to the maintainer with git log --oneline origin/main feat/<branch> --not --graph and ask …
- Distinctive: line 578
Never silently rebase a feature branch onto main.
- Distinctive: line 584
When a PR is squash-merged to main, the feature branch's local history diverges from main because the 20 commits on the branch become 1 …
- Distinctive: line 588
Delete the feature branch and start a new one from updated main for the next piece of work
≈ “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
Flightdeck -- Claude Code Rules
These rules exist because something went wrong or almost went wrong without them. Follow them without exception. If a rule conflicts with a task instruction, raise the conflict with the maintainer before proceeding. "The maintainer" means the person directing this session.
Component-specific rules live in
dashboard/CLAUDE.md(frontend + E2E discipline) andsensor/CLAUDE.md(sensor + framework coverage). They load automatically when working on files under those directories.
Before Every Session
- Read ARCHITECTURE.md in full. Not a skim. Every section. The architecture is the source of truth. Code that contradicts it is wrong, not the architecture. Read the DECISIONS.md entries (and DECISIONS-ARCHIVE.md for D001-D213) for the area you touch, so a rejected alternative is not proposed again.
- Check for open TODO, FIXME, and HACK comments in any file you are about to touch. List them in your plan.
- Write architectural decisions down before the code. A decision ARCHITECTURE.md does not cover is recorded first (rules 42 and 43): ARCHITECTURE.md, then DECISIONS.md when it qualifies, otherwise the PR description. Ask the maintainer instead of deciding when the choice changes scope, removes existing behaviour or content, or is a product call the docs do not settle.
Planning Rules
- Always plan before implementing. For every task, write down every file you will create or modify and why (a scratch plan or the PR description). Implement without waiting for approval unless a rule in this file or a component CLAUDE.md requires the maintainer's approval.
- Scope tasks tightly. If a task touches more than 5-8 files, split it into separate PRs where the pieces stand alone. Large tasks drift and produce hard-to-review changes.
- State your assumptions. If the task is ambiguous, list your assumptions in the plan. Do not silently assume.
Code Rules
- Tests are not optional. Every task that produces code must also produce tests. A task with no tests is incomplete. Run the full test suite before reporting done.
- Never break existing tests. If your change breaks a test you did not touch, fix it before reporting back.
- Backend unit tests: Go testing package for Go components. pytest for flightdeck-sensor. No real API calls. Mock all external services.
- Integration tests: pytest. Full pipeline against the dev stack: the
flightdeckbinary with its embedded NATS, on Postgres or on SQLite. Run withmake test-integration; the tests that pause the worker container run withmake test-split.
Frontend code rules (11-17) live in dashboard/CLAUDE.md.
Prompt Capture Rules (CRITICAL)
- Never store or log prompt content when capture_prompts=false. This is a hard rule with no exceptions. When capture is off, event payloads contain only token counts, model names, latency, and tool names. No message content. No system prompts. No tool inputs or outputs. No response text. If you find code that stores content when capture is off, it is a bug.
- Content goes in event_content table only, except transiently, while a
GenAI trace is assembled. That staged content is written only when the
exporter declares capture, and is deleted on assembly or by the backstop
sweep. Prompt content is never stored
inline in the events table. The events table always contains metadata only.
Content is fetched on demand via
GET /v1/events/:id/content. - Preserve provider terminology. Never normalize Anthropic's
system+messagesinto OpenAI'smessages-only format or vice versa. Store and display exactly what the provider received. ThePromptViewercomponent handles provider-specific rendering -- do not change this logic without the maintainer's approval. - The Prompts tab in the session drawer shows a clear disabled state when capture is off for that session: "Prompt capture is not enabled for this deployment." Never show an empty tab, a loading spinner that never resolves, or an error message.
Analytics Rules
- Every analytics chart must have a working group-by control.
A chart without a functional
DimensionPickeris an incomplete task. The group-by dropdown must change the chart data, not just the label. - The global time range picker applies to all charts simultaneously. If you implement a chart that ignores the global time range, it is wrong.
- All analytics charts use the same
GET /v1/analyticsendpoint. Different charts pass differentmetricandgroup_byparameters. Do not create separate endpoints per chart. - Available dimensions are exactly:
flavor,model,framework,host,agent_type,team,provider,agent_role,parent_session_id. No other values. Do not add dimensions without updating ARCHITECTURE.md first.providerreads the sensor-stampedevents.providerand falls back to a SQL CASE overmodelfor older rows.agent_rolegroups by the framework-supplied sub-agent role string; sessions with nullagent_rolebucket as(root).parent_session_idgroups by the parent session UUID; root sessions bucket as(root). Thegroup_byquery param accepts one or two dimensions comma-separated:?group_by=dim1keeps the single-axis shape;?group_by=dim1,dim2returns a two-key rollup wheredim1is the primary (outer) axis anddim2is the secondary (inner) axis. Both positions accept any value from the locked list above. - Available metrics are exactly:
tokens,sessions,latency_avg,latency_p50,latency_p95,policy_events,estimated_cost,parent_token_sum,child_token_sum,child_count,parent_to_first_child_latency_ms. Same rule applies.estimated_costsums metered calls only and prices them from themodel_pricingtable, whichapi/internal/store/pricing_loader.gorebuilds at API startup from the vendored litellm catalogue and thepricing.yamloverrides; refresh the catalogue withmake pricing-refresh(CONTRIBUTING.md has the steps). The four sub-agent-aware metrics operate over the parent / child relationship via recursive CTE onparent_session_id; see ARCHITECTURE.md analytics endpoint section for the contract and the known-performance-characteristic note.
Sensor Rules
Sensor rules (27-32) live in sensor/CLAUDE.md.
API and Schema Rules
- Never change the event payload schema without updating ARCHITECTURE.md first. The schema is a contract between the sensor and the ingestion API.
- All database schema changes must use golang-migrate. Create a new numbered
migration pair in
storage/migrations/postgres/and one with the same number instorage/migrations/sqlite/(the SQLite translation):000NNN_description.up.sql000NNN_description.down.sqlThe down file must be the exact inverse of the up file. Never add schema changes toinit.sql-- it contains seed data only. Never modify an existing migration file that has already been applied. Always add a new migration.scripts/check-migration-pairs.shfails CI when the two directories' version lists differ; the storage module's parity test fails when the two schemas differ. - SQL lives only in each service's store packages, never in handlers.
Those are
api/internal/store(with the token lookups ofapi/internal/auth),ingestion/internal/session,ingestion/internal/auth,ingestion/internal/directive,ingestion/internal/otlpstageandworkers/internal/writer; thestoragemodule applies the migration files. Stores open their database through thestoragemodule (storage.Open,storage.Dialect,storage.Bus; the Storage section of ARCHITECTURE.md), never through pgx directly. The current places outside store packages that run SQL are:workers/internal/processor/policy.go: token policy lookups and the directives it issues;workers/internal/processor/session.go: session-row reads (rowOwnerless,handleSessionGuard,sessionLookupState);workers/internal/processor/event.go: theenrichSessionEndqueries.
- Validate all event payloads at the ingestion API boundary. Do not pass invalid events to NATS.
- GET /v1/events/:id/content returns 404 when capture is disabled for that session. Not 200 with empty data. Not 403. 404 -- the resource does not exist.
Reporting Rules
- After every task, report:
- Every file created or modified
- Every decision made not explicitly covered in ARCHITECTURE.md
- Test count before and after (must increase)
- Whether both themes pass (for frontend tasks)
- Any blockers
- If you find a discrepancy between code and ARCHITECTURE.md, report it immediately. Log it, fix it, report it.
- Do not report a task complete if tests are failing.
Live Stack Verification Rule
40a. Any new runtime code path must be exercised against the live dev stack before claiming it works. Passing unit tests with mocks is insufficient evidence on its own. A playground script or smoke test that pytest never executes -- real API calls, real dev stack, real event persistence -- is the verification standard.
Applies to:
- New sensor framework interceptors (Anthropic, OpenAI, litellm, and every
future addition).
- New playground scripts.
- New worker code paths (state transitions, revive logic, session guards).
- New dashboard behavior where the claim is user-facing ("state revives
on event", "filter composes with flavor").
- Any "this should work" claim that unit tests alone can't verify.
Does NOT apply to:
- Pure refactors where behavior is identical and tests pass.
- Docs-only changes.
- Type-only fixes.
If a live-run is genuinely not feasible (requires production credentials,
or the dev stack can't exercise the path), flag explicitly in the commit
body:
Not verified against live stack because <reason>. Unit tests cover
<paths>; live verification deferred to <mechanism>.
Never silently claim verification that wasn't done. Mock-only coverage
has shipped real bugs in this repo (a litellm interceptor that passed
mocked tests and never fired live, a workers binary that drifted from
its source, CI annotations that only surfaced on Node 20). The rule is
the lesson.40a.A. Every playground script must declare a meaningful agent_type and
flavor. Never "unknown", never empty, never inherited defaults.
Convention:
- agent_type = "coding" (dev smoke, from the locked agent_type vocabulary)
- flavor = "playground-<script-name>"
Enforced mechanically by ``playground/_helpers.py::init_sensor`` for
sensor scripts and by ``playground/_genai.py::configure_exporter`` for
the OpenTelemetry framework scripts.
Without this rule every playground run lands as ``flavor="unknown"`` /
``agent_type="autonomous"`` -- outside the locked agent_type vocabulary
(``coding``, ``production``) -- which makes the Fleet view unreadable.40a.B. Every playground script must enable maximum capture.
capture_prompts=True is the default in
playground/_helpers.py::init_sensor. Any future sensor capture flag
(currently only capture_prompts exists) defaults to its most
expansive setting in the helper. Playground is the highest-fidelity
smoke surface -- it demonstrates what the sensor can see, not a minimal
happy path.
The one legitimate override is ``09_capture.py`` which exercises the
``capture_prompts=False`` / ``True`` matrix explicitly to verify the
``GET /v1/events/{id}/content`` 404-vs-200 contract. Any other script
that turns capture off needs a commit-body justification.
Both sub-rules inherit from rule 40a. Any new playground script must
satisfy both at creation.40b. Before committing changes that touch code paths with runtime
behavior, run the full test suite against a locally-running dev
stack that reflects the current branch state. CI is not the
first-line detector for runtime bugs — local pre-commit
verification is. Unit tests with mocks pass while live queries
500 exactly when the mocks diverge from reality. The
feedback_pre_commit_live_test.md entry in the auto-memory
captures this rule in permanent agent memory.
How to apply:
- For sensor / ingestion / worker / API / dashboard API-contract
changes: rebuild the binary (`make dev-restart`) so the dev
stack is running branch HEAD, then run the component's full
test suite (unit + integration) locally. Don't push until green.
- The project's dev stack (`make dev`, `scripts/dev-stack.sh`) is
the `flightdeck` binary built from the checkout, with the
dashboard bundle embedded, beside one Postgres container. The
binary is built when the stack starts, so a running stack does
NOT reflect your edits: run `make dev-restart` after a Go or a
dashboard change. When the change touches a store or SQL, run
the suite on both databases (`make dev DB=sqlite` for the
second).
- Exempt: pure docs, comments, type-only fixes, and formatting
passes that cannot change runtime behavior.
Inherits from rule 40a (live-stack verification). Where 40a says
"new runtime code must be exercised live before claiming it
works," 40b says "and that verification happens before the
commit, not after push-to-CI."40c. E2E discipline rules (40c through 40c.4) live in dashboard/CLAUDE.md.
40d. Framework coverage rules live in sensor/CLAUDE.md.
40e. Pre-push lint is a hard rule. Before pushing any code, run the appropriate linter for every component touched and fix every finding. Component → command:
- Sensor / playground / tests (Python): ``ruff check .`` and
``ruff format --check .`` from the component root. ``mypy
--strict`` on sensor.
- Ingestion / workers / api (Go): ``gofmt -l .`` (the gofmt of
the toolchain ``go.mod`` selects; ``make lint`` runs it) and
``golangci-lint run`` from the component root. The binary lives at
``/home/omria/go/bin/golangci-lint`` on the dev box (PATH may
not include it). ``go test ./...`` alone misses ``unused``
and other lints CI enforces.
- Dashboard (TypeScript): ``npm run lint`` and
``npm run typecheck`` from ``dashboard/``.
CI runs these gates and a push that lands red blocks the PR.
Catching the failure locally takes seconds; catching it after
a CI run wastes ~5-10 minutes per cycle. Inherits from rule
40b (pre-commit live test). Where 40b is about runtime
behaviour, 40e is about static checks; both must pass before
push.
Does NOT apply to: docs-only commits with no source-file
changes. A README/CHANGELOG/CLAUDE.md edit is exempt.Living Document Rules
ARCHITECTURE.md is a living document, not a contract carved in stone. When implementation reveals that a planned approach is wrong, impractical, or superseded by a better idea, update the document to reflect reality. A codebase that matches a stale ARCHITECTURE.md is worse than no ARCHITECTURE.md at all.
ARCHITECTURE.md describes what the system IS, not how it got there. A new contributor with zero project history must be able to read it and learn the system as it stands today. Phase references, "was added in Phase X", "previously did Y", "pre-fix the worker dropped Z", and other temporal qualifiers do not belong in ARCHITECTURE. They belong in:
CHANGELOG.mdfor user-visible changes per release.DECISIONS.mdfor the durable decisions rule 43 describes.- PR descriptions and commit bodies for phase decisions, V-pass methodology notes, pre-existing bugs surfaced during audit, and phase-ancestry of individual features.
D-numbers (D057, D094, D115, etc.) are NOT acceptable in ARCHITECTURE.md either, nor in code, comments or log strings. Decision-record pointers belong in CHANGELOG.md, DECISIONS.md itself, and PR/commit bodies — a reader should not need a D-number lookup to understand what the system does today. Architecture prose states the fact directly with the WHY in plain English.
- When any planned decision changes, update docs before merging code. The order is always: update ARCHITECTURE.md → record the decision (in DECISIONS.md when rule 43 says so, otherwise in the PR description) → write the code → tests pass → report back. Never merge code that contradicts the architecture docs.
- DECISIONS.md records the decisions future contributors would otherwise relitigate, and only those. Add an entry, before the code, when a decision changes a contract (event payload, API, wire or file format), changes the database schema, moves a trust or security boundary, or rejects an alternative someone would plausibly propose again. Keep it to 10-15 lines: decision, why, rejected alternative (format in the file's header). Every other pivot (switching library X for Y, a plan change, a review finding) is explained in the PR description and commit body. Entries D001-D213 are frozen in DECISIONS-ARCHIVE.md.
- Phase plan changes must be approved by the maintainer. If a task reveals that a planned deliverable is wrong in scope, sequencing, or approach, raise it before changing the plan. Do not silently resequence phases or remove deliverables. The maintainer decides whether to update the plan or stay the course.
- Acceptance criteria can be revised if they are wrong. If a criterion turns out to be untestable, overconstrained, or based on a wrong assumption, raise it with the maintainer. Do not silently skip a criterion.
Git Rules
- Never commit directly to main. All changes go through a branch.
- Commit messages follow conventional commits:
feat:,fix:,test:,docs:,chore:,refactor: - Never commit secrets, API keys, or tokens.
Issue Tracking Rules
No indefinite deferral bucket. Issues land in one of three states: fixed in the release they are filed in, declined with a documented reason (typically in the commit body or DECISIONS.md), or on the roadmap as a GitHub issue labelled
roadmap, with a milestone when it is planned for a release. The priorKNOWN_ISSUES.md/Deferred to v0.4.0bucket was retired; it had become a dumping ground where items sat for months. Roadmap issues are public so the work is visible, and users prioritize it with reactions and comments. The README links to the label and carries no roadmap list of its own.When you would have filed a KI, instead:
- If it's a bug that needs fixing now: fix it in this commit or the next release. Don't file, don't defer.
- If it's a legitimate architectural trade-off: document the decision in the PR body, or in DECISIONS.md when rule 43 applies (with a follow-up pointer if there's a real path to revisit), and close the matter.
- If it's a post-launch follow-up that might matter to users but has
no concrete owner yet: open or update a
roadmapissue. - If it's outside scope entirely (feature creep, hypothetical): decline in the PR or commit body with reason. No entry anywhere.
TODO(KI...)comments in code are retired. If a comment refers to deferred work, useTODO: <short description>with the roadmap issue number when applicable. PlainTODOfor local "come back to this after the branch merges" work is still fine.
API Documentation Rules
Every API endpoint must have complete Swagger documentation.
When any new endpoint is added to ingestion or api:
- Add swaggo annotations to the handler before the task is considered complete
- Required annotations: @Summary, @Description, @Tags, @Accept, @Produce, @Param (every param including query params), @Success with the correct response struct, @Failure for every error code the handler can return, @Router
- Regenerate the docs with
make -C <component> build(it runsgo tool swag, the version the component'sgo.modpins; ingestion writes OpenAPI 3.1 with--v3.1, the api Swagger 2.0) - Commit the regenerated
docs/directory
At the end of every phase audit, verify:
- Every endpoint listed in ARCHITECTURE.md has a Swagger annotation in the handler
- The Swagger spec accurately reflects the actual request and response schemas (field names, types, nullable fields marked as omitempty or pointer)
curl -s -o /dev/null -w "%{http_code}" http://localhost:4000/api/docs/index.htmlandcurl -s -o /dev/null -w "%{http_code}" http://localhost:4000/ingest/docs/index.htmlboth return 200- No endpoint exists in the code that is absent from the Swagger spec
If any endpoint is undocumented, the phase audit fails. Document it before the phase can close.
No-Defer Discipline
No-defer discipline. When methodology or scope gaps surface mid-phase that fit the phase's intent, they land in the current PR. They do not get deferred to a follow-up PR. Deferring recreates the drift the current phase exists to prevent.
The phase's intent is defined by its title and goal statement. A finding that clearly fits is in scope. A finding that clearly doesn't (e.g., unrelated feature work that warrants user prioritisation) lands as a
roadmapissue and is addressed later. Borderline cases are resolved by the maintainer, not deferred unilaterally. There is no separate "follow-ups" file — the roadmap issues and the current PR are the only two destinations.This rule applies to Claude Code's "preserve intentionally" or "flag for deferral" proposals — the default answer is "address now", not "defer". The maintainer authorizes deferral explicitly, or it doesn't happen.
Why: Phase 4 surfaced multiple gaps mid-phase (embeddings content capture, framework attribution always-null, V-DRAWER dead-end, ARCHITECTURE phase-tag drift, ARCHITECTURE structural reorganization) that a strict reading of the original V-pass would have deferred. Each fit the phase's "agent communication coverage hardening" intent, was addressed in PR #28, and would have compounded as drift if shipped to a follow-up. This rule codifies the principle that has been applied ad-hoc throughout PR #28.
What Is Out of Scope
Do not implement without explicit maintainer instruction:
- Notification infrastructure: Slack, email, PagerDuty (v2)
- TimescaleDB migration (v2 -- analytics page works on plain Postgres)
- Proxy or gateway pattern for LLM traffic interception
- MCP server
- Multi-tenant SaaS (self-hosted only in v1)
Git Discipline
These rules exist because a rebase operation earlier orphaned 27 commits of real work and nearly lost the Analytics v2 feature. The reflog saved us. The rules below make that class of mistake harder.
No destructive operations without explicit maintainer approval
The following are DESTRUCTIVE -- they rewrite history, drop commits, or make remote state unrecoverable from the branch. Never run any of these without the maintainer approving the exact command in the chat:
git rebase(interactive or--onto)git reset --hardgit push --forcegit push --force-with-leasegit push -fgit branch -D(force delete)git checkout -- <file>(when it would discard uncommitted work)git clean -fdgit filter-branchgit commit --amend(on a commit that has already been pushed)- Any git operation involving
--onto,--orphan, or reflog manipulation
If any of these feels necessary, stop and write a plan describing:
- What you intend to run (exact command)
- What state you expect before and after
- How the maintainer can verify the result is what was intended
- What the rollback path is if it goes wrong
The maintainer must explicitly respond with go before execution.
Default safe operations
For normal work, stick to:
git add,git commitgit push(fast-forward only)git pull --ff-onlygit fetch+git merge --ff-onlygit merge(only when explicitly asked)git stash/git stash pop
Always start from latest main
Before beginning any task, fetch from origin, fast-forward main to origin/main, and create a new feature branch from there. Never start work on a stale branch or on a branch carried over from a previous task unless the maintainer explicitly says to continue. Canonical sequence:
git fetch origin
git checkout main
git pull --ff-only origin main
git checkout -b feat/<descriptive-name>If the working tree is dirty, stop and ask the maintainer before proceeding. Never auto-stash, auto-discard, or carry forward unrelated changes. If main is not fast-forwardable to origin/main (which would only happen with local commits on main that should never exist per Rule 46), stop and ask.
This sequence is the FIRST step before any code reading, planning, or implementation. The branch name uses a descriptive slug for the work; future PRs use their own.
Syncing with main
When main moves forward and the feature branch needs updates:
git fetch origingit merge --ff-only origin/main(if possible)- If not fast-forwardable, report the situation to the maintainer with
git log --oneline origin/main feat/<branch> --not --graphand ask before merging, rebasing, or resolving.
Never silently rebase a feature branch onto main. Squash merges from PRs create non-linear history that rebase does not handle cleanly -- the rebase earlier in this project kept only one commit and dropped 27.
PR and merge workflow
When a PR is squash-merged to main, the feature branch's local history diverges from main because the 20 commits on the branch become 1 commit on main. Do NOT try to "clean this up" with rebase. Either:
- Delete the feature branch and start a new one from updated main for the next piece of work
- OR keep working on the feature branch, treating it as
divergent-but-valuable, and merge main in periodically with
git merge --ff-only origin/main(or a non-ff merge if ff is impossible, with the maintainer's approval)
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.

