fraim-framework 2.0.65 → 2.0.67

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

@@ -0,0 +1,65 @@
+# 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/dist/registry/workflows/product-building/design.md

@@ -0,0 +1,263 @@
+---
+{
+  "name": "design",
+  "initialPhase": "design-design",
+  "phases": {
+    "design-design": {
+      "onSuccess": "design-completeness-review",
+      "onFailure": "design-design"
+    },
+    "design-completeness-review": {
+      "onSuccess": "submit",
+      "onFailure": "design-design"
+    },
+    "submit": {
+      "onSuccess": "address-feedback",
+      "onFailure": "submit"
+    },
+    "address-feedback": {
+      "onSuccess": "retrospective",
+      "onFailure": "design-design"
+    },
+    "retrospective": {
+      "onSuccess": null,
+      "onFailure": null
+    }
+  }
+}
+---
+
+# Workflow: design
+
+# Design Workflow
+
+## INTENT
+To create comprehensive technical design documents using a phase-based approach guided by the AI Mentor, ensuring proper architecture, clear requirements, and stakeholder alignment.
+
+## Phase: design-design
+
+### INTENT
+To create a comprehensive technical design that translates the feature specification into implementable architecture, APIs, and technical solutions.
+
+### OUTCOME
+A complete technical design document that:
+- Translates spec requirements into technical architecture
+- Defines APIs, data models, and system interactions
+- Identifies technical risks and mitigation strategies
+- Provides clear implementation guidance
+- Includes technical validation criteria
+
+### PRINCIPLES
+- **Spec-Driven**: Design directly addresses specification requirements
+- **Implementation-Ready**: Provides clear technical guidance
+- **Risk-Aware**: Identifies and mitigates technical risks
+- **Validation-Focused**: Includes technical validation criteria
+- **Template-Compliant**: Follows RFC template structure
+- **Spike-First**: Follow usage of spikes for unfamiliar technology (read `rules/spike-first-development.md`)
+
+### WORKFLOW
+
+#### Step 1: Get Issue Details
+
+**Read Issue Details**: Use {{get_issue}} to get the complete issue information:
+- Read the full issue description, title, and labels
+- Check for linked documents (specs, RFCs, design docs)
+- Review any comments or discussion threads
+- Note acceptance criteria and requirements
+- Identify if there's an existing specification document
+
+#### Step 2: Load Template and Specification
+- Call `get_fraim_file({ path: "templates/specs/TECHSPEC-TEMPLATE.md" })` (for features)
+- Call `get_fraim_file({ path: "templates/specs/BUGSPEC-TEMPLATE.md" })` (for bugs)
+- Read the completed specification document from previous phase
+- Call `get_fraim_file({ path: "rules/spike-first-development.md" })`
+
+#### Step 3: Check for PR Feedback
+
+**CRITICAL**: Before creating design, check for feedback:
+- **PR Review Feedback**: `docs/evidence/{issue_number}-design-feedback.md`
+
+**If PR feedback exists:**
+- **MUST address all UNADDRESSED items** before proceeding
+- Update feedback file after addressing each item
+- Change status from UNADDRESSED to ADDRESSED with resolution details
+- Cannot skip or defer feedback items
+- Phase cannot complete until all feedback is addressed
+
+**PR Feedback File Format** (if exists):
+```markdown
+### Comment X - ADDRESSED
+- **Author**: reviewer_name
+- **Comment**: Original feedback
+- **Status**: ADDRESSED
+- **Resolution**: How you addressed this feedback
+```
+
+#### Step 4: Analyze Specification Requirements
+- Extract all technical requirements from specification
+- Identify system components that need modification
+- Determine API changes or additions needed
+- Note any performance or scalability considerations
+- List integration points with existing systems
+
+#### Step 5: Create Technical Design Document
+- Create RFC file at `docs/rfcs/{issue_number}-{kebab-case-title}.md`
+- Follow appropriate template structure (TECHSPEC or BUGSPEC)
+- Include all required sections:
+  - Problem statement (from spec)
+  - Technical requirements
+  - Proposed solution architecture
+  - API design and data models
+  - Implementation plan
+  - Testing strategy
+  - Risk assessment and mitigation
+  - Alternative approaches considered
+
+#### Step 6: Design System Architecture
+- Define component interactions and data flow
+- Specify API endpoints and request/response formats
+- Design database schema changes (if needed)
+- Plan integration with existing systems
+- Consider scalability and performance implications
+
+#### Step 7: Identify Technical Risks
+- List unfamiliar technologies or patterns
+- Note complex integrations or dependencies
+- Identify performance bottlenecks
+- Consider security implications
+- Plan risk mitigation strategies
+
+#### Step 8: Apply Labels
+- Use {{add_issue_labels}} to label the issue with `phase:design`
+- This will trigger automatic PR creation/update
+
+### VALIDATION
+
+#### Phase Complete When:
+- ✅ Technical design document created using appropriate template
+- ✅ All specification requirements addressed technically
+- ✅ System architecture clearly defined
+- ✅ API design and data models specified
+- ✅ Technical risks identified and mitigation planned
+- ✅ Implementation plan provides clear guidance
+- ✅ Testing strategy defined
+- ✅ **PR feedback addressed** (if `docs/evidence/{issue_number}-design-feedback.md` exists)
+- ✅ Issue labeled with `phase:design`
+
+#### Phase Incomplete If:
+- ❌ Design document missing or incomplete
+- ❌ Template structure not followed
+- ❌ Specification requirements not addressed
+- ❌ Architecture unclear or missing
+- ❌ Technical risks not identified
+- ❌ Implementation guidance insufficient
+- ❌ **PR feedback not addressed** (UNADDRESSED items remain in feedback file)
+
+### Report Back:
+When you complete this phase, call:
+
+```javascript
+seekMentoring({
+  workflowType: "design",
+  issueNumber: "{issue_number}",
+  currentPhase: "design-design", 
+  status: "complete",
+  evidence: {
+    designDocument: "docs/rfcs/{issue_number}-{title}.md",
+    templateUsed: "TECHSPEC-TEMPLATE.md",
+    architectureComponents: ["API layer", "Database schema", "UI components"],
+    technicalRisks: ["Integration with legacy system", "Performance at scale"],
+    issueLabeled: "phase:design"
+  },
+  findings: {
+    keyDecisions: ["Use REST API", "PostgreSQL for data storage", "React components"],
+    riskMitigation: ["Spike legacy integration", "Load testing plan"]
+  }
+})
+```
+
+## Phase: design-completeness-review
+
+### INTENT
+To verify that the technical design addresses all aspects of the functional specification, including the validation plan and testing strategy.
+
+### OUTCOME
+Confirmation that:
+- Design addresses all functional spec requirements
+- Validation plan from spec is reflected in design
+- Testing strategy covers all specified scenarios
+- Technical approach enables spec validation
+- Design is ready for implementation
+
+### WORKFLOW
+
+#### Step 1: Load Functional Specification
+- Read the functional specification document from `docs/feature specs/{issue_number}-*.md`
+- Extract all requirements, user workflows, and validation criteria
+- Note any UI mockups and interaction patterns
+
+#### Step 2: Verify Spec Requirements Coverage
+- Check that design addresses each functional requirement
+- Confirm technical approach supports all user workflows from spec
+- Verify API design enables the specified user experience
+- Ensure data models support all spec requirements
+
+#### Step 3: Validation Plan Alignment
+**Critical**: The spec's validation plan must be implementable with this design
+- Review validation scenarios from functional spec
+- Confirm design provides necessary APIs/interfaces for validation
+- Check that testing strategy covers all validation scenarios
+- Verify design enables browser testing (if UI changes)
+- Ensure backend validation points are accessible
+
+#### Step 4: Technical Feasibility Check
+- Confirm design is technically sound and implementable
+- Check that all spec requirements can be built with this approach
+- Verify integration points are well-defined
+- Assess if design enables the spec's success criteria
+
+### VALIDATION
+
+#### Phase Complete When:
+- ✅ All functional spec requirements addressed in design
+- ✅ Validation plan from spec is implementable with this design
+- ✅ Testing strategy covers all spec scenarios
+- ✅ Technical approach is sound and feasible
+- ✅ Design enables spec success criteria
+- ✅ Ready for implementation phase
+
+#### Phase Incomplete If:
+- ❌ Functional spec requirements not addressed
+- ❌ Validation plan not implementable with current design
+- ❌ Testing strategy insufficient for spec scenarios
+- ❌ Technical approach infeasible or unclear
+- ❌ Design doesn't enable spec success criteria
+
+### Report Back:
+```javascript
+seekMentoring({
+  workflowType: "design",
+  issueNumber: "{issue_number}",
+  currentPhase: "design-completeness-review", 
+  status: "complete",
+  evidence: {
+    specRequirementsCovered: true,
+    validationPlanImplementable: true,
+    testingStrategySufficient: true,
+    technicallyFeasible: true,
+    functionalSpecPath: "docs/feature specs/{issue_number}-*.md"
+  }
+})
+```
+
+## Phase: submit
+
+{{include:delivery/submit.md}}
+
+## Phase: address-feedback
+
+{{include:delivery/address-feedback.md}}
+
+## Phase: retrospective
+
+{{include:delivery/retrospective.md}}