fraim-framework 2.0.35 → 2.0.37

package/registry/workflows/improve-fraim/file-issue.md

@@ -1,32 +0,0 @@
-# Workflow: File Issue for FRAIM
-
-**Path:** `workflows/improve-fraim/file-issue.md`
-
----
-
-# File Issue Workflow
-
-## INTENT
-Allows users to easily file bugs or feature requests for the FRAIM framework directly from their working environment.
-
-## STEPS
-
-### Step 1: Gather Information
-1. Ask the user to describe the **Issue** (Bug or Feature Request).
-   - Example: "Please describe the bug you encountered or the feature you would like to request."
-
-### Step 2: Categorization (Optional)
-Ask if this is a **Bug** or a **Feature**.
-- If Bug: Use label `bug`.
-- If Feature: Use label `enhancement`.
-- Default: `triage`.
-
-### Step 3: Execute Issue Filing
-Call the `file_issue` tool with the details gathered.
-
-- `title`: `"[ISSUE]: <Short Summary>"`
-- `body`: `"<Full Description>"`
-- `labels`: `["<bug/enhancement>"]`
-
-### 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.

package/registry/workflows/marketing/content-creation.md

@@ -1,37 +0,0 @@
-# Workflow: content-creation
-
-**Path:** `workflows/marketing/content-creation.md`
-
----
-
-# Content Creation Phase
-
-## INTENT
-To produce high-quality marketing assets, including blog posts, social media content, and email campaigns, that effectively communicate the feature's value.
-
-## PRINCIPLES
-- **Storytelling**: Use narratives to engage the audience.
-- **Visual Excellence**: Ensure all assets are visually appealing and on-brand.
-- **Consistency**: Maintain a consistent voice and style across all content.
-- **Action-Oriented**: Include clear calls to action in all materials.
-
-## CONTENT CREATION WORKFLOW
-
-### Step 1: Asset Identification
-- What assets are needed based on the strategy? (Blog post, Social thread, Email)
-
-### Step 2: Drafting
-- Create drafts for each asset in `docs/marketing/content/{issue_number}/`
-- Follow the brand voice guidelines.
-
-### Step 3: Visual Asset Prep
-- Identify core screenshots or diagrams needed.
-- Write descriptions for images.
-
-### Step 4: Review
-- Ensure content is free of errors and aligns with the strategy.
-
-## OUTPUT
-- Blog Post Draft
-- Social Media Thread Draft
-- Email Campaign Draft

package/registry/workflows/marketing/hbr-article.md

@@ -1,73 +0,0 @@
-# Workflow: hbr-article
-
-**Path:** `workflows/marketing/hbr-article.md`
-
----
-
-# Harvard Business Review Article Phase
-
-## INTENT
-Design a repeatable reviewable process for researching, drafting, and submitting an HBR or similar thought-leadership article that follows the Harvard Business Review author guidelines and documents each review before publication.
-
-## PRINCIPLES
-- **Strategy First** – Explain why the piece matters to HBR readers and how it advances the product roadmap.
-- **Evidence-Led Storytelling** – Back every claim with customer insights, data, or experiments and include proper citations.
-- **Executive Clarity** – Keep the tone structured, concise, and professional while still being compelling.
-- **Review Discipline** – Require sign-offs during every milestone so the article progresses with confidence.
-
-## HARVARD BUSINESS REVIEW GUIDELINES SUMMARY
-- **Audience & Outcome**: HBR serves ambitious senior leaders with rigorous, evidence-backed insights they can apply today.
-- **Topic Scope**: Strategy, leadership, culture, operations, technology change, innovation, communication, decision-making, talent, and transitions.
-- **Five Quality Criteria**: Expertise, evidence, originality (or a counterintuitive twist), practical usefulness, and excellent writing.
-- **Responsible Storytelling**: Represent diverse organizations, avoid bias/stereotypes, disclose conflicts, and explain any generative AI usage.
-- **Pitch Checklist** (covered during Step 2 and in the template): central message, importance/counterintuition, novelty, leader application, authority/backing, supporting research/examples, and relevant experiences.
-
-## HBR ARTICLE WORKFLOW
-
-### Step 1: Confirm the story belongs with HBR
-- Articulate the insight, the proposed HBR section (Strategy, Leadership, Technology, etc.), and why the timing is right.
-- Cite the HBR guidelines (https://hbr.org/guidelines-for-authors) for exclusivity, word count, bylines, and conflict-of-interest disclosures.
-- Document how the story ties to the product roadmap, clarify the customer problem, and capture any embargo or exclusivity constraints with marketing and executive reviewers.
-
-### Step 2: Research & angle sharpening
-- Gather customer data, experiments, interviews, or telemetry that demonstrate the thesis.
-- Review two recent HBR pieces in the target section to understand structure, tone, and citation style.
-- Identify outstanding sourcing needs (people, metrics, visuals) and schedule them before drafting.
-- Use the HBR prompts to refine the story:
-  - What is the central message of the article?
-  - Why is it important, useful, or counterintuitive?
-  - What is new about the idea?
-  - Why do senior leaders need to know about it today, and how can they apply it?
-  - What is the source of the team’s authority (prior work, credentials, experience)?
-  - What research or examples will back the idea?
-  - What academic, professional, or personal experience will you draw on?
-
-### Step 3: Outline and structure guardrails
-- Draft an outline covering:
-  - Hook and problem framing
-  - Diagnostic/evidence blocks (data, quotes, frameworks)
-  - Practice-ready recommendation and product-specific next steps
-- Annotate each section with required references and attachments.
-- Share the outline with product and marketing reviewers, collect feedback, and incorporate it prior to drafting.
-
-### Step 4: Draft, iterate, and polish
-- Adhere to HBR word limits and formatting expectations; note disclosures, partnerships, or competing interests directly in the draft.
-- Run two review passes: one focused on clarity (peer reviewer) and one on strategic voice (executive reviewer).
-- Track edits through versioned drafts, doc comments, or PR history and finalize the headline/angle with the marketing lead.
-- Capture approvals for accuracy, voice, and compliance before locking the draft.
-
-### Step 5: Finalize submission + collateral
-- Verify the draft satisfies the HBR checklist (tone, length, references, conflicts) and secure the final sign-off.
-- Draft the submission email (subject line, synopsis, attachments) and log it in `docs/marketing/hbr/submission-log.md` or an equivalent tracking document.
-- Plan accompanying collateral (blog post, newsletter snippet, executive update) that repurposes the article's insight and assign owners.
-- Note follow-up steps for publication tracking and audience engagement.
-
-## OUTPUT
-- Thesis/angle memo that explains the fit for HBR.
-- Approved outline and draft with reviewer notes and version history.
-- Submission package (email, attachments, compliance checklist).
-- Launch collateral plan with asset owners and delivery status.
-
-## DOCUMENT TEMPLATE STRUCTURE
-
-Use `get_fraim_file({ path: "templates/marketing/HBR-ARTICLE-TEMPLATE.md" })` to capture the thesis, outline, draft, review log, submission log, and launch collateral plan for each HBR article. 

package/registry/workflows/marketing/launch-checklist.md

@@ -1,37 +0,0 @@
-# Workflow: launch-checklist
-
-**Path:** `workflows/marketing/launch-checklist.md`
-
----
-
-# Launch Checklist Phase
-
-## INTENT
-To ensure a smooth and successful feature launch by systematically verifying all marketing, technical, and operational readiness.
-
-## PRINCIPLES
-- **Meticulous Preparation**: Leave no stone unturned before launch.
-- **Cross-Functional Alignment**: Ensure all teams are ready for the launch.
-- **Timely Execution**: Follow the schedule for maximum impact.
-- **Post-Launch Verification**: Monitor performance and address issues immediately.
-
-## LAUNCH CHECKLIST WORKFLOW
-
-### Step 1: Readiness Check
-- Is the feature deployed and verified?
-- Are the marketing assets ready?
-- Is the support team briefed?
-
-### Step 2: Launch Execution
-- Post to social channels.
-- Send announcement emails.
-- Update documentation.
-
-### Step 3: Post-Launch Monitoring
-- Check for user feedback.
-- Monitor error rates.
-- Engagement metrics.
-
-## OUTPUT
-- Launch Status Report
-- Post-Launch Feedback Summary

package/registry/workflows/marketing/marketing-strategy.md

@@ -1,45 +0,0 @@
-# Workflow: marketing-strategy
-
-**Path:** `workflows/marketing/marketing-strategy.md`
-
----
-
-# Marketing Strategy Phase
-
-## INTENT
-To define the value proposition, target audience, and launch strategy for new features, ensuring clear communication of benefits and effective market entry.
-
-## PRINCIPLES
-- **Value-First**: Focus on the problem solved and the value delivered.
-- **Audience-Centric**: Identify exactly who the feature is for.
-- **Clear Messaging**: Ensure simplicity and clarity in all marketing materials.
-- **Channel Alignment**: Choose appropriate channels for the target audience.
-
-## MARKETING STRATEGY WORKFLOW
-
-### Step 1: Feature Analysis
-- What is the core problem being solved?
-- What are the key benefits?
-- Who is the primary persona?
-
-### Step 2: Value Proposition Definition
-- Draft 1-2 sentences describing the feature's value.
-- Identify the "Hero" benefit.
-
-### Step 3: Target Audience Identification
-- Define the specific segment of users this is for.
-- Identify there pain points.
-
-### Step 4: Channel Strategy
-- Where will we announce this? (Twitter, LinkedIn, Email, In-app)
-- What is the tone for each channel?
-
-### Step 5: Marketing Brief Creation
-- Create a `docs/marketing/strategy/{issue_number}-{feature-name}.md`
-- Use `MARKETING-STRATEGY-TEMPLATE.md`
-
-## OUTPUT
-- Marketing Strategy Doc
-- Value Prop
-- Target Audience
-- Launch Checklist status

package/registry/workflows/marketing/storytelling.md

@@ -1,65 +0,0 @@
-# Workflow: storytelling
-
-**Path:** `workflows/marketing/storytelling.md`
-
----
-
-# Marketing Storytelling Workflow
-
-## INTENT
-To transform product development experiences into compelling founder narratives for events, conferences, and speaking opportunities that connect technical reality with broadly applicable lessons.
-
-## PRINCIPLES
-- **Grounded in Reality**: All narratives based on actual product development experiences
-- **Story Arc Focus**: Follow intent → friction → insight → outcome structure
-- **Audience-Specific**: Tailor messaging to event type and audience expectations
-- **Authentic Voice**: Avoid sales pitch tone, focus on genuine founder lessons
-
-## STORYTELLING WORKFLOW
-
-### Step 1: Artifact Collection
-Gather source materials that tell the product development story:
-- Product documentation (specs, architecture notes, design docs)
-- Development retrospectives or post-mortems
-- Code repositories and key commits
-- Prior pitches, emails, or presentations
-
-### Step 2: Story Arc Extraction
-Extract the core narrative following the story structure:
-- **Intent**: What was the original vision and why it mattered?
-- **Friction**: What unexpected challenges or failures occurred?
-- **Insight**: What key learnings or "aha moments" emerged?
-- **Outcome**: What was built and why it works?
-
-### Step 3: Founder Lessons Development
-Transform technical experience into broadly applicable lessons:
-- Identify 3-5 key takeaways that apply to other founders
-- Remove internal jargon and technical complexity
-- Focus on decision-making processes and trade-offs
-- Highlight counterintuitive or surprising discoveries
-
-### Step 4: Event-Specific Adaptation
-Customize content for target event and audience:
-- Research event format (conference, panel, workshop, podcast)
-- Adapt language for audience (technical, business, mixed)
-- Create appropriate time formats (5min, 15min, 30min, 45min)
-- Develop supporting materials and Q&A preparation
-
-### Step 5: Content Package Creation
-Generate complete materials for event submission:
-- Email pitch with compelling subject line
-- Session title with clear hook
-- 1-2 sentence session description
-- Speaker bio highlighting relevant experience
-- Presentation outline and talking points
-
-## TEMPLATE USAGE
-
-Use `get_fraim_file({ path: "templates/marketing/STORYTELLING-TEMPLATE.md" })` to create:
-- `docs/marketing/storytelling/{issue_number}-{event-name}.md`
-
-## OUTPUT
-- Compelling founder narrative grounded in product reality
-- Event-ready submission materials
-- Multi-format presentation content
-- Reusable story framework for future opportunities

package/registry/workflows/performance/analyze-performance.md

@@ -1,65 +0,0 @@
-# Performance Analysis Phase
-
-## INTENT
-To diagnose production performance issues (CPU, Memory, Swap) and provide actionable recommendations for stabilization without performing direct application or infrastructure modifications.
-
-## PRINCIPLES
-- **Observational Only**: Do not modify code or infrastructure during this phase.
-- **Data-Driven**: Base all recommendations on metrics collected from the environment.
-- **Non-Invasive**: Use non-destructive commands that do not impact server stability.
-- **Actionable**: Provide clear, prioritized recommendations for remediation.
-
-## ANALYSIS WORKFLOW
-
-### Step 1: Run the Performance Profiler
-Execute the profiling script against the production environment to collect plan-level and process-level metrics.
-
-**Note**: `profile-server.ts` has FRAIM dependencies and requires ephemeral execution.
-
-```bash
-# Get the profile-server script ephemerally (has FRAIM dependencies)
-# Use get_fraim_file({ path: "scripts/performance/profile-server.ts" }) and save to tmp/profile-server.ts
-npx tsx tmp/profile-server.ts --prod
-```
-
-### Step 2: Inspect Automated Diagnosis
-Review the "Step 4: Automated Diagnosis" section of the output. 
-It will specifically check for:
-- **Swap Death**: If >95% swap is used, the server is thrashing.
-- **Absent Application**: If `server.js` is missing, the infrastructure is healthy but the app is crashed/not starting.
-- **Infrastructure Hogs**: If Azure agents (Kudu/dotnet) are consuming excessive RAM.
-
-### Step 3: Deep Dive Log Analysis
-If a crash loop or high operation frequency is suspected, collect and analyze application logs using the same script with the `--logs` flag.
-
-```bash
-# Use the same ephemeral script with logs flag
-npx tsx tmp/profile-server.ts --prod --logs
-```
-Look for:
-- Frequency of initialization logs (e.g., "Ensured unique index").
-- Patterns indicative of OOM events or unhandled exceptions.
-- High volume of specific operations (e.g., decryptions) suggesting an infinite loop.
-
-### Step 4: Formulate Recommendations
-Based on the diagnosis, provide specific recommendations in your response or an implementation plan (if a fix is needed in a subsequent phase).
-Examples:
-- **Restart**: If swap usage is high or rogue processes are detected.
-- **Upgrade Plan**: If physical memory is chronically saturated (B1 to P1v3).
-- **Code Optimization**: If log analysis reveals initialization loops or leaks.
-
-## EXAMPLES
-
-### Good Analysis
-> "The profiler shows 98% CPU usage and 'Swap Death'. The logs show 'Ensured unique index' occurring 100 times per minute. I recommend implementing an initialization guard in `PrismaDatabaseService` to break this loop."
-
-### Bad Analysis (Do not do)
-> "I found a loop, so I've updated `server.ts` to fix it." 
-> *Correction: Propose the fix first, do not implement it within the analysis workflow.*
-
-## COMPLETION CHECKLIST
-- [ ] Profiler run successfully on production.
-- [ ] Resource bottlenecks (CPU/Mem/Swap) identified.
-- [ ] Application process stability verified.
-- [ ] Root cause hypothesis formulated based on metrics and logs.
-- [ ] Prioritized recommendations delivered to the user.

package/registry/workflows/product-building/design.md

@@ -1,130 +0,0 @@
-# Workflow: design
- 
-**Path:** `workflows/design.md`
- 
----
- 
-# Design Phase
- 
-## INTENT
-To create comprehensive, detailed technical design documents that plan solutions before implementation, ensuring proper architecture, clear requirements, and stakeholder alignment through structured RFCs and bug fix templates.
- 
-## PRINCIPLES
-- **Success Criteria**: Optimize for Integrity, Correctness, Completeness, Independence, and Speed - see `rules/agent-success-criteria.md` (fetch via `get_fraim_file`).
-- **Design First**: Plan before implementing to avoid rework
-- **Template Consistency**: Use established templates for different types of changes
-- **Stakeholder Alignment**: Get review and approval before implementation
-- **Clear Documentation**: Create detailed, actionable design documents
-- **Iterative Refinement**: Incorporate feedback and iterate on designs
-- **Spike-First Development**: Follow "Spike-First Development" rule (read `rules/spike-first-development.md` using `get_fraim_file`) to validate technology compatibility before building complex solutions
-- **Simplicity**: Follow "Simplicity" principle (read `rules/simplicity.md` using `get_fraim_file`)
-- **Architecture**: Follow existing architecture - see `.fraim/config.json` for the path (`customizations.architectureDoc`)
- 
-## DESIGN WORKFLOW
-
-### Step 1: Issue Identification
-Ask for {issue_number} (and optional {slug})
-### Step 2: Phase Initiation
-Label the issue 'phase:design' (GitHub Action will automatically create a draft PR if none exists, or update the existing PR with phase-specific details, and label the issue `status:wip`)
-
-### Step 3: Environment Setup
-**IMPORTANT**: The user has already run `prep-issue.sh` which has:
-- ✅ Created the feature branch
-- ✅ Checked out the branch
-- ✅ Pushed the empty branch to origin
-- ✅ Indexed the codebase with Serena
-- ✅ Opened the editor in the prepared workspace
-
-You can start working immediately in the prepared environment. No need to create branches or wait for GitHub Actions.
-
-### Step 4: Work Location
-You are already in the correct workspace prepared by the user. Confirm you're on the right branch and start working.
-
-### Step 5: Pre-Creation Validation
-Before creating any design document, agents MUST:
-
-1. **Spike-First Development Check**:
-   - Read and follow "Spike-First Development" rule (retrieve via `get_fraim_file({ path: "rules/spike-first-development.md" })`)
-   - If design involves unfamiliar technology, plan spike/proof-of-concept first
-   - Validate technology compatibility before designing complex solutions
-   - Avoid "Build First, Integrate Later" anti-pattern
-
-2. **Verify Template Selection**:
-   - For bug fixes: Use Bug Spec template (retrieve via `get_fraim_file({ path: "templates/specs/BUGSPEC-TEMPLATE.md" })`)
-   - For new features: Use Tech Spec template (retrieve via `get_fraim_file({ path: "templates/specs/TECHSPEC-TEMPLATE.md" })`)
-   - Confirm template exists before proceeding
-   - If you cannot find the template, stop and ask for help as per "Communication" rule (retrieve via `get_fraim_file({ path: "rules/communication.md" })`)
-
-3. **Validate Naming Convention**:
-   - Format: `docs/rfcs/{issue_number}-{kebab-title}.md`
-   - Example: `docs/rfcs/228-improve-token-refresh.md`
-   - NO other naming patterns allowed
-
-4. **Template Compliance Check**:
-   - Read the selected template first
-   - Ensure all required sections are included
-   - Verify placeholder format matches template
-
-5. **Workflow Rule Verification**:
-   - Confirm issue is labeled `phase:design`
-   - Verify branch exists before starting work
-   - Check working directory is correct
-
-### Step 6: Design Document Creation
-Your work entails the following:
-- Create docs/rfcs/{issue_number}-{slug}.md.  
-- Use the correct template as per #1
-- Check if there is an existing spec for  this issue. Specs are stored in `docs/feature specs/` and share the same naming convention as the RFCs. If there is an existing spec, read through it and understand if fully.
-- Understand the issue, the existing codebase, and be detailed in your technical design. The better your initial design, manual valiation, testing plan, the smoother the implementation will go.
-
-
-### Step 7: Design Creation Checklist
-Before commiting your work, verify:
-- [ ] Correct template used (BUGFIX-TEMPLATE.md or RFC-TEMPLATE.md)
-- [ ] Proper file naming: `{issue_number}-{kebab-title}.md`
-- [ ] All template sections completed
-- [ ] No placeholder text remaining
-- [ ] Issue labeled `phase:design`
-- [ ] Working in correct branch
-- [ ] File saved in `docs/rfcs/` directory
-- [ ] If issue is a bug, you have reproduced it
-- [ ] You understand the codebase and have high confidence in your design
-
-### Step 8: Submit for Review
-- Commit and sync your work
-- Label the issue 'status:needs-review' and remove 'status:wip'
-- Update the PR with a comment to include evidence - Use Design Evidence template (retrieve via `get_fraim_file({ path: "templates/evidence/Design-Evidence.md" })`)
-- **Next Step**: Switch to "Iterate on PR Comments" workflow (retrieve via `get_fraim_file({ path: "workflows/product-building/iterate-on-pr-comments.md" })`) to monitor actions and handle feedback.
-
-### Step 9: Iteration
-If workflow actions or reviewer feedback indicates more work is needed:
-- Label the issue 'status:wip' and remove 'status:needs-review'
-- Go back to Step 6 and iterate until PR is approved
-
-## EXAMPLES
-
-### Good: Comprehensive Design Process
-```
-Issue #84: "Fix calendar sync timeout"
-1. ✅ Identified: Issue #84, slug: "fix-sync-timeout"
-2. ✅ Phase: Set phase:design, PR created
-3. ✅ Environment: User ran prep-issue.sh, ready to work
-4. ✅ Location: Working in prepared workspace with Serena indexing
-5. ✅ Design: Created docs/rfcs/84-fix-sync-timeout.md
-6. ✅ Template: Used BUG-TEMPLATE.md for bug fix
-7. ✅ Review: Set status:needs-review
-8. ✅ Iteration: Incorporated feedback, updated design
-Result: Clear, actionable design document
-```
-
-### Bad: Incomplete Design Process
-```
-Issue #84: "Fix calendar sync timeout"
-1. ✅ Identified: Issue #84
-2. ❌ Skip: Didn't set phase:design
-3. ❌ Skip: Didn't create branch
-4. ❌ Skip: Started coding without design
-5. ❌ Skip: No RFC document created
-6. ❌ Skip: No stakeholder review
-Result: Unclear requirements, potential rework
-```