Imagine — Idea Intake (Interactive)

Invocation

Run this command with either:

• A free-form initial idea (recommended):

  • /imagine <initial idea text...>

OR

• An existing idea folder id to refine the current idea:

  • /imagine <IDEA_ID>

Where:

• $ARGUMENTS

  may contain spaces if you pass an initial idea text.
• If

  $ARGUMENTS

  is empty, STOP and ask the user to rerun with an initial idea (or an IDEA_ID).

---

Resolve IDEA_ID (required)

Before using any paths, resolve or create the idea folder:

• If

  $ARGUMENTS

  matches

  ^IDEA-\\d{4}(-.*)?$

  , treat it as

  IDEA_REF

  and call

  vf.resolve_idea_id

  with

  idea_ref = $ARGUMENTS

  .
• Otherwise, treat

  $ARGUMENTS

  as free-form idea text and call

  vf.create_idea_from_text

  with

  initial_text = $ARGUMENTS

  .
• Store the returned

  idea_id

  as

  IDEA_ID

  .
• Use

  IDEA_ID

  for all paths, YAML headers, and run log entries.

---

Goal

Turn a rough idea into a first, reviewable

idea.md

stored at:

• docs/forge/ideas/<IDEA_ID>/inputs/idea.md

This command is interactive by default:

• Phase 1: draft an idea.md + ask clarifying questions
• Phase 2: after user replies, save the final

  idea.md

  and capture answers for future stages

---

Canonical paths (repo-relative)

Ideas root:

• docs/forge/ideas/

Per-idea root:

• docs/forge/ideas/<IDEA_ID>/

Inputs:

• docs/forge/ideas/<IDEA_ID>/inputs/idea.md

  (final target)

• docs/forge/ideas/<IDEA_ID>/inputs/imagine_questions.md

  (generated)

• docs/forge/ideas/<IDEA_ID>/inputs/imagine_answers.md

  (captured; append-only)

History:

• docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/imagine_questions.md

• docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/idea_draft.md

• docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/idea_final.md

Per-idea logs:

• docs/forge/ideas/<IDEA_ID>/run_log.md

  (append-only)

• docs/forge/ideas/<IDEA_ID>/manifest.md

  (rolling status)

---

Directory handling

Ensure these directories exist (create them if missing):

• docs/forge/ideas/

• docs/forge/ideas/<IDEA_ID>/inputs/

• docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/

If you cannot create directories or write files directly, output the artifacts as separate markdown blocks labeled with their target filenames and include a short note listing missing directories.

---

Step 0 — Resolve or create IDEA_ID

Use the tool-based resolution logic from Resolve IDEA_ID (required) above, then proceed:

• If

  docs/forge/ideas/<IDEA_ID>/inputs/idea.md

  exists, use it as the base idea.
• If it does not exist, proceed as a new idea using the resolved/created

  IDEA_ID

  .

---

Step 1 — Create the idea workspace (if missing)

Ensure per-idea files exist:

• docs/forge/ideas/<IDEA_ID>/run_log.md

  (create if missing; can start empty)

• docs/forge/ideas/<IDEA_ID>/manifest.md

  (create if missing; template below)

---

Step 2 — Run identity

Generate:

• RUN_ID

  as a filesystem-safe id (Windows-safe, no

  :

  ), e.g.:

  • 2026-01-14T05-22-41Z_imagine-8f3c

Also capture:

• generated_at

  as ISO-8601 time (may include timezone offset)

---

Step 3 — Gather context

If refining an existing idea

Include file contents in context:

• Existing idea (if present): @docs/forge/ideas/<IDEA_ID>/inputs/idea.md

If creating a new idea

Use

$ARGUMENTS

(initial idea text) as the base.

---

Step 4 — Produce clarifying questions

Create 5–12 questions, optimized to reduce ambiguity without over-scoping.

Guidance:

• Prefer questions that resolve: target user, core problem, non-goals, constraints, MVP vs later, inputs/outputs.
• Avoid implementation rabbit holes unless the idea explicitly mentions them.
• If the idea implies a framework/tooling product, ask about: audience, intended workflow, what “done” looks like.

Write questions to:

• docs/forge/ideas/<IDEA_ID>/inputs/imagine_questions.md

  (overwrite allowed)

• docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/imagine_questions.md

---

Step 5 — Draft

idea.md

(REVIEWABLE)

Create a draft idea document based on:

• the base idea (existing idea.md or initial text)
• reasonable assumptions clearly marked
• TODO markers where answers are needed

Write draft to:

• docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/idea_draft.md

Do NOT write to

inputs/idea.md

yet.

---

Step 6 — Ask the user and stop (Phase 1)

In chat, present:

1. The generated questions as a numbered list.
2. A short note: “Reply with answers in the same numbered format. Optionally include edits to the draft idea.”
3. Also present the draft idea (or a short summary + tell where it was saved, depending on tool limits).

Then append a run_log entry with:

• Status:

  NEEDS_USER_INPUT

• Run-ID:

  <RUN_ID>

• Outputs so far:

  inputs/imagine_questions.md

  ,

  runs/<RUN_ID>/idea_draft.md

STOP and wait for the user reply.

---

Phase 2 — Capture answers, finalize

inputs/idea.md

When the user replies:

Step 7 — Persist answers (append-only)

Append the user’s answers to:

• docs/forge/ideas/<IDEA_ID>/inputs/imagine_answers.md

Format:

### <ISO-8601> — Answers for <RUN_ID>

<user answers verbatim, lightly formatted if needed>

---

Step 8 — Produce final

idea.md

Update the draft by incorporating answers:

• Replace TODOs with decisions
• Move information into correct sections
• Keep scope stable; do not add new requirements beyond what the user confirmed
• If something remains unclear, keep it in an “Open Questions” section (but keep it short)

Write final to BOTH:

• docs/forge/ideas/<IDEA_ID>/inputs/idea.md

  (overwrite allowed)

• docs/forge/ideas/<IDEA_ID>/runs/<RUN_ID>/idea_final.md

---

Step 9 — Update logs + manifest

Append a SUCCESS entry to:

• docs/forge/ideas/<IDEA_ID>/run_log.md

And create/update manifest:

• if

  manifest.md

  exists, update only the keys under

  Idea

  section

---

Output Format:

idea.md

(Markdown + YAML header)

Write

idea.md

with a YAML header followed by sections.

YAML header (example)

---
doc_type: idea
idea_id: "<IDEA_ID>"
generated_by: "Imagine (Idea Intake)"
generated_at: "<ISO-8601>"
run_id: "<RUN_ID>"
source:
  - "user_input ($ARGUMENTS or existing inputs/idea.md)"
qa:
  questions: "inputs/imagine_questions.md"
  answers: "inputs/imagine_answers.md (appended)"
status: "Draft"
---

Recommended sections

Idea

One-liner

(1 sentence)

Problem / Motivation

• ...

Target Users

• ...

Goals

• ...

Non-Goals

• ...

Constraints

• ...

Inputs

• ...

Outputs

• ...

High-level Workflow

1. ...
2. ...

Success Criteria

• ...

Open Questions (if any)

• ...

---

Logging Requirements:

run_log.md

(append-only)

Append entries with this shape:

Phase 1 (needs input)

### <ISO-8601 timestamp> — Imagine (Idea Intake)

- Idea-ID: <IDEA_ID>
- Run-ID: <RUN_ID>
- Mode: new | refine
- Inputs:
  - user_input ($ARGUMENTS) OR inputs/idea.md (if refining)
- Outputs:
  - inputs/imagine_questions.md
  - runs/<RUN_ID>/imagine_questions.md
  - runs/<RUN_ID>/idea_draft.md
- Status: NEEDS_USER_INPUT
- Notes:
  - <1–3 bullets on main unknowns>

Phase 2 (finalized)

### <ISO-8601 timestamp> — Imagine (Idea Intake) — Finalize

- Idea-ID: <IDEA_ID>
- Run-ID: <RUN_ID>
- Outputs:
  - inputs/imagine_answers.md (appended)
  - inputs/idea.md
  - runs/<RUN_ID>/idea_final.md
- Status: SUCCESS | SUCCESS_WITH_WARNINGS | FAILED
- Notes:
  - <1–5 bullets on key decisions captured>

---

Manifest template (if creating new)

# Manifest — <IDEA_ID>

## Idea

- idea_status: Draft
- last_updated: <YYYY-MM-DD>
- last_run_id: <RUN_ID>
- latest_inputs:
  - inputs/idea.md
  - inputs/imagine_questions.md
  - inputs/imagine_answers.md
- notes:
  - <optional bullets>

---

Failure handling

If the initial idea is extremely short/vague:

• Still generate questions
• Draft

  idea.md

  with placeholders/TODOs
• Do not invent details