# LLM Front End UI Development Rules v0.01
This document contains structured guidance for an AI development assistant. To use effectively:

1. Submit this entire document to the LLM in sections if character limits are a concern
2. After sending the three foundational payloads (Workflow Requirements, Best Practices, and Technical Specifications), PAUSE
3. Do NOT request code or implementation until the LLM has acknowledged understanding these guidelines
4. Only after acknowledgment, provide the project-specific specifications
5. The LLM should NOT begin coding until explicitly directed to do so after all information exchange

# Developer Introduction (all projects):
This guide establishes the foundation for effective development collaboration. Before writing any code, developers should thoroughly understand the project requirements, specifications, and development approach. Successful projects begin with clarity and comprehensive planning rather than jumping directly into implementation.

## Managed Expectations:
Before learning about the specific project, you will receive three critical information payloads:

1. **Development Workflow Requirements** - The step-by-step process for development, documentation, and verification
2. **Development Best Practices** - Core principles for maintainable, high-quality code development
3. **Development Technical Specifications** - Universal technical guidelines for repository structure, data management, etc.

These represent strict guidelines that must be followed throughout the development process. After receiving each payload, do not proceed with implementation - simply acknowledge understanding and commitment to following these standards.

The final information you'll receive will be:

4. **Project Specifications** - Project-specific details including identity, features, frameworks, and design requirements

Only after receiving and acknowledging ALL information should you confirm readiness to begin the project. Do not start coding until explicitly instructed to do so.

# Development Workflow Requirements (all projects):
### Verification Requirements
When implementing each step of the workflow:
- NEVER mark any step as complete without providing verifiable evidence
- Proceed with code as pair programming usually would, but with you as the driver and navigator
- During your pair programming steps, I will be the observer and assistant and have the ultimate say
- Include specific command outputs, test results, or screenshots as proof
- For testing specifically, report actual test coverage percentages and results
- Document any challenges or limitations encountered during implementation
- If a step cannot be fully completed, document the blockers transparently
- Prioritize accuracy over claiming completion

### Step 1: Dependency Installation
Install all project dependencies with latest compatible versions. Resolve any errors without using --legacy-peer-deps or any other flags to force-circumvent compatibility issues. This step includes the fleshing out the necessary project files and directories while making use of best practices for the frameworks and libraries you are told to use. Document installation process in `context-for-llm/01-dependency-installation.md`. Initialize the git repo and commit all changes.

### Step 2: Project Structure Documentation
Ensure the file and directory structure is correct and architecture is sound for making use of the initial files and directories according to the frameworks and libraries you are told to use. Create `context-for-llm/02-project-structure.md` detailing project initialization, directory structure, and package selection. Document should enable complete project recreation. Commit all changes.

### Step 3: Linting Configuration
Configure and run linter across all files. Fix all TypeScript, ESLint, and any other linter or langauge engine errors or warnings. You will not stop until all are fixed. Summarize corrections in `context-for-llm/03-linting-corrections.md`. Commit all changes.

### Step 4: Testing Implementation
Develop and run all tests and ensure full coverage of components, functions, and state management. Add missing tests as needed as you make your way through the codebase. Also, create and maintain the CI workflow for GitHub as you proceed with fleshing out the tests. Make sure they're compatible and effectively able to run with GitHub Actions. Update README.md with test instructions. Document test results in `context-for-llm/04-test-summary.md`. Commit all changes.

### Step 5: Build Process
Execute build commands and resolve any errors or warnings. Simplify into npm scripts for various build scenarios. Remember, one of the goals could be to run the build on the server with a reverse proxy and SSL certificate, while another potential might be targeting Cloudflare Pages or GitHub Pages. Should any build issues or linter errors arise, be sure to fix them and containue to maintain our tests and CI workflow. Update README.md with build instructions. Document in greater detail in `context-for-llm/05-build-summary.md`. Commit all changes.

### Step 6: Deployment Setup
For testing and what might could become the final deployment, be sure to install nginx and set up a reverse proxy and SSL via certbot. Fix any deployment issues, while maintaining our tests and CI workflow. Update README.md with deployment instructions. Document process including firewall configuration in `context-for-llm/06-deployment-summary.md`. Commit all changes.

### Step 7: Future-Proofing
Update all packages to latest stable versions. Add future maintenance guidelines to README. Create `context-for-llm/07-future-updates.md` explaining future-proofing strategy in detail while summarizing the correct approach for future updates in the README.md file. Commit all changes.

### Step 8: Feature Extension Guide
Document process for adding new features, including linter/test/build updates with comprehensive guidance for extending the project in detail in `context-for-llm/08-additional-features.md`. Provide a summary of the correct approach for feature extension in the README.md file. Commit all changes.

# Development Best Practices:
When approaching this project, adhere to these foundational principles:

1. **Context Awareness**
- Always verify you're working on the correct project and branch
- Review the existing file structure before adding new files
- Understand the purpose and scope of each file you modify
- Consider how your changes affect the overall architecture
- Use `tree` command to visualize directory structure (install with `sudo apt install -y tree` if needed)
- Leverage code exploration tools like:
- `grep`/`ripgrep` for searching code patterns
- IDE symbol search features for function/component discovery
- Static analyzers for dependency graphs
- `npm list` or `yarn why` to understand package relationships
- TypeScript language server to explore type definitions
- ESLint output to understand code standards

2. **Code Organization**
- Follow established project patterns and conventions
- Group related functionality in appropriate directories
- Don't duplicate existing functionality or create parallel implementations
- Use descriptive, consistent naming that aligns with project conventions

3. **Quality Standards**
- Apply DRY (Don't Repeat Yourself) principles through reusable components and functions
- Write self-documenting code with appropriate comments for complex logic
- Implement proper error handling and edge case management
- Keep functions focused on single responsibilities

4. **Modification Safety**
- Make incremental changes that can be easily tested and reviewed
- Test your changes thoroughly before considering work complete
- Validate that your changes don't break existing functionality
- Prefer extending existing patterns rather than introducing new ones

5. **Uncertainty Management**
- When unsure about implementation approach, research project patterns first
- Reference existing code for guidance before introducing new patterns
- Document any assumptions made during implementation
- Ask specific questions rather than making uninformed decisions

6. **Environment Awareness**
- When running terminal commands, anticipate and handle prompts that require responses
- Don't pause workflows on obvious confirmations like "Ok to proceed? (y)"
- Practice safe command execution and NEVER run destructive commands like rm -rf /*
- Wait for full command completion (bash prompt $ or #) before proceeding
- Always activate appropriate virtual environments before running Python code
- For Python, use `source .venv/bin/activate` before executing tests or scripts

7. **Verification Standards**
- Never mark any step as complete without providing verifiable evidence
- Include specific command outputs, test results, or screenshots as proof
- For testing specifically, report actual test coverage percentages and results
- Document any challenges or limitations encountered during implementation
- If a step cannot be fully completed, document the blockers transparently
- Prioritize accuracy over claiming completion

# Development Technical Specifications (all projects):

## Repository Structure:
It is important to follow the repository structure below. The working directory has already been created and described above as the repository name. It should be used as the project root. When initializing the project:

1. DO NOT create another directory inside this folder
2. DO NOT run commands like `npx create-react-app new-directory-name` or `expo init new-directory-name`
3. DO use the current directory for all setup (e.g., `npx create-react-app .` or `expo init .`)
4. All files should be placed directly in the existing directory specified above which is the repository name.
5. This directory will be the Git repository root

## Data Management:
- Implement a centralized observable store with strict TypeScript interfaces
- Set data freshness parameters per data type to control update frequency
- Fetch data lazily as components require it, avoiding unnecessary loading
- Prune stale data when no longer observed while preserving navigation state
- Use framework-specific routing for seamless screen transitions with history support

## Styling:
- Minimalist, clean design with focus on readability
- Fully responsive layout with minimal inline styles
- Consistent component usage throughout the application
- Dark/light theme toggle that respects system settings initially
- Theme preference stored for persistence across sessions

PWA:
- Implement full Progressive Web App capabilities
- Include manifest.json, service worker, and web app icons
- Enable offline functionality and home screen installation

## Code Quality:
- Write concise, efficient code using TypeScript throughout
- Configure ESLint to enforce strict TypeScript standards
- Use latest stable package versions without dependency compromises
- Avoid flags like --legacy-peer-deps or --force when installing packages

## Testing:
- Comprehensive Jest tests for all functions, components, and state management
- Headless browser testing with Cypress for E2E validation
- GitHub workflow for CI integration with matching CLI and CI test capabilities
- Test coverage should scale with code additions

## Documentation & Deployment:
- Comprehensive README with complete setup and installation instructions
- Ubuntu server deployment guide with dependency installation steps
- Testing guide with expected results and CI verification steps
- Production deployment with nginx reverse proxy and SSL via certbot
- Include configuration templates and firewall setup instructions