BeatFlow

Use Codex for musical decisions. Use the bundled engine for exact timing,

functional pitch realization, voicing, validation, diagnostics, compilation,

MIDI rendering, and inspection.

Runtime

Refer to this skill directory as `<skill-root>` and run:

```text

python "<skill-root>/scripts/run.py" <command> ...

```

Require Python 3.10 or newer. Write composition scripts and generated

artifacts in the user's workspace, never in `<skill-root>`.

Workflow

1. Extract duration, form, tempo, meter, tonal language, instrumentation,

energy path, priorities, and exclusions from the brief. Make reversible

assumptions for missing details.

2. Classify each instrument as `essential`, `substitutable`, or `optional`.

Separately classify its prominence as `primary`, `co-primary`, `support`,

or `background`. Preserve essential instruments and repair their writing,

balance, or playback program before considering a contract change.

3. Read [composition-guidance.md](references/composition-guidance.md) and

[composition-format.md](references/composition-format.md). Read

[phrasing-and-coordination.md](references/phrasing-and-coordination.md)

for prominent melody, thematic development, complex meter, or timing

repair. Read [long-form.md](references/long-form.md) for work longer than

90 seconds. Read [diagnostics.md](references/diagnostics.md) when revising

or comparing candidates. Load

[research-foundations.md](references/research-foundations.md) only when

methodological evidence is useful.

4. Plan before writing events:

- frame: duration, sections, tempo, meter, tactus, tonic, and mode;

- phrase: grouping, harmonic rhythm, attention, arrivals, and releases;

- skeleton: pulse, bass, harmony, role entries, rests, and handoffs;

- foreground: rhythmic identity, contour, density, texture, and structural

tones;

- decoration: fills, secondary attacks, counterlines, and articulation.

5. Render the quantized skeleton before adding foreground. Keep at least one

stable time reference and make important harmony changes and arrivals

perceptible. Treat foreground as optional; a bass hook, designed chord top

line, or rhythmic texture may already lead attention.

6. Author a trusted Python file whose `build()` function returns

`Composition`. Use `SongBuilder`; let style affect the authored music, not

the schema or compiler.

7. For a complete song, separate reusable section material from timeline

occurrences. Use occurrence development and `arrange()` treatments to

create formal change without copying whole sections.

8. For quality-sensitive melody or thematic work, audition short,

structurally different candidates before expanding the form. Compare

rhythm and duration without pitch decoration, preserve an early

recognizable statement, and select by listening.

9. Render the selected candidate:

```text

python "<skill-root>/scripts/run.py" compose "<output>/<name>.py" "<output>/<name>.mid" --composition-output "<output>/<name>.composition.json" --project-output "<output>/<name>.project.json" --report "<output>/<name>.report.json"

```

10. Treat validation errors as hard failures. Treat diagnostics as evidence

against the written intent, not as taste scores. Revise the highest causal

layer responsible, rerender, and listen again.

11. Report the musical design, assumptions, validation result, diagnostic

findings, MIDI facts, and any decisions that still require listening

judgment.

Core constraints

only when the user explicitly requests a timing experiment, and preserve a

quantized baseline.

beat. Use `song.at()`, `song.tactus()`, and `song.bars()` for meter-aware

plans.

musical function.

primary arrival. Use `phrase()`, `phrase_stage()`, and `arrival()` when

their intent needs to be testable.

Use `interaction()` when independence, interlocking, call-and-response, or

handoff is central to the brief.

Add a separate lead only when it has a clear complementary role.

next attack.

Revision

Diagnose in this order:

1. meter and shared clock;

2. role ownership and instrument contracts;

3. phrase grouping, gesture continuity, and arrival;

4. harmonic rhythm, bass support, and voicing;

5. pitch contour and non-chord-tone behavior;

6. articulation, balance, and playback timbre.

Use three simple comparisons before adding rules:

Repair causal structure rather than isolated notes. Do not use random density,

arbitrary jitter, blanket humanization, or a new genre-specific engine rule as

a shortcut.

Commands

Use `project-schema`, `project-validate`, and `render-project` only for the

low-level compiled Project boundary.

Boundaries

living artist.

destination instruments or DAW.