A complete framework for transforming **one structured conversation** with an AI into every artifact an autonomous coding agent needs to ship a product.

---
## 0. Setup & Conventions
| Item | Convention |
|------|------------|
| Conversation tag | `#[PROJECT‑NAME]` prefix on every message |
| Transcript capture | Persist markdown log to `/convo/YYYY‑MM‑DD.md` after each session |
| Decision stamp | Inline `DECISION:` blocks; auto‑collected into `/docs/decisions.md` |
| Assumption stamp | Inline `ASSUME:` blocks; auto‑collected into `/docs/assumptions.md` |
| Model role prompt | `You are the Conversation Facilitator…` (system) |
| Temperature default | 0.4 (deterministic); override via `!temp <0‑1>` |

---
## 1. Purpose
Provide a repeatable, LLM‑agnostic pathway from **dialogue → documentation → code**, enabling the Product Owner (PO) to stay in “conversation mode” while AI handles the heavy documentation lift.

## 2. Roles
| Role | Played by | Key responsibilities |
|------|-----------|----------------------|
| Product Owner (PO) | You | Bring context, choose trade‑offs, final sign‑off |
| Conversation Facilitator (CF) | GPT‑4o / o3 / 4.1 mini‑high | Guide dialog, extract clarity, draft docs |
| Builder Agent (BA) | Any coding LLM/agent crew | Consume docs, generate/review code, deploy |

---
## 3. High‑Level Flow
1. **Idea Triage** – compare candidate ideas & pick one.
2. **Problem Deep‑Dive** – capture users, pain, constraints, metrics.
3. **Solution Framing** – craft value prop & user stories.
4. **Scope Guardrails** – prevent scope creep & over‑engineering.
5. **Incremental Road‑mapping** – MVP → V1 → V2 → V3.
6. **Doc Generation** – auto‑create VISION, PRD, BACKEND, FRONTEND, IMPLEMENTATION, VERSIONING, SCOPE docs.
7. **Definition‑of‑Done & Handoff** – formal checklist before any code starts.
8. **Review & Iterate** – PO reviews PRs; CF syncs docs and code reality.

> **Rule‑of‑Thumb:** No code generation (by BA) begins until step 7 is green across the board.

---
## 4. Phase‑by‑Phase Guide & Prompts
### 4.1 Idea Triage
**Goal:** Select the idea with the highest Expected Value (EV).

*Prompt skeleton (for each idea)*
```
#IDEA   <one‑liner>
#MARKET <target users / TAM>
#PAIN   <why current workaround hurts>
#EDGE   <differentiator>
#EFFORT_EST <S/M/L guess>
```

**CF actions**
1. Score each idea with the EV rubric (Appendix 7.1).
2. Return comparison matrix + recommendation.

### 4.2 Problem Deep‑Dive
**CF asks:**
1. Who is the *primary* user & extreme persona?  
2. Job‑to‑be‑Done & context triggers?  
3. Current workaround & pain intensity (1‑5)?  
4. Moments of friction?  
5. Success metrics from user POV?  
6. Business / regulatory constraints?  

**Output:** `/docs/problem_summary.md` (auto‑generated).

### 4.3 Solution Framing
CF guides:
* Craft the value‑prop sentence: *“For \<persona\> who struggle with \<pain\>, \<Product> is a \<category\> that enables \<benefit\> unlike \<alt>.”*
* List 3‑5 key user stories in Gherkin‑ish form.
* Identify unique insight or technical advantage.

### 4.4 Scope Guardrails
CF prompts:
1. Must‑have vs nice‑to‑have?  
2. Time‑box for MVP (e.g. 4 wks)?  
3. Max acceptable unknowns / external dependencies?  
4. Exit criteria for “good enough to ship”?  

**Output:** `/docs/scope.md` – constraints accepted by PO.

### 4.5 Incremental Road‑mapping
| Release | Guiding principle | Feature bucket |
|---------|------------------|-----------------|
| **MVP** | *De‑risk viability* | 1–3 core stories, manual ops OK |
| **V1** | *Retention & reliability* | Auth, analytics, self‑serve onboarding |
| **V2** | *Growth & moat* | Integrations, automation, pricing tiers |
| **V3** | *Platform expansion* | Public APIs, marketplace, SDK |

CF maps each user story to earliest sensible release & flags postponed tech debt in `/docs/versioning.md`.

### 4.6 Definition‑of‑Done (DoD) & Handoff Protocol
| Checklist | Details |
|-----------|---------|
| **Docs frozen** | Tag `doc‑vX.Y` & hash transcript ID |
| **File tree ready** | Matches Section 6.1 structure |
| **Acceptance tests** | Specs in `/tests`; PO validated |
| **Risk register reviewed** | High L×I risks have mitigations |
| **Builder prompt** | `/docs/builder_prompt.md` one‑pager |
| **Retrieval key** | Vector‑DB embed of docs+transcript |

Only when every cell is ✅ does BA begin scaffolding.

### 4.7 Review & Iterate
* CF watches PRs, summarises diffs for PO daily.  
* If code diverges from docs, CF opens a `/docs/update‑request.md` issue.  
* Weekly retro on doc adequacy & process friction.

---
## 5. Governance & Source‑of‑Truth
* `main` branch holds only approved docs.  
* PR templates force link to relevant decision & risk IDs.  
* Lint rule: docs change ⇒ bump `doc‑v` version.

---
## 6. Quick Reference
### 6.1 Recommended File Tree
```
/README.md
/docs
  vision.md
  prd.md
  backend.md
  frontend.md
  implementation.md
  versioning.md
  scope.md
  risk_register.md
  builder_prompt.md
  decisions.md
  assumptions.md
/tests
  unit/
  e2e/
/convo
  2025‑04‑19.md
``` 

### 6.2 Slash Commands
| Command               | Action                      |
|-----------------------|-----------------------------|
| `!new‑idea`           | Start Idea Triage           |
| `!deep‑dive`          | Begin Problem Deep‑Dive     |
| `!scope`              | Enter Scope Guardrails      |
| `!roadmap`            | Map releases                |
| `!generate <DOC>`     | Create specified doc        |
| `!handoff`            | Run DoD checklist           |

### 6.3 Testing Guidelines
> **Purpose:** Ensure consistent, automated quality checks throughout the development lifecycle, driven by AI agents where possible.

---

# 7. Appendix

## 7.1 Expected Value (EV) Rubric

| Factor         | Weight | Scoring Guide (1–5)                |
|----------------|--------|------------------------------------|
| User Impact    | 3×     | How much pain does this solve?     |
| Feasibility    | 2×     | Can we build it with current team? |
| Strategic Fit  | 2×     | Does it align with our vision?     |
| Differentiation| 1×     | Is it unique vs. alternatives?     |
| Effort         | -1×    | How much work is required?         |

**EV Score = (User Impact ×3) + (Feasibility ×2) + (Strategic Fit ×2) + (Differentiation ×1) – (Effort ×1)**

## 7.2 Example Comparison Matrix

| Idea         | User Impact | Feasibility | Strategic Fit | Differentiation | Effort | EV Score |
|--------------|-------------|-------------|--------------|-----------------|--------|----------|
| Idea A       | 5           | 4           | 5            | 3               | 3      | 31       |
| Idea B       | 3           | 5           | 4            | 2               | 2      | 25       |

## 7.3 Example Decision Log

| ID     | Date       | Summary                          | Rationale               | Owner |
|--------|------------|----------------------------------|-------------------------|-------|
| DEC-001| 2025-04-19 | Postgres chosen over MongoDB     | Need ACID compliance    | PO    |

## 7.4 Example Assumption Log

| ID     | Date       | Assumption                       | Rationale               | Owner |
|--------|------------|----------------------------------|-------------------------|-------|
| ASSUME-001| 2025-04-19 | Users will prefer email auth  | Simpler onboarding      | PO    |

   - **Unit Tests:** Cover individual functions/components. Aim for ≥80% coverage.
   - **Integration Tests:** Verify interactions between modules (e.g., API ↔ DB).
   - **End-to-End (E2E) Tests:** Simulate real user flows across front-end/back-end.
   - **Performance/Load Tests:** Validate latency SLAs (p95, throughput).
   - **Security/Compliance Tests:** Basic auth checks, input sanitization.

2. **Test-Driven Workflow**
   - Encourage TDD: AI modules generate tests before implementation.
   - Define test stubs as part of Sequenced Build Steps (Step 5: Tester).

3. **Naming & File Organization**
   - Unit tests alongside code: `ComponentName.test.tsx` or `module.spec.py`.
   - Integration/E2E under `/tests/integration` and `/tests/e2e` respectively.

4. **Mocking & Fixtures**
   - Use consistent fixture files in `/tests/fixtures`.
   - AI Agent should generate realistic mock data per API schema.

5. **CI Integration**
   - All tests run on PR; failures block merge.
   - Quick feedback: prioritize fast unit tests, parallelize E2E.

6. **Reporting & Metrics**
   - CI badges: coverage %, build status in README.
   - Automated test reports archived by date/commit.

7. **Agent Responsibilities**
   - **Scaffolder:** generate basic test config (jest.config.js, pytest.ini).
   - **Tester Module:** populate test cases and maintain fixtures.
   - **Integrator:** verify tests against deployed staging env after each release.

8. **DoD Extension**
   - All new features include passing unit, integration, and critical E2E tests before merging.
   - Performance tests meet SLAs before production deployment.


### 7.5 Full Document Templates
<details><summary>Click to view skeletons</summary>

#### **vision.md**
```markdown
# Vision

> **Purpose:** Paint a vivid picture of the change we seek to make, for whom, and why it matters. Influenced by Seth Godin’s principles of remarkability, smallest viable audience, and tribe-building.

## 1. Problem (Status Quo)
- What persistent tension or frustration exists today?
- Whose status is affected (emotional resonance)?

## 2. Change We Seek to Make
- One sentence: "We’re on a mission to ___ so that ___."
- Why will the world miss us if we don’t succeed?

## 3. Smallest Viable Audience (SVA)
| Segment                 | Size (est.) | Shared Worldview / Story               |
|-------------------------|-------------|-----------------------------------------|
| Indie developers who…   | 15 k        | Believe in OSS, distrust BigCloud       |

> If it’s not for someone in particular, it’s for no one.

## 4. Purple Cow / Remarkability
- What makes the product genuinely worth talking about?
- Evidence we deliver 10× improvement and a share-worthy story.

## 5. Future State Narrative (3 yrs)
- Describe a day-in-the-life of an SVA member post-adoption.

## 6. North-Star Metric
- Quantitative measure of progress toward our change.

## 7. Guiding Principles (3–5)
- E.g., "Default to open", "Delight > complexity".

## 8. Tribe & Storytelling Hooks
- Symbols or rituals that signal belonging.
```

#### **prd.md**
```markdown
# Product Requirements Document

> **Purpose:** Provide crystal-clear framing so AI agents build with minimal ambiguity. Combines JTBD, Thiel’s Seven Questions, and Godin’s audience & storytelling.

---
## Thiel Check – Seven Questions
| # | Question                                    | AI Prompt Expansion                 |
|---|---------------------------------------------|-------------------------------------|
| 1 | Can we deliver 10× improvement?             | Define metric and tech enabler.     |
| 2 | Is now the right time?                      | List enabling trends/timing risks.  |
| 3 | Can we dominate a small niche?              | Specify niche TAM and moat path.    |
| 4 | Do we have the right team?                  | Map skills and gaps.                |
| 5 | How will we distribute?                     | Outline scalable acquisition.       |
| 6 | Will advantages last 10+ years?             | Identify and defend moats.         |
| 7 | What secret truth do we know?               | State non-consensus insight.        |

---
## Godin Lens – Story & Market
| Aspect                  | Question                                    | Notes                            |
|-------------------------|---------------------------------------------|----------------------------------|
| Smallest Viable Audience| Who exactly are we building for?            | Size, worldview, early adopters. |
| Story Worth Spreading   | What narrative will users retell?           | Purple Cow signal.               |
| Permission Asset        | How will we earn ongoing attention?         | Community, API, email, etc.      |

---
## 1. Objectives
- **Primary Objective:** JTBD-driven goal.
- **Secondary Objectives:** Additional outcomes.

## 2. Out of Scope
- Features or domains deferred.

## 3. Personas & JTBD
| Persona           | JTBD Statement                          | Trigger                      |
|-------------------|-----------------------------------------|------------------------------|
| Early Adopter Emi | When X happens, I want Y so I can Z.    | Describe context.            |

## 4. Key User Stories & Acceptance Criteria
| ID   | User Story                                | Acceptance Criteria        |
|------|-------------------------------------------|----------------------------|
| US-1 | As a user, I can ___ so I ___             | Given… When… Then…         |

## 5. Success Metrics & KPIs
- **North-Star Metric:** Aligned with Vision.
- **Supporting Metrics:** Conversion, retention, engagement.

## 6. Hypotheses & Risks
| Hypothesis                         | Confidence | Test / Mitigation           |
|------------------------------------|------------|-----------------------------|
| Feature X increases activation 15% | Medium     | A/B test cohort.            |

## 7. Open Questions
- List pending decisions or required research.
```

#### **backend.md**
```markdown
# Backend Spec

> **Guidelines:** Treat sections 1–4 as mandatory; 5–6 optional.

## 1. Architecture Diagram (Mermaid) [Mandatory]
- Services, data stores, external dependencies.

## 2. Data Models (ERD) [Mandatory]
- Entities, relationships, attributes.

## 3. Core API Contracts (OpenAPI) [Mandatory]
- Endpoints with method, path, schemas.
- Versioning strategy (e.g., /v1/).

## 4. Non-Functional Requirements [Mandatory]
- Scale targets, latency SLAs, security.

## 5. Observability Plan [Recommended]
- Logging, metrics, tracing.

## 6. Additional Considerations [Optional]
- Caching, rate limiting, backups.
```

#### **frontend.md**
```markdown
# Frontend Spec

## 1. Architecture & Tech Stack
- Library (React/Vue), UI toolkit, state management, routing.

## 2. Component Inventory
| Component | Purpose         | Inputs     | Outputs    |
|-----------|-----------------|------------|------------|
| AppShell  | Layout & nav    | user, routes | —        |
| ItemList  | Display items   | items[]   | onSelect  |

## 3. Data Binding & Contracts
- Map components to OpenAPI endpoints.

## 4. State Management
- Global vs local state, caching, optimistic updates.

## 5. Styling & Theming
- Design tokens, Tailwind vs CSS-in-JS, dark mode.

## 6. Accessibility & i18n
- ARIA roles, keyboard nav, locale files.

## 7. Testing & Quality
- Unit & e2e coverage, linting, type checks.

## 8. Code Generation Hints
- File/folder conventions, component stub example.
```

#### **implementation.md**
```markdown
# Implementation Plan

## Integration Overview
- High-level architecture diagram (FE, BE, infra).
- Data flow narrative (request → logic → DB → response).

## Sequenced Build Steps
| Step | AI Module      | Description                              | Inputs           | Outputs         |
|------|----------------|------------------------------------------|------------------|-----------------|
| 1    | Scaffolder     | Scaffold repo & folders                  | versioning.md    | /src skeleton   |
| 2    | API Generator  | Build endpoints from backend.md          | backend.md       | /src/backend    |
| 3    | UI Generator   | Generate components from frontend.md     | frontend.md      | /src/frontend   |
| 4    | Integrator     | Wire UI to live API; replace mocks       | openapi.yaml     | integrated app  |
| 5    | Tester         | Write/run unit & e2e tests               | tests specs      | test reports    |
| 6    | Deployer       | Configure CI/CD & deploy staging         | IaC, Dockerfile  | staging URL     |

## Shared Contracts
- OpenAPI definitions, shared types, error schema.

## Environments
| Env     | Branch    | Purpose        |
|---------|-----------|----------------|
| Local   | feature/* | Development    |
| Staging | develop   | QA & UAT       |
| Prod    | main      | Live service   |

## Deployment Pipeline
- PR merge → build → test → dockerize → deploy → smoke.
- Auto rollback on smoke failure.

## Observability
- Logging (JSON), metrics (Prometheus), tracing (OTel).

## AI Agent Exit Criteria
- All journeys pass e2e in staging.
- p95 latency <300ms; error rate <1% @50rps.
- PO approval on staging demo.

## WBS, Sprint Plan, Resourcing, Tooling
- See detailed breakdown in implementation.md comments.
```

#### **decisions.md**
```markdown
# Decision Log

> **Purpose:** Track key decisions and rationale for auditability.

| ID     | Date       | Summary                          | Rationale               | Owner |
|--------|------------|----------------------------------|-------------------------|-------|
| DEC-001| 2025-04-19 | Postgres chosen over MongoDB     | Need ACID compliance    | PO    |
```

</details>

### 7.6 Risk Register Template Risk Register Template
```markdown
| ID | Risk | Likelihood (1‑5) | Impact (1‑5) | Owner | Mitigation |
|----|------|-----------------|--------------|-------|------------|
| R‑1 | API rate‑limits | 3 | 4 | Dev‑Sam | Caching proxy |
```

### 7.7 Glossary
| Term | Meaning |
|------|---------|
| CF | Conversation Facilitator |
| BA | Builder Agent |
| EV | Expected Value |
| DoD | Definition‑of‑Done |

---
**End Playbook v0.3**