Stage: scoping

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

Purpose: Q&A with the user to lock in the target community, the repo angle, post goal, audience, language, multimedia formats, and any exclusions. Output is the scope brief every later stage reads. Output artifact: write to the absolute path provided in your I/O context Valid results this stage writes: pending (scope drafted, awaiting user approval), approved (user has explicitly confirmed)

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

By the time you read this file, state.md already exists with status: scoping and epoch is set. Read it for the current epoch before writing the artifact.

Read your I/O context

Read every input path from the I/O context block in your prompt — do NOT construct or hardcode paths. The optional repo_root run file gives you the absolute repo path; the optional current_date run file gives you today's date.

Immediately write a pending artifact

Before asking any questions, write the output artifact at the path shown in your I/O context with result: pending and a stub body. This signals the stop hook that the stage is in progress so it won't try to advance the state machine mid-conversation.

Ask clarifying questions

Inline Q&A — one question per message, multiple-choice (A/B/C) when possible. Typically 3-6 questions. Cover at minimum:

• Target community — Product Hunt, Twitter / X, Xiaohongshu (RED), Reddit (which subs), LinkedIn, Hacker News, Bilibili, other?
• Post goal — drive sign-ups, GitHub stars, hiring, traffic to a docs site, raise awareness, fundraising, etc.
• Repo angle — which feature / story does the user want to lead with? Is this a launch, an update, or a re-introduction?
• Audience — devs, designers, founders, non-technical end users, enterprise buyers, students, etc.
• Language and tone — English / Chinese / bilingual; formal, playful, story-driven, technical deep dive.
• Multimedia formats wanted — slide deck, hero image, carousel images, short video (script + storyboard), GIF, none.
• Exclusions / constraints — claims to avoid, competitors not to mention, NDA topics, brand voice rules, link policy.

Stop asking when you have enough to fill the brief below.

Present and iterate

Summarize the scope back to the user in plain prose. Iterate until they explicitly approve.

Write the scope brief into the artifact

Once they approve, overwrite the artifact:

---
epoch: <epoch from state.md>
result: approved
---
# Scope Brief

## Target community
<platform + sub-community / subreddit / topic tag>

## Post goal
<single concrete success metric — e.g. "100 GitHub stars in 7 days">

## Repo angle
<the angle / story / feature to lead with>

## Audience
<who the post is written for>

## Language and tone
<language(s) + tone descriptors>

## Multimedia formats requested
- <slide deck | hero image | carousel | video script | none>

## Exclusions and constraints
- <claims, competitors, links, brand-voice rules to honor>

## Notes for downstream stages
<anything researching / drafting / evaluating / media_production should keep in mind>

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