Create Plan Artifact

BRANCH=$(git branch --show-current)
DIR=".agent/${BRANCH}"
mkdir -p "${DIR}"
echo "PLAN=${DIR}/plan.md CHECKS=${DIR}/checks.yaml"

node "${AW_SKILL_DIR:-$HOME/.claude/skills/autonomous-workflow}/scripts/run-checks.mjs" "${DIR}/checks.yaml" --seal

---
created: {TIMESTAMP}
version: {N}
branch: {BRANCH}
task: {TASK_DESCRIPTION}
tier: {Lite | Full}
complexity: {LOW | MEDIUM | HIGH}
turn_cap: {N}
status: approved
approved: true
---

# Plan: {TASK_DESCRIPTION}

## Task

{1–3 sentences: what changes, why, and what a reviewer will see when it is done.}

## Requirements

1. {requirement} — [user-stated | inferred] — {source: "quoted words" from the user or ticket, or the outcome a reviewer would require}

### Out of Scope

1. {item} — {reason}

## Guardrails

- Do not modify: `{path or glob}` — {source: the user, the ticket, or a repo doc}
- Keep unchanged: {public API, behaviour, output format, or config} — {source}
- Never: {forbidden move, e.g. weaken or skip a test, add a dependency, edit checks.yaml definitions}

## Acceptance Criteria (Definition of Done)

- [ ] AC-1 (covers: R1) — When {trigger}, the system shall {observable response}.
- [ ] AC-2 (covers: R2) — {concrete, testable criterion}

- **After editing**: `{fast check, e.g. pnpm tsc --noEmit}`
- **Before PR**: `{full suite, e.g. pnpm test && pnpm lint}`

Done when `run-checks.mjs` prints `CHECKS {M}/{M} PASS (<sha>)` and the draft PR URL is printed.

## Turn Cap

{N} turns — {why this budget}.

## File Changes

Starting points, not a fence: the worker changes whatever the task needs and names every extra file in the walkthrough.

| Action | File   | Change                  | Reason |
| ------ | ------ | ----------------------- | ------ |
| create | {path} | {purpose / key exports} | {why}  |
| modify | {path} | {expected change}       | {why}  |

<!-- ✗ Wrong — a guardrail nobody can check -->
- Be careful not to break anything.

<!-- ✗ Wrong — a design guess written as a limit; the ticket never said it, and it contradicted an edge case -->
- Keep unchanged: `markSessionExpired` — the reconnect flow owns it.

<!-- ✓ Right — names the area and where the limit came from -->
- Do not modify: `src/api/public/**` — CLAUDE.md: external consumers pin this contract.

# .agent/{branch}/checks.yaml — the executable Definition of Done.
# Derived from plan.md by aw-create-plan and sealed in checks.lock.
# Executor: only `status:` may change freely; `run:`/`setup:` only with a
# check-run-amended Progress Log entry. id/requirement/ears/kind/expect are sealed.
- id: AC-1
  requirement: R1
  ears: "When the token is expired, GET /me shall return 401"
  kind: command                  # command | grep | judge
  setup: "none"                  # or a shell command that must exit 0
  run: "curl -s -o /dev/null -w '%{http_code}' localhost:3000/me -H 'Authorization: Bearer expired'"
  expect: "401"                  # exact stdout | `exit <n>` | `re:<pattern>` | `re/<flags>:<pattern>`
  status: pending                # pending | pass | fail | unsatisfiable

# ✓ Right — a telemetry criterion, decided by the run's telemetry, not by reading the code
- id: AC-4
  requirement: R2
  ears: "When checkout is submitted, the system shall emit a checkout.submit span with order.id, with ERROR status on decline"
  kind: judge
  setup: none
  run: "aw-verify run local"
  expect: "confirms"
  status: pending

# ✗ Wrong — "works" is not checkable, and the braces never resolve
- id: AC-2
  run: "{run the tests}"
  expect: "works"

# ✓ Right — a runnable command and an exact expectation
- id: AC-2
  kind: command
  setup: none
  run: "pnpm vitest run src/auth --reporter=dot"
  expect: "exit 0"
  status: pending

P=".agent/$(git branch --show-current)/plan.md"
grep -cE '^## (Task|Requirements|Guardrails|Acceptance Criteria|Turn Cap|File Changes)' "$P"   # must print 6
grep -cE '^- \[ \] AC-[0-9]+ \(covers: R[0-9]' "$P"                                           # ≥ 1
node "${AW_SKILL_DIR:-$HOME/.claude/skills/autonomous-workflow}/scripts/run-checks.mjs" --self-test