Repo Instructions

Repo instructions are the durable context layer for local Mogplex work.

Use them for facts that should survive across prompts: repo layout, build commands, verification rules, ownership boundaries, style conventions, and known workflow constraints.

Do not use them as a scratchpad for one temporary task. The current prompt is still the right place for volatile instructions.

What Mogplex reads

The CLI runtime can load two repo-local files:

AGENTS.md is the main file. agent.json is useful when a project needs a small structured override beside the prose instructions.

Discovery order

Mogplex discovers instruction fragments from the current working directory and the active Mogplex home directory.

The current discovery model is:

1. $MOGPLEX_HOME/AGENTS.md for user-level guidance.
2. the git project root's AGENTS.md.
3. nested AGENTS.md files between the project root and the current working directory.

Within each directory, AGENTS.override.md wins over AGENTS.md.

That gives you three useful layers:

Keep the project-root file broad. Put package-specific exceptions closer to the package that needs them.

Session behavior

Instruction files are startup context for the run, not live chat messages.

Mogplex assembles the system prompt by combining the base runtime prompt, discovered AGENTS.md fragments, and the supported agent.json prompt suffix. The assembled prompt is cached for the session.

If you change instruction files while a session is already running, treat the next session as the clean verification point unless the surface you are using explicitly reloads project configuration.

Create a starter file

In the CLI composer:

/init

/init asks Mogplex to scan the repo and create:

• AGENTS.md
• .agents/commands/review.md

Use the generated file as a draft. Read it before trusting it, especially in a large repo where build and test commands may be conditional.

Good AGENTS.md content

Good repo instructions are short, operational, and checkable:

# AGENTS.md

## Commands

- Install: `pnpm install`
- Lint: `pnpm lint`
- Typecheck: `pnpm types:check`
- Build: `pnpm build`

## Repo Rules

- Use `rg` for source search.
- Keep docs claims grounded in sibling app and CLI repos.
- Do not hand-edit generated command reference files.
- Preserve unrelated dirty worktree changes.

## Verification

- For docs-only edits, run `git diff --check`.
- For TypeScript or MDX structure changes, run `pnpm types:check`.

Prefer commands and rules over philosophy. A future run should be able to use the file without asking what the sentence means.

agent.json

agent.json is a strict JSON object at the project root.

The current schema accepts:

{
  "model": "anthropic/claude-sonnet-4-6",
  "system_prompt_suffix": "Prefer focused fixes and cite touched files.",
  "disabled_tools": ["example-tool"],
  "extra_slash_dirs": [".agents/team-commands"],
  "personality": "direct"
}

Use system_prompt_suffix only for short, durable behavior that belongs after the markdown instructions.

For model routing, managed access, and tool policy, prefer the first-class Mogplex controls unless the specific surface you are using documents that it honors the agent.json field.

What not to put here

Avoid:

• secrets, tokens, API keys, or passwords
• task-specific notes that only matter today
• long copied docs from external systems
• instructions that contradict the repo's actual scripts
• broad personality prose that does not change execution

If a sentence cannot guide a future command, edit, test, or review decision, it probably does not belong in repo instructions.

Related reusable layers

Read next