Write your first writ

This procedure creates a writ, runs it, and shows the result. The example agent makes one failing test pass.

Before you start, do these two things:

Install Writ.
Configure the engagement. The registrar cannot engage a model without a configuration.

1. Create the file

Go to the root directory of your project.
Run this command:
Terminal window
```
writ init bug-fixer
```

The command creates bug-fixer.yaml. The file contains the three necessary fields and some example bounds in comments.

writ: bug-fixer
mandate: ""
grants: []

# bounds:
#   iterations: 25
#   cost: $1.00
#   wall_clock: 15m

To include each optional field, add the --full flag.

2. Write the terms

Open bug-fixer.yaml.

Replace the contents with these terms:

writ: bug-fixer
mandate: "The failing test {failing_test} passes without breaking other tests."

grants:
  - read:  { paths: ["**/*"] }
  - shell: { commands: ["pytest *"] }
  - edit:  { paths: ["src/**"] }

bounds:
  iterations: 40
  cost: $2.50
  wall_clock: 20m

invariants:
  - { layer: letter, no_edits_outside: ["src/**"] }

satisfaction:
  all:
    - { layer: letter, run: "pytest {failing_test} -x -q", exit: 0 }

remedies:
  on_bound_breach: { do: halt, inform: issuer }

The name in braces is a placeholder. You give the placeholder a value when you issue the writ. Read more about placeholders.

The invariants clause stops the agent from a change outside src. The satisfaction clause is the proof of completion: the test command must exit with code 0.

3. Validate the file

Run this command:
Terminal window
```
writ check bug-fixer.yaml
```
If the command prints an error, correct the file. Then do step 1 again.

The command prints bug-fixer.yaml: valid when the file is correct.

To see the terms with each default value applied, add the --explain flag.

4. Issue the writ

Run this command. Use the name of a test that fails in your project:
Terminal window
```
writ issue bug-fixer.yaml --set failing_test=tests/test_sync.py::test_retry
```

The registrar starts the run. The registrar shows each action, each check, and each decision while the run continues.

The run stops for one of these three reasons:

The satisfaction clauses pass. The exit code is 0.
A bound stops the run, or an invariant stops the run. The exit code is 1.
An error stops the run. The exit code is 2 or 3.

5. Read the record

Run this command:
Terminal window
```
writ record bug-fixer
```

The command shows the last run. Each line shows one action and the checks that applied to that action.

To see the record in a browser, add the --web flag:

writ record bug-fixer --web

Add a limit that the agent broke. Read about bounds.
Stop a behaviour that the record shows. Read about invariants.
Add a check that a person makes. Read about the three check layers.