fraim-framework 2.0.55 → 2.0.56

package/dist/registry/workflows/customer-development/strategic-brainstorming.md

@@ -0,0 +1,146 @@
+# Strategic Brainstorming Workflow
+
+## INTENT
+To help Product Managers brainstorm and validate their customer development strategy through deep thinking, assumption challenging, and market research to identify the right customer segments and validation questions.
+
+## PRINCIPLES
+- **Assumption Challenging**: Question PM's assumptions and explore alternatives
+- **Deep Research**: Use market research to validate/invalidate assumptions
+- **Strategic Thinking**: Help PM think through customer segments and priorities
+- **Actionable Output**: Provide clear recommendations for customer interviews
+
+## WORKFLOW TRIGGER
+**PM explicitly starts this workflow**:
+- "Starting Strategic Brainstorming"
+- "I need to brainstorm our customer development strategy"
+- "Following the strategic brainstorming workflow"
+
+## AI AGENT PROCESS
+
+### Step 1: Deep Context Gathering
+**AI Agent First Actions**:
+1. **Read Business Context**
+   - Read through `docs/business/` folder for company vision, strategy, and market positioning
+   - Review existing business documents and market analysis
+   - Understand current product positioning and competitive landscape
+
+2. **Read Customer Insights**
+   - Review `docs/customer-insights/` folder for existing customer research
+   - Analyze previous customer interviews and feedback
+   - Identify patterns in customer pain points and needs
+
+3. **Analyze Codebase Context**
+   - Review current product features and capabilities
+   - Understand technical architecture and constraints
+   - Identify areas where customer feedback could inform development
+
+**PM provides unstructured input**:
+- Raw thoughts about current product state
+- Initial assumptions and hypotheses
+- Unstructured priorities and concerns
+- Any existing customer insights
+- Competitive concerns or opportunities
+
+**AI Agent Response**:
+- Acknowledge the brainstorming session with deep context understanding
+- Reference specific insights from business docs and customer research
+- Ask probing questions informed by existing knowledge
+- Identify key assumptions to explore based on current context
+
+### Step 2: Assumption Challenging & Exploration
+**AI Agent Brainstorming Process**:
+1. **Challenge Assumptions**
+   - "What makes you think [assumption] is true?"
+   - "Have you considered alternative perspectives?"
+   - "What evidence do you have for this assumption?"
+
+2. **Explore Alternatives**
+   - Suggest different customer segments
+   - Propose alternative problem definitions
+   - Consider different solution approaches
+
+3. **Identify Gaps**
+   - What assumptions need validation?
+   - What customer segments are missing?
+   - What competitive threats exist?
+
+### Step 3: Market Research & Validation
+**AI Agent Research Process**:
+1. **Market Research**
+   - Research industry trends and customer pain points
+   - Analyze competitive landscape
+   - Identify potential customer personas
+
+2. **Assumption Validation**
+   - Find evidence for/against assumptions
+   - Identify similar companies and their approaches
+   - Research customer segment characteristics
+
+3. **Opportunity Analysis**
+   - Identify market gaps
+   - Assess segment attractiveness
+   - Evaluate competitive positioning
+
+### Step 4: Strategic Recommendations
+**AI Agent Output**:
+- **Customer Segment Prioritization**: Ranked list of segments to interview
+- **Assumption Validation Map**: Key assumptions mapped to validation questions
+- **Interview Sequence**: Recommended order and rationale
+- **Risk Mitigation**: Potential risks and mitigation strategies
+
+### Step 5: Document Creation
+**AI Agent Final Action**:
+- Create strategic recommendations document in `docs/customer-insights/`
+- Use intuitive naming based on context (e.g., `ashley-market-niche-strategy.md`)
+- Include all research findings and recommendations
+- Provide actionable next steps for PM
+- Save document for future reference and team sharing
+
+## OUTPUT TEMPLATE
+
+### Strategic Recommendations Document
+**Template**: Retrieve via `get_fraim_file({ path: "templates/customer-development/strategic-recommendations-template.md" })`
+**File Location**: `docs/customer-development/[contextual-name].md` (e.g., `ashley-market-niche-strategy.md`)
+
+**Process**:
+1. Use the strategic recommendations template
+2. Fill in all sections with research findings and recommendations
+3. Save with contextual naming based on strategic focus
+4. Include specific customer names and companies when available
+5. Reference existing business documents and customer insights
+
+## EXAMPLES
+
+### Good: Strategic Brainstorming Session
+```
+PM: "Starting Strategic Brainstorming. We're building Ashley, an AI executive assistant. I think enterprise execs want AI to handle calendar conflicts automatically, but I'm not sure if that's right."
+
+AI Agent: "Perfect! I've reviewed your business docs and customer insights. I can see from your WhyAshley document that you're positioning Ashley as 'Your Agent for Time, Priorities, and Human Potential' and targeting enterprise executives. I also noticed from your existing customer interviews with Ronil, Sanjoy, and Olga that calendar conflict resolution came up as a key pain point across all three customers.
+
+However, I'm curious about your 'automatic' assumption. From your existing customer insights, I see that trust and delegation control were major themes - Ronil mentioned 'Don't have trust in tech to read email - need to have hands in it' and Sanjoy was concerned about 'Disturb during highly important meetings'. What makes you think they want it 'automatic' vs 'suggested'?"
+
+PM: "Good point. I guess I'm assuming automatic because that's what would save them the most time."
+
+AI Agent: "That's a reasonable assumption, but based on your existing customer feedback, there's a clear pattern of wanting control and oversight. Ronil mentioned wanting to 'observe for 2 weeks, then take action' and Olga talked about how good EAs 'enforce workback plans based on business priorities' rather than just doing what they're asked. What if we validated this by asking about their current delegation patterns and comfort levels with AI autonomy?"
+
+[Brainstorming continues with deep context...]
+
+AI Agent Output: Strategic recommendations document informed by existing business context and customer insights
+```
+
+### Bad: Surface-Level Brainstorming
+```
+PM: "We're building Ashley, an AI executive assistant. Who should we interview?"
+
+AI Agent: "You should interview enterprise executives."
+
+PM: "Okay, thanks."
+
+Result: No deep thinking, no assumption validation, no strategic recommendations
+```
+
+## SUCCESS METRICS
+- **Assumption Validation**: 80% of key assumptions have clear validation questions
+- **Customer Segment Clarity**: Clear rationale for segment prioritization
+- **Interview Readiness**: PM has clear next steps for customer interviews
+- **Risk Awareness**: Potential risks identified and mitigated

package/dist/registry/workflows/customer-development/thank-customers.md

@@ -0,0 +1,203 @@
+# Thank Customers Workflow
+
+## INTENT
+To automatically generate and send personalized thank you emails to customers whose feedback has been implemented, strengthening customer relationships and encouraging continued engagement.
+
+## PRINCIPLES
+- **Personal Touch**: Ashley's voice, grateful tone, "Thank you for making me better..."
+- **Voice & Pronouns**: Emails are written in first person from Ashley ("I", "me", "my"). When referring to Ashley in third person (outside the email body), use they/them pronouns. Avoid gendered pronouns for Ashley.
+- **Customer-Focused**: No technical jargon or issue numbers in customer emails
+- **Short and Sweet**: To the point, instructive, humble
+- **Encourage more feedback**: ChatGPT (https://ashley-chat.wellnessatwork.me) is the best way
+
+## WORKFLOW TRIGGER
+**User triggers this workflow manually**:
+- When customer issues are resolved and deployed
+- User says: "Generate thank you emails for customers" or similar
+
+## AI AGENT PROCESS
+
+### Step 1: Issue Retrieval
+**AI Agent calls function**:
+```typescript
+// Import helper functions directly from synced location
+const os = require('os');
+const path = require('path');
+const scriptsDir = path.join(os.homedir(), '.fraim', 'scripts');
+const scriptPath = path.join(scriptsDir, 'generate-engagement-emails.ts');
+
+import { getResolvedIssues, findExecutiveByEmail, getAshleyEmailForExecutive } from scriptPath;
+
+// Get issues resolved since last thank-you date (automatic) or user-specified date
+const resolvedIssues = await getResolvedIssues(); // Automatically uses latest thank-you date
+// OR with explicit date:
+const resolvedIssues = await getResolvedIssues('2025-10-29'); // Optional: user-specified date
+```
+
+**Note**: The `getResolvedIssues()` function automatically:
+- Finds the most recent date from existing `thank-you-candidates-YYYY-MM-DD.json` files where emails were sent (status: "sent")
+- Uses that date as the starting point to only fetch issues resolved AFTER that date
+- If no thank-you files exist, falls back to last 14 days
+- This ensures we never send duplicate thank-you emails for the same resolved issues
+
+### Step 2: Customer Information Extraction
+**AI Agent does intelligent extraction**:
+1. **Go through each resolved issue**
+2. **Extract customer email** from:
+   - Issue title format: `email@domain.com: summary`
+   - Issue body: look for email patterns
+   - If no email found, extract customer name and use database lookup
+3. **Extract customer name** from:
+   - Issue title or body
+   - Previous thank-you notes
+   - Onboarding insights documents
+
+### Step 3: Database Lookup
+**AI Agent calls function for each customer**:
+```typescript
+// Look up executive by customer email
+const executive = await findExecutiveByEmail(customerEmail);
+
+// Get Ashley email address for this executive
+const ashleyEmail = await getAshleyEmailForExecutive(executive.id);
+```
+
+### Step 4: Collate Issues by Customer
+**AI Agent organizes data**:
+- Group all resolved issues by customer email
+- **Consolidate customers with multiple email addresses** by matching customer names (case-insensitive)
+- When a customer has multiple emails, use the primary email from the database lookup
+- Output customer list to console for verification
+
+### Step 5: Generate Single Thank-You File
+**AI Agent creates ONE file**:
+- File: `docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json`
+- Format: Structured JSON (not markdown) for easy parsing by mail sending script
+- Contains ALL customers and their personalized emails
+- **AI Agent writes the email content** - be creative, personal, and contextual!
+- Follow principles: personal touch, customer-focused, short and sweet, encourage feedback
+- **NO TECHNICAL JARGON**: Do not mention issue numbers, BAML, internal systems, or technical details
+- **CUSTOMER EXPERIENCE FOCUS**: Describe what was broken from the user's perspective, what was fixed, and how they can verify it works
+- **First-person Email Body**: Use "I" for actions Ashley took (e.g., "I fixed", "I now", "I will"), not "Ashley" or "she". Sign off as Ashley.
+- Include `From:` field showing Ashley email from PPE (via `getAshleyEmailForExecutive()`)
+
+**File format** (JSON):
+```json
+{
+   "metadata": {
+     "generatedOn": "2025-10-29T02:29:02.497Z",
+     "issuesResolvedSince": "2025-10-28",
+     "totalCustomers": 2,
+     "totalIssues": 3
+   },
+   "candidates": [
+     {
+       "customer": {
+         "name": "Olga Ivanova",
+         "email": "olga.ivanova@gmail.com"
+       },
+       "executive": {
+         "name": "Olga Ivanova",
+         "id": "exec-..."
+       },
+       "status": "pending",
+       "from": {
+         "displayName": "Ashley - Olga Ivanova's AI Executive Assistant",
+         "email": "ashley+olga@ashleycalendar.ai"
+       },
+       "to": "olga.ivanova@gmail.com",
+       "subject": "Thank you for your feedback - your issues have been addressed!",
+       "greeting": "Hi Olga,",
+       "opening": "Thank you for making me better! I wanted to personally reach out because your feedback helped us catch and fix an important bug.",
+       "improvements": [
+         {
+           "title": "Issue filing feature",
+           "description": "The issue filing feature is now working properly - when you ask me to file a bug or feature request through voice, I'll handle it correctly.",
+           "verification": "Try asking me to file a bug or feature request and it should work smoothly now."
+         }
+       ],
+       "closing": "Your quick feedback saved you (and others) frustration down the line. That kind of real-time input makes all the difference as I'm learning."
+     }
+   ]
+ }
+```
+
+**Note**: The structured format allows the HTML template to format each section beautifully:
+- `greeting`: Personal greeting (e.g., "Hi Olga,")
+- `opening`: Opening paragraph - thanks and context
+- `improvements[]`: Array of improvements (title, description, optional verification step)
+- `closing`: Closing paragraph - encouraging more feedback
+
+The HTML template formats each section with appropriate styling.
+
+### Step 6: User Review
+**AI Agent**:
+1. **Points user to the generated file**: `docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json`
+2. **Requests review** and any edits needed (user can edit JSON directly)
+3. **Waits for user approval** before proceeding
+
+**Note**: Each email section includes a `From:` field showing the display name and email address that will be used when sending. The signature includes a humble note about ramping up, without displaying a generic email address.
+
+### Step 7: Send Emails (Separate Command)
+**When user says "Send the emails" or similar**:
+
+**AI Agent calls function**:
+```typescript
+// Import helper functions directly from synced location
+const os = require('os');
+const path = require('path');
+const scriptsDir = path.join(os.homedir(), '.fraim', 'scripts');
+const scriptPath = path.join(scriptsDir, 'generate-engagement-emails.ts');
+
+import { sendCustomerMail } from scriptPath;
+
+// Send emails from the candidates JSON file (all pending candidates)
+await sendCustomerMail('docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json');
+
+// OR send to a specific executive only (optional)
+await sendCustomerMail('docs/customer-development/thank-you-notes/thank-you-candidates-YYYY-MM-DD.json', 'exec-1761011032377-q36j91sdl');
+```
+
+**Note**: The `sendCustomerMail` function parses JSON (not markdown) for easy, deterministic parsing.
+
+**Function parameters**:
+- `candidatesFilePath` (required): Path to the JSON candidates file
+- `executiveId` (optional): If provided, only sends emails for candidates matching this executive ID. If omitted, sends to all pending candidates.
+
+**This function will**:
+- Parse the JSON candidates file
+- If `executiveId` is provided, filter to only that executive's candidates
+- For each candidate with `status: "pending"`, send email
+- Use the `from` field (displayName and email) specified in JSON
+- Use the `to`, `subject`, and `body` fields from JSON
+- Update the JSON file after each send with status: `"sent"` or `"failed"`
+- Skip candidates that already have status `"sent"` or `"failed"`
+
+## REQUIRED FUNCTIONS IN SCRIPT
+
+The script must provide these deterministic functions for AI agents to call:
+
+```typescript
+// Get resolved issues since a date
+export async function getResolvedIssues(date: string): Promise<ResolvedIssue[]>
+
+// Find executive by email in PPE database  
+export async function findExecutiveByEmail(email: string): Promise<Executive | null>
+
+// Get Ashley email for executive from PPE database
+export async function getAshleyEmailForExecutive(executiveId: string): Promise<string>
+
+// Send emails from candidates file
+// executiveId is optional - if provided, only sends to that executive; if omitted, sends to all pending
+export async function sendCustomerMail(candidatesFilePath: string, executiveId?: string): Promise<void>
+```
+
+**Note**: The script provides ONLY data retrieval and sending. The AI agent does ALL intelligent work:
+- Extracts customer info from issues (intelligent parsing)
+- Writes personalized, creative email content (better than hardcoded templates!)
+- Organizes and formats the candidates file
+
+## WORKFLOW COMPLETION
+
+**Generate workflow completes with**: Single candidates file ready for review
+**Send workflow completes with**: All emails sent and file updated with status

package/dist/registry/workflows/customer-development/user-survey-dispatch.md

@@ -0,0 +1,60 @@
+# FRAIM Workflow: user-survey-dispatch
+
+**Path:** `workflows/customer-development/user-survey-dispatch.md`
+
+---
+
+# User Survey Dispatch Workflow - AI Coach Guided
+
+## INTENT
+To systematically formulate, build, and dispatch user surveys across multiple platforms (LinkedIn, Reddit, X, Facebook) to validate target audience assumptions and gather product insights.
+
+## HOW IT WORKS
+This workflow uses the **AI Coach** for transition-based guidance. Instead of manually following steps, you interact with the coach at each phase boundary:
+
+- **Phase Initiation**: Call the coach to get the specific "Build" or "Dispatch" instructions for the target platform.
+- **Evidence Validation**: Submit evidence (documents, screenshots) to the coach to move to the next platform/phase.
+- **Failure Recovery**: If a platform-specific build fails, the coach directs you back to revise the survey scope.
+
+## PHASE PROGRESSION
+
+**Survey Flow**: `survey-scoping` → `survey-build-linkedin` → `survey-build-reddit` → `survey-build-x` → `survey-build-facebook` → `survey-build-custom` → `survey-dispatch`
+
+## GETTING COACHING
+
+Use the following tool to get instructions for your current phase:
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "user-survey",
+  issueNumber: "51", // or your specific identifier
+  currentPhase: "survey-scoping",
+  status: "starting"
+})
+```
+
+### Supported Status Values
+- **starting**: Called at the beginning of any phase to get the platform-specific "Building" or "Dispatch" guidelines.
+- **complete**: Called when you have finished the work for a phase (e.g., generated Reddit copy). Provide the copy/evidence in the `evidence` field.
+- **incomplete**: Called if you encounter technical blockers (e.g., subreddit rules) and need coaching on how to adapt.
+- **failure**: Called if a phase cannot be completed (e.g., account restricted). The coach will route you back to a previous phase.
+
+## GETTING STARTED
+
+### 1. Initiate Scoping
+Start by defining the core goal and questions for your survey. This ensures all platform-specific posts are aligned.
+
+```javascript
+seekCoachingOnNextStep({
+  workflowType: "user-survey",
+  issueNumber: "51",
+  currentPhase: "survey-scoping",
+  status: "starting"
+})
+```
+
+### 2. Follow Platform Builds
+After scoping, the coach will guide you through building optimized content for LinkedIn, Reddit, X, and Facebook sequentially.
+
+### 3. Automated Dispatch
+Once all content is ready, the coach will provide you with the **Playwright-driven** instructions to execute the posts across the platforms.

package/dist/registry/workflows/customer-development/users-to-target.md

@@ -0,0 +1,112 @@
+# FRAIM Workflow: users-to-target
+
+## Intent
+Help founders systematically identify and build an inventory of specific potential customers across multiple platforms for customer discovery and outreach.
+
+## Overview
+This workflow guides founders through a 4-phase process to discover, qualify, and document potential customers using browser automation across LinkedIn, Reddit, X (Twitter), Facebook, forums, and web search.
+
+## Prerequisites
+- Clear understanding of your target customer profile
+- Access to social media platforms (LinkedIn, Reddit, X, Facebook)
+- Browser automation capabilities via Playwright MCP
+
+## Phases
+
+### Phase 1: Customer Profiling
+**Objective**: Define target customer characteristics and search criteria
+
+**Actions**:
+1. Complete customer persona template
+2. Define pain points and behavioral indicators
+3. Create platform-specific search keywords
+4. Set geographic and demographic constraints
+
+**Evidence Required**:
+- Completed customer persona document: `docs/customer-development/customer-persona-{timestamp}.md`
+- List of search keywords for each platform
+- Qualification criteria definition
+
+### Phase 2: Multi-Platform Discovery
+**Objective**: Execute automated searches across all target platforms
+
+**Actions**:
+1. LinkedIn professional network search
+2. Reddit community discussions search
+3. X (Twitter) conversations search
+4. Facebook groups and discussions search
+5. Industry-specific forums search
+6. General web search for blogs and articles
+
+**Evidence Required**:
+- Screenshots from each platform search
+- Raw prospect data captured
+- Search query refinements documented
+
+### Phase 3: Prospect Qualification
+**Objective**: Evaluate and score discovered prospects
+
+**Actions**:
+1. Apply qualification criteria to all prospects
+2. Score relevance (1-10 scale)
+3. Identify contact information
+4. Document pain points and context
+5. Prioritize for outreach
+
+**Evidence Required**:
+- Qualified prospect list with scores
+- Contact information where available
+- Pain point documentation
+
+### Phase 4: Inventory Compilation
+**Objective**: Create final structured prospect database
+
+**Actions**:
+1. Compile all qualified prospects into CSV format
+2. Add follow-up priority rankings
+3. Include discovery context and quotes
+4. Generate summary statistics
+5. Create outreach recommendations
+
+**Evidence Required**:
+- Final CSV file: `docs/customer-development/users-to-target-{timestamp}.csv`
+- Summary report with statistics
+- Top 20 priority prospects identified
+
+## Success Metrics
+- 50-200 qualified prospects identified
+- 70%+ relevance score for prospects
+- Contact information for 60%+ of prospects
+- Clear next steps for top 20 prospects
+
+## Templates
+- Customer Persona Template: `templates/customer-development/customer-persona-template.md`
+- Search Strategy Template: `templates/customer-development/search-strategy-template.md`
+- Prospect Inventory Template: `templates/customer-development/prospect-inventory-template.csv`
+
+## AI Coach Integration
+This workflow uses the AI Coach system for phase-by-phase guidance:
+
+```javascript
+// Start the workflow
+seekCoachingOnNextStep({
+  workflowType: "customer-development",
+  issueNumber: "users-to-target-001", // or your specific identifier
+  currentPhase: "customer-profiling",
+  status: "starting"
+})
+
+// After completing each phase
+seekCoachingOnNextStep({
+  workflowType: "customer-development", 
+  issueNumber: "users-to-target-001",
+  currentPhase: "customer-profiling",
+  status: "complete",
+  evidence: {
+    // Your completed evidence for the phase
+  }
+})
+```
+
+## Output Location
+`docs/customer-development/users-to-target-{timestamp}.csv`