Stage: briefing

Runtime config (canonical): workflow.json → stages.briefing

Purpose: collect the goal description from the user, translate it into verifiable success criteria, and obtain explicit user approval before launching the execute → evaluate loop. Output artifact: write to the absolute path provided in your prompt Valid results this stage writes: pending (briefing drafted, awaiting user approval), approved (user has explicitly confirmed)

This is an interruptible stage — the stop hook allows natural pauses for Q&A.

Note: picking the topic name and activating the workflow (setup-workflow.sh) happen in SKILL.md's protocol (Step 1 — Bootstrap), before any stage runs. By the time you read this file, state.md already exists with status: briefing and epoch is set.

Step 1 — Read state and stub the artifact immediately

Read state.md for the current epoch. Then immediately write the output artifact at the absolute path in your I/O context with result: pending so the stop hook knows the stage is in progress. You will overwrite it later with the final content.

---
epoch: <epoch>
result: pending
---
# Goal Briefing (drafting)

Step 2 — Understand the project context

If the user's goal touches the project worktree, briefly survey the relevant files, conventions, and tech stack. If the goal is purely external (research, planning, content), note that explicitly and skip codebase exploration.

Step 3 — Clarify the goal

Inline Q&A — the stop hook allows natural pauses.

• Start with the goal description the user provided in the task. If it is vague, ask focused questions (one per turn, prefer A/B/C choices) to pin down:
  • What — the concrete outcome the user wants
  • Done condition — how will we know the goal is achieved (the more verifiable, the better)
  • Constraints — scope boundaries, things explicitly out of scope, deadlines, allowed/forbidden tools
  • Quality bar — what level of polish counts as "done" (proof-of-concept vs. production-ready)
• Stop asking once you can write success criteria that another agent could check without ambiguity.

Step 4 — Translate to verifiable success criteria

Each success criterion MUST be:

• Specific — names a concrete deliverable or observable behavior
• Verifiable — an evaluator agent can check it by reading files, running commands, or inspecting output
• Bounded — not "is high quality" but "passes test X" / "file Y exists with property Z" / "command W exits 0"

Avoid vague criteria like "looks good" or "is reasonable." If the user's goal is inherently subjective, propose proxy criteria (e.g. "matches the example artifact at <path>", "covers all bullet points listed in the brief").

Step 5 — Write the full briefing into the output artifact

Overwrite the artifact (still result: pending until the user approves):

---
epoch: <epoch>
result: pending
---
# Goal Briefing: <Topic>

## Goal
<one-paragraph restatement of the user's goal in your own words>

## Scope
- In scope: ...
- Out of scope: ...

## Success Criteria
- [ ] <criterion 1 — specific, verifiable, bounded>
- [ ] <criterion 2>
- [ ] ...

## Constraints
<deadlines, allowed tools, forbidden actions, quality bar>

## Evaluation Notes
<concrete instructions for the evaluator: which files to inspect, which commands to run, what counts as evidence of each criterion>

The Evaluation Notes section is critical — the evaluate stage reads it to know exactly how to verify each criterion. Be explicit.

Step 6 — Get user approval

Show the user a short summary of the success criteria and ask:

"Briefing saved to the session's briefing-report.md. Please review the success criteria and confirm to start the execute → evaluate loop, or request changes."

If the user requests changes, iterate on the body — keep result: pending. Do NOT advance until the user explicitly approves.

Step 7 — Finalize

Once the user explicitly approves, edit the output artifact: change result: pending → result: approved.

That is the only action needed here. The SKILL.md main loop's step (e) reads the artifact's result: and calls update-status.sh to advance the state machine — do NOT call it yourself from this stage file.