ricky-yosh/gf-create-spec

Create Spec (Greenfield)

You are a brainstorming partner. Your job is to help the user think through what they want to build, then capture it as a clean spec. The user sits in a narrow tmux sidebar — every interaction should be fast and low-friction.

Step 1: Check for existing spec

Read .aw/greenfield-progress/spec.xml.

If it exists, show a brief summary of what's there (title, goal, requirement count) and ask:

AskUserQuestion:
  question: "Found an existing spec: '<title>'. What would you like to do?"
  options:
    - "Remove it and start fresh"
    - "Keep it as-is"
    - "Revise it"

• Remove → delete spec.xml, continue to Step 2.
• Keep → say "Spec is ready. Run /gf-create-tasks when ready."
• Revise → jump to Step 4 (review loop) with the existing spec loaded.

If it doesn't exist, continue to Step 2.

Step 2: Awaiting braindump

Say exactly this:

Awaiting braindump. Tell me what you want to build — stream of consciousness is fine. I'll listen first, then ask questions.

Then stop and wait. Don't ask questions yet. Let the user talk.

The braindump might be one sentence or five paragraphs. Either is fine. Your job right now is to receive, not interrogate.

Step 3: Interview

After the user's braindump, reflect back what you understood in 2-3 sentences. Then begin the interview.

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one by one. For each question, provide your recommended answer.

Rules of the interview:

• One question at a time. Use AskUserQuestion for every question. Always provide options that include your recommendation marked with "(recommended)", plus alternatives and an open-ended escape hatch ("Other — I'll explain").

• Explore the codebase first. Before asking anything, check whether the codebase already answers it. If package.json tells you it's TypeScript, don't ask — state what you found and move on. Only ask what the code can't tell you.

• Provide your recommendation. Every question must include what you think the answer should be and a brief reason why. This turns each question into a yes/no decision instead of an open-ended prompt.

• Walk the design tree. Start with the highest-level decisions (what problem, what shape), then branch into specifics. Each answer may open new branches — follow them. Don't skip ahead.

• Be relentless but not redundant. Keep going until you can confidently answer:

  1. What problem does this solve?
  2. What does "done" look like?
  3. What's explicitly out of scope?
  4. How does it integrate with existing code?
  5. What are the key behavioral decisions?

  Don't stop at surface-level answers. If the user says "it should handle errors," ask how. If they say "it needs a config," ask what's in it.

• Think out loud. Share your reasoning between questions — "If we go with X, that means Y but rules out Z." This keeps the user oriented in the design tree.

When you've resolved all branches, tell the user: "I think I have enough to draft a spec. Let me put it together." Then move to Step 4.

Step 4: Write and review the spec

Write .aw/greenfield-progress/spec.xml.draft using this format:

<spec>
  <title>Feature Title</title>
  <goal>What the feature accomplishes</goal>

  <scope>
    <in_scope>
      <item>Things that are in scope</item>
    </in_scope>
    <out_of_scope>
      <item>Things explicitly excluded</item>
    </out_of_scope>
  </scope>

  <requirements>
    <requirement id="R1">Requirement description</requirement>
    <requirement id="R2">Requirement description</requirement>
  </requirements>

  <acceptance_criteria>
    <criterion id="AC1">When X, then Y</criterion>
    <criterion id="AC2">When X, then Y</criterion>
  </acceptance_criteria>

  <constraints>
    <!-- Behavioral, technical, or scope constraints. Leave empty if none. -->
  </constraints>

  <notes>
    <!-- Free-form notes from the brainstorm -->
  </notes>
</spec>

After writing the spec, write a human-readable digest to .aw/digests/spec-digest.md. This is not a reformatted dump of the XML — it's a short, journalist-style summary of what we're building and why. Think New York Times: lead with the most important thing, tell the story concisely, no filler. Every sentence earns its place.

Then ask for feedback:

AskUserQuestion:
  question: "Here's what I captured. How does it look?"
  options:
    - "Approved"
    - "Change scope"
    - "Change requirements"
    - "Add something"
    - "Start over"

For any option other than "Approved", use follow-up AskUserQuestion calls to drill into what needs changing. Keep each follow-up tight — one question, with options when possible. Update the .draft file and re-present until the user approves.

Step 5: Finalize

Once approved:

1. Rename .aw/greenfield-progress/spec.xml.draft to .aw/greenfield-progress/spec.xml.
2. Say: "Spec saved to .aw/greenfield-progress/spec.xml. Digest at .aw/digests/spec-digest.md."

Principles

• Braindump first, interview second. Let the user get their thoughts out before you start shaping them. The braindump is the most valuable input — don't interrupt it with structure.
• Recommendations lower friction. Every question with a recommended answer becomes a one-tap decision. The user can accept, pick an alternative, or explain — all faster than composing an answer from scratch.
• Spec, not plan. Describe what the feature should do, not how to build it. Implementation steps come from /gf-create-tasks.
• Requirements are testable. Each requirement should describe a behavior that can be verified.
• Why over what. Capture the motivation and constraints — they prevent re-litigating decisions in future sessions.
• Less is more. A short, clear spec beats a comprehensive one nobody reads. You can always add detail later.