whiteport-design-studio 0.1.0

package/src/workflows/1-project-brief/alignment-signoff/steps-c/step-02-explore-sections.md

@@ -0,0 +1,159 @@
+# Step 2: Explore Pitch Sections
+
+## Purpose
+
+Guide the user through exploring all pitch sections in a natural, collaborative flow.
+
+---
+
+## Pitch Structure (All Sections to Cover)
+
+**Inspired by proven frameworks**: Customer-Problem-Solution, Value Proposition Canvas, Problem-Agitate-Solve, Business Case Framework
+
+The pitch should eventually cover these 10 sections:
+
+1. **The Realization** - What we've realized needs attention (PAS: Problem)
+2. **Why It Matters** - Why this matters and who we help (Value Prop Canvas: Customer Profile + Impact)
+3. **How We See It Working** - Brief overview of the solution approach (CPS: Solution)
+4. **Paths We Explored** - 2-3 solution options we considered
+5. **Recommended Solution** - Preferred approach and why (CPS: Solution)
+6. **The Path Forward** - How the work will be done (WDS phases and practical approach)
+7. **The Value We'll Create** - What happens if we DO build this (Business Case: Return)
+8. **Cost of Inaction** - What happens if we DON'T build this (PAS: Agitate / Business Case: Risk)
+9. **Our Commitment** - Resources needed and potential risks (Business Case: Cost + Risk)
+10. **Summary** - Summary of key points
+
+**Note**: You don't need to cover these in this exact order. Follow the user's natural thinking flow. The frameworks are guides, not rigid rules.
+
+---
+
+## Detect Starting Point
+
+**Ask**: "Where would you like to start? Are you seeing a problem that needs solving, or do you have a solution in mind?"
+
+**If user starts with problem**:
+- Explore the problem first
+- Then naturally move to "who is affected"
+- Then explore solutions
+
+**If user starts with solution**:
+- Capture the solution idea
+- Then explore "what problem does this solve?"
+- Then explore "who is affected"
+- Then explore other possible approaches
+
+**If user starts elsewhere**:
+- Follow their lead
+- Guide them through remaining sections naturally
+
+---
+
+## Guiding Principles
+
+**When responding to user ideas or questions, follow this pattern:**
+
+1. **Acknowledge** - "I hear you asking about..." or "That's an interesting idea..."
+2. **Summarize** - "So you're thinking that..." or "What I'm understanding is..."
+3. **Confirm understanding** - "Is that right?" or "Am I understanding correctly?"
+4. **Then explore solutions** - Only after confirming understanding, offer options or suggestions
+
+**Never jump straight to bullet lists or solutions.** Always acknowledge, summarize, and confirm understanding first.
+
+**Collaborative, not interrogative**:
+- "Let's explore this together..."
+- "What I'm hearing is..."
+- "This is interesting - tell me more about..."
+- "How do you see this working?"
+
+**Allow ideas to evolve**:
+- If user's idea changes as they talk, that's good!
+- Reflect back: "It sounds like your thinking is evolving - that's great!"
+- Update understanding as you go
+
+**Natural flow**:
+- Don't force a rigid sequence
+- Follow the user's thinking
+- Guide them to cover all sections, but in whatever order makes sense
+
+**Make it shine**:
+- Help them articulate their idea clearly
+- Find the compelling angles
+- Present it in the best light
+
+---
+
+## Section Exploration Guide
+
+**Reference**: `src/modules/wds/workflows/1-project-brief/alignment-signoff/section-guide.md`
+
+Use the section guide to explore each section as the user naturally moves through them.
+
+**Important**: The Work Plan section (section 6) explains which WDS phases will be used and how the work will be done practically. This helps stakeholders understand the approach and workflow.
+
+**Framework Inspiration**: This guide draws from proven frameworks:
+- **Customer-Problem-Solution (CPS)** - Clear structure
+- **Value Proposition Canvas** - Understanding customer needs
+- **Problem-Agitate-Solve (PAS)** - Natural flow
+- **Business Case Framework** - Investment and consequences
+
+---
+
+## Best Practice: Realization Section with Evidence
+
+**When exploring "The Realization" section**, help the user identify and confirm the realization with evidence:
+
+### Step 1: Identify the Realization
+- What have you realized needs attention?
+- What observation or challenge are you seeing?
+- What opportunity is being missed?
+
+### Step 2: Confirm It's Real
+- Is there evidence that supports this realization?
+- Do stakeholders recognize this as real?
+- Does this matter to stakeholders?
+
+### Step 3: Gather Evidence
+
+**Help them identify both types of evidence:**
+
+**Soft Evidence** (qualitative indicators):
+- **Testimonials**: "Do you have customer feedback or testimonials about this?"
+- **Complaints**: "What complaints or support tickets mention this?"
+- **Observations**: "What patterns have you observed?"
+- **Interviews**: "What do user interviews or conversations reveal?"
+- **Indications**: "What signs indicate this is a problem?"
+
+**Hard Evidence** (quantitative data):
+- **Statistics**: "Do you have numbers or percentages?"
+- **Analytics**: "What do analytics or usage data show?"
+- **Surveys**: "Have you run surveys or tests?"
+- **Logs**: "What do server logs or error reports indicate?"
+- **Metrics**: "What metrics demonstrate this problem?"
+
+**Best Practice**: Combine both types for maximum credibility:
+- Start with soft evidence (testimonials, complaints, observations)
+- Support with hard evidence (statistics, analytics, survey results)
+- Show the problem is real, measurable, and matters to stakeholders
+
+**Example of combining evidence:**
+> "Our customers consistently report frustration with checkout (testimonials). Analytics confirm: 45% abandon checkout, taking 12 minutes on average - 3x longer than industry standard (statistics). Support tickets show 60% of complaints are about checkout complexity (complaints), and our survey found 78% rated it as 'difficult' (survey results)."
+
+**If they don't have evidence yet:**
+- That's okay - acknowledge this
+- Propose gathering evidence as part of the project
+- Use stakeholder conversations as initial evidence
+- Reference similar problems in the industry
+
+**Why evidence matters:**
+- Stakeholders recognize the problem exists
+- The urgency is clear
+- Budget approval is easier
+- The case for action is compelling
+
+---
+
+## Next Step
+
+After exploring all sections (in whatever order made sense), proceed to:
+→ `step-03-synthesize.md`
+

package/src/workflows/1-project-brief/alignment-signoff/steps-c/step-03-synthesize.md

@@ -0,0 +1,48 @@
+# Step 3: Synthesize Alignment Document
+
+## Purpose
+
+Crystallize all explored sections into a clear, compelling alignment document (pitch).
+
+---
+
+## Instruction
+
+**After covering all sections** (in whatever order made sense):
+
+1. **Reflect back** what you've captured
+2. **Help crystallize** into a clear, compelling narrative using framework thinking:
+   - **Realization → Why It Matters → How We See It Working → Value We'll Create**
+   - **Realization → Agitate (Cost of Inaction) → Solve (Solution) → Commitment**
+3. **Ask**: "Does this capture your alignment document? Anything you'd like to adjust?"
+4. **Confirm**: "Does this present your idea in the best light?"
+
+**Framework check**: Does the alignment document flow logically?
+- Realization is clear and evidence-backed
+- Why it matters and who we help is understood
+- Solution addresses the realization
+- Commitment is reasonable and risks acknowledged
+- Cost of inaction makes the case
+- Value we'll create justifies the commitment
+
+---
+
+## Create Alignment Document
+
+**Output file**: `docs/1-project-brief/pitch.md` (deliverable name: "pitch")
+
+**Format**: Clear, brief, readable in 2-3 minutes
+
+**Structure**: Use the 10-section structure covered in the exploration
+
+**Template reference**: `src/modules/wds/workflows/1-project-brief/alignment-signoff/pitch.template.md`
+
+---
+
+## Next Step
+
+After creating the pitch document, proceed to:
+→ `step-04-present-for-approval.md` (Present pitch for stakeholder review and approval)
+
+**Note**: The agreement document (contract/service agreement/signoff) will be generated AFTER the pitch is approved, allowing for changes and iterations during the pitch phase.
+

package/src/workflows/1-project-brief/alignment-signoff/steps-c/step-03.5-generate-contract.md

@@ -0,0 +1,87 @@
+# Step 3.5: Generate Signoff Document (Optional)
+
+## Purpose
+
+Offer to create a formal signoff document based on the accepted pitch - contract, service agreement, or internal signoff depending on context.
+
+---
+
+## Context for Agent
+
+**After the pitch is accepted by stakeholders**, you'll offer to create a signoff document to formalize the commitment. This step routes to substeps that handle the document generation process.
+
+**Key Principle**: The pitch got everyone aligned. The signoff document secures the commitment before starting work.
+
+---
+
+## Instructions
+
+Execute the following substeps in sequence to handle signoff document generation:
+
+### Substep 1: Offer Signoff Document
+
+Load, read completely, then execute:
+`substeps/04-generate-signoff/20-offer-signoff-document.md`
+
+This substep will:
+- Present document type options (contract, service agreement, internal signoff, or skip)
+- Gather user's choice
+- Route based on selection
+
+### Substep 2: Determine Business Model (if contract/service agreement selected)
+
+If user chose to create a signoff document, load, read completely, then execute:
+`substeps/04-generate-signoff/21-determine-business-model.md`
+
+This substep will:
+- Ask about business model (fixed price, time & materials, retainer, or hourly)
+- Configure sections based on model
+
+### Substeps 3-14: Build Contract Sections (if contract selected)
+
+If user chose contract or service agreement, execute substeps 22-33 in sequence:
+
+1. `substeps/05-build-contract/22-build-section-01-project-overview.md`
+2. `substeps/05-build-contract/23-build-section-02-business-model.md`
+3. `substeps/05-build-contract/24-build-section-03-scope-of-work.md`
+4. `substeps/05-build-contract/25-build-section-04-payment-terms.md`
+5. `substeps/05-build-contract/26-build-section-05-timeline.md`
+6. `substeps/05-build-contract/27-build-section-06-availability.md`
+7. `substeps/05-build-contract/28-build-section-07-confidentiality.md`
+8. `substeps/05-build-contract/29-build-section-08-not-to-exceed.md`
+9. `substeps/05-build-contract/30-build-section-09-work-initiation.md`
+10. `substeps/05-build-contract/31-build-section-10-terms-and-conditions.md`
+11. `substeps/05-build-contract/32-build-section-11-approval.md`
+12. `substeps/05-build-contract/33-finalize-contract.md`
+
+### Internal Signoff Document (if internal signoff selected)
+
+If user chose internal signoff, execute substeps 34-35:
+
+1. `substeps/06-build-signoff-internal/34-build-internal-signoff.md`
+2. `substeps/06-build-signoff-internal/35-finalize-internal-signoff.md`
+
+---
+
+## If User Chooses "Skip"
+
+If user skips signoff document creation:
+- Acknowledge: "No problem! The pitch document is ready to share. You can always generate a signoff document later if needed."
+- Proceed directly to step-04-present-for-approval.md
+
+---
+
+## Critical Rules
+
+- 🛑 **NEVER** load multiple substeps simultaneously
+- 📖 **ALWAYS** read entire substep file before execution
+- 🚫 **NEVER** skip substeps or optimize the sequence
+- 🎯 **ALWAYS** follow the exact instructions in each substep
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+
+---
+
+## Next Step
+
+After signoff document generation is complete (or skipped):
+→ `step-04-present-for-approval.md`

package/src/workflows/1-project-brief/alignment-signoff/steps-c/step-04-present-for-approval.md

@@ -0,0 +1,89 @@
+# Step 4: Present Alignment Document for Approval
+
+## Purpose
+
+Present the completed alignment document and guide user on next steps.
+
+---
+
+## Instruction
+
+**Present the alignment document for review and approval**:
+
+"I've created your alignment document at `docs/1-project-brief/pitch.md`. 
+
+This alignment document (pitch) is ready to share with your stakeholders. It's designed to be clear, brief, and compelling - readable in just 2-3 minutes.
+
+**Next steps**:
+1. Share the alignment document with stakeholders for review
+2. Gather their feedback - we can negotiate and make changes
+3. Update the alignment document until everyone is on board
+4. Once the alignment document is accepted and everyone is aligned on the idea, why, what, how, budget, and commitment
+5. **After acceptance**, I'll generate the signoff document (contract/service agreement/signoff) to secure the commitment
+6. Then we'll proceed to create the full Project Brief
+
+**Remember**: The alignment phase is collaborative - we can negotiate and iterate until everyone is on the same page. The signoff document comes after acceptance to formalize the commitment. WDS has your back - we'll help you get alignment and secure commitment before starting the work!
+
+Would you like to:
+- Review the alignment document together and make any adjustments before sharing?
+- Proceed to share it with stakeholders for feedback?
+- Make changes based on stakeholder feedback?
+- Or something else?"
+
+---
+
+## After Approval
+
+**Once the alignment document is accepted**, proceed to generate the signoff document:
+
+**Next Step**: Generate Signoff Document
+→ `step-03.5-generate-contract.md` (Generate contract, service agreement, or signoff)
+
+**Why after acceptance**: 
+- The alignment phase allows for negotiation and iteration
+- Stakeholders can review, provide feedback, and request modifications
+- Once accepted, everyone is aligned on the project
+- Then the signoff document formalizes the commitment
+
+**After signoff document is finalized**:
+- Project initiation is complete ✅
+- Proceed to full Project Brief workflow:
+→ `src/modules/wds/workflows/1-project-brief/project-brief/complete/workflow.md` (Full Project Brief)
+
+The alignment document provides the foundation and context for the detailed Project Brief work. With stakeholder acceptance secured and commitment formalized, you're ready to dive into the comprehensive strategic planning.
+
+---
+
+## State Update
+
+Update frontmatter of output file:
+
+```yaml
+stepsCompleted: 
+  - 'step-01-start.md'
+  - 'step-01.5-extract-communications.md' (if used)
+  - 'step-02-explore-sections.md'
+  - 'step-03-synthesize.md'
+  - 'step-03.5-generate-contract.md' (if used)
+  - 'step-04-present-for-approval.md'
+status: 'complete'
+pitch:
+  realization: '[captured realization]'
+  why_it_matters: '[why it matters and who we help]'
+  how_we_see_it_working: '[solution approach]'
+  paths_we_explored: '[options explored]'
+  recommended_solution: '[preferred approach]'
+  path_forward: '[WDS phases and practical workflow]'
+  value_we_create: '[benefits of building, ambition, success metrics]'
+  cost_of_inaction: '[consequences of not building]'
+  our_commitment: '[resources needed and potential risks]'
+  summary: '[summary of key points]'
+  pitch_statement: '[synthesized pitch narrative]'
+```
+
+---
+
+**Alignment & Signoff workflow complete** - Ready for stakeholder approval!
+
+**After approval**: Project initiation is complete. Proceed to full Project Brief.
+

package/src/workflows/1-project-brief/alignment-signoff/substeps/01-start-understand/01-understand-situation.md

@@ -0,0 +1,27 @@
+# Substep 01: Understand Situation
+
+**Purpose**: Clarify the user's situation before proceeding
+
+---
+
+## Instruction
+
+Ask the user to clarify their situation:
+
+"I'd like to understand your situation first. This will help me guide you efficiently.
+
+**Are you:**
+- A consultant proposing a solution to a client?
+- A business owner hiring consultants/suppliers to build software?
+- A manager or employee seeking approval for an internal project?
+- Or doing this yourself and don't need stakeholder alignment?
+
+Let's get clear on what you need so we can move forward."
+
+---
+
+## Next Step
+
+After understanding their situation:
+→ `02-determine-if-needed.md`
+

package/src/workflows/1-project-brief/alignment-signoff/substeps/01-start-understand/02-determine-if-needed.md

@@ -0,0 +1,32 @@
+# Substep 02: Determine If Alignment & Signoff Is Needed
+
+**Purpose**: Determine if user needs alignment & signoff or can proceed directly
+
+---
+
+## Instruction
+
+Based on the user's situation, determine the path:
+
+**If they need alignment & signoff** (consultant, business owner, manager/employee):
+
+"Good. We're going to work together to create an alignment document that presents your idea clearly and gets stakeholders aligned.
+
+This alignment document will help you get alignment on your idea, why it matters, what it contains, how it will be executed, the budget needed, and the commitment required. We can iterate until everyone is on board. Once they accept it, we'll create a signoff document to secure the commitment, then proceed to the full Project Brief.
+
+You can start anywhere - with something you've realized needs attention, or with a solution you have in mind. I'll guide us through the important questions in whatever order makes sense for your thinking."
+
+**If they're doing it themselves** (don't need alignment & signoff):
+
+"That's great! If you have full autonomy and don't need stakeholder alignment, you can skip alignment & signoff and go straight to the Project Brief workflow. Would you like me to help you start the Project Brief instead?"
+
+---
+
+## Decision Point
+
+**If they need alignment & signoff**:
+→ `03-offer-extract-communications.md` (same folder)
+
+**If they're doing it themselves**:
+→ Route to Project Brief workflow
+

package/src/workflows/1-project-brief/alignment-signoff/substeps/01-start-understand/03-offer-extract-communications.md

@@ -0,0 +1,31 @@
+# Substep 03: Offer to Extract Information from Communications
+
+**Purpose**: Offer optional step to extract information from existing communications/documents
+
+---
+
+## Instruction
+
+Ask if they have relevant communications or documents:
+
+"Do you have any email threads, chat conversations, documents, or other materials from clients or stakeholders about this project? 
+
+If you do, I can extract key information from them - things like:
+- Realizations or observations they've mentioned
+- Requirements they've discussed
+- Concerns or questions they've raised
+- Context about the project
+- Existing documentation or specifications
+
+This can help us create a more informed alignment document. You can paste the content here, share the communications, or upload documents, and I'll extract the relevant information."
+
+---
+
+## Decision Point
+
+**If user provides communications/documents**:
+→ `04-extract-info.md` (same folder)
+
+**If user doesn't have any or skips**:
+→ `05-detect-starting-point.md` (same folder)
+

package/src/workflows/1-project-brief/alignment-signoff/substeps/01-start-understand/04-extract-info.md

@@ -0,0 +1,39 @@
+# Substep 04: Extract Information from Communications
+
+**Purpose**: Extract key information from provided communications/documents
+
+---
+
+## Instruction
+
+Extract relevant information from the communications/documents:
+
+**What to extract**:
+- **Realizations mentioned** - What have stakeholders realized or observed?
+- **Requirements discussed** - What do they need or want?
+- **Concerns raised** - What questions or concerns have they expressed?
+- **Context** - Background information about the project
+- **Timeline or urgency** - Any deadlines or time-sensitive information
+- **Budget or constraints** - Financial or resource limitations mentioned
+
+**Use extracted information**:
+- Inform The Realization section (what realizations or observations are mentioned)
+- Inform Why It Matters (who is experiencing issues and why it matters)
+- Inform Our Commitment (any budget/resource discussions)
+- Inform Cost of Inaction (any urgency or consequences mentioned)
+- Add context throughout the alignment document
+
+**Don't**:
+- Copy entire communications or documents verbatim
+- Include personal or irrelevant details
+- Overwhelm with too much detail
+- Use information that's clearly outdated
+- Include sensitive information that shouldn't be in the alignment document
+
+---
+
+## Next Step
+
+After extracting information:
+→ `05-detect-starting-point.md` (same folder)
+

package/src/workflows/1-project-brief/alignment-signoff/substeps/01-start-understand/05-detect-starting-point.md

@@ -0,0 +1,34 @@
+# Substep 05: Detect Starting Point
+
+**Purpose**: Determine where the user wants to start exploring sections
+
+---
+
+## Instruction
+
+Ask where they'd like to start:
+
+"Where would you like to start? Have you realized something that needs attention, or do you have a solution in mind?"
+
+---
+
+## Decision Point
+
+**If user starts with realization**:
+- Explore the realization first
+- Then naturally move to "why it matters" and "who we help"
+- Then explore solutions
+→ `../02-explore-sections/06-explore-realization.md`
+
+**If user starts with solution**:
+- Capture the solution idea
+- Then explore "what realization does this address?"
+- Then explore "why it matters" and "who we help"
+- Then explore other possible approaches
+→ `../02-explore-sections/07-explore-solution.md`
+
+**If user starts elsewhere**:
+- Follow their lead
+- Guide them through remaining sections naturally
+→ Route to appropriate section exploration micro-instruction
+

package/src/workflows/1-project-brief/alignment-signoff/substeps/02-explore-sections/06-explore-realization.md

@@ -0,0 +1,45 @@
+# Substep 06: Explore The Realization
+
+**Purpose**: Help user articulate what they've realized needs attention
+
+---
+
+## Instruction
+
+Explore the realization section with the user.
+
+**Reference**: `src/modules/wds/workflows/1-project-brief/alignment-signoff/section-guide.md` (Section 1: The Realization)
+
+**Questions to explore**:
+- "What have you realized needs attention?"
+- "What observation have you made?"
+- "What challenge are you seeing?"
+- "What evidence do you have that this is real?"
+
+**Best Practice: Confirm the Realization with Evidence**
+
+**Help them identify evidence:**
+
+**Soft Evidence** (qualitative indicators):
+- "Do you have testimonials or complaints about this?"
+- "What have stakeholders told you?"
+- "What patterns have you observed?"
+- "What do user interviews reveal?"
+
+**Hard Evidence** (quantitative data):
+- "Do you have statistics or metrics?"
+- "What do analytics show?"
+- "Have you run surveys or tests?"
+- "What do server logs or error reports indicate?"
+
+**Help them combine both types** for maximum credibility.
+
+**Keep it brief** - 2-3 sentences for the realization, plus 1-2 sentences of evidence
+
+---
+
+## Next Step
+
+After exploring the realization:
+→ `08-explore-why-it-matters.md` (same folder)
+

package/src/workflows/1-project-brief/alignment-signoff/substeps/02-explore-sections/07-explore-solution.md

@@ -0,0 +1,25 @@
+# Substep 07: Explore Solution (If Starting with Solution)
+
+**Purpose**: Capture solution idea and then explore the underlying realization
+
+---
+
+## Instruction
+
+If user starts with a solution idea:
+
+1. **Capture the solution**: "Tell me about your solution idea..."
+
+2. **Then explore the underlying realization**: "What realization does this solution address? What have you observed that led to this solution?"
+
+3. **Then explore why it matters**: "Why does this matter? Who are we helping?"
+
+4. **Then explore other approaches**: "What other ways could we approach this?"
+
+---
+
+## Next Step
+
+After capturing solution and exploring realization:
+→ `08-explore-why-it-matters.md` (same folder)
+

package/src/workflows/1-project-brief/alignment-signoff/substeps/02-explore-sections/08-explore-why-it-matters.md

@@ -0,0 +1,33 @@
+# Substep 08: Explore Why It Matters
+
+**Purpose**: Help user articulate why this matters and who we help
+
+---
+
+## Instruction
+
+Explore why it matters and who we help.
+
+**Reference**: `src/modules/wds/workflows/1-project-brief/alignment-signoff/section-guide.md` (Section 2: Why It Matters)
+
+**Questions to explore**:
+- "Why does this matter?"
+- "Who are we helping?"
+- "What are they trying to accomplish?" (Jobs)
+- "What are their pain points?" (Pains)
+- "What would make their life better?" (Gains)
+- "How does this affect them?"
+- "What impact will this have?"
+- "Are there different groups we're helping?"
+
+**Keep it brief** - Why it matters and who we help
+
+**Help them think**: Focus on the value we're adding to specific people and why that matters
+
+---
+
+## Next Step
+
+After exploring why it matters:
+→ `09-explore-how-we-see-it-working.md` (same folder)
+