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 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:

• 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:

# 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.