fraim-framework 1.0.12 → 2.0.2

package/.ai-agents/rules/software-development-lifecycle.md

@@ -0,0 +1,276 @@
+# Software Development Lifecycle
+
+## INTENT
+To establish a systematic, phase-based development process that ensures quality, maintainability, and proper documentation throughout the software development lifecycle.
+
+## PRINCIPLES
+- **Phase-Based Development**: Clear phases with defined deliverables
+- **Quality Gates**: Each phase has completion criteria
+- **Documentation**: Comprehensive documentation at each phase
+- **Review Process**: Peer review and approval at key milestones
+- **Traceability**: Clear links between requirements, design, and implementation
+
+## DEVELOPMENT WORKFLOW
+
+### Branch Management
+Always work on the feature branch for the current issue: `feature/<issue#>-<kebab-title>`. Never push to master.
+
+### Development Workflow
+1. **Clone Setup**: Work in your own cloned repository folder. Folder name should be `{PROJECT_NAME} - Issue {issue_number}`
+2. **Branch Management**: Create/checkout feature branch for your issue
+3. **Local Development**: Make changes, run tests locally
+4. **Check before commit**: Only commit after approval from the user.
+5. **Push Changes**: Push to feature branch, never to master
+6. **PR Creation**: Let GitHub Actions create/update PRs automatically
+
+## PHASE-BASED DEVELOPMENT
+
+### Phase 1: Specification (phase:spec)
+**Objective**: Define what needs to be built
+
+**Activities**:
+- Gather requirements from stakeholders
+- Define functional and non-functional requirements
+- Create user stories and acceptance criteria
+- Document constraints and assumptions
+- Risk assessment and mitigation planning
+
+**Deliverables**:
+- Requirements specification document
+- User stories with acceptance criteria
+- Risk assessment
+- Success metrics definition
+
+**Completion Criteria**:
+- All requirements documented and approved
+- Stakeholder sign-off obtained
+- Technical feasibility confirmed
+- Success criteria defined and measurable
+
+### Phase 2: Design (phase:design)
+**Objective**: Define how it will be built
+
+**Activities**:
+- System architecture design
+- Component design and interfaces
+- Database schema design
+- API specification
+- Security design considerations
+- Performance requirements analysis
+
+**Deliverables**:
+- Architecture design document
+- Component diagrams
+- Database schema
+- API specifications
+- Security design
+- Performance benchmarks
+
+**Completion Criteria**:
+- Design document complete and approved
+- Architecture review passed
+- Security review completed
+- Performance requirements validated
+
+### Phase 3: Test Planning (phase:tests)
+**Objective**: Define how it will be tested
+
+**Activities**:
+- Test strategy development
+- Test case creation
+- Test data preparation
+- Test environment setup
+- Automation test planning
+- Performance test planning
+
+**Deliverables**:
+- Test plan document
+- Test cases and scenarios
+- Test data sets
+- Automated test scripts
+- Performance test plan
+
+**Completion Criteria**:
+- Comprehensive test plan approved
+- Test cases cover all requirements
+- Test automation framework ready
+- Test environment configured
+
+### Phase 4: Implementation (phase:impl)
+**Objective**: Build the solution
+
+**Activities**:
+- Code implementation
+- Unit testing
+- Integration testing
+- Code review
+- Documentation updates
+- Performance optimization
+
+**Deliverables**:
+- Working software
+- Unit tests
+- Integration tests
+- Code documentation
+- Updated system documentation
+
+**Completion Criteria**:
+- All features implemented per design
+- All tests passing
+- Code review completed
+- Documentation updated
+- Performance requirements met
+
+## QUALITY GATES
+
+### Specification Gate
+- [ ] Requirements are clear and testable
+- [ ] Stakeholder approval obtained
+- [ ] Technical feasibility confirmed
+- [ ] Success criteria defined
+
+### Design Gate
+- [ ] Architecture is sound and scalable
+- [ ] Security considerations addressed
+- [ ] Performance requirements feasible
+- [ ] Design review approved
+
+### Test Gate
+- [ ] Test coverage is comprehensive
+- [ ] Test automation is in place
+- [ ] Test environment is ready
+- [ ] Test plan approved
+
+### Implementation Gate
+- [ ] All functionality implemented
+- [ ] All tests passing
+- [ ] Code review completed
+- [ ] Documentation complete
+- [ ] Performance validated
+
+## DOCUMENTATION REQUIREMENTS
+
+### Phase Documentation
+Each phase must produce:
+- Phase-specific deliverables
+- Decision rationale
+- Assumptions and constraints
+- Risks and mitigation strategies
+- Review and approval records
+
+### Code Documentation
+- Inline code comments for complex logic
+- API documentation
+- Configuration documentation
+- Deployment documentation
+- Troubleshooting guides
+
+### Process Documentation
+- Development setup instructions
+- Testing procedures
+- Deployment procedures
+- Maintenance procedures
+
+## REVIEW PROCESS
+
+### Design Reviews
+- Architecture review by senior developers
+- Security review by security team
+- Performance review by performance team
+- Stakeholder review for business alignment
+
+### Code Reviews
+- Peer review of all code changes
+- Security review for sensitive changes
+- Performance review for critical paths
+- Documentation review
+
+### Testing Reviews
+- Test plan review
+- Test case review
+- Test results review
+- Performance test review
+
+## BRANCH AND MERGE STRATEGY
+
+### Branch Naming
+- Feature branches: `feature/{issue-number}-{description}`
+- Hotfix branches: `hotfix/{issue-number}-{description}`
+- Release branches: `release/{version}`
+
+### Merge Requirements
+- All tests must pass
+- Code review approved
+- Documentation updated
+- No merge conflicts
+- Branch up to date with master
+
+### Merge Process
+1. Create pull request from feature branch
+2. Automated tests run
+3. Code review conducted
+4. Approval obtained
+5. Merge to master
+6. Deploy to staging
+7. Validation testing
+8. Deploy to production
+
+## CLEANUP PROCESS
+
+### End of Development
+When work is complete, clean up your environment:
+
+```bash
+# Navigate out of local clone
+cd ..
+
+# Remove your local clone folder
+rm -rf \"{PROJECT_NAME} - Issue {issue_number}\"
+```
+
+### Branch Cleanup
+- Delete feature branch after merge
+- Clean up local branches
+- Archive old release branches
+
+## CONTINUOUS IMPROVEMENT
+
+### Retrospectives
+- Conduct retrospectives after each major release
+- Document lessons learned
+- Update processes based on feedback
+- Share learnings across teams
+
+### Metrics Collection
+- Track development velocity
+- Monitor defect rates
+- Measure test coverage
+- Analyze performance metrics
+
+### Process Updates
+- Regular review of development processes
+- Update based on industry best practices
+- Incorporate team feedback
+- Align with organizational standards
+
+## COMPLIANCE AND GOVERNANCE
+
+### Code Standards
+- Follow established coding standards
+- Use automated code formatting
+- Enforce code quality metrics
+- Regular code quality audits
+
+### Security Requirements
+- Security code review for all changes
+- Vulnerability scanning
+- Dependency security checks
+- Security testing
+
+### Documentation Standards
+- Consistent documentation format
+- Regular documentation updates
+- Version control for documentation
+- Accessibility compliance
+
+Respect CODEOWNERS; don't modify auth/CI without approval.

package/.ai-agents/rules/spike-first-development.md

@@ -0,0 +1,199 @@
+# Spike-First Development Pattern
+
+## INTENT
+Prevent the "Build First, Integrate Later" anti-pattern that leads to wasted work, technical debt, and incomplete implementations. Ensure agents validate technology compatibility and requirements understanding before building complex solutions.
+
+## CORE PRINCIPLE
+**"Validate Early, Validate Often"** - Always prove that your approach works with the smallest possible test before building anything complex.
+
+## THE ANTI-PATTERN: "Build First, Integrate Later" ❌
+
+### What It Looks Like
+1. **Build Infrastructure First**: Create complex modular systems, frameworks, or architectures
+2. **Assume Technology Support**: Assume unfamiliar technologies will support your approach
+3. **Attempt Integration**: Discover incompatibilities or limitations late in the process
+4. **Panic Implementation**: Rush to salvage work, often missing original requirements
+
+### Why It's Dangerous
+- **Wasted Work**: Build incompatible solutions that must be thrown away
+- **Rushed Integration**: Leads to incomplete implementations and missed requirements  
+- **Technical Debt**: Creates bloat and confusion in the codebase
+- **False Progress**: Appears productive while actually going backwards
+- **Missed Requirements**: Focus on infrastructure instead of actual goals
+
+## THE CORRECT PATTERN: "Spike, Analyze, Implement Incrementally" ✅
+
+### 1. SPIKE/PROOF-OF-CONCEPT FIRST (5-15 minutes)
+**Goal**: Validate the basic technology works with minimal effort
+
+**Examples**:
+- Testing Jinja in BAML: Add `{% if true %}Hello{% endif %}` to a prompt
+- Testing API integration: Make one simple API call
+- Testing database connection: Execute one basic query
+- Testing new library: Import and call one function
+
+**Questions to Answer**:
+- Does the technology support what I need?
+- What are the syntax requirements?
+- What are the limitations?
+- Does it integrate with existing systems?
+
+### 2. ANALYZE DATA STRUCTURES (10-20 minutes)
+**Goal**: Understand what data is available for your implementation
+
+**Examples**:
+- Examine input/output classes and their fields
+- Review existing data flows and transformations
+- Identify what fields are available for conditional logic
+- Map data relationships and dependencies
+
+**Questions to Answer**:
+- What fields can I use for conditionals?
+- What data is available at runtime?
+- How does data flow through the system?
+- What are the data constraints?
+
+### 3. IDENTIFY OPPORTUNITIES (15-30 minutes)
+**Goal**: Map requirements to implementation opportunities
+
+**Examples**:
+- Identify large code sections that should be conditional
+- Find repetitive patterns that can be optimized
+- Locate areas where data-driven logic would help
+- Spot opportunities for code reduction or simplification
+
+**Questions to Answer**:
+- Where should conditional logic be applied?
+- What sections are candidates for optimization?
+- How can I reduce complexity or bloat?
+- What are the highest-impact changes?
+
+### 4. IMPLEMENT INCREMENTALLY (Variable time)
+**Goal**: Build one small piece at a time with continuous validation
+
+**Process**:
+- Add ONE conditional/feature at a time
+- Test after each change
+- Ensure existing functionality is preserved
+- Validate requirements are being met
+- Only proceed to next change after current one works
+
+**Examples**:
+- Add one `{% if %}` conditional, test, then add next
+- Implement one API endpoint, test, then add next
+- Add one database operation, test, then add next
+
+### 5. VALIDATE CONTINUOUSLY (Throughout)
+**Goal**: Ensure each step works before proceeding
+
+**Validation Steps**:
+- Run tests after each change
+- Verify compilation/generation works
+- Check that existing functionality is preserved
+- Confirm requirements are being addressed
+- Get feedback early and often
+
+## GOOD vs BAD EXAMPLES
+
+### ❌ BAD: Jinja Templating Implementation
+```
+1. Create 15 modular Jinja template files
+2. Build complex include system
+3. Assume BAML supports {% include %}
+4. Discover BAML doesn't support includes
+5. Panic and rush minimal implementation
+6. Miss obvious conditional opportunities
+7. Break existing functionality
+```
+
+### ✅ GOOD: Jinja Templating Implementation
+```
+1. SPIKE: Test {% if true %}Hello{% endif %} in BAML (5 min)
+2. ANALYZE: Examine UserIntent/UserInfo classes (10 min)
+3. IDENTIFY: Map prompt sections to conditional opportunities (15 min)
+4. IMPLEMENT: Add {% if user.role == "admin" %} around admin logic (20 min)
+5. VALIDATE: Run tests, ensure functionality preserved (10 min)
+6. REPEAT: Add next conditional incrementally
+```
+
+### ❌ BAD: API Integration
+```
+1. Build complex API client framework
+2. Create elaborate error handling system
+3. Design sophisticated caching layer
+4. Discover API has rate limits that break the design
+5. Rush to add rate limiting as afterthought
+6. End up with over-engineered, fragile system
+```
+
+### ✅ GOOD: API Integration
+```
+1. SPIKE: Make one simple API call (5 min)
+2. ANALYZE: Read API documentation for limits/constraints (15 min)
+3. IDENTIFY: Determine what endpoints are needed (10 min)
+4. IMPLEMENT: Add one endpoint call with basic error handling (30 min)
+5. VALIDATE: Test the call works reliably (10 min)
+6. REPEAT: Add next endpoint incrementally
+```
+
+### ❌ BAD: Database Schema Changes
+```
+1. Design complete new schema
+2. Write migration scripts for all tables
+3. Update all model classes
+4. Discover performance issues with new design
+5. Rush to add indexes and optimize queries
+6. Break existing functionality in multiple places
+```
+
+### ✅ GOOD: Database Schema Changes
+```
+1. SPIKE: Test schema change on one small table (10 min)
+2. ANALYZE: Review existing queries and performance (20 min)
+3. IDENTIFY: Plan migration strategy and rollback plan (15 min)
+4. IMPLEMENT: Change one table with migration (45 min)
+5. VALIDATE: Test performance and functionality (15 min)
+6. REPEAT: Migrate next table incrementally
+```
+
+## ENFORCEMENT RULES
+
+### MANDATORY SPIKE REQUIREMENTS
+- **Any unfamiliar technology**: Must spike basic functionality first
+- **Any complex integration**: Must test simplest case first
+- **Any architectural changes**: Must validate approach with minimal example
+- **Any new libraries/frameworks**: Must test basic usage first
+
+### VALIDATION CHECKPOINTS
+- After spike: Technology compatibility confirmed
+- After analysis: Data structures and constraints understood
+- After identification: Implementation plan is clear and achievable
+- After each increment: Functionality works and tests pass
+- Before completion: All requirements met and validated
+
+### RED FLAGS (Stop and Spike)
+- Building complex systems without testing basic functionality
+- Making assumptions about unfamiliar technology capabilities
+- Creating elaborate architectures before validating core concepts
+- Spending significant time on infrastructure before proving it works
+- Claiming progress without demonstrable working functionality
+
+## BENEFITS OF SPIKE-FIRST DEVELOPMENT
+
+1. **Reduced Risk**: Discover incompatibilities early when they're cheap to fix
+2. **Faster Delivery**: Avoid wasted work on incompatible approaches
+3. **Better Quality**: Continuous validation ensures functionality is preserved
+4. **Clearer Requirements**: Understanding constraints leads to better solutions
+5. **Increased Confidence**: Each step is validated before proceeding
+6. **Easier Debugging**: Problems are isolated to small, recent changes
+
+## SUMMARY
+
+The spike-first development pattern prevents catastrophic failures by ensuring agents:
+- Validate technology compatibility before building
+- Understand data structures and constraints upfront
+- Implement incrementally with continuous validation
+- Focus on requirements rather than infrastructure
+- Avoid the dangerous "Build First, Integrate Later" anti-pattern
+
+**Remember**: It's always faster to spike first than to rebuild later.