rulespec_checklist.md

OElite Project Specification Bootstrap Checklist

Overview

This checklist provides a structured process for AI agents to bootstrap a new .spec folder documentation for OElite projects. The process is interactive and requires user confirmation before making changes to existing .spec folders.

Prerequisites

• Access to project repository
• Understanding of OElite coding standards
• Knowledge of project technology stack
• User confirmation for .spec folder operations

Phase 1: Project Assessment

1.1 Repository Analysis

• Identify project type (.NET, Angular, Next.js, etc.)
• Determine technology stack from existing code
• Check for existing .spec folder
• Review project structure and dependencies

1.2 Codebase Analysis and Business Understanding (Existing Projects Only)

For existing repositories with code:

• Perform comprehensive codebase analysis
• Identify project type, domain, and primary functionality
• Analyze existing features and capabilities
• Assess implementation completeness and maturity level
• Evaluate code quality, architecture patterns, and technical debt
• Infer potential business requirements from code functionality
• Generate business domain understanding and use case analysis

Business Requirements Inference:

• Map code functionality to potential business needs
• Identify user roles and workflows from implementation
• Assess feature completeness and gaps
• Determine scalability and performance requirements
• Analyze integration points and external dependencies

Implementation Assessment:

• Evaluate overall code quality and maintainability
• Assess testing coverage and quality assurance practices
• Identify technical architecture and design patterns
• Determine technology stack usage and maturity
• Analyze deployment and operational readiness

Interactive Understanding Validation:

• Present comprehensive analysis: "Based on my review of the codebase, this appears to be a [project type] for [business domain] with [key features]. Implementation is [completeness level] with [quality assessment]."
• Ask user: "Does this analysis align with your understanding? Please correct any misconceptions or provide additional context."
• Incorporate user feedback to refine understanding
• Proceed with corrected business and technical context

1.3 Code Quality and Standards Compliance Review (Existing Projects Only)

For existing repositories with code:

• Analyze codebase against OElite coding standards
• Check project structure compliance with recommended patterns
• Assess naming conventions and file organization
• Evaluate architecture alignment with OElite patterns
• Identify potential refactoring opportunities
• Generate compliance report with specific recommendations

Interactive Standards Assessment:

• Present findings: "I found X areas that don't align with OElite coding standards"
• Ask user: "Would you like to include a refactoring phase in the implementation plan to bring the code into compliance with OElite standards?"
• If yes: Add Phase 0 (Refactoring) to implementation plan
• If no: Proceed with current codebase as-is

1.3 Interactive User Confirmation

Repository Validation:

• Confirm repository path is correct and accessible
• Ask user to verify project name and basic details

Spec Folder Assessment:

• Check for existing .spec folder in the specified repository
• If exists: Ask user permission to update/create missing documents
• If doesn't exist: Ask user permission to create new .spec folder

Workflow Confirmation:

• Explain the interactive process: "I'll guide you through collecting information for 6 specification documents"
• If refactoring phase included: "Plus an initial refactoring phase to align with OElite standards"
• Ask user: "Would you like to proceed with the interactive specification creation?"
• Wait for user confirmation before starting information gathering

Phase 2: Information Gathering

2.1 Team Skills Assessment

• Ask user about team composition and experience levels
• Inquire about current technology proficiencies
• Identify any skill gaps or training needs
• Determine preferred development methodologies

2.2 Business Requirements Collection

• Ask user to provide business problem statement
• Request user stories or use cases
• Gather success metrics and KPIs
• Identify key stakeholders and constraints

2.3 Technical Requirements Gathering

• Ask about scalability requirements
• Determine integration needs
• Identify security and compliance requirements
• Gather performance and reliability expectations

Phase 3: Document Generation

3.1 Create .spec Folder Structure

.spec/
├── 0.0_skills.md                    # Team capabilities
├── 0.1_business_requirements.md     # Business requirements
├── 0.2_software_requirements.md     # Technical specifications
├── 0.3_project_data_schema.md       # Data architecture
├── 0.4_api_design.md               # API contracts
└── 0.5_project_implementation_plan.md # Implementation roadmap

3.2 Generate Documents Using Templates

• Use 0.0_team_tech_stack_template.md to create 0.0_skills.md
• Use 0.1_business_requirement_template.md to create 0.1_business_requirements.md
• Use 0.2_software_requirement_template.md to create 0.2_software_requirements.md
• Use 0.3_project_data_schema_template.md to create 0.3_project_data_schema.md
• Use 0.4_api_design_template.md to create 0.4_api_design.md
• Use 0.5_project_implementation_plan_template.md to create 0.5_project_implementation_plan.md

3.3 Populate with Collected Information

• Fill templates with gathered business requirements
• Include team skills assessment data
• Add technical specifications based on project analysis
• Incorporate architectural decisions
• Define implementation phases and tasks

Phase 4: Validation and Review

4.1 Cross-Document Consistency Check

• Verify business requirements align with technical specs
• Ensure data schema supports API design
• Confirm team skills match technology choices
• Validate implementation plan feasibility

4.2 User Review and Approval

• Present generated documents to user for review
• Ask for feedback and required modifications
• Incorporate user changes and suggestions
• Get final approval before committing documents

Phase 5: Documentation Maintenance

5.1 Version Control Integration

• Commit documents to repository
• Add appropriate commit messages
• Create initial tags if needed
• Set up documentation update workflows

5.2 Continuous Updates

• Establish process for keeping documents current
• Define triggers for document updates
• Set up review cycles for specification documents
• Create templates for change requests

Error Handling and Rollback

Recovery Procedures

• Document backup strategy for existing .spec folders
• Provide rollback commands for failed operations
• Include cleanup procedures for partial completions
• Define recovery steps for interrupted processes

User Communication

• Clear error messages for failed operations
• Progress indicators during document generation
• Confirmation prompts before destructive operations
• Success notifications with next steps

Quality Assurance

Document Validation

• Schema validation for generated documents
• Cross-reference checking between documents
• Completeness verification against templates
• Consistency checking for terminology and formatting

Process Validation

• Verify all user interactions were completed
• Confirm all required information was collected
• Validate document generation followed templates
• Ensure proper file permissions and repository integration

Integration with Development Workflow

CI/CD Integration

• Automated validation of .spec documents
• Documentation completeness checks
• Cross-reference validation in pipelines
• Automated updates for template changes

Development Process Integration

• Reference documents in pull request templates
• Include specification checks in code reviews
• Link implementation to specification requirements
• Track specification compliance in project management

---

Quick Reference for AI Agents

Natural Language Triggers

• "as specPlanner, please create specs for our new project [NAME] (repo at [PATH])"
• "specPlanner create specs for [PROJECT]"
• "update specs for [PROJECT]"

Interactive Workflow Sequence for New Projects

1. parse_natural_language_prompt() - Extract project name and repo path
2. validate_repository_access() - Confirm repo exists and is accessible
3. analyze_project_structure() - Determine tech stack and project type
4. analyze_codebase_business_domain() - Understand business domain and existing implementation
5. infer_business_requirements() - Generate potential business requirements from code analysis
6. present_business_understanding() - Show analysis and get user validation/correction
7. review_code_standards_compliance() - Analyze codebase against OElite standards
8. assess_refactoring_needs() - Present findings and ask about refactoring phase
9. check_existing_spec_folder() - Assess current .spec folder state
10. request_user_permission() - Get approval for .spec folder operations
11. gather_team_skills_interactive() - Collect team capabilities using 0.0 template
12. collect_business_requirements_interactive() - Gather objectives using 0.1 template (enhanced with code analysis)
13. gather_technical_requirements_interactive() - Collect architecture details using 0.2 template
14. design_data_schema_interactive() - Define data structures using 0.3 template
15. design_api_contracts_interactive() - Specify APIs using 0.4 template
16. plan_implementation_interactive() - Create roadmap using 0.5 template (includes Phase 0 if needed)
17. generate_documents_from_templates() - Populate all templates with collected data
18. validate_cross_references() - Ensure document consistency
19. present_for_user_review() - Show generated documents for approval
20. commit_to_repository() - Save specifications to repo

Interactive Workflow Sequence for Existing Projects

1. parse_natural_language_prompt() - Extract project name and repo path
2. validate_repository_access() - Confirm repo exists and is accessible
3. analyze_codebase_business_domain() - Understand business domain and existing implementation
4. infer_business_requirements() - Generate potential business requirements from code analysis
5. present_business_understanding() - Show analysis and get user validation/correction
6. review_code_standards_compliance() - Analyze codebase against OElite standards
7. assess_refactoring_needs() - Present findings and ask about refactoring phase
8. check_existing_spec_folder() - Locate and assess current .spec folder
9. request_update_permission() - Get approval for updates
10. assess_missing_documents() - Identify gaps in current specifications
11. gather_update_information_interactive() - Collect missing or updated information (enhanced with code analysis)
12. update_existing_documents() - Modify current specs with new data
13. generate_missing_documents() - Create any missing specification documents
14. validate_updated_references() - Ensure all cross-references are current
15. present_changes_for_review() - Show modifications for user approval
16. commit_updates_to_repository() - Save updated specifications

Error Recovery

• Permission Denied: Ask user to grant necessary permissions
• Template Missing: Report missing templates and request fixes
• Validation Failed: Show specific validation errors and request corrections
• User Cancelled: Clean up any partial changes and exit gracefully

This checklist ensures consistent, high-quality specification document generation while maintaining user control and system integrity.