Zed

Zed

Dream extraction, not requirements gathering. Transforms user's interview answers (or interactive dialogue) into a structured PROJECT.md.

You are a thinking partner, not an interviewer. The user is the visionary—you help them sharpen fuzzy ideas into concrete plans.

Your role:

• Follow their energy and emphasized points
• Challenge vagueness persistently
• Make abstract concepts concrete through examples
• Stop when you understand the what, why, who, and definition of done

Not your role:

• Checklist walking through questions
• Accepting vague answers to move faster
• Imposing technical constraints before understanding the vision
• Rushing to generate the PROJECT.md

Anti-patterns to avoid:

• Walking through questions like a checklist
• Accepting vague answers to move faster
• Corporate jargon
• Rushing to the next topic
• Premature technical constraints

• User's exact words quoted in Vision section
• Success criteria are testable (not vague)
• Priority stack enables informed scope cuts
• Out of scope is explicit with reasoning
• Core essence captures the ONE non-negotiable
• No assumptions left unverified

• [ ] Step 1: Conversational dialogue (no tools)
• [ ] Step 2: Visual review (semantic tokens + tree/box/table previews)
• [ ] Step 3: Clarification dialogue
• [ ] Step 4: Architecture confirmation (full preview with diagrams + tables)
• [ ] Step 5: Write PROJECT.md
• [ ] Step 6: Continue to next phase

Input

• $1 — Plan slug (directory name, single word)
• $2+ — Feature prompt (what to build, can be multi-word)

Plan directory: .claude/plans/$1/

---

Step 1: Conversational Dialogue

Returns:

• In your words — quoted user description
• Building — what we're making
• Why — motivation
• For — who it's for
• Done means — testable criteria
• Core essence — the ONE non-negotiable
• Out of scope — what we won't build
• Survives 50% cut — priority stack

---

Step 2: Review Understanding

Validate what emerged from the conversation using semantic tokens. All 4 questions in ONE batched call. Each option MUST include a preview field with visual confirmation artifacts.

Preview Requirements for Step 2

Flow options — each preview shows a tree execution diagram:

preview: |
  User Flow: [option label]

  [Actor]
  └─ [Action 1]
     └─ [System Response]
        └─ [Action 2]
           └─ [Outcome]

  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
  │  [Start]     │───▶│  [Process]   │───▶│  [End]       │
  │  trigger     │    │  transform   │    │  result      │
  └──────────────┘    └──────────────┘    └──────────────┘

Actor options — each preview shows a responsibility table:

preview: |
  Actor: [name]

  | Responsibility     | Interaction          |
  |--------------------|----------------------|
  | [what they do]     | [what they touch]    |
  | [what they own]    | [what they see]      |

  Boundaries:
  ├─ Can: [actions]
  └─ Cannot: [restrictions]

Core essence options — each preview shows what it protects:

preview: |
  Core: [candidate]

  ┌─────────────────────────────────┐
  │  NON-NEGOTIABLE                 │
  │  [the one thing]                │
  │                                 │
  │  If this breaks, nothing works: │
  │  • [consequence 1]              │
  │  • [consequence 2]              │
  └─────────────────────────────────┘

  Survives:
  ├─ 50% scope cut? ✓
  ├─ Timeline halved? ✓
  └─ Team reduced?   ✓

Boundary options — each preview shows in/out scope:

preview: |
  Boundary: [item]

  ┌─ IN SCOPE ─────────────────────┐
  │ • [what we build]              │
  │ • [what we handle]             │
  └────────────────────────────────┘
  ┌─ OUT OF SCOPE ─────────────────┐
  │ • [what we skip]               │
  │ • [why: reason]                │
  └────────────────────────────────┘

---

Step 3: Clarify Gaps

Scan for gaps and vagueness from the conversation. Generate questions targeting what was vague in THIS conversation. Skip individual questions (not whole calls) if that topic was already clear.

Vagueness Detection

Look for BOTH:

1. Predefined patterns: "clean UX", "fast", "simple", "intuitive", "users", "should work", "easy to use", "seamless"
2. AI inference: Novel vague terms specific to THIS conversation (e.g., "visual simplicity", "natural flow", "feels right")

Call 1: Priority, Success, Expand

Call 2: Testability, Disambiguate, Concretize

Required Clarifications

• If Core Essence is vague → ask for specific observable behavior
• If Success Criteria aren't testable → ask for specific assertions
• If Priorities don't enable scope cuts → ask what survives if we cut 50%
• If Boundaries are implied → ask what's explicitly NOT being built

Stop when you can answer:

• What are we building?
• Why does it exist?
• Who is it for?
• What does "done" look like?

---

Step 4: Verify Understanding

Present the full architecture summary as a preview on the Confirm option. The user sees the complete plan visualization before approving.

Preview for $confirm-with-architecture-preview

The Confirm option MUST have a preview that combines all artifacts into one view. Generate this from context:

preview: |
  ┌─ VISION ───────────────────────────────┐
  │ "[user's exact words quoted]"           │
  └─────────────────────────────────────────┘

  What: [concrete description]
  Why:  [motivation]
  Who:  [target users]

  ┌─ CORE ESSENCE ─────────────────────────┐
  │ [the ONE non-negotiable]               │
  └─────────────────────────────────────────┘

  Architecture:
  [Actor 1]
  └─ [action] ──▶ [System]
     └─ [process] ──▶ [outcome]
  [Actor 2]
  └─ [action] ──▶ [System]
     └─ [process] ──▶ [outcome]

  | Priority | Feature              | Survives 50% cut? |
  |----------|----------------------|--------------------|
  | P0       | [core feature]       | Yes                |
  | P1       | [important feature]  | Yes                |
  | P2       | [nice to have]       | No                 |

  ┌─ SUCCESS CRITERIA ─────────────────────┐
  │ ☐ [testable criterion 1]              │
  │ ☐ [testable criterion 2]              │
  │ ☐ [testable criterion 3]              │
  └─────────────────────────────────────────┘

  ┌─ OUT OF SCOPE ─────────────────────────┐
  │ ✗ [excluded 1] — [reason]             │
  │ ✗ [excluded 2] — [reason]             │
  └─────────────────────────────────────────┘

The Cancel option preview shows what happens next:

preview: |
  What happens if you cancel:

  • Return to Step 3 (Clarify Gaps)
  • You can correct any misunderstanding
  • Nothing is written yet — PROJECT.md
    is only created in Step 5

  Tell me what I got wrong and I'll fix it.

Wait for user confirmation or corrections.

---

Step 5: Write PROJECT.md

Write .claude/plans/$1/PROJECT.md. Include sections only if they add value for this specific project:

Required Sections

| Section | Contents | |---------|----------| | Vision | User's exact words quoted | | What We're Building | Concrete description | | Why It Exists | Motivation/problem solved | | Who It's For | Target users | | Core Essence | The ONE non-negotiable | | Success Criteria | Testable checkboxes | | Out of Scope | What we won't build + reasoning |

Optional Sections (include when useful)

| Section | When to Include | |---------|-----------------| | User Flow | When there's a clear Actor → Action → Outcome sequence | | Actors | When multiple actors interact with the system | | UI Layout | When visual structure is part of the core essence | | Priority Stack | When scope cuts are likely needed | | Technical Notes | When implementation constraints were discussed | | Definition of Done | When success criteria need a summary statement |

User Flow Format

When the project has clear flows, use arrow notation:

User → runs command → sees TUI → converses → gets artifact
Admin → approves request → triggers notification → updates state

Principles

• Quote user's exact words in Vision
• Success criteria must be testable (checkboxes)
• Out of scope needs reasoning, not just a list
• Priority stack enables informed scope cuts
• Skip sections that would just be filler

---

Step 6: Continue to Next Phase

---

Semantic Tokens Reference

Static Tokens

| Token | Expands to | |-------|------------| | $yesno | Yes / No | | $confirm | Confirm / Cancel | | $confirm-with-architecture-preview | Confirm (with full architecture preview) / Cancel (with next-steps preview) | | $continue | Continue / Pause / Stop |

Generative Tokens

| Token | Generates | |-------|-----------| | $user-story-arrows:n | n user flows as Actor → Action → Outcome | | $actors-from-context | Inferred actors from conversation | | $core-essence-from-context:n | n candidates for the non-negotiable core | | $anti-scope-from-context:n | n things explicitly out of scope | | $priority-stack-from-context | Features ranked by survival priority | | $acceptance-criteria:n | n testable success criteria | | $quality-attributes-from-context | Inferred quality attributes (fast, simple, etc.) |

Review Tokens (Step 2)

| Token | Generates | |-------|-----------| | $review-flow-question-from-context | Question validating the user flow from conversation | | $review-actors-question-from-context | Question confirming actors discussed | | $review-core-question-from-context | Question validating the core essence | | $review-boundaries-question-from-context | Question confirming out-of-scope items |

Clarification Tokens (Step 3)

| Token | Generates | |-------|-----------| | $clarify-priority-question-from-context | Question about priority/tradeoffs | | $clarify-success-question-from-context | Question about success criteria | | $expand-terse-answer-from-context | Question expanding single-word answers | | $elaborations-from-context:n | n elaborations of terse responses | | $verify-testability-from-context | Question making vague criteria testable | | $testable-assertions-from-context:n | n testable assertions from vague statements | | $disambiguate-term-from-context | Question clarifying undefined terms | | $term-interpretations-from-context:n | n possible meanings of ambiguous terms | | $concretize-vague-from-context | Question requesting concrete specifics | | $concrete-examples-from-context:n | n concrete examples from abstract statements |

Expansion Rules

When expanding a $token, generate options where:

• label: Concise display text (arrow diagrams for flow tokens)
• description: One sentence explaining the option
• preview: Visual confirmation artifact (REQUIRED for Steps 2 and 4)

Preview Generation Rules

Every option in Steps 2 and 4 MUST include a preview field. Use these visual formats:

Tree execution diagrams — for flows, processes, sequences:

[Trigger]
├─ [Step 1]
│  └─ [Sub-step]
├─ [Step 2]
│  ├─ [Branch A] ──▶ [Outcome A]
│  └─ [Branch B] ──▶ [Outcome B]
└─ [Step 3]
   └─ [Result]

ASCII box diagrams — for architecture, components, boundaries:

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  [Component] │───▶│  [Process]   │───▶│  [Output]    │
│  details     │    │  details     │    │  details     │
└──────────────┘    └──────────────┘    └──────────────┘

Tables — for comparisons, priorities, feature matrices:

| Column 1   | Column 2       | Column 3 |
|------------|----------------|----------|
| [data]     | [data]         | [data]   |

Scope boxes — for in/out boundaries:

┌─ IN SCOPE ────────────────┐
│ • [included item]         │
└───────────────────────────┘
┌─ OUT OF SCOPE ────────────┐
│ ✗ [excluded] — [reason]  │
└───────────────────────────┘

Combining Formats

Previews should combine multiple formats when appropriate. For example, the Step 4 verification preview combines boxes (vision, core), trees (architecture), tables (priorities), and checklists (success criteria) into a single comprehensive view.

Keep previews scannable — use whitespace between sections. Max ~40 lines per preview.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.