fraim-framework 2.0.65 → 2.0.67

package/dist/registry/workflows/customer-development/weekly-newsletter.md

@@ -0,0 +1,366 @@
+# Weekly Newsletter Workflow
+
+## INTENT
+To generate and distribute a compelling weekly newsletter that showcases the AI Agent's amazing new features and improvements, creating excitement among current users and FOMO for subscribers who haven't joined yet.
+
+## PRINCIPLES
+- **Value-Focused**: Highlight features and improvements that deliver real value to users
+- **User-Facing Only**: Do NOT include internal features (admin dashboards, monitoring, backups, devops)
+- **Authentic Testimonials**: Only use real testimonials from actual users - NO fake quotes
+- **FOMO-Inducing**: Create urgency and excitement about missing out
+- **Visually Stunning**: Beautiful design that catches the eye
+- **Concise**: Scannable format with clear sections
+- **AI Creativity**: AI agent makes all editorial decisions - what's a feature vs bug, what's worth highlighting
+
+## WORKFLOW TRIGGER
+**User triggers this workflow manually**:
+- Weekly, typically Monday morning
+- User says: "Generate this week's newsletter" or similar
+
+## AI AGENT PROCESS
+
+### Step 1: Issue Retrieval
+**AI Agent calls function**:
+```typescript
+// Import newsletter 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, 'newsletter-helpers.ts');
+
+// Import from the synced script
+const { getResolvedIssuesForNewsletter } = await import(scriptPath);
+
+// Use the function
+const resolvedIssues = await getResolvedIssuesForNewsletter(); 
+```
+
+**Note**: The `getResolvedIssuesForNewsletter()` function automatically:
+- Finds the most recent newsletter date from existing files
+- Uses that date as the starting point to fetch issues resolved AFTER that date
+- If no newsletter files exist, falls back to last 7 days
+- Returns ALL closed issues - AI agent decides what to include
+
+### Step 2: Intelligent Categorization & Filtering
+**AI Agent does creative analysis**:
+
+1. **Go through each resolved issue** and make editorial decisions:
+   - Is this user-facing or internal?
+   - Is this a feature, improvement, or bug fix?
+   - Is this worth highlighting to users?
+   - How should this be described to non-technical users?
+
+2. **Filter out internal-only issues**:
+   - Admin dashboards, monitoring, analytics (internal tools)
+   - Database backups, devops improvements
+   - CI/CD, deployment automation
+   - Developer tools, debugging features
+   - Documentation updates, dependency updates
+   - **API route fixes, endpoint refactoring, code structure changes**
+   - **Environment variable updates, configuration file changes**
+   - **Developer setup improvements, build process updates**
+   - **Internal bug fixes that don't impact user experience**
+   - Any change without user-facing impact
+
+3. **Categorize remaining issues**:
+   - **Features**: Adds NEW capability users didn't have before
+   - **Improvements**: Makes existing functionality better/faster/easier
+   - **Bug Fixes**: Fixes something that was broken
+
+4. **Select hero feature** (optional):
+   - Pick the MOST impactful feature or improvement
+   - Must have clear user value and ideally a quantifiable impact statement
+
+### Step 3: Write Compelling Content
+**AI Agent writes newsletter content** - be creative, exciting, and user-focused!
+
+**Guidelines**:
+- **NO TECHNICAL JARGON**: Don't mention internal systems, code, or technical details
+- **USER VALUE FOCUS**: Describe what the user can now do, not how it works
+- **ACTIVE, EXCITING LANGUAGE**: "You can now...", "The AI Agent now automatically...", "Your calendar finally..."
+- **QUANTIFY IMPACT**: "85% reduction in...", "5 hours saved per week", "3x faster"
+- **CREATE FOMO**: "Current users are already...", "Join 500+ executives who..."
+
+**For each item, write**:
+- **Title**: Short, benefit-focused (e.g., "Smart Timezone Detection" not "Implement timezone handling")
+- **Description**: What the user can do now, why it matters (2-3 sentences)
+- **Impact** (optional): Quantified benefit or user testimonial
+
+**Example**:
+```json
+{
+  "title": "Work Hours & Focus Blocks on Your Calendar",
+  "description": "Your work hours and focus blocks now automatically appear as visual blocks on your calendar! No more scheduling conflicts during your protected time. The AI creates beautiful calendar events that sync across all your devices, making it crystal clear when you're available and when you're in deep work mode.",
+  "impact": "Users report 85% reduction in meeting conflicts during focus time. Your calendar finally shows the complete picture of your day!"
+}
+```
+
+### Step 4: Generate Newsletter JSON
+**AI Agent creates ONE file**:
+- File: `docs/customer-development/newsletters/newsletter-YYYY-MM-DD.json`
+- Format: Structured JSON for deterministic rendering
+- Contains ALL content ready for user review
+
+**File format** (JSON):
+```json
+{
+  "metadata": {
+    "generatedOn": "2025-11-01T00:00:00.000Z",
+    "weekStart": "2025-10-25",
+    "weekEnd": "2025-11-01",
+    ...
+  },
+  "content": {
+    "weekTitle": "Work Hours & Focus Blocks Now on Your Calendar! 🎯",
+    "weekSubtitle": "8 powerful updates that supercharge your productivity",
+    "weekDate": "Oct 25 - Nov 1, 2025",
+    "openingMessage": "This week has been HUGE! We've shipped game-changing features that make the AI Agent even more powerful at protecting your time and managing your schedule. Current users are already saving hours every week - here's what you've been missing! 🚀",
+    "heroFeature": { ... },
+    "newFeatures": [ ... ],
+    "improvements": [ ... ],
+    "bugFixes": [ ... ],
+    "testimonial": {
+      "text": "The AI saved me 5 hours this week just by protecting my focus blocks...",
+      "author": "Sid Mathur",
+      "role": "Founder"
+    },
+    "comingNext": "Next week: Voice commands for calendar management, smart meeting summaries...",
+    "ctaLink": "https://example.com/wellness/ai-agent",
+    "ctaText": "Start Your Free Trial"
+  }
+}
+```
+
+### Step 5: Generate HTML
+// 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, 'newsletter-helpers.ts');
+
+const { saveNewsletter } = await import(scriptPath);
+
+// 2. Save newsletter JSON and generate HTML
+const savedPath = saveNewsletter(newsletter);
+```
+
+**This function will**:
+- Save the JSON file
+- Generate beautiful HTML from the template
+- Save the HTML file
+- Return path to JSON file
+
+### Step 6: User Review
+**AI Agent**:
+1. **Points user to the generated file**: `docs/customer-development/newsletters/newsletter-YYYY-MM-DD.json`
+2. **Shows preview**: Points to HTML file for browser preview
+3. **Requests review** and any edits needed (user can edit JSON directly)
+4. **Waits for user approval** before proceeding
+
+**Note**: User can:
+- Edit titles to be more compelling
+- Add/remove items
+- Adjust descriptions
+- Add real testimonials (verify authenticity!)
+- Add "coming next" teaser
+
+### Step 7: Send Newsletter (Separate Command)
+**When user says "Send the newsletter" or similar**:
+
+**User runs deterministic script**:
+```bash
+npm run send-newsletter
+```
+
+// 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, 'newsletter-helpers.ts');
+
+const { sendNewsletterToExecutives } = await import(scriptPath);
+
+// 2. Send newsletter to all active executives
+await sendNewsletterToExecutives('docs/customer-development/newsletters/newsletter-2025-11-01.json');
+```
+
+**This function will**:
+- Load the approved newsletter JSON
+- Get all active executives from database
+- For each executive:
+  - Get their AI Agent email address
+  - Get their OAuth tokens
+  - Send personalized newsletter from their AI identity
+- Log results and exit
+
+## NEWSLETTER STRUCTURE
+
+### Hero Section
+- **Week Title**: Catchy title based on hero feature or main theme
+- **Subtitle**: Count of updates
+- **Stats Banner**: Features | Improvements | Bug Fixes counters
+
+### Content Sections
+1. **Opening Message**: Exciting intro about what shipped (AI agent writes this)
+2. **Hero Feature** (optional): Spotlights the most impactful change with red "HERO FEATURE" badge
+3. **New Capabilities**: Major new features added
+4. **Major Improvements**: Significant enhancements
+5. **Fixes & Polish**: Bug fixes and minor improvements
+6. **Testimonial** (optional): Real user quote about impact (VERIFY AUTHENTICITY)
+7. **Coming Next** (optional): Preview of upcoming features
+
+### Call-to-Actions
+- **FOMO CTA**: "Don't Miss Out!" with signup link
+- **Feedback CTA**: Link to ChatGPT interface
+
+## EDITORIAL GUIDELINES
+
+### What to Include ✅
+- New features that add capability for users
+- Improvements that save time or improve UX
+- Bug fixes that had user impact
+- Real user testimonials (ONLY - verify authenticity)
+- Quantified benefits (time saved, conflicts reduced, etc.)
+
+### What to Exclude ❌
+- Internal infrastructure changes
+- **Admin dashboards, monitoring, analytics (internal-only)**
+- **Backups, database operations, devops**
+- **API route fixes, duplicate endpoint resolution**
+- **Environment configuration, .env file updates**
+- **Developer setup scripts, build configuration**
+- CI/CD improvements
+- Documentation updates
+- Dependency updates
+- Technical debt cleanup
+- Developer tools and debugging features
+- **Internal bug fixes (code structure, not user experience)**
+- Issues without user-facing impact
+- **FAKE TESTIMONIALS - authenticity is critical**
+
+**Rule of thumb**: If the user wouldn't notice the change in their daily use of the AI Assistant, don't include it.
+
+### Writing Style
+
+**Titles:**
+- Short, punchy, benefit-focused
+- ❌ "Implement timezone handling in calendar service"
+- ✅ "Smart Timezone Detection"
+
+**Descriptions:**
+- Start with the benefit to the user
+- Use "you" and "your" to make it personal
+- Be specific about what changed
+- ❌ "Fixed bug where calendar events weren't syncing correctly"
+- ✅ "Your calendar now stays perfectly in sync across all devices, no more mysterious missing meetings!"
+
+**Impact Statements:**
+- Quantify whenever possible
+- Include real user feedback
+- ❌ "Improved performance"
+- ✅ "Calendar loads 3x faster, getting you to your day in seconds instead of minutes"
+
+### Creating FOMO
+
+- **Quantify Success**: "500+ executives already using this feature"
+- **Show Savings**: "Don't miss out on 5 hours saved per week"
+- **Create Urgency**: "Limited spots available"
+- **Social Proof**: Real testimonials, growth stats, company names (with permission)
+
+## EXAMPLES
+
+### Example 1: Feature-Rich Week
+```
+User: "Generate this week's newsletter"
+
+AI Agent:
+1. Calls getResolvedIssuesForNewsletter() → gets 15 issues
+2. Analyzes each issue:
+   - 3 user-facing features
+   - 5 improvements
+   - 2 bugs
+   - 5 internal/devops (FILTERED OUT)
+3. Writes compelling content for each item
+4. Selects "Voice Commands for Calendar" as hero feature
+5. Writes exciting opening: "This week has been HUGE!..."
+6. Creates newsletter JSON with all content
+7. Calls saveNewsletter() → generates HTML
+8. Shows preview: "Newsletter ready! docs/customer-development/newsletters/newsletter-2025-11-01.html"
+
+User: "Looks great, send it"
+
+AI Agent or User:
+Runs: npm run send-newsletter
+OR
+Calls: sendNewsletterToExecutives('newsletter-2025-11-01.json')
+```
+
+### Example 2: User Adds Testimonial
+```
+User: "Generate newsletter"
+
+AI Agent:
+[Creates newsletter with 5 improvements, no testimonial]
+
+User: "Add a testimonial from me - I saved 5 hours this week thanks to focus blocks"
+
+AI Agent:
+[Edits JSON to add testimonial with user's name]
+[Regenerates HTML]
+Shows: "Updated! Ready to send?"
+
+User: "Yes, send it"
+
+User runs: npm run send-newsletter
+```
+
+## TIPS FOR COMPELLING NEWSLETTERS
+
+### Highlight User Value
+- Focus on what users can DO, not how it works
+- "You can now..." not "We implemented..."
+- "Your calendar automatically..." not "The system now..."
+
+### Use Concrete Examples
+- "Schedule meetings in seconds" not "Faster scheduling"
+- "85% fewer conflicts" not "Better conflict detection"
+- "Save 5 hours per week" not "More efficient"
+
+### Create Narrative
+- Opening: "This week has been incredible!"
+- Hero feature: Build excitement around main change
+- Coming next: Build anticipation for next week
+
+### Make it Scannable
+- Short paragraphs (2-3 sentences max)
+- Clear section headers
+- Visual hierarchy with emojis and formatting
+- Impact callouts that stand out
+
+## QUALITY CHECKLIST
+
+Before approving newsletter, verify:
+- [ ] All items are user-facing (no internal/devops features)
+- [ ] Testimonials are real and verified
+- [ ] Impact statements are accurate and quantified
+- [ ] Descriptions focus on user value, not implementation
+- [ ] Opening message is exciting and FOMO-inducing
+- [ ] Links are correct (Azure signup URL)
+- [ ] No mention of API credits or costs (the service is free)
+- [ ] Grammar and spelling are perfect
+- [ ] Preview HTML looks beautiful in browser
+
+## FREQUENCY
+
+**Recommended**: Weekly, sent Monday morning
+- Catches people starting their week
+- Fresh in mind for decision-making
+- Consistent schedule builds anticipation
+
+**Alternative**: Bi-weekly if weekly feels too frequent
+
+**Special editions**: 
+- Major feature launches
+- Milestone celebrations (e.g., "100 users!")
+- Holiday/end-of-year roundups

package/dist/registry/workflows/deploy/cloud-deployment.md

@@ -0,0 +1,310 @@
+# Cloud Deployment Workflow
+
+## Overview
+This workflow guides agents through deploying an application to cloud platforms (Azure, AWS, GCP), including infrastructure setup, CI/CD configuration, and database initialization.
+
+## Prerequisites
+- Application is implemented and tested
+- Cloud platform account access
+- Understanding of chosen cloud platform
+- GitHub repository (for CI/CD)
+
+## Workflow Steps
+
+### Phase 1: Platform Selection
+
+1. **Evaluate Options**
+   Consider:
+   - **Cost**: Free tier availability, pricing structure
+   - **Features**: Required services (hosting, database, storage)
+   - **Ease of Use**: Setup complexity, documentation quality
+   - **Scalability**: Future growth requirements
+
+2. **Common Platform Choices**
+   - **Azure**: Good for Microsoft ecosystem, free tier available
+   - **AWS**: Most comprehensive, free tier available
+   - **GCP**: Good for Google services, free tier available
+   - **Vercel/Netlify**: Simple for frontend, limited backend options
+
+3. **Resource Planning**
+   - **Hosting**: App Service, EC2, Cloud Run, etc.
+   - **Database**: Cosmos DB, RDS, Cloud SQL, etc.
+   - **Storage**: Blob Storage, S3, Cloud Storage
+   - **Networking**: CDN, load balancer (if needed)
+
+### Phase 2: Infrastructure Setup
+
+1. **Create Resource Group/Project**
+   ```bash
+   # Azure
+   az group create --name <resource-group> --location <region>
+   
+   # AWS
+   aws ec2 create-vpc ...
+   
+   # GCP
+   gcloud projects create <project-id>
+   ```
+
+2. **Create Database**
+   ```bash
+   # Azure Cosmos DB
+   az cosmosdb create --name <db-name> --resource-group <rg> ...
+   
+   # AWS RDS
+   aws rds create-db-instance ...
+   
+   # GCP Cloud SQL
+   gcloud sql instances create <instance-name> ...
+   ```
+
+3. **Create Hosting Service**
+   ```bash
+   # Azure App Service
+   az webapp create --name <app-name> --resource-group <rg> ...
+   
+   # AWS Elastic Beanstalk
+   eb init ...
+   
+   # GCP Cloud Run
+   gcloud run deploy ...
+   ```
+
+4. **Configure Networking**
+   - Set up database firewall rules
+   - Configure CORS if needed
+   - Set up custom domains (if needed)
+
+### Phase 3: CI/CD Pipeline Setup
+
+1. **GitHub Actions Workflow**
+   Create `.github/workflows/deploy.yml`:
+   ```yaml
+   name: Deploy to Cloud
+   
+   on:
+     push:
+       branches: [main]
+   
+   jobs:
+     deploy:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v3
+         - name: Setup Node.js
+           uses: actions/setup-node@v3
+         - name: Install dependencies
+           run: npm ci
+         - name: Build
+           run: npm run build
+         - name: Deploy
+           uses: azure/webapps-deploy@v2
+           with:
+             app-name: <app-name>
+             publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
+   ```
+
+2. **Configure Secrets**
+   - Store publish profiles/credentials in GitHub Secrets
+   - Store connection strings securely
+   - Never commit secrets to repository
+
+3. **Test Deployment**
+   - Push to trigger deployment
+   - Monitor deployment logs
+   - Verify application is accessible
+
+### Phase 4: Environment Configuration
+
+1. **Environment Variables**
+   Set in cloud platform:
+   - `NODE_ENV=production`
+   - `MONGO_DATABASE_URL=<connection-string>`
+   - `API_URL=<api-endpoint>`
+   - Any other required variables
+
+2. **Connection Strings**
+   - Get database connection string from cloud platform
+   - Configure in application settings
+   - Test connection
+
+3. **Build Configuration**
+   - Ensure build process works in CI/CD
+   - Check that all dependencies are in package.json
+   - Verify build outputs are correct
+
+### Phase 5: Database Initialization
+
+1. **Create Database**
+   ```bash
+   # MongoDB/Cosmos DB
+   az cosmosdb mongodb database create \
+     --account-name <account> \
+     --resource-group <rg> \
+     --name <database-name>
+   ```
+
+2. **Run Seed Script**
+   ```bash
+   # Set connection string
+   export MONGO_DATABASE_URL="<connection-string>"
+   
+   # Run seed (with CLEAR_DB=false to preserve data)
+   npm run seed
+   ```
+
+3. **Verify Data**
+   - Check database has expected collections
+   - Verify seed data was created
+   - Test application can read data
+
+### Phase 6: Deployment Validation
+
+1. **Health Check**
+   - Verify application is running
+   - Check health endpoint
+   - Verify database connection
+
+2. **Functional Testing**
+   - Test key user flows
+   - Verify API endpoints work
+   - Check frontend loads correctly
+
+3. **Error Monitoring**
+   - Check application logs
+   - Monitor for errors
+   - Verify error handling works
+
+## Platform-Specific Guides
+
+### Azure Deployment
+
+1. **Create Resources**
+   ```bash
+   # Resource Group
+   az group create --name <rg> --location westus
+   
+   # Cosmos DB
+   az cosmosdb create --name <db> --resource-group <rg> --server-version 4.2
+   
+   # App Service Plan
+   az appservice plan create --name <plan> --resource-group <rg> --sku FREE
+   
+   # Web App
+   az webapp create --name <app> --resource-group <rg> --plan <plan>
+   ```
+
+2. **Configure App Settings**
+   ```bash
+   az webapp config appsettings set \
+     --name <app> \
+     --resource-group <rg> \
+     --settings MONGO_DATABASE_URL="<connection-string>"
+   ```
+
+3. **Deploy via GitHub Actions**
+   - Use `azure/webapps-deploy` action
+   - Store publish profile in secrets
+   - Configure workflow to build and deploy
+
+### AWS Deployment
+
+1. **Create Resources**
+   ```bash
+   # RDS Instance
+   aws rds create-db-instance ...
+   
+   # Elastic Beanstalk
+   eb init
+   eb create
+   ```
+
+2. **Configure Environment**
+   - Set environment variables in EB console
+   - Configure security groups
+   - Set up IAM roles
+
+### GCP Deployment
+
+1. **Create Resources**
+   ```bash
+   # Cloud SQL
+   gcloud sql instances create <instance> ...
+   
+   # Cloud Run
+   gcloud run deploy <service> ...
+   ```
+
+## Best Practices
+
+1. **Start Simple**: Use free tiers initially
+2. **Secure Secrets**: Never commit credentials
+3. **Monitor Costs**: Set up billing alerts
+4. **Test Locally**: Test deployment process locally first
+5. **Version Control**: Keep infrastructure as code
+
+## Common Challenges
+
+1. **Connection Issues**: Database not accessible
+   - **Solution**: Check firewall rules, verify connection strings
+
+2. **Build Failures**: CI/CD build fails
+   - **Solution**: Test build locally, check all dependencies committed
+
+3. **Environment Variables**: App can't find variables
+   - **Solution**: Verify variable names, check platform-specific requirements
+
+4. **Database Initialization**: Seed script doesn't run
+   - **Solution**: Run manually first, check connection, verify script works
+
+5. **Static File Serving (SPA Routing)**: Frontend routes return 404
+   - **Symptom**: API works (`/api/health` returns OK) but frontend routes show "Not Found"
+   - **Root Cause**: Path resolution for static files incorrect in deployment environment
+   - **Solution for Express/Node.js**:
+     ```javascript
+     // Use process.cwd() for path resolution in deployment
+     // In deployment, process.cwd() is the root of the deployment package
+     const distPath = path.join(process.cwd(), 'dist')
+     app.use(express.static(distPath))
+     
+     // Serve React app for all non-API routes (SPA routing)
+     app.get('*', (req, res) => {
+       if (req.path.startsWith('/api')) {
+         return res.status(404).json({ error: 'Not found' })
+       }
+       res.sendFile(path.join(distPath, 'index.html'))
+     })
+     ```
+   - **Verification**: 
+     - Check that `dist/` directory exists in deployment package
+     - Verify `index.html` is in `dist/` directory
+     - Test that non-API routes serve `index.html`
+     - Test that API routes still work correctly
+
+## Output Artifacts
+
+1. **Infrastructure Documentation**
+   - Resources created
+   - Configuration details
+   - Connection information
+
+2. **CI/CD Workflow**
+   - GitHub Actions workflow file
+   - Deployment process documentation
+
+3. **Deployment Checklist**
+   - Steps completed
+   - Issues encountered
+   - Solutions applied
+
+## Next Steps
+
+After completing this workflow, proceed to:
+- **Iterative Improvement Cycle** workflow (`workflows/quality-assurance/iterative-improvement-cycle.md`) (recommended for systematic validation)
+- **Browser Validation & Iteration** workflow (`workflows/quality-assurance/browser-validation.md`)
+- Monitor application in production
+
+## Related Workflows
+- `workflows/quality-assurance/iterative-improvement-cycle.md` - **Recommended**: Systematic review-critique-fix-validate cycle
+- `workflows/replicate/re-implementation-strategy.md`
+- `workflows/quality-assurance/browser-validation.md`

package/dist/registry/workflows/improve-fraim/contribute.md

@@ -0,0 +1,32 @@
+# Workflow: Contribute to FRAIM
+
+**Path:** `workflows/improve-fraim/contribute.md`
+
+---
+
+# Contribute Workflow
+
+## INTENT
+Allows users to contribute new workflow ideas back to the FRAIM project. The agent collects necessary information and files a GitHub issue with the contribution details.
+
+## STEPS
+
+### Step 1: Gather Information
+1. Ask the user for the **Workflow Name**.
+   - Example: "What is the name of the workflow you would like to contribute?"
+2. Ask the user for the **Recommended Prompt** / Description.
+   - Example: "Please provide the recommended prompt or a detailed description of what this workflow should do."
+
+### Step 2: Confirmation
+Confirm the details with the user before proceeding.
+- "I am about to file a contribution for workflow '{workflow_name}' with the following prompt: '{workflow_prompt}'. Is this correct?"
+
+### Step 3: Execute Contribution
+Call the `file_issue` tool with the details gathered.
+
+- `title`: `"[CONTRIBUTION]: {workflow_name}"`
+- `body`: `"{workflow_prompt}"`
+- `labels`: `["enhancement", "workflow"]`
+
+### Step 4: Completion
+Notify the user that the issue has been filed successfully. Summarize the information (title and body) that was filed. Do not provide the issue number or URL.