AGENTS.md

Read by every AI tool working in this repo. Where a tool-specific config disagrees with this file, this file wins.

What is being built: compass/framework/mvp-brd.md. Read it first. It is the single description of the product — the concept, the four delivery phases, the decisions already taken and what each one beat, the requirements, and what is deliberately out of scope. Anything implying a different target is stale.

This file is only about building the codebase. Repo layout, which engine runs, where truth lives, the git and testing rules, and the mistakes this repo keeps repeating. CLAUDE.md is a one-line pointer here, as app/CLAUDE.md already was.

It deliberately does NOT describe the product's runtime. Roles are rows in compass/seed/roles.csv; the process is rows in compass/seed/*.csv imported into the database; the discipline an agent carries is inlined in compass/agents/<agent>.md, which is what lets one be pasted into a host that cannot see this repo. A fourth copy here would go stale, and that is the failure this repo keeps having.

The product, in short

An ERP for software delivery. The lifecycle — setup → sprint 0 → sprint N — is an executable process rather than a document. The AI drafts the first version of every deliverable the plan calls for; a named human reviews it and advances it. Status is position in the flow, and it lives in the client's tracker, not here.

One consequence shapes almost every decision below: the row is the instruction. A row names who, on what basis, producing what, after what, accepted by whom — a complete functional rule. The model supplies craft, the org's reference material supplies house style, and process discipline is structural rather than something an agent is told. So discipline belongs in rows and gates, not in prose about roles.

Layout

Both halves live here; a change spanning them is one commit.

• repo root — the framework a consumer vendors: compass/agents/, compass/seed/, compass/templates/, compass/scripts/, and the Python orchestrator (v1).
• app/ — the control tower (Next.js 16 / Supabase). Its own toolchain; see app/AGENTS.md, which carries a Next 16 breaking-change warning worth heeding.

The app (in app/) is the engine. Where anything disagrees with it, the app is what runs.

One engine, and the v1 orchestrator it still calls

The app used to carry two engines, which was the single most confusing thing in the repo and the source of most of its drift. v1's app half — its API routes, the root lib/*.ts modules that served them, its pages, components and eleven of its tables — has been deleted.

What remains of v1 is the Python orchestrator, and the app still uses it for exactly one job:

Two v1 remnants are still live, and look deletable when they are not:

• lib/authz.ts + user_role / app_user — kept on purpose as the groundwork for real identity.
• spec_file (+ spec_file_version) — the source of agent prompts and the doc tree. The app reads it through resolveSpecFromTable, the orchestrator through spec_source; neither falls back to the disk. app/scripts/seed-specs.mts loads it from compass/agents/, compass/stacks/ and the remaining compass/templates/; nothing else writes it, so a change is a direct edit of the row. resolveSpec in lib/specs.ts still falls back to the disk — nothing that runs calls it.

Before dropping a table, search ALL remaining source for it and trace each hit to a caller — a root-level lib/*.ts module is not v1 just because of where it sits.

The agent files are not the task definitions

compass/agents/<agent>.md files carry ### Task: sections. Those are the initial design and are not what runs. The app never looks a task up by slug: buildContext loads the whole agent file as the system prompt, and takes the instruction from the ROW — its title, reads, produces and the criteria. A slug that is not a heading in the agent file breaks nothing.

So do not treat those sections as the source of a task, do not add a task there expecting it to be dispatched, and do not report a row as broken because its slug is missing from an agent file. The task lives in compass/seed/workflow-steps.csv.

The one exception is the orchestrator's code steps. The app strips ## Tasks I own from the prompt at read time (withoutTaskCatalogue); the orchestrator does not, and a build step takes its instruction from the ### Task: section of its agent file (implement-story, respond-to-review, review-pr, write-e2e-tests). So the engineer, reviewer and automation rows in spec_file keep those sections, and the other rows do not. Do not strip them from those three.

What an agent file still owes is what a ROLE brings and a row cannot: identity, the discipline it carries, and the house standard for what it produces. The stale task sections are dead weight in a file pasted whole into every prompt for that role — they will be cleared when the agent files are re-authored, and until then they are to be ignored rather than followed.

Where truth lives, and what checks it

Several places describe the same workflows. Know which one executes:

• compass/seed/*.csv — what the app imports and actually runs. Carries produces, reads, criteria and title.
• the database — a versioned copy of the seed. Published versions match it row for row; older versions accumulate, so raw counts overstate.
• compass/archive/workflows/*.md — the framework's v1 dispatch graphs, archived design history. Nothing executes them and nothing checks them against the seed: the orchestrator builds its steps from the published workflow_step rows. 19 of the 32 have no database row at all (fix, triage, ops, release…), so they are the only record of those designs. Read them for intent, never for what runs. See compass/archive/workflows/README.md.
• .claude/skills/ — slash commands, most of which map to workflows the app cannot run.
• prose inside the code — migration headers, module docstrings, the ### Task: sections. These record why a change was made ON THE DAY IT WAS MADE; app/supabase/MIGRATIONS.md asks for exactly that ("the diff says what changed and the comment says why"). So a header's opening paragraph is usually the BEFORE state, written to justify the change shipping in the same commit — 047_backlog_item opens "draft-epics produced a DOCUMENT" inside the very commit that stopped it doing only that. Read them for reasoning. Never quote them for current behaviour.

What runs is the database, loaded from compass/seed/*.csv. There is no longer a check that compares it to a second description; if two places disagree, the published workflow_step rows win.

Runtime notes

Shape, not discipline — these make a tool efficient here and never override a task's own rules.

• Read over web fetch for files in the workspace
• Edit over Write for existing files — sends only the diff
• background execution for long-running processes
• gh CLI for GitHub

Capturing work

Framework work is tracked in GitHub. There is no improvement log in the repo.

• the why → a GitHub issue in vivekschaudhary/compass, labelled and milestoned
• the change → a PR that closes it (Closes #N)
• the shipped summary → CHANGELOG.md + Releases

Consumer projects track their work in Jira and Confluence, not GitHub issues.

Refusal rules

Generic to this runtime. Task-specific rules live in the agent files.

1. Do not skip HITL gates. They are hard stops.
2. Do not skip steps silently. A declined step is logged with its rationale.
3. Do not amend commits unless asked. A pre-commit failure means the commit did not happen — fix, re-stage, make a NEW commit. --amend rewrites the previous one and can destroy work.
4. Do not force-push to main. Warn if asked.
   • 4a. Write-mode work on product code lands on a branch. Framework-doc edits to this repo's main are the standing exception the user has authorised; product code changes are not.
5. Do not skip git hooks (--no-verify, --no-gpg-sign) unless explicitly asked.
6. Do not commit secrets.
7. Do not run destructive git (reset --hard, push --force, clean -f, branch -D) unless explicitly asked.
8. Grep before committing a load-bearing amendment. A rename, a count, a version string, a contract surface: run python3 compass/scripts/pre-push-consistency-check.py "<old phrasing>" and sweep every hit in the SAME commit.
9. The mechanical backstop. compass/scripts/consistency-check.py computes the drift classes that keep recurring. Enable the shared hook once per clone: git config core.hooksPath compass/scripts/githooks.
10. Ship tests alongside new code paths. A new write path, parsing behaviour or capability lands its tests in the same commit — creation, the new behaviour, and the edge and failure cases. Run python3 -m unittest discover -s compass/orchestrator/tests and npm --prefix app test before committing.
11. Fail loud, not silent. Default a failure's direction toward a loud halt. A swallowed failure — a silent pass, a NULL that reads as "nothing wrong", a default standing in for a missing answer — is worse than a crash because it is indistinguishable from success. Aggregates over zero rows are the classic case: the guard finds no blockers and the gate passes because there was nothing to check.
12. Inspect the output, not the exit code. A process can succeed and produce the wrong thing.
13. A data surface gets a test through the real vertical on a prod-like build — authenticate as a real user, hit the authorization-enforced query, assert on what comes back. A unit test over a mocked client cannot see an authorization rule that is wrong.
14. Reproduce before diagnosing. An explanation built on a story about the failure, rather than on the failure itself, fixes the story.
15. Claim only what you checked, at the scope you checked it. "No code reads this" after grepping one file extension, a count read off a list instead of counted, a defect inferred from one row without checking the row next to it — each is a true observation reported at a wider scope than the evidence covers, and it is indistinguishable from a verified fact to whoever reads it. Widen the check or narrow the sentence.

Before you write

1. compass/framework/mvp-brd.md — what is being built
2. the code you are changing, and its tests
3. PROJECT.md if present

Skipping (1) is how a session ends up building something the BRD already decided against.

Lessons this repo keeps re-teaching

Every one shipped green and was caught by probing behaviour, not by reading output.

• A migration reported "Finished" and changed nothing — if not exists (conname = ...) found a same-named constraint from an older migration and skipped. A named constraint that must CHANGE is dropped and recreated; migrations assert their own effect.
• A checker carried the literal it was policing — consistency-check.py hardcoded "N of 18 workflows", so adding a workflow made the checker the stale claim. Compute both numbers.
• A diff that omits a field reports "unchanged" — the importer's step key lacked nests and title, so a row could change what it nested and the import called it identical.
• Identical created_at is not an ordering. A phase writes every row in one transaction.
• A rename is a writing job. Blind substitution produced "The epics is published", and a slash-anchored pattern never saw Path("docs") / "bets".
• Fixing the caller and not the callee leaves the bug alive: open_phase_run got a fallback its own first task never used, because that task comes from open_workflow_run.
• A test can outlive the behaviour it tests. Removing a check left a test asserting the removed behaviour; it failed for the right reason and had to be rewritten, not deleted quietly.
• Deleting a document is not a documentation change. Removing improvements.md touched two scripts' lists, a test, four docstrings and two templates. Grep for the path, not just the prose.