Writing a kickoff

A kickoff is the only input that matters. It is a markdown file that states an outcome precisely enough for a planner to decompose and for a verifier to disprove. Everything downstream — recipe choice, plan size, gates, verdict — is a function of how well the kickoff is written.

The shape

The shipped examples/01-hello-world kickoff is the minimal useful template:

# Kickoff: Add CHANGELOG Unreleased Entry

## Problem

The project has no record of the new `feature/session-token-rotation` work under the
`[Unreleased]` section of its `CHANGELOG.md`.

## Definition of Done

New entry exists in `CHANGELOG.md` under `## [Unreleased]`.

## Scope

Only `CHANGELOG.md` may be edited. No other file may be touched.

## Success Criteria

- `grep -A3 "## \[Unreleased\]" CHANGELOG.md` returns at least one bullet line.
- The new entry describes the session-token-rotation feature in plain language.
- No other file in the repository is modified.

## Model Preference

`claude-sonnet-4-5` (single-epic, low complexity — no need for Opus).

## Notes

This is an intentionally minimal kickoff.

Section	What it buys you
# Kickoff: <title>	One line naming the outcome; the classifier and planner both read it
## Problem	The defect or gap, with the evidence that it exists
## Definition of Done	The end state in one sentence
## Scope	The files or directories the change may touch — and an explicit exclusion
## Success Criteria	Checks that can be run, not qualities that must be judged
## Model Preference	Optional routing hint; the lane policy still decides
## Notes	Constraints, context, prior attempts

Scope is the strongest lever

Every failure mode of a plan is usually a scope failure. State the boundary in both directions:

## Scope

Only `src/tally.js` and `tests/tally.test.js` may be edited.
No other file in the repository may be modified.

A scope statement that names a directory without naming an exclusion invites the implementer to "fix" adjacent files. The scope gate compares changed paths against the plan and rejects out-of-scope edits; the tighter the statement, the fewer rejections there are to debug.

Success criteria must be executable

A criterion is usable when a command decides it. Compare:

Weak	Executable
"The code is cleaner"	python -m ruff check src/ exits 0
"The bug is fixed"	python -m pytest tests/test_tally.py -q exits 0, and tally([5]) == 5
"No regression"	the existing suite is green before and after
"Docs are updated"	grep -q "session-token-rotation" CHANGELOG.md

Write criteria the verifier can run without asking you what "clean" means. If a criterion genuinely needs human judgement, say so explicitly — a human gate is better than an unverifiable claim of success.

How the classifier reads it

mini-ork classify <kickoff.md> matches the document against every seeded task_class.yaml. Each task class declares what it matches on:

name: code_fix
description: "Single-patch code change: bug fix, small feature, refactor of a single function"
matches:
  keywords: [fix, bug, patch, update, refactor]
  path_globs: ["**/*"]
  regex: []
risk_class: medium

The classifier prints the winning class, its risk class and a confidence:

[classify]  task_class=code_fix  risk=medium  confidence=0.96

Two consequences for kickoff authors:

• Use the vocabulary of the class you want. A changelog edit that never says "fix", "update" or "document" can land in an unexpected class.
• A low confidence is a signal, not a failure. Force the recipe instead of wordsmithing the kickoff:

mini-ork run docs ./kickoff.md

To see every candidate, run mini-ork classify on its own. See CLI reference: lifecycle commands.

Sizing

One kickoff should have one outcome. The planner states its size up front:

[plan]  steps: 1  estimated_lines_changed: 5

Plan shape	What to do
1–3 steps, one file surface	Ideal — run it
4–8 steps, one subsystem	Acceptable; review the plan before executing
Many steps across unrelated subsystems	Split into separate kickoffs or an epic recipe
The planner keeps splitting into the same sub-tasks	The kickoff is contradictory; rewrite the Definition of Done

A kickoff that needs a paragraph of "also, while you're in there…" is two kickoffs. Use bdd-first-delivery or epic-runner when the work genuinely is multi-epic.

Failure modes

Symptom	Cause	Fix
Plan restates the problem without a change	No Definition of Done	Add the end state and file surface
Plan touches files outside the intent	Scope names no exclusion	Add "no other file may be modified"
Verify passes but the result is wrong	Criteria are descriptive, not executable	Add a command that fails on the wrong result
Classified into an unrelated recipe	Missing keywords	Force the recipe or add domain terms
Run fails immediately on scope gate	Scope excludes a file the fix needs	Widen scope deliberately, not silently
Plan is truncated or shallow	Kickoff is very long	Move context into a referenced file; keep the kickoff to the outcome

Kickoff plus recipe

The kickoff never names the workflow. That is the recipe's job. The same kickoff can be run under a different recipe when you want a different verification posture:

mini-ork run code-fix ./kickoff.md        # single patch, test-gated
mini-ork run bdd-first-delivery ./kickoff.md   # specs first, parallel implementation

What changes is the workflow and gates, not the statement of intent. See Recipes and task classes.

Checklist

Before running, confirm:

• The title names one outcome.
• The problem cites the evidence (file, line, failing behaviour).
• The Definition of Done is a single sentence in the past tense.
• Scope names the files that may change and excludes everything else.
• At least one success criterion is a command with an expected result.
• The kickoff does not ask for two unrelated things.

Next

• Recipes and task classes
• Verification and gates
• Your first run