design

Design phase (Full tier)

Design is phase 2 of the four-phase loop. It writes the single artifact for the job: plan.md. That file carries the Why, the Acceptance criteria, the ordered Tasks (both work items and verify items), and — optionally — the Decisions worth recording.

Design is the single planning phase. Apply and Verify only execute; if either hits a missing piece, it pauses and comes back to Design briefly with a visible revision note.

Steps

1. Pick a slug. Short, lowercased, kebab-case (e.g. plan-kyoto-trip). Full job folder: jobs/<YYYY-MM-DD>-<slug>/.
2. Create the job folder. Directly under jobs/ — flat, no nesting.
3. Write plan.md (required). Structure below.
4. Add the TODO.md Active entry: append - [[jobs/<YYYY-MM-DD>-<slug>]] — <one-line intent> under ## Active.
5. STOP. Do NOT start Apply until the user has at least seen the plan. If the user redirects, revise in place and note the revision visibly.

plan.md structure

# <Job title>

<1–2 sentences: what this is and why we're doing it.>

## Acceptance criteria
1. <concrete, testable criterion>
2. <concrete, testable criterion>

## Tasks
- [ ] 1. <first unit of work>
- [ ] 2. <second unit>
- [ ] 3. <third unit>
- [ ] V1. Verify criterion 1: <verbatim criterion from above>
- [ ] V2. Verify criterion 2: <verbatim criterion from above>

## Decisions  <!-- optional; only for non-obvious trade-offs -->

### <decision title>
- **Choice:** ...
- **Rationale:** ...
- **Alternatives considered:** ...

<!-- Optional: `relates: jobs/<other-slug>/` if this depends on / extends another job. -->

Task list rules

One Tasks section, two task kinds:

• Work tasks numbered 1., 2., ... — executed by Apply.
• Verify tasks prefixed V1., V2., ... — executed by Verify. There is exactly one V-task per acceptance criterion, and the V-task cites its criterion verbatim.

Design writes both up front. Numbered work tasks come first; V-tasks come last in the list.

Writing acceptance criteria

Each criterion must be answerable pass or fail with evidence. Write so the corresponding V-task can record a file path, command output, or concrete observation as evidence.

Bad: "the itinerary looks good" Good: "the itinerary covers 5 days, includes one lodging option per night with a link, and totals under ¥250,000"

Minimum one criterion; most jobs have 2–5.

Decisions section (optional)

Skip entirely for jobs whose approach is obvious. Write when a reader a month from now would reasonably ask "why did we do it this way?" and the answer isn't already in the acceptance criteria or tasks.

Each decision is a short sub-heading with Choice / Rationale / Alternatives considered.

Allowed writes (this phase)

• Create jobs/<YYYY-MM-DD>-<slug>/.
• Write jobs/<slug>/plan.md.
• Append one line to TODO.md under ## Active.

Forbidden writes (this phase)

• Checking off any task (that's Apply for work tasks, Verify for V-tasks).
• Anything under memory/.
• Anything under resources/generated/ (that's Apply).
• Writing files under jobs/<slug>/ other than plan.md — there is no separate proposal / design / tasks / verify file.

Guardrails

• Flat jobs tree. One folder per job. No sub-folders under a job folder. Cross-job dependencies use a relates: line in plan.md.
• V-tasks cite verbatim. Each V-task's body is exactly the acceptance criterion text, no paraphrase. If a criterion is wrong, the fix is a visible revision of both the criterion and its V-task.
• Pre-commitment is binding. Do not soften a criterion later to make Verify pass. If the plan turns out wrong during Apply or Verify, revise visibly with a > Revised: <reason> note — don't rewrite history.
• All planning stays here. Apply does not add tasks, revise scope, or introduce new criteria. Verify does not edit criteria silently. If either discovers a gap, it pauses and returns to Design briefly.
• One plan per job. If a follow-up needs its own plan, that's a new job with a relates: pointer, not a second plan file in the same folder.

Exit criterion

You exit Design when:

1. plan.md exists with at least one numbered acceptance criterion and a matching V-task per criterion.
2. The Tasks section has an ordered set of numbered work tasks (1., 2., …) followed by the V-tasks (V1., V2., …).
3. The TODO.md Active entry is added.
4. The user has had a chance to see the plan.

Advance to Apply.