# Configuration You can control how Rookery works on a repository. Put the configuration files in the repository. Rookery reads them from the base branch at the start of each job. Rookery does not read configuration from the branch that the agent changes. Thus a change to the configuration has an effect only after a person merges it to the base branch. ## Files | Path | Purpose | | --- | --- | | `CLAUDE.md` | Instructions for the agent. Rookery reads only the file at the root. The maximum size is 64 KB. | | `AGENTS.md` | Rookery reads the root `AGENTS.md` when there is no root `CLAUDE.md`. If the two files exist, Rookery uses `CLAUDE.md` only. The run log shows which file Rookery read. | | `.rookery/workflow.json` | The agent, the skills and the instructions for each part of a run, and the other repositories that an issue can change. | | `.rookery/agents/<name>.md` | Agents for Rookery only. | | `.rookery/skills/<name>/SKILL.md` | Skills for Rookery only. | | `.claude/skills/<name>/SKILL.md` | Skills that your developers also use. | If you do not add these files, Rookery uses its default workflow with no skills. ## workflow.json The file has one entry for each slot. A slot is one part of a run: - `plan`: the planning. - `task`: each task. - `review`: the review after the last task. - `pr-review`: the review of a pull request that a person asks for (see [Workflow](workflow.md)). - `after`: a list of extra steps before the review. It can also have `with`, a list of other repositories that an issue can change (see below). Each slot can set: - `agent`: the name of the agent to use. - `skills`: a list of skill names. - `instructions`: text that Rookery adds to the instructions of the agent. ```json { "plan": { "skills": ["repo-recon"], "instructions": "Every schema change gets its own task." }, "task": { "skills": ["verification-before-completion"] }, "after": [ { "agent": "reviewer", "mode": "check", "skills": ["security-review"] }, { "agent": "docs", "mode": "write", "skills": ["changelog"] } ], "review": { "agent": "reviewer" } } ``` If you do not set a key, Rookery uses the default value for that key. If the file is not valid, or if it names a skill or an agent that does not exist, the job fails at the start. Rookery writes the error in a comment. It does not use the default workflow in place of a configuration that is not correct. ## Agents Rookery has four agents: - `planmaker` writes the plan. - `reviewer` reviews the full change. - `pr-reviewer` reviews a pull request when a person asks for it. - `scope-checker` finds changes that the plan did not ask for: refactors, abstractions, flags and defensive code. No slot uses it by default. To use it, add `{ "agent": "scope-checker", "mode": "check" }` to `after`. The tasks do not use an agent. They use the default Claude harness. To add an agent, write `.rookery/agents/<name>.md`. Use the Claude Code agent format. The frontmatter can have only these keys: `name`, `description`, `tools`, `model` and `skills`. An agent with the name `planmaker`, `reviewer`, `pr-reviewer` or `scope-checker` replaces the agent of Rookery with that name. Names use only lower-case letters, digits and hyphens. ### Use your own pull request reviewer | To do this | Do this | | --- | --- | | Change the instructions of the Rookery reviewer | Write `.rookery/agents/pr-reviewer.md`. | | Use an agent with a different name, skills or instructions | In `.rookery/workflow.json`, write `{"pr-review": {"agent": "my-reviewer", "skills": ["security-review"]}}`. Then write `.rookery/agents/my-reviewer.md`. | | Do the same for all repositories of an owner | Put the same files at the root of `<owner>/.rookery`. | Rookery reads the reviewer from the base branch, not from the pull request. Thus a pull request that changes `.rookery/agents/pr-reviewer.md` gets a review from the agent that is on the base branch now. ## Skills When a slot names a skill, Rookery tells the agent to use that skill in each step of the slot. Rookery also gives the agent a list of the other skills in `.rookery/skills/`, `.claude/skills/` and `<owner>/.rookery`. The agent uses a skill from this list only when the description of the skill agrees with the work. If a skill must run each time, name it in the slot. If two skills have the same name, Rookery uses the first one that it finds in this order: 1. `.rookery/skills/` 2. `.claude/skills/` 3. The owner defaults (see below) 4. The catalog of Rookery The frontmatter of a skill can have only these keys: `name`, `description`, `allowed-tools`, `argument-hint` and `disable-model-invocation`. ### Skill catalog | Skill | Slot | Purpose | | --- | --- | --- | | `repo-recon` | plan | Read the repository before the plan. | | `verification-before-completion` | task | Check the work before the task is complete. | | `systematic-debugging` | task | Find the cause of a bug before it changes the code. | | `security-review` | check, pr-review | Look for security problems in the change. | | `changelog` | write | Add an entry to the changelog. | The portal shows the catalog in **Skills**. ## Extra steps (after) `after` is a list of a maximum of 5 steps. The steps run in order, after the last task and before the review. Each step has a `mode`: | Mode | Can change files | Replies | Result | | --- | --- | --- | --- | | `check` | No. Rookery reverts all changes and marks the run. | `check-ok` or `changes-needed` | The agent gives its findings as JSON. Rookery writes them into the pull request body as a verdict and a list of findings. `changes-needed` sets `rookery:changes-wanted`. The push continues. | | `write` | Yes | `step-done` or `failed` | Rookery commits the change as `#<n> step <agent>`. `failed` stops the run. | When you approve again, Rookery does not repeat a `write` step that has a commit on the branch. It runs each `check` step again. ## Change more than one repository (with) An issue can need a change in two repositories. For example, a field in the API and the page that shows it. To let Rookery change a second repository, add its name to `with`: ```json { "with": ["sa-es-ir/shop-frontend"] } ``` The repository of the issue is the home. Each repository in `with` is a companion. - The list has a maximum of 3 repositories. - Each companion has the same owner as the home. The Rookery App must be installed on it. - Rookery reads `with` only from `.rookery/workflow.json` of the repository. It does not read `with` from the owner defaults. On each issue, Rookery gives the agent a worktree for each companion. The plan agent decides which repositories the issue needs. When the run is complete: - Each companion that has changes gets a branch `feature/<home>-issue-<n>` and a draft pull request. Its body names the issue and the pull request of the home. It does not close an issue. - The pull request of the home lists the companion pull requests under **Companion PRs**. - A companion that has no changes gets no branch and no pull request. The labels, the comments, the caps and the API key are the ones of the home. Rookery never puts a label or a comment on an issue of a companion. Merge the pull requests together. Rookery does not merge them. To approve, or to ask for a follow-up, you must have write access to the home and to each companion. Replies during planning need write access to the home only. A companion can add skills and agents from its `.rookery/skills/`, `.claude/skills/` and `.rookery/agents/`. If the home already has a skill or an agent with the same name, Rookery uses the one of the home. Rookery also gives the agent the `CLAUDE.md` of each companion. It does not read the `workflow.json` of a companion. If an issue names a repository of the same owner, for example `sa-es-ir/shop-frontend`, and `with` does not list it, Rookery writes a comment that tells you how to add it. The run continues with the home only. The plan lists what the other repository needs. After you add the repository to `with`, reply on the issue to make the plan again. In the portal builder, drag a repository from **Repos** on the shelf onto **Repos** at the top of the workflow. Drag it back to the shelf, or select ×, to remove it. ## Owner defaults To use one configuration for all repositories of an owner, make a repository with the name `<owner>/.rookery`. Install the App on it. Put these at the root of that repository: - `workflow.json` - `agents/` - `skills/` The configuration of a repository wins over the owner defaults, one key at a time. An `after` list in a repository replaces all of the `after` list of the owner. ## Change the configuration from the portal Open a repository in the portal and select **Workflow**. You see the workflow that the next issue gets. If the configuration is not valid, you see the error that the job will show. Select **Advanced: edit the files as text** at the bottom of the page. Use **Propose a change** to edit `workflow.json` or an agent file. Rookery checks the change. Then it opens a pull request. Nothing changes until a person merges the pull request. You must have write access to the repository. To change the workflow without JSON, use the builder at the top of **Workflow**. In the builder, a slot shows as a stage. Drag an agent or a skill from the shelf onto a stage. Drag the agent of one stage onto another stage to swap them. Drag a skill to the shelf to remove it. Drop an agent on **Drop an agent here** to add a step after the tasks. If you cannot drag, click a box, then click the place for it. The builder changes `workflow.json` in the editor below it. When you change something, a bar at the bottom of the screen shows the number of changed files. Select **Open pull request** in that bar. Select **Discard** to remove all changes. ## A pull request that changes the configuration If a branch of Rookery changes `.rookery/`, `.claude/`, the root `CLAUDE.md` or the root `AGENTS.md`, the pull request starts with a warning. Review that change carefully. After you merge it, it controls the agent on the next runs.