Skip to content
Shell

Add Stage 0 Discovery and Client Project Template

eddiebe147f1e3f018d2e1
diff --git a/CLAUDE.md b/CLAUDE.md
index 64b917d..5885893 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -210,10 +210,29 @@ Then automatically:
This pipeline governs ALL ID8Labs product development. Follow it without exception.
-## The 11 Stages
+## The 12 Stages
Every project flows through these stages in order. Hard stops at each gate.
+### Stage 0: Discovery (Client Projects Only)
+**When:** Building for someone other than yourself (client, colleague, stakeholder)
+**Skip if:** Building your own product — go straight to Stage 1
+
+**Gate:** You deeply understand the person and their problem before touching code.
+
+**Process:**
+1. Run the discovery interview (see `~/.claude/CLIENT_PROJECT_TEMPLATE.md`)
+2. Complete the Client Profile (who they are, what they want, how they communicate)
+3. Document look/feel preferences and constraints
+4. Create project CLAUDE.md from template
+5. Create TECHNICAL.md for your stack decisions
+
+**Checkpoint:** "Can I explain what we're building and why — in their words, not mine?"
+
+**Key principle:** The client is the expert on *what* they want. You're the expert on *how* to build it. Stage 0 ensures you understand their world before applying your expertise.
+
+---
+
### Stage 1: Concept Lock
**Gate:** One sentence defines the problem and who it's for.
**Checkpoint:** "What's the one-liner?"
@@ -312,6 +331,8 @@ When user says:
- "pipeline status" → Report current stage and next checkpoint
- "checkpoint cleared" → Advance to next stage, update PIPELINE_STATUS.md
- "skip to [stage]" → Require reason, log override, proceed
+- "client project" → Start Stage 0 discovery using CLIENT_PROJECT_TEMPLATE.md
+- "my project" → Skip Stage 0, go directly to Stage 1
---
diff --git a/CLIENT_PROJECT_TEMPLATE.md b/CLIENT_PROJECT_TEMPLATE.md
new file mode 100644
index 0000000..6c63847
--- /dev/null
+++ b/CLIENT_PROJECT_TEMPLATE.md
@@ -0,0 +1,220 @@
+# Client Project Template
+
+Use this template when starting a project for a **non-technical client**. Copy this to the project's `CLAUDE.md` and complete the interview before building anything.
+
+---
+
+## How to Use This Template
+
+1. **Start the interview** — Run through all discovery questions conversationally
+2. **Fill in the sections** — Complete each section based on interview answers
+3. **Create TECHNICAL.md** — Separate file for your technical decisions (client never sees this)
+4. **Begin Stage 1** of ID8Pipeline — Concept Lock
+
+---
+
+# CLAUDE.md — [Project Name]
+
+## Section 1: Client Profile
+
+### Who They Are
+- **Name:** [Client name]
+- **Role/Business:** [What they do]
+- **Tech comfort level:** [Non-technical / Somewhat technical / Technical but not a developer]
+
+### What They Want
+- **Problem statement (their words):**
+ > [Capture exactly how they describe the problem]
+
+- **Who it's for:** [Just them / Their team / Their customers / Public]
+
+- **Success criteria:**
+ > [How will they know it's "done"? What does success look like?]
+
+- **Reference examples:** [Any apps, sites, or tools they mentioned as similar]
+
+### Constraints
+- **Must-haves:**
+ - [ ] [Essential feature 1]
+ - [ ] [Essential feature 2]
+ - [ ] [Essential feature 3]
+
+- **Nice-to-haves:**
+ - [ ] [Optional feature 1]
+ - [ ] [Optional feature 2]
+
+- **Timeline:** [Any deadlines or time pressure]
+
+- **Budget considerations:** [If relevant]
+
+### Communication Preferences
+- **How they want updates:** [Working demos / Screenshots / Simple descriptions]
+- **Check-in frequency:** [Daily / Every few days / Weekly / Milestones only]
+- **Feedback style:** [Try and react / Review screenshots / Describe what's wrong]
+- **Stress triggers:** [Anything to avoid in the process]
+
+---
+
+## Section 2: Look and Feel
+
+- **Desired experience:** [Fast and simple / Rich and detailed / Playful / Professional / Other]
+- **Visual direction:** [Colors, styles, brands to align with]
+- **Existing materials:** [Logos, docs, examples provided]
+- **Accessibility needs:** [Any known requirements]
+- **Device priorities:** [Desktop first / Mobile first / Both equally]
+
+---
+
+## Section 3: Communication Rules
+
+When talking to this client:
+
+1. **NEVER ask technical questions.** Make all technical decisions yourself.
+
+2. **NEVER use jargon.** Translate everything:
+ - "the database" → "where your information is stored"
+ - "API" → "how different parts talk to each other"
+ - "deploy" → "make it live"
+ - "authentication" → "the login system"
+
+3. **Explain like a smart friend** who doesn't work in tech.
+
+4. **Celebrate in their language:**
+ - YES: "People can now sign up and log in"
+ - NO: "Implemented auth flow with JWT tokens"
+
+5. **Show, don't tell.** Demos > descriptions. Screenshots > explanations.
+
+---
+
+## Section 4: Decision Authority
+
+### You Decide (Never Ask Client)
+- Languages, frameworks, architecture
+- Libraries, dependencies, packages
+- Database design and structure
+- File organization
+- Hosting and infrastructure
+- API design
+- Code patterns and conventions
+- Security implementation details
+- Performance optimizations
+
+**Guiding principles:**
+- Choose boring, reliable, well-supported tech over cutting-edge
+- Optimize for maintainability and simplicity
+- Document decisions in TECHNICAL.md (for future developers, not client)
+
+### Ask Client Only When
+It directly affects what they **see or experience**. When you do:
+
+1. Explain the tradeoff in plain language
+2. Describe how each option affects their experience
+3. Give your recommendation with reasoning
+4. Make it easy to say "go with your recommendation"
+
+**Examples of when to ask:**
+- "This can load instantly but look simpler, or look richer but take 2 seconds. Which matters more?"
+- "I can make this work on phones too, but it adds a day. Worth it?"
+- "There are two ways to organize this screen. Let me show you both."
+
+**Examples of when NOT to ask:**
+- Anything about databases, APIs, frameworks, or architecture
+- Library choices or dependencies
+- How to implement any feature technically
+- File structure or code organization
+
+---
+
+## Section 5: Quality Standards
+
+Apply automatically without discussion:
+
+### Code Quality
+- [ ] Clean, well-organized, maintainable code
+- [ ] Comprehensive automated testing (unit, integration, E2E)
+- [ ] Self-verification — system checks itself
+- [ ] Graceful error handling with friendly messages
+- [ ] Input validation and security best practices
+- [ ] Clear for future developers to understand
+- [ ] Proper version control with clear commits
+
+### Before Showing Client
+- [ ] Test everything yourself first
+- [ ] Never show broken functionality
+- [ ] Fix problems — don't explain technical issues
+- [ ] Everything visible must work
+- [ ] Automated checks pass before going live
+
+### Progress Updates
+- [ ] Show working demos when possible
+- [ ] Use screenshots when demos aren't practical
+- [ ] Describe changes in experience terms, not technical terms
+- [ ] Celebrate milestones in language they care about
+
+---
+
+## Section 6: Project-Specific Details
+
+[Complete this section with everything learned from the discovery interview]
+
+### The Project
+[What are we building?]
+
+### Key Features (Priority Order)
+1. [Feature 1]
+2. [Feature 2]
+3. [Feature 3]
+
+### User Flows
+[How will people use this?]
+
+### Special Considerations
+[Anything unique about this project]
+
+---
+
+## Discovery Interview Script
+
+Use this conversational flow. Ask 1-2 questions at a time. Let answers guide follow-ups.
+
+### Opening
+> "Before we build anything, I want to understand you and what you're trying to accomplish. There are no wrong answers — you're the expert on what you want, I'm the expert on how to build it."
+
+### About Them
+- Who are you? What do you do?
+- How comfortable are you with technology in general? (Just so I know how to communicate)
+- How do you prefer to see progress? (Working demos, screenshots, descriptions?)
+
+### About What They Want
+- What problem are you trying to solve? (In your own words)
+- Who is this for? (Just you, team, customers, public?)
+- What does success look like? How will you know when it's "done"?
+- Have you seen anything similar to what you want? (Apps, websites, tools — even vague comparisons help)
+- What absolutely must be included? What would be nice but isn't essential?
+- Is there a timeline or deadline?
+
+### About Look and Feel
+- How should it feel to use? (Fast and simple? Rich and detailed? Playful? Professional?)
+- Any colors, styles, or brands you want it to align with?
+- Will different types of people use this? Any accessibility needs?
+- Do you have existing materials to share? (Logos, documents, examples)
+
+### About Working Together
+- How do you want to give feedback? (Try things? Review screenshots? Describe issues?)
+- How often do you want to check in?
+- Is there anything that would make this process stressful that we should avoid?
+
+### Dig Deeper
+- Follow up on anything important
+- Ask clarifying questions
+- Don't rush
+
+---
+
+## After Interview Checklist
+
+- [ ] All sections above completed
+- [ ] Created TECHNICAL.md with stack decisions
+- [ ] Created PIPELINE_STATUS.md
+- [ ] Ready to begin Stage 1: Concept Lock