Write a good task

A task is one Markdown file — the spec kusaw add checks and queues as a run. Write one change per task, with commands under ## Verification that prove it worked.

kusaw serve has to be running for the queued run to start. kusaw ui opens the Dashboard.

The task fileCopy Anchor Link

Front matter, then five sections in this order. The spec check is structural only: it does not call a model.

---
id: demo-json-flag
title: JSON flag
repos: [demo]
---

## Goal

Add a `--json` flag to report so a script can read the result.

## Scope

The report command in the `demo` repo. One flag.

## Acceptance criteria

- [ ] `--json` prints `{"text":"report"}`.

## Verification

- `go test ./...`

## Out of scope

Other flags, renaming report, and changing the default output.

• id and title are required. id is the task id.
• title is the short name you see on Runs.
• Goal is what and why.
• Scope and Out of scope are the constraints.
• Acceptance criteria is a list of what done looks like.
• ## Verification holds commands that prove it works. Each command is a list item whose only text is a command in backticks.
• repos: names the factory repo labels this task uses. With one repository in the factory you can omit it; with several you have to list them. At most eight. See Multi-repo runs.

One change per task. Two independent flags, or a flag plus a rename, are two tasks.

What makes the spec check ask for moreCopy Anchor Link

kusaw add rejects a file that does not match the shape. Each problem is printed as Spec rejected (unclear_spec): plus the reason. Typical reasons:

• Front matter is missing, or it still has repo: instead of repos:.
• id or title is missing.
• A required section is missing or empty.
• ## Acceptance criteria has no list item.
• ## Verification has no command (a sentence such as "run the tests" is not a command).
• A listed repo is not in kusaw.yaml, or a command under Verification is not scoped to a repo when the task names more than one.

Fix the file and run kusaw add again. The spec check does not rewrite the file for you.

Before and after (demo)Copy Anchor Link

This before file fails the spec check. It uses repo:, the Goal is vague, and Verification is not a command:

---
id: demo-json-flag
title: JSON flag
repo: demo
---

## Goal

Make report better.

## Scope

The report command.

## Acceptance criteria

- [ ] It works.

## Verification

Run the tests.

## Out of scope

Other flags.

kusaw add prints Spec rejected (unclear_spec): for repo: and for Verification. The after file (the task file above) is one change, names repos: [demo], and proves the flag with go test ./....

If it goes wrongCopy Anchor Link

• Spec rejected (unclear_spec): — the message after the colon is the fix. Put a real command under ## Verification, use repos: (not repo:), and fill every required section.
• The run never leaves queued — kusaw serve is not running. Start it, or open the factory and check the queue is not Paused.
• Verification fails later in the run — the command under ## Verification is what the factory runs. Fix the command or the code, then requeue or resume.