issue

name	issue
description	Use when drafting, writing, or filing a GitHub issue that komandant — or any autonomous coding agent — will implement unattended. Covers the required

komandant:issue

Overview

komandant spawns an autonomous Claude Code worker for each labelled GitHub issue. The worker reads ONLY the issue body — no human will clarify anything. Its very first step parses the body for an acceptance checklist; that checklist is the hard gate the implementation must pass before a PR opens.

Core rule: an issue with no parseable ## Evaluation checklist makes the worker abort immediately and comment a failure. A vague issue with a strong, runnable checklist succeeds; a beautifully-written issue without one fails. Spend your effort on the checklist.

The komandant contract (non-negotiable)

The worker only recognizes a checklist that obeys ALL of these:

1. A heading spelled exactly ## Evaluation (or exactly ## Tests). Not ## Acceptance Criteria, not ## Evaluation / Tests, not ### Evaluation. Any other text and the worker finds no checklist and aborts.
2. Items are GitHub task-list lines: - [ ] ....
3. Each item is one of:
   • command — a shell command in backticks or a fenced block. The worker runs it verbatim; exit code 0 = pass. Most reliable.
   • prose — anything else. A sub-agent inspects code/behavior and judges it. Use only when a command can't express the check.

Prefer command items. Every prose item is a judgment call that can go either way.

Workflow

1. Decide interview vs. format. If the user already gave enough to write concrete, verifiable checks (the change, and how to confirm it), just format. If not, ask only the gaps — typically: target repo, the precise desired behavior, and how success is verified (a command? an observable output?). Don't pad with questions you can already answer.
2. Write the issue using the template below.
3. Build the checklist — the real work (see rules below).
4. Deliver — create it or hand over paste-ready markdown (see Delivery).

Template

Title: Conventional-Commits style — <type>: <concise imperative summary> (e.g. feat: add --json flag to greet CLI). Type is one of feat, fix, chore, refactor, docs, test, perf. Lowercase type, lowercase summary.

Keep the summary short — aim for ≤ 50 characters, ~6 words. komandant derives the worker's git branch/worktree name from the title (<type>/<slugified-summary>-<issue-number>), and claude's worktree names cap at 64 characters. A long, clause-packed summary gets truncated mid-word, so the branch is less readable and less obviously tied to the issue. Put the detail in ## Context / ## Desired behavior, not the title. Prefer fix: fail loud on scheduling-note read-back over fix: persistence safety for scheduling notes — merge read-back, fail loud (M0).

Body:

## Context
<Why this is needed and the current behavior. One short paragraph.>

## Desired behavior
<Concretely what should change — inputs, outputs, edge cases. Be specific
enough that an agent with no further questions can implement it.>

## Evaluation
- [ ] `<runnable shell command that exits 0 when the change works>`
- [ ] `<another runnable check>`
- [ ] <prose check, only when no command can express it>

Writing a strong checklist

• Exercise real behavior, not internals: drive the CLI/API/endpoint the way a user would and assert the output.

  - [ ] `greet Bob --json | python -c "import json,sys; assert json.load(sys.stdin) == {'greeting':'Hello, Bob!'}"`
  

• Include a no-regression check: - [ ] <test suite command, e.g. pytest -q>`` so existing behavior stays intact.
• Don't reference files that don't exist yet. The worker writes tests during implementation, but a checklist command runs after and must succeed on its own. Check behavior through the program, or run the whole suite — don't hardcode a path to a test file you're hoping it creates, unless the body explicitly tells it to create exactly that file.
• One assertion per item. Easier to repair when one fails.
• Keep commands simple and portable. One pipe, plain quoting. Avoid process substitution <(...), deep nested quote-escaping, and bash-only syntax — the worker runs the line verbatim, and fragile shell can fail a correct change (false negative). If a check needs real logic, put it in a tiny test the suite runs and assert via the suite command instead.
• Keep prose checks falsifiable: "the --json output contains exactly one key greeting" — not "the output looks clean".

Delivery

If a GitHub issue-creating tool/connector is available: confirm the target owner/repo, create the issue with the title and body, then add the trigger label so komandant picks it up (default komandant, or whatever trigger_label is set to in that repo's komandant config). Report the issue URL.

Otherwise (mobile, no connector): output the title on one line and the body in a single fenced markdown block ready to paste into GitHub's "New issue" form. Then tell the user: after creating it, add the komandant label — the label is what triggers pickup; the issue sits idle without it.

Common mistakes

Mistake	Why it breaks komandant
Heading like ## Acceptance Criteria or ## Evaluation / Tests	Worker matches the heading exactly; anything but ## Evaluation / ## Tests = no checklist found = instant abort.
All checks written as prose	Each becomes a fuzzy agent judgment. Use runnable commands; exit 0 = pass.
No checklist at all	Worker aborts and comments a failure before touching code.
Forgetting the trigger label	Issue is never picked up. Always remind the user (paste mode) or apply it (connector mode).
Checklist command references a not-yet-created test file	Runs after implementation and fails because the path doesn't exist. Test behavior through the program instead.
### Evaluation (wrong level) or a typo in the heading	Same as wrong heading — not found. Must be ## Evaluation.