Working in this repository

The shared contract for every coding agent in every tale-project repository. Read it, then read .agents/repo.md — the repo-specific contract — before your first change.

Repositories are Bun workspaces (with Turborepo where there is more than one workspace); a workspace script runs through bun run --filter <workspace> <script>.

Read the repo contract next

.agents/repo.md is the per-repo file: layout, stack, domain rules, extra gates, and the debt ledger. This shared file never carries repo facts — if a fact is specific to one repository, it belongs there. When the two seem to disagree, the repo contract wins.

How to work

The biggest quality lever is deciding well, not typing fast. Work in this order:

1. Classify the task and follow its discipline end-to-end: a defect (find the root cause, lock it with a regression test); structure-not-behaviour (refactor without changing behaviour); new behaviour (a feature, screen, endpoint, or flag); a review (an adversarial read before merge). Exploring is read-only and returns the conclusion; a migration is phased and reversible, each phase green.
2. Write a short planning note first — capture intent, status quo, and plan before any edit; keep scratch files in your global notes directory, never in the clone.
3. Unknowns outside the repo? Research before deciding — questions first, sources in order, evidence in the note.
4. Search before you write — orient, find the concept to reuse, enumerate the blast radius. The request names one site; the task is the concept.
5. UI in scope? Learn the repo's design system first — where it lives is in .agents/repo.md — then build to it.
6. Too big for one thread? Split it into disjoint units with complete briefs; you keep the done-gate.
7. Do the work thin and reversible, following the discipline you classified — ask the moment a fork or roadblock appears; never guess.
8. Prove it — tests carry the change; observe the real outcome; drive web UIs in a real browser.
9. Review your own diff — adversarial read, then the automated reviewers.
10. Land it — meet the shared definition of done, atomic commits, pushed straight to main; no branch and no PR unless the repo contract says otherwise. The autonomous development cycle's tasks ride the repo's merge train instead, where it runs one.

Every code-writing task passes two gates. Gate A — before code: note · intent · status quo · reuse · conventions · blast radius — a divergent second copy of an existing concept is a defect, not a feature. Gate B — before done: the shared definition of done — green gate · security · tests · migration/data · locales (where the repo ships them) · docs · accessibility · sweep · observed · commits. Never claim a success you haven't observed.

Discover the conventions — don't memorize them

This file does not list the coding rules; the repo's own tooling does, and it can't drift. Read the enforced source and match it (orient in the repo first, then read the surrounding code):

The guards are the spec — run bun run check and read the failures; they teach the house style faster than prose. When you add a rule, add its guard — a rule no test enforces rots.

Manual tests

Every deployable unit carries a manual layer at <unit>/tests/manual/, in the same shape in every repository, scaffolded by the generator and gated by bun run lint:manual. It holds what a headless run cannot judge — layout, focus, print, live reactivity across two sessions, degraded modes, exploratory pokes:

Suites and rounds are separate things. A suite is a test: evergreen, re-runnable, and never carrying a tick or a finding. A round is history: it ticks a session log outside the repo and lands as one record in runs/. A box is one line — - [ ] `ID` · **action** → judgment. — and its ID is a stable contract: each suite declares the prefix its boxes carry, IDs are unique per unit, and you append, never renumber. Ship new behaviour with its box, or with a row in reference/automation.md when a spec owns it end to end.

Non-negotiable boundaries

Safety and architecture invariants — they hold even where no linter covers them:

• Never destroy state without explicit permission — local databases, caches, config files, seed data, fixtures. Assume every file on disk is the user's in-progress work.
• Secrets live in environment variables only — never hardcode or commit them; scrub logs.
• Validate at every boundary — user input, external APIs, webhooks; parameterized queries only, never string-built SQL or shell.
• Accessibility is WCAG 2.1 AA — real HTML, keyboard reachable, visible focus, labelled controls, AA contrast.
• Commits follow .commitlintrc.json (atomic, imperative, ≤72-char header) and land directly on main — no feature branch, no pull request, unless the repo contract says otherwise. The merge train is the exception every repository that runs one shares: the autonomous development cycle works each task on a branch off train and opens no pull request, its reviewer squashes the task into one commit on train, and train reaches main in one pull request per train (train-<YYYYMMDD-HHMM>); the repo contract says when a train departs, how its pull request is checked and who lands it. Never add Co-Authored-By or "Generated with Claude Code" / any attribution line — .husky/commit-msg strips such trailers before commitlint runs.
• Branches — where the repo contract asks for one, name it for the work, never for the tool that did it: <type>/<kebab-slug> with a type from .commitlintrc.json (feat/, fix/, refactor/, docs/, chore/, ci/), or dist/ for published build output. Never an agent-vendor namespace (codex/…, claude/…, cursor/…); renovate/ and automated/ belong to the bots, train and train-* to the merge train.
• A change is rarely one file — sweep the concept's blast radius: a user-visible string → every locale the repo ships (+ docs); a new UI element → label + a11y + docs + tests; an env var / flag / API field → docs + .env.example + the READMEs. The guards catch the big ones — run them.

• One TypeScript config — a workspace tsconfig.json is exactly one key, extends, and holds NO compilerOptions, include, or exclude. Every option lives in the root family, and a leaf picks the member that fits:

  Member	Adds
  tsconfig.base.json	everything; bun + node types, no DOM
  tsconfig.dom.json	the DOM libs
  tsconfig.vite.json	DOM + vite/client
  tsconfig.node.json	node types ONLY — for code that runs on node
  tsconfig.strict.json	noUncheckedIndexedAccess
  tsconfig.convex.json	Convex's required settings

  The base reaches into each workspace through ${configDir}, so include/exclude need no per-leaf copy. Need an option one workspace alone wants? Add a family member — never a key in the leaf. Unused locals/params are the LINTER's job (eslint/no-unused-vars, which honours the ^_ prefix); never add noUnusedLocals/noUnusedParameters here, or the two guards disagree.

• Scaffold a new part (package / service / tool / skill) from a template (bun run gen …), never hand-rolled — so it carries the standard configs, the test layout and the manual layer.
• Reach for a well-known, maintained library before hand-rolling — prefer the established package over a custom solution; write it yourself only when no suitable library exists.
• Instructions are docs too — change a path, command, or pattern a skill or an agent contract documents, and update it in the same change.

Skills

Repo-dev skills live in .agents/skills/; bun run skills:sync mirrors them into .claude/skills/ as a plain copy — Claude Code reads the mirror, while Cursor/Codex/Copilot read .agents/skills/ directly. After editing a skill, run bun run skills:sync; never hand-edit the .claude/skills/ mirror. Each repo's skill index lives in .agents/repo.md.