# Work with a coding agent

Any coding agent that can edit local files and run shell commands can work on a DAWN song. Give it the project directory and an outcome, then use the same check-and-render loop you would use yourself.

## Set up the project

Install DAWN using the [first-song prerequisites](/docs/first-song#install-dawn), then run `dawn init` in a new song folder. It creates `AGENTS.md` with the current project workflow and a `CLAUDE.md` that refers to it. Existing notes outside the DAWN-owned markers are preserved.

The agent should read `AGENTS.md`, `song.ts`, relevant track files and `.dawn/sdk/v1.ts` before editing. The SDK is a dependency-free TypeScript file with the exact types, defaults and JSDoc examples for the version this project uses.

## Give the agent a complete task

> Add a quieter piano answer in the chorus. Keep the existing bass and drum parts. Run the project check, then render a new WAV and a MIDI file.

Keep a copy or a commit of the project before a substantial edit. DAWN evaluates song source in a sealed engine with no file, network or process access, but a coding agent works with your own authority, so only run agents you trust.

## Use the edit loop

1. Edit `song.ts` or `tracks/<slug>/track.ts`.
2. Run `dawn check --json` and fix the reported problems.
3. Run `dawn render review.wav --measure` and inspect the result.
4. Run `dawn render review.mid` when you need an editable MIDI export.

`dawn check` exits zero after a successful check and one on a source problem. The JSON result carries diagnostics; ordinary text output also names the file, line and column. A project that needs a DAWN update or a format migration stops with exit three and a corrective command.

Use the vendored SDK’s existing builders, or update DAWN and review the SDK changes. `dawn migrate` shows a proposed migration; `dawn migrate --apply` writes it and retains a backup.

## Record requests and decisions

A project made by `dawn init` records a trace in `trace/`: each check, render and source change, including the edits the agent makes directly to `song.ts` and the track files, with the revision before and after. Ask the agent to add what only it knows: the request it was given, the decisions it made and a handoff before it stops.

```sh
export DAWN_TRACE_AGENT="Claude Code"   # or "Codex"; names the agent on captured commands
dawn trace note --kind prompt --text "Add a quieter piano answer in the chorus"
dawn trace note --kind decision --text "Piano an octave below the lead; bass and drums untouched"
dawn trace note --kind heard --text "The answer is audible at bar 17 without masking the vocal"
dawn trace note --kind handoff --text "Next: check the piano level against the pad, then render"
```

`dawn trace note` assigns the event ID and records against the project's current revision; it evaluates the project to learn that revision unless `--base` is given. Record concise reasons and observable results, not a whole conversation or internal reasoning. Credential-shaped text is replaced by `[redacted]`, but keep credentials out of notes in the first place.

`trace/` is committed with the song, so a `git push` publishes every prompt, note and comment recorded there. Run `dawn trace enable . --no-text` to keep metadata only, or `dawn trace disable .` to stop recording. The [trace reference](/docs/traces) lists what each command records.

## Pick the interface for the task

| Interface                                    | Use                                                                  |
| -------------------------------------------- | -------------------------------------------------------------------- |
| TypeScript SDK                               | Author notes, tracks, instruments, effects, automation and song form |
| `dawn check --json`                          | Read structured project diagnostics                                  |
| `dawn lint --json`                           | Check musical structure and register                                 |
| `dawn measure --json`, `dawn mixqa --json`   | Read audio measurements and mix checks                               |
| `dawn render`                                | Export audio, MIDI, stems or score JSON                              |
| `dawn workflow`                              | Inspect and resume durable song jobs                                 |
| `dawn changes --json`, `dawn migrate --json` | Inspect compatibility changes                                        |
| `dawn trace note`, `dawn trace read --json`  | Record and read requests, decisions, handoffs and project history    |

Preserve a quality report and its rendered input together. Optional learned judges, local models, vocals and media helpers have their own setup and compute requirements; use the [workflow guide](/docs/workflows) before invoking them.

The [CLI reference](/docs/cli), [SDK guide](/docs/sdk), complete [SDK API reference](/docs/sdk-index) and [score schema](/docs/score-format) describe these shared interfaces. The workflow uses local files and commands and works independently of an agent vendor.
