# Repository conventions

Every team has its own idea of the right reading order. A conventions file tells LogiKFlow and your AI agents how *your* repository should be arranged, so every pull request in it is ordered the team's way.

## Add the file

Create `.github/logikflow.md` on the repository's default branch. It's plain Markdown: write what you'd tell a new teammate about reviewing this code base.

LogiKFlow reads the file from the pull request's **base branch**, so a PR that changes the conventions is still arranged by the current rules.

## What agents do with it

When an agent calls `get_pull_request`, the file comes back as `repoConventions`, and `get_ordering_guide` includes it too if you pass the owner and repo. The [ordering guide](/docs/ordering-guide) tells agents to follow your conventions, and that **your rules win** where they conflict with the general ones.

## A checklist section

Any heading that contains the word **checklist** starts a list of default checklist items. In arrange mode, **Add the team checklist** adds them to the order in one click, and agents add them to the most relevant section. Up to 20 items are used.

## Diagrams

Add a `diagram:` line anywhere in the file to decide whether agents draw a [flow diagram](/docs/agents#diagrams):

- `diagram: ask` (the default): after arranging, the agent asks the person whether they want one.
- `diagram: always`: the agent draws one for every pull request, without asking.
- `diagram: never`: the agent never offers one.

## Example

This is what a conventions file for an Android app might look like:

```markdown
# Reviewing this repository

## Order
- Feature flags and settings keys first, then models, then storage.
- Controllers before views; dependency injection and app wiring go last.
- Put XML layouts after the Kotlin that inflates them, and strings last.
- Keep `build.gradle` and version catalog changes in their own section at the top.

## Notes
- Anything behind a flag: say what happens with the flag off.
- Mention if a change affects startup time or scrolling performance.

## Checklist
- With the flag off, behaviour is unchanged
- No disk or network work on the main thread
- New strings are in `strings.xml`, not hard-coded
- Analytics events fire once per action

diagram: ask
```

## Tips

- Keep it short. A page of clear rules beats a long style guide.
- Say *why* when a rule isn't obvious. Agents follow reasons better than bare orders.
- Only the first 20,000 characters are read.