Using the agents

Examples

Ready-to-copy custom commands and agents from the AlbertCode repository, a contract, scripted runs, and how to write requests that plan well.

The custom commands and agents below are copied verbatim from the examples/ folder of the AlbertCode SWE Agent repository (Apache-2.0). Both agents read the same format.

Using them

For one repository, copy the files into .albertcode/commands/ or .albertcode/agents/ and commit them, so your team has them too:

Terminal

mkdir -p .albertcode/commands .albertcode/agents
cp examples/commands/review.md .albertcode/commands/
cp examples/agents/reader.md   .albertcode/agents/

For yourself across every repository, copy them into commands/ or agents/ in the agent's settings folder (see Configuration).

Commands

`/review <file>` — correctness review, without changing anything

Markdown

---
description: Review a file for correctness bugs, without changing it
agent: reader
mode: ask
argument-hint: <file>
---
Review $ARGUMENTS for correctness bugs, not style. For each problem, give the file and line, what
goes wrong and with which input, and how sure you are. Say plainly if you found nothing.

`/fix-test <test>` — fix the cause, not the test

Markdown

---
description: Find why a test fails and fix the cause
mode: governed
argument-hint: <test name or path>
---
The test $ARGUMENTS fails. Run it, find the root cause in the code under test, and fix that. Do not
change the test's assertions unless the test itself is wrong; if it is, say why. Run the test and
the tests around it again before you finish.

`/explain <path>` — onboarding a new teammate

Markdown

---
description: Explain how a module works, for someone new to it
mode: ask
argument-hint: <path>
---
Explain how $ARGUMENTS works to a developer who has just joined the project: what it is for, its
main entry points, how data flows through it, what calls it, and the parts that are easy to get
wrong. Point to files and lines rather than pasting large blocks of code.

`/add-tests <path>` — tests in the project's own style

Markdown

---
description: Add tests for untested behaviour, following the project's conventions
agent: test-writer
mode: governed
argument-hint: <path>
---
Find behaviour in $ARGUMENTS that no test covers, starting with error handling and edge cases.
Add tests for it in the style, location and framework the project already uses. Do not change the
code under test. Run the new tests and report anything they reveal.

Agents

`reader` — reads and reports; can never edit

Markdown

---
description: Reads and reports; never edits
tools: read, run
---
You are reviewing someone else's code. Be specific: file, line, the input that triggers the problem,
and what happens. Prefer one well-supported finding over several guesses.

`test-writer` — may only add and change tests

Markdown

---
description: Adds and changes tests only
tools: read, edit, run
---
You write tests. Change only test files and test fixtures. If a test you write fails because of a
bug in the code under test, report the bug instead of fixing it or weakening the test.

A contract that protects payments code

AlbertCode SWE Agent. Save as albertcode.contract.toml at the repository root and commit it:

TOML

version = 1
name = "shop"

[scope]
forbidden_paths = ["src/payments/**", "infra/**", "**/migrations/**"]
max_files_changed = 15

[verification]
required = true
must_pass = [["npm", "test"]]

[approvals]
require_admin_for_risk = ["high"]

Scripted runs

Terminal

# A question, with no changes possible
albertcode run "Why does the cart total round down?" --lane ask

# A governed change where you approve the plan from the script but read the result yourself
albert-mini run "add a health check endpoint" --approve plan
echo "exit code: $?"      # 3 means it is waiting at the result gate

# Every event as JSON lines, to read in the run planner afterwards
albert-mini run "add a test for cart totals" --approve plan --json > albertcode-run.jsonl

The run planner generates these for your shell — with the request safely quoted — and reads the .jsonl file back.

Writing requests that plan well

Name the outcome, not the implementation. "Make repeat charges safe" leaves the planner room; "add a dict cache in views.py" commits you to one design.
Say how you'll know it worked. "…and add a test that fails before the fix" gives verification something to prove.
Point at evidence. Attach the stack trace, the failing test name or a screenshot (/attach in the terminal, paste or drop in the browser).
Keep one change per request. A plan that names three files is easier to approve than one that names thirty.

A guide written for this site, covering both agents. For every command and setting, see the full reference for AlbertCode SWE Agent and mini-AlbertCode.