fraim-framework 2.0.34 → 2.0.36

package/registry/workflows/convert-to-pdf.md

@@ -0,0 +1,235 @@
+# Convert to PDF Workflow
+
+## INTENT
+To provide agents with a reliable workflow for converting markdown files to professional PDF documents, enabling seamless document sharing and archival while maintaining formatting integrity and visual appeal.
+
+## PRINCIPLES
+- **Format Preservation**: Maintain all markdown formatting including tables, code blocks, and images
+- **Professional Output**: Generate clean, readable PDFs suitable for business use
+- **Flexible Configuration**: Support various paper formats, margins, and styling options
+- **Error Resilience**: Handle common conversion issues gracefully with clear error messages
+- **Cross-Platform Compatibility**: Work consistently across Windows, macOS, and Linux
+
+## Overview
+This workflow guides agents through converting markdown files to PDF format using the markdown-to-pdf script. The conversion maintains formatting, supports code highlighting, tables, and images while producing professional-looking PDF documents.
+
+## When to Use
+- User requests converting markdown documentation to PDF
+- Need to generate PDF reports from markdown content
+- Creating printable versions of specifications or documentation
+- Sharing formatted documents with stakeholders who prefer PDF format
+- Archiving documentation in a portable format
+
+## Prerequisites
+Before using this workflow, ensure the following dependencies are installed:
+
+```bash
+npm install puppeteer markdown-it markdown-it-highlightjs
+```
+
+## Script Location
+The conversion script is synced to: `~/.fraim/scripts/markdown-to-pdf.js`
+
+## Workflow Steps
+
+### Phase 1: Validate Environment
+
+1. **Check Dependencies**
+   ```bash
+   node -e "console.log('puppeteer:', require.resolve('puppeteer')); console.log('markdown-it:', require.resolve('markdown-it')); console.log('markdown-it-highlightjs:', require.resolve('markdown-it-highlightjs'));"
+   ```
+
+2. **Verify Script Availability**
+   - Confirm `~/.fraim/scripts/markdown-to-pdf.js` exists
+   - Check script permissions (executable on Unix systems)
+
+3. **Test Basic Functionality**
+   ```bash
+   node ~/.fraim/scripts/markdown-to-pdf.js --help
+   ```
+
+### Phase 2: Prepare Input
+
+1. **Validate Input File**
+   - Confirm markdown file exists and is readable
+   - Check for any syntax issues in markdown
+   - Verify image paths are correct and accessible
+
+2. **Determine Output Requirements**
+   - Ask user about desired output location
+   - Confirm paper format preferences (A4, Letter, etc.)
+   - Check if custom styling is needed
+   - Determine header/footer requirements
+
+3. **Prepare Output Directory**
+   - Ensure output directory exists
+   - Verify write permissions
+
+### Phase 3: Execute Conversion
+
+1. **Basic Conversion**
+   ```bash
+   node ~/.fraim/scripts/markdown-to-pdf.js <input.md>
+   ```
+
+2. **Advanced Conversion with Options**
+   ```bash
+   node ~/.fraim/scripts/markdown-to-pdf.js <input.md> [output.pdf] [options]
+   ```
+
+3. **Monitor Progress**
+   - Watch for error messages
+   - Verify successful completion
+   - Check output file size and accessibility
+
+### Phase 4: Validate Output
+
+1. **Verify PDF Generation**
+   - Confirm PDF file was created
+   - Check file size is reasonable
+   - Verify file is not corrupted
+
+2. **Quality Check**
+   - Review formatting preservation
+   - Check image rendering
+   - Verify code block highlighting
+   - Confirm table alignment
+
+3. **User Acceptance**
+   - Share output location with user
+   - Confirm output meets requirements
+   - Offer to regenerate with different options if needed
+
+### Available Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--format <format>` | Paper format (A4, Letter, Legal, etc.) | `--format Letter` |
+| `--margin <margin>` | Page margins in inches | `--margin 1` |
+| `--css <file>` | Custom CSS file for styling | `--css custom.css` |
+| `--header <text>` | Header text | `--header "Company Report"` |
+| `--footer <text>` | Footer text | `--footer "Page <span class='pageNumber'></span>"` |
+| `--landscape` | Use landscape orientation | `--landscape` |
+| `--no-background` | Disable background graphics | `--no-background` |
+
+### Common Examples
+
+1. **Basic conversion:**
+   ```bash
+   node ~/.fraim/scripts/markdown-to-pdf.js README.md
+   ```
+
+2. **Specify output location:**
+   ```bash
+   node ~/.fraim/scripts/markdown-to-pdf.js docs/spec.md output/specification.pdf
+   ```
+
+3. **Letter format with custom margins:**
+   ```bash
+   node ~/.fraim/scripts/markdown-to-pdf.js report.md --format Letter --margin 0.75
+   ```
+
+4. **With custom styling:**
+   ```bash
+   node ~/.fraim/scripts/markdown-to-pdf.js document.md --css styles/custom.css --header "Project Documentation"
+   ```
+
+5. **Landscape orientation:**
+   ```bash
+   node ~/.fraim/scripts/markdown-to-pdf.js wide-table.md --landscape --format A3
+   ```
+
+## Agent Instructions
+
+When a user requests markdown to PDF conversion:
+
+1. **Identify the source file(s)**: Confirm which markdown file(s) need to be converted
+2. **Check dependencies**: Verify that required npm packages are installed
+3. **Determine output requirements**: Ask about:
+   - Desired output location
+   - Paper format preferences
+   - Custom styling needs
+   - Header/footer requirements
+4. **Execute conversion**: Run the appropriate command with the specified options
+5. **Verify output**: Confirm the PDF was generated successfully and meets requirements
+
+### Error Handling
+
+If the script fails:
+- Check that all dependencies are installed
+- Verify the input file exists and is readable
+- Ensure the output directory is writable
+- Check for any syntax errors in the markdown file
+
+### Troubleshooting Common Issues
+
+1. **Missing dependencies**: Install required packages with npm
+2. **Permission errors**: Ensure write permissions for output directory
+3. **Large files**: Consider breaking large markdown files into smaller sections
+4. **Image issues**: Verify image paths are correct and accessible
+5. **Font rendering**: Use web-safe fonts or include custom font CSS
+
+## Customization
+
+### Custom CSS Styling
+Create a CSS file to customize the PDF appearance:
+
+```css
+/* custom-style.css */
+body {
+  font-family: 'Times New Roman', serif;
+  font-size: 12pt;
+}
+
+h1 {
+  color: #2c3e50;
+  border-bottom: 3px solid #3498db;
+}
+
+code {
+  background-color: #f0f0f0;
+  border: 1px solid #ccc;
+}
+
+@page {
+  margin: 1in;
+  @top-center {
+    content: "Confidential Document";
+  }
+}
+```
+
+### Batch Processing
+For converting multiple files, create a simple loop:
+
+```bash
+for file in docs/*.md; do
+  node ~/.fraim/scripts/markdown-to-pdf.js "$file" "output/$(basename "$file" .md).pdf"
+done
+```
+
+## Quality Assurance
+
+After conversion, verify:
+- All content is present and properly formatted
+- Images are displayed correctly
+- Code blocks maintain syntax highlighting
+- Tables are properly aligned
+- Page breaks occur at appropriate locations
+- Headers and footers appear as expected
+
+## Best Practices
+
+1. **Test with sample content** before processing important documents
+2. **Use consistent styling** across related documents
+3. **Optimize images** for better PDF file size
+4. **Consider accessibility** when choosing fonts and colors
+5. **Version control** both source markdown and generated PDFs when appropriate
+
+## Integration with Other Workflows
+
+This workflow can be combined with:
+- Documentation generation workflows
+- Report automation processes
+- CI/CD pipelines for document publishing
+- Content review and approval workflows

package/registry/workflows/customer-development/insight-analysis.md

@@ -1,156 +1,156 @@
-# Insight Analysis Workflow
-
-## INTENT
-To help Product Managers extract, structure, and analyze customer insights from interview notes, enabling data-driven product decisions and systematic customer relationship management.
-
-## PRINCIPLES
-- **Comprehensive Extraction**: Capture all insights from raw notes
-- **Structured Analysis**: Organize insights into actionable categories
-- **Customer Scoring**: Evaluate customer fit and prioritization
-- **Follow-up Generation**: Create personalized follow-up communications
-
-## WORKFLOW TRIGGER
-**PM explicitly starts this workflow**:
-- "Starting Insight Analysis for [Customer Name]"
-- "I want to analyze the interview with [Customer Name]"
-- "Following the insight analysis workflow"
-
-## INPUT REQUIREMENTS
-**PM provides**:
-- The `[customer-name]-interview-prep.md` file that needs to be updated
-- Raw interview notes in any format (bullet points, paragraphs, voice-to-text, etc.)
-- Brief unstructured thoughts about the interview (optional but helpful)
-
-## AI AGENT PROCESS
-
-### Step 1: Insight Extraction & Template Update
-**AI Agent Analysis Process**:
-1. **Read Existing Prep File**
-   - Load the `[customer-name]-interview-prep.md` file
-   - Understand the customer context and research from preparation phase
-   - Review the pre-filled template structure
-
-2. **Parse Raw Notes**
-   - Extract customer quotes and key statements
-   - Identify pain points and challenges
-   - Capture success and failure criteria
-   - Note feature requests and preferences
-   - **Date Handling**: If user provides relative time references (e.g., "yesterday", "today", "last Friday"), run `new Date()` to determine the actual date and use that in the analysis file
-
-3. **Create Analysis File**
-   - Create new file: `[customer-name]-interview-analysis.md`
-   - Include comprehensive analysis with customer scoring and insights
-   - Reference the prep file for context but keep files separate
-   - Include follow-up actions and next steps
-
-### Step 2: Customer Scoring & Prioritization
-**AI Agent Scoring Process**:
-1. **Customer Fit Scoring (1-10)**
-   - Target customer segment alignment
-   - Pain point severity and frequency
-   - Budget and decision-making authority
-   - Influence and referral potential
-
-2. **Urgency Assessment**
-   - Active seeking of solutions
-   - Budget allocation and timeline
-   - Competitive pressure
-   - Implementation readiness
-
-3. **Willingness to Pay**
-   - Budget authority and constraints
-   - Current spending on similar solutions
-   - Value perception and ROI understanding
-
-### Step 3: Follow-up Generation
-**AI Agent Communication Process**:
-1. **Generate Follow-up Email**
-   - Use follow-up email templates as reference
-   - Create personalized email based on interview content
-   - Include key takeaways confirmation
-   - Add specific next steps and timeline
-   - Reference customer quotes and insights
-
-2. **Follow-up Questions**
-   - Clarify any gaps in understanding
-   - Deepen insights on key topics
-   - Validate assumptions and priorities
-   - Explore referral opportunities
-
-3. **Next Steps Planning**
-   - Demo scheduling if appropriate
-   - Additional stakeholder meetings
-   - Resource sharing and education
-   - Timeline and milestone setting
-
-### Step 4: File Creation & Finalization
-**AI Agent File Management**:
-1. **Create Analysis File**
-   - Create `[customer-name]-interview-analysis.md` with comprehensive analysis
-   - Include customer scoring, insights, and follow-up actions
-   - Reference the prep file for context but keep files separate
-
-2. **Preserve Prep File**
-   - Keep `[customer-name]-interview-prep.md` unchanged
-   - Maintains clean separation between preparation and analysis
-   - Both files can be referenced independently
-
-## OUTPUT TEMPLATE
-
-### Analysis File Template
-**Template**: Retrieve via `get_fraim_file({ path: "templates/customer-development/insight-analysis-template.md" })`
-**File Location**: `docs/customer-development/[customer-name]-interview-analysis.md`
-
-**Process**:
-1. Use the insight analysis template
-2. Extract insights from raw interview notes
-3. Score customer based on fit, urgency, willingness to pay, and likelihood to buy
-4. Include direct customer quotes for authenticity
-5. Create next steps and follow-up questions
-6. Reference the original prep file for context
-7. **Generate personalized follow-up email** using follow-up email templates as reference `get_fraim_file({ path: "templates/customer-development/follow-up-email-templates.md" })` ... add this to the end of the analysis file.
-
-## EXAMPLES
-
-### Good: Insight Analysis
-```
-Input: 
-- File: ronil-dhruva-interview-prep.md
-- Raw notes: "Ronil mentioned calendar conflicts, uses Outlook, frustrated with rescheduling, would pay $50/month, concerned about AI decisions. He was really engaged and seemed to understand the problem well."
-
-AI Agent Process:
-1. Reads existing prep file with LinkedIn research
-2. Extracts insights from raw notes
-3. Creates separate analysis file: ronil-dhruva-interview-analysis.md
-4. Preserves original prep file unchanged
-5. **Generates personalized follow-up email** using follow-up email templates
-6. Creates next steps and follow-up questions
-
-Output:
-- New analysis file: ronil-dhruva-interview-analysis.md
-- Original prep file: ronil-dhruva-interview-prep.md (unchanged)
-- Customer score: 8/10 (high fit, clear pain points, enterprise budget)
-- **Personalized follow-up email** using template structure with customer-specific content
-- Next questions: "What specific hierarchy rules should AI respect?"
-```
-
-### Bad: Surface-Level Analysis
-```
-Input: 
-- File: ronil-dhruva-interview-prep.md
-- Raw notes: "Ronil interview went well"
-
-AI Agent Output:
-- Generic analysis with no specific insights
-- No customer scoring or prioritization
-- No follow-up recommendations
-- No actionable next steps
-
-Result: Lost insights, no clear next steps, wasted prep work
-```
-
-## SUCCESS METRICS
-- **Insight Extraction**: 95% of key insights captured from raw notes
-- **Customer Scoring**: Consistent scoring across all customers
-- **Follow-up Quality**: 80% of follow-up emails result in positive responses
-- **Action Clarity**: Clear next steps for every customer
+# Insight Analysis Workflow
+
+## INTENT
+To help Product Managers extract, structure, and analyze customer insights from interview notes, enabling data-driven product decisions and systematic customer relationship management.
+
+## PRINCIPLES
+- **Comprehensive Extraction**: Capture all insights from raw notes
+- **Structured Analysis**: Organize insights into actionable categories
+- **Customer Scoring**: Evaluate customer fit and prioritization
+- **Follow-up Generation**: Create personalized follow-up communications
+
+## WORKFLOW TRIGGER
+**PM explicitly starts this workflow**:
+- "Starting Insight Analysis for [Customer Name]"
+- "I want to analyze the interview with [Customer Name]"
+- "Following the insight analysis workflow"
+
+## INPUT REQUIREMENTS
+**PM provides**:
+- The `[customer-name]-interview-prep.md` file that needs to be updated
+- Raw interview notes in any format (bullet points, paragraphs, voice-to-text, etc.)
+- Brief unstructured thoughts about the interview (optional but helpful)
+
+## AI AGENT PROCESS
+
+### Step 1: Insight Extraction & Template Update
+**AI Agent Analysis Process**:
+1. **Read Existing Prep File**
+   - Load the `[customer-name]-interview-prep.md` file
+   - Understand the customer context and research from preparation phase
+   - Review the pre-filled template structure
+
+2. **Parse Raw Notes**
+   - Extract customer quotes and key statements
+   - Identify pain points and challenges
+   - Capture success and failure criteria
+   - Note feature requests and preferences
+   - **Date Handling**: If user provides relative time references (e.g., "yesterday", "today", "last Friday"), run `new Date()` to determine the actual date and use that in the analysis file
+
+3. **Create Analysis File**
+   - Create new file: `[customer-name]-interview-analysis.md`
+   - Include comprehensive analysis with customer scoring and insights
+   - Reference the prep file for context but keep files separate
+   - Include follow-up actions and next steps
+
+### Step 2: Customer Scoring & Prioritization
+**AI Agent Scoring Process**:
+1. **Customer Fit Scoring (1-10)**
+   - Target customer segment alignment
+   - Pain point severity and frequency
+   - Budget and decision-making authority
+   - Influence and referral potential
+
+2. **Urgency Assessment**
+   - Active seeking of solutions
+   - Budget allocation and timeline
+   - Competitive pressure
+   - Implementation readiness
+
+3. **Willingness to Pay**
+   - Budget authority and constraints
+   - Current spending on similar solutions
+   - Value perception and ROI understanding
+
+### Step 3: Follow-up Generation
+**AI Agent Communication Process**:
+1. **Generate Follow-up Email**
+   - Use follow-up email templates as reference
+   - Create personalized email based on interview content
+   - Include key takeaways confirmation
+   - Add specific next steps and timeline
+   - Reference customer quotes and insights
+
+2. **Follow-up Questions**
+   - Clarify any gaps in understanding
+   - Deepen insights on key topics
+   - Validate assumptions and priorities
+   - Explore referral opportunities
+
+3. **Next Steps Planning**
+   - Demo scheduling if appropriate
+   - Additional stakeholder meetings
+   - Resource sharing and education
+   - Timeline and milestone setting
+
+### Step 4: File Creation & Finalization
+**AI Agent File Management**:
+1. **Create Analysis File**
+   - Create `[customer-name]-interview-analysis.md` with comprehensive analysis
+   - Include customer scoring, insights, and follow-up actions
+   - Reference the prep file for context but keep files separate
+
+2. **Preserve Prep File**
+   - Keep `[customer-name]-interview-prep.md` unchanged
+   - Maintains clean separation between preparation and analysis
+   - Both files can be referenced independently
+
+## OUTPUT TEMPLATE
+
+### Analysis File Template
+**Template**: Retrieve via `get_fraim_file({ path: "templates/customer-development/insight-analysis-template.md" })`
+**File Location**: `docs/customer-development/[customer-name]-interview-analysis.md`
+
+**Process**:
+1. Use the insight analysis template
+2. Extract insights from raw interview notes
+3. Score customer based on fit, urgency, willingness to pay, and likelihood to buy
+4. Include direct customer quotes for authenticity
+5. Create next steps and follow-up questions
+6. Reference the original prep file for context
+7. **Generate personalized follow-up email** using follow-up email templates as reference `get_fraim_file({ path: "templates/customer-development/follow-up-email-templates.md" })` ... add this to the end of the analysis file.
+
+## EXAMPLES
+
+### Good: Insight Analysis
+```
+Input: 
+- File: ronil-dhruva-interview-prep.md
+- Raw notes: "Ronil mentioned calendar conflicts, uses Outlook, frustrated with rescheduling, would pay $50/month, concerned about AI decisions. He was really engaged and seemed to understand the problem well."
+
+AI Agent Process:
+1. Reads existing prep file with LinkedIn research
+2. Extracts insights from raw notes
+3. Creates separate analysis file: ronil-dhruva-interview-analysis.md
+4. Preserves original prep file unchanged
+5. **Generates personalized follow-up email** using follow-up email templates
+6. Creates next steps and follow-up questions
+
+Output:
+- New analysis file: ronil-dhruva-interview-analysis.md
+- Original prep file: ronil-dhruva-interview-prep.md (unchanged)
+- Customer score: 8/10 (high fit, clear pain points, enterprise budget)
+- **Personalized follow-up email** using template structure with customer-specific content
+- Next questions: "What specific hierarchy rules should AI respect?"
+```
+
+### Bad: Surface-Level Analysis
+```
+Input: 
+- File: ronil-dhruva-interview-prep.md
+- Raw notes: "Ronil interview went well"
+
+AI Agent Output:
+- Generic analysis with no specific insights
+- No customer scoring or prioritization
+- No follow-up recommendations
+- No actionable next steps
+
+Result: Lost insights, no clear next steps, wasted prep work
+```
+
+## SUCCESS METRICS
+- **Insight Extraction**: 95% of key insights captured from raw notes
+- **Customer Scoring**: Consistent scoring across all customers
+- **Follow-up Quality**: 80% of follow-up emails result in positive responses
+- **Action Clarity**: Clear next steps for every customer