Project instructions

Titah reads instruction files from your repository and puts them into the system prompt, so a project can tell every agent the same things without anyone retyping them.

Read order

Titah reads, in this order:

1. AGENTS.md
2. CLAUDE.md
3. TITAH.md

…walking up from the working directory to the git root. The file closest to the working directory is read last, so it wins.

TITAH.md comes last in the per-directory order too, which makes it the Titah-specific override: a repo that already has AGENTS.md for everyone can add a short TITAH.md for the things only Titah needs to know.

Naming your own files

{ "instructions": "titah-instruction.md" }
{ "instructions": { "path": "titah-instruction.md" } }
{ "instructions": ["a.md", { "path": "docs/house-style.md" }] }

All three forms mean the same thing. The single form is accepted because it is what people write first, and rejecting a config whose meaning is already obvious only moves work onto you. The object form follows skills.paths, which already takes string | { path } — two axes that both point at files should be written the same way.

Files are created rather than silently missing

A declared instruction file that does not exist is created on the first turn of a session, and a project with no instruction file at all gets a starter AGENTS.md. A path in the config that quietly resolves to nothing is a rule everyone believes is in force and nothing is enforcing.

{ "scaffold": false }

turns all of it off — nothing is written that you did not ask for.

What belongs in them

Things that are true about the project and would otherwise be retyped every session:

# AGENTS.md

- Code comments in this repository are written in Indonesian; the user-facing
  interface and all documentation are in English.
- `config.schema.json` is generated from `src/core/schema.ts` — never edit it by
  hand. Run `npm run schema` after changing the schema.
- `npm test` builds `dist/` first: the TUI tests render real Ink components, and
  Node cannot load `.tsx` directly.

What does not belong in them

• Credentials. Instruction files are committed. Use auth.json or ${env:VAR} — see Credentials.
• Anything that changes per session. Use plan for intent that dies with the session, or memory for a durable project fact recorded by the model itself. See Tools.
• Permission policy. An instruction file is a prompt; it cannot stop a tool from running. Use permission in the config, which is checked before execution. See Permissions & undo.

That last point is the important one: an instruction file persuades, it does not enforce.

Interaction with skills

Instruction files and skills solve different problems. An instruction file is loaded for every turn in this repository. A skill is loaded when it is relevant — either because you invoked it, an agent declares it, or the model picked it out of the catalogue.

If a piece of guidance is only relevant to one kind of task, it belongs in a skill; if it is true of every change made in the repository, it belongs in an instruction file. See Skills.