Briefs work

Briefs: Work Session

Executor mode. CURRENT.md is the contract for this session: it says what to build, in what order, under which settled decisions. Your job is to work through it — not to redesign it.

Starting a Session

Step 1: Find the briefs folder. Check these in order:

• Read .claude/briefs-path for a saved path
• Check if .briefs/ exists in the project root
• If neither works, ask the user for the path

If the folder has a PLAN.md but no BACKLOG.md, it predates the rename — treat PLAN.md as BACKLOG.md and offer to mv it.

Step 2: Read CURRENT.md. If there's an active task, summarize it — including the first unchecked item in # Task list and any recent # Log entries — and ask: "Pick up where we left off, or start something new?"

If CURRENT.md is empty but queue/ has staged plans, offer to promote one: move its content into CURRENT.md, delete the queue file, add the task to BACKLOG.md's ## Up next if missing — then re-verify before executing:

• Check the plan's named files, functions, and patterns still exist as described (the Approach header says which commit it was planned against — git diff --stat <that-sha>..HEAD shows what moved underneath it).
• Superficial drift (file moved, rename, shifted line numbers): fix the plan's references inline, note it in # Log, proceed.
• Structural drift (a pattern to mirror was refactored away, a settled decision conflicts with current reality): stop and tell the user the plan needs a /briefs-plan pass — do not improvise around a broken plan.

Step 3: Check the shape of the task:

• Approach is filled in → execute it (see below).
• No Approach and the task is non-trivial (multiple files, design choices, unknowns) → recommend running /briefs-plan first, ideally on a stronger model. Planning done here, ad hoc, is how tasks go sideways.
• No Approach but the task is small and obvious (typo-level, single-file, no decisions) → just do it; a plan would cost more than the work.

Executing

• Work the # Task list in order. Follow the ## Order of work gates — if a step says "make test green", it means green before moving on.
• Settled decisions are settled. If # Approach says the status code is hardcoded, do not add a config option because it "seems better". If you believe a decision is actually wrong or impossible, stop and say so — with the evidence — instead of silently deviating.
• When reality disagrees with the plan (a named file doesn't exist, a pattern changed, an API behaves differently): make the smallest sensible adaptation and record it in # Log (see below). If the deviation would change something under ## Decisions (settled), stop and ask instead.
• Respect ## Hard rules for the implementing session absolutely.
• If the user asks for something outside the active task, add it to BACKLOG.md (under ## Backlog) rather than expanding the session's scope — unless the user explicitly says to switch.

File rules — what this skill may and may not write

These rules exist because sessions used to declare work "done" before the user ever reviewed or tested it. The boundary: you record progress; only the user, via /briefs-done, records completion.

• CURRENT.md — keep it live during the session:
  • Tick # Task list checkboxes when an item is implemented and verified (tests/checks pass). A ticked box means "built and checked", not "accepted" — acceptance happens in /briefs-done after the user reviews.
  • Append dated one-liners to # Log: deviations from the Approach (with why), blockers hit, anything the next session must know to continue cold. When the user hands you a commit SHA for finished subtask work, record it here too ("backend committed as abc1234") and mention that /briefs-done can checkpoint it into PROGRESS.md without closing the task.
  • Add reviewer-relevant facts to # Review notes as you create them (surprising changes, migration notes, things to test manually).
  • Never reset CURRENT.md, remove the task, or write anything that declares the task finished. Even with every box ticked, the task is "awaiting review" — say exactly that, and point the user at /briefs-done.
• BACKLOG.md — may append newly discovered work to ## Backlog. Nothing else.
• PROGRESS.md — never touch. Only /briefs-done writes there.
• NOTES.md — may append reusable learnings (gotchas, commands, references).

Ending a session

Before stopping — whether finished or interrupted — make CURRENT.md reflect reality: boxes ticked to match verified work, # Log updated with current state and the concrete next step. A fresh session must be able to continue from the file alone.

If all boxes are ticked: report what was built and how it was verified, then hand off — "ready for your review; run /briefs-done when you've reviewed and committed." Do not celebrate completion; that's the user's call.

Rules

• One task at a time. CURRENT.md holds exactly one active task. If you're tempted to add a second, put it in BACKLOG.md instead. ## Up next must stay short (max 3 items) — if it has more, mention it and suggest /briefs-health.
• Keep output concise. Report outcomes and load-bearing findings, not narration.
• Don't use numbered lists in the briefs files unless order truly matters — they make reordering painful.