agents.md & project rules

agents.md is a Markdown file at your repo root that tells Friday how this codebase wants to be worked on: where things live, how to run the tests, what to never touch. Friday reads it at session start and inlines its contents into the system prompt of Dispatch and every worker thread, so your conventions show up on every turn without you re-typing them. The format follows the agents.md and agentskills.io conventions, which means a single file works across Friday, Claude Code, Codex, and any other agent that adopts the standard. In Friday, agents.md plays the role CLAUDE.md plays in Claude Code.

Where Friday looks

Friday checks the project root in this order and uses the first file it finds:

agents.md (primary, current convention).
.fridayrules (legacy Friday-specific fallback, still supported for older projects).

Friday does not read CLAUDE.md. If you're migrating from Claude Code, rename your existing rules file to agents.md (or copy its contents into one). The .claude/ discovery root is still read as a Claude-compatible source for skills, commands, and subagents, but project rules specifically have to live in agents.md or .fridayrules.

A user-global file at ~/.agents/agents.md is applied on top of every project's rules. Use it for personal preferences that apply across every repo, like "always run pnpm format after edits" or "prefer rg over grep".

What goes in it

Keep it tactical. The file is in every prompt, so length costs tokens on every turn.

Good fits:

Build, run, test, and lint commands. How to run a single test.
Where the source lives, where the tests live, where the docs live.
Code style preferences ("Pydantic v2 for models," "tabs not spaces," "no default exports").
Hard rules ("never run db migrate against prod env," "don't touch vendored/").
Post-edit commands you want every thread to run ("pnpm format after edits to app/").

Poor fits:

Sprint goals, ticket assignments, and other things that decay quickly.
Long code samples. Friday can read source faster than it can parse a code block.
Secrets, tokens, or credentials.

Example

# Project rules

## Stack

- Python 3.12, FastAPI, Pydantic v2.
- Frontend: Next.js 15, TypeScript strict mode.

## Commands

- Tests: `pytest tests/` (single test: `pytest tests/path::test_name`).
- Lint: `ruff check . && ruff format .`.
- Frontend: `pnpm dev`, `pnpm build`, `pnpm typecheck`.

## Conventions

- New API routes go in `app/api/`. Add a Pydantic model for every response.
- Database migrations: write them by hand in `migrations/`. Do not autogenerate.

## Don't

- Never edit `vendored/`. It's a snapshot.
- Don't run `db migrate` outside the local Docker compose stack.

Generating one

Run /agentsmd from inside Friday. It inspects the project and drafts a baseline agents.md. Edit it before committing; the draft is a starting point, not the final form. Re-run /agentsmd later to refresh it as the codebase evolves.

Per-user vs per-project

Per project. agents.md lives at the repo root and is committed. Everyone on the team gets the same rules.
Per user. ~/.agents/agents.md holds rules that apply to every project you open with Friday. There is no Claude-style fallback here either: Friday does not read ~/.claude/CLAUDE.md.

The two layer, with project rules taking precedence on overlap.

Worker threads see it too

In GIT mode every worker thread runs in its own git worktree, but agents.md is a tracked file in your repo, so it lives inside every worktree the same way any other source file does. You don't have to do anything special. Edit agents.md, commit, and the next thread that spawns picks up the new rules.

If you want a thread that's already running to see a change, restart it; the system prompt is built when the thread spawns.