Task: Generate PROPOSAL.md — Vision Layer for a New ADD Project

Task: Generate PROPOSAL.md — Vision Layer for a New ADD Project

Objective

Produce a PROPOSAL.md that anchors an Agent-Driven Development project at the vision layer. The document states the problem in the user's domain language, the thesis of the solution, the principles that will constrain every later decision, the non-goals that prevent scope creep, the testable success criteria, the target actors, the first-milestone scope boundaries, the risks and assumptions, a small glossary stub, and any genuinely unresolved questions. An agent reading this document alone can set the direction for downstream artifacts — /use-cases derives its actors and scenarios from it, /domain draws its initial glossary from it, /architecture inherits its principles and non-goals — without needing to re-ask the user what the project is about or why it matters.

PROPOSAL.md is the first file written in an ADD project and has no prior artifacts to read. It is produce-once and read-many: every later phase cites it for grounding. A weak proposal produces weak downstream artifacts; treat every section as a commitment that propagates.

Inputs

1. User intent prompt (required) — the free-form description of what the user wants built. May be a single sentence or a multi-paragraph brief. This is the single primary input; everything in the output traces back to it.
2. Reference material (optional) — prior art the user points at (competitor docs, research notes, related projects, internal memos). Read it to extract decision-shaping facts; do not inline large excerpts. Cite by short name where a principle or non-goal is drawn from a specific source.
3. Existing PROPOSAL.md (auto-discovered — only if refining) — if a PROPOSAL.md already exists at the expected path, read it fully and treat every decision as authoritative unless the new prompt explicitly contradicts it. Preserve prior principles, non-goals, and success criteria when they remain valid; merge new information; never silently renumber or drop existing commitments.

Read-set size: 1 required + up to 2 optional. The read count at this step is 0 prior ADD artifacts — the proposal is the seed. Read the user prompt word-for-word; subtle hints about users, scale, or constraints are often the deciding input for a section.

Workflow

Proposal generation proceeds in six phases: intent extraction, problem-and-thesis draft, principles-and-non-goals, success-criteria-and-actors, scope-risks-glossary, and validation. Phases are sequential — each phase feeds the next — but revisit earlier phases if a later one reveals a gap or contradiction.

Phase 1: Intent Extraction

Read the user prompt and any reference material end-to-end. Extract four things into a working list:

• Nouns the user uses for the thing being built — the candidate product name and the candidate names for core concepts (e.g., Repository, Push, Collaborator; Order, Cart, Line Item). These seed § 9 Glossary and hint at actors.
• Pain statements — every phrase where the user describes something as broken, slow, awkward, missing, or frustrating. These seed § 1 Problem Statement.
• Belief statements — every phrase where the user says "we think", "the key insight is", "it should", "always", "never". These seed § 2 Solution Thesis and § 3 Core Principles.
• Exclusion statements — every phrase where the user says "not", "won't", "out of scope", "later", "not in v1". These seed § 4 Non-Goals.

If any of the four categories is empty, do not invent content — note the gap as an open question in Phase 6.

Pick the product name: prefer the name the user uses verbatim; if absent, use a bracketed placeholder like {ProductName} throughout and list "confirm product name" as an open question.

Phase 2: Problem Statement & Solution Thesis

Draft § 1 and § 2 in that order. § 1 must precede § 2 so the thesis answers a named problem.