recreate-fob 1.0.0 → 2.0.0

package/.codex/commands/FOB/experts/codebase/self-improve.md

@@ -0,0 +1,191 @@
+---
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write, TodoWrite
+description: Self-improve Codebase expertise by validating against codebase implementation
+argument-hint: [check_git_diff (true/false)] [focus_area (optional)]
+---
+
+# Purpose
+
+You maintain the Codebase expert system's expertise accuracy by comparing the existing expertise file against the actual codebase implementation. Follow the `Workflow` section to detect and remedy any differences, missing pieces, or outdated information, ensuring the expertise file remains a powerful **mental model** and accurate memory reference for codebase-related tasks.
+
+## Variables
+
+CHECK_GIT_DIFF: $1 default to false if not specified
+FOCUS_AREA: $2 default to empty string
+EXPERTISE_FILE: .claude/commands/experts/codebase/expertise.yaml
+MAX_LINES: 1000
+
+## Instructions
+
+- This is a self-improvement workflow to keep Codebase expertise synchronized with the actual codebase
+- Think of the expertise file as your **mental model** and memory reference for all codebase-related functionality
+- Always validate expertise against real implementation, not assumptions
+- Focus exclusively on Codebase-related functionality (File structures, frontend current state, backend current state, authentication patterns, database schema overview, etc.)  
+- If FOCUS_AREA is provided, prioritize validation and updates for that specific area
+- Maintain the YAML structure of the expertise file
+- Enforce strict line limit of 1000 lines maximum
+- Prioritize actionable, high-value expertise over verbose documentation
+- When trimming, remove least critical information that won't impact expert performance
+- Git diff checking is optional and controlled by the CHECK_GIT_DIFF variable
+- Be thorough in validation but concise in documentation
+- Don't include 'summaries' of work done in your expertise when a git diff is checked. Focus on true, important information that pertains to the key codebase functionality and implementation.
+- Write as a principle engineer that writes CLEARLY and CONCISELY for future engineers so they can easily understand how to read and update functionality surrounding the codebase implementation.
+- Keep in mind, after your thorough search, there may be nothing to be done - this is perfectly acceptable. If there's nothing to be done, report that and stop.
+
+## Workflow
+
+1. **Check Git Diff (Conditional)**
+   - If CHECK_GIT_DIFF is "true", run `git diff` to identify recent changes to Codebase-related files
+   - If changes detected, note them for targeted validation in step 3
+   - If CHECK_GIT_DIFF is "false", skip this step
+
+2. **Read Current Expertise**
+   - Read the entire EXPERTISE_FILE to understand current documented expertise
+   - Identify key sections: overview, frontend_current_state, backend_current_state, auth_current_state, database_schema_overview, etc.
+   - Note any areas that seem outdated or incomplete
+
+3. **Validate Against Codebase**
+   - Read the EXPERTISE_FILE to identify which files are documented as key implementation files
+   - Read those files to understand current implementation:
+   - Compare documented expertise against actual code:
+     - Existing frontend structure and pages
+     - Existing backend structure and endpoints
+     - Authentication patterns and methods
+     - Database schema overview (list of tables and their general purpose)
+   - If FOCUS_AREA is provided, prioritize validation of that specific area
+   - If git diff was checked in step 1, pay special attention to changed areas
+
+4. **Identify Discrepancies**
+   - List all differences found:
+     - Missing files or features
+     - Outdated route endpoints or file paths
+     - Changed implementation details
+     - New features/files not documented
+     - Removed features/files still documented
+
+5. **Update Expertise File**
+   - Remedy all identified discrepancies by updating EXPERTISE_FILE
+   - Add missing information
+   - Update outdated information
+   - Remove obsolete information
+   - Maintain YAML structure and formatting
+   - Ensure all file paths and line numbers are accurate
+   - Keep descriptions concise and actionable
+
+6. **Enforce Line Limit**
+   - Run: `wc -l .claude/commands/experts/codebase/expertise.yaml`
+   - Check if line count exceeds MAX_LINES (1000)
+   - If line count > MAX_LINES:
+     - Identify least important expertise sections that won't impact expert performance:
+       - Overly verbose descriptions
+       - Redundant examples
+       - Low-priority edge cases
+     - Trim identified sections
+     - Run line count check again
+     - REPEAT this sub-workflow until line count ≤ MAX_LINES
+   - Document what was trimmed in the report
+
+7. **Validation Check**
+   - Read the updated EXPERTISE_FILE
+   - Verify all critical Database information is present
+   - Ensure line count is within limit
+   - Validate YAML syntax by compiling the file:
+     - Run: `python3 -c "import yaml; yaml.safe_load(open('EXPERTISE_FILE'))"`
+     - Replace EXPERTISE_FILE with the actual path from the variable
+     - Confirm no syntax errors are raised
+     - If errors occur, fix the YAML structure and re-validate
+
+## Report
+
+Provide a structured report with the following sections:
+
+### Summary
+- Brief overview of self-improvement execution
+- Whether git diff was checked
+- Focus area (if any)
+- Total discrepancies found and remedied
+- Final line count vs MAX_LINES
+
+### Discrepancies Found
+- List each discrepancy identified:
+  - What was incorrect/missing/outdated
+  - Where in the codebase the correct information was found
+  - How it was remedied
+
+### Updates Made
+- Concise list of all updates to EXPERTISE_FILE:
+  - Added sections/information
+  - Updated sections/information
+  - Removed sections/information
+
+### Line Limit Enforcement
+- Initial line count
+- Final line count
+- If trimming was needed:
+  - Number of trimming iterations
+  - What was trimmed and why
+  - Confirmation that trimming didn't impact critical expertise
+
+### Validation Results
+- Confirm all critical Codebase expertise is present
+- Confirm line count is within limit
+- Note any areas that may need future attention
+
+### Codebase References
+- List of files validated against with line numbers where relevant
+- Key methods and functions verified
+
+**Example Report Format:**
+
+```
+✅ Self-Improvement Complete
+
+Summary:
+- Git diff checked: Yes
+- Focus area: backend_current_state
+- Discrepancies found: 3
+- Discrepancies remedied: 3
+- Final line count: 520/1000 lines
+
+Discrepancies Found:
+1. Missing endpoint: 'edit_image' not documented
+   - Found in: backend/app/api/routes/images.py
+   - Remedied: Added to backend_current_state section
+
+2. Outdated endpoint: 'get_image' documented
+   - Found in: backend/app/api/routes/images.py
+   - Remedied: Updated to 'get_image_by_id'
+
+3. New feature: 'delete_image' not documented
+   - Found in: backend/app/api/routes/images.py
+   - Remedied: Added to backend_current_state section
+
+Updates Made:
+- Added: edit_image endpoint to backend_current_state section
+- Updated: get_image endpoint to get_image_by_id in backend_current_state section
+- Added: delete_image endpoint to backend_current_state section
+
+Line Limit Enforcement:
+- Initial: 520 lines
+- Required trimming: No
+- Final: 520 lines ✓
+
+Validation Results:
+✓ All 6 backend endpoints and features documented 
+✓ All 6 frontend pages and features documented
+✓ Core Database schema present
+✓ Core Authentication patterns present
+✓ YAML syntax valid (compiled successfully)
+
+Codebase References:
+- backend/app/api/routes/images.py:1-150 (validated)
+- frontend/src/pages/ImageGallery.tsx:1-496 (validated)
+- backend/app/core/auth.py:1-150 (validated)
+- backend/app/models/image.py:1-496 (validated)
+- backend/app/schemas/image.py:1-150 (validated)
+- backend/app/services/image.py:1-496 (validated)
+- backend/app/tests/test_images.py:1-150 (validated)
+- backend/app/tests/test_auth.py:1-496 (validated)
+- backend/app/tests/test_schemas.py:1-150 (validated)
+- backend/app/tests/test_services.py:1-496 (validated)
+```

package/.codex/commands/FOB/init_project.md

@@ -0,0 +1,135 @@
+---
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TodoWrite
+description: Initialize a project based on a spec file with frontend/backend structure, Docker, and shell scripts
+argument-hint: [SPEC_FILE_PATH]
+model: opus
+---
+
+# init_project
+
+Initializes a new project based on requirements defined of the `SPEC_FILE_PATH`. Create a full project structure including frontend and backend apps, Docker configuration, and shell scripts for development workflows. Follow the `Workflow` section to complete the initialization and the `Validation` section to verify everything works correctly. Create the necessary files and directory for each module where appropriate eg frontend, backend, etc. and leave empty where not needed eg. no typechecking required for convex.
+
+## Variables
+
+SPEC_FILE_PATH: $1
+PROJECT_STRUCTURE: |
+  .claude
+      agents
+      commands
+      hooks
+      skills
+  .codex
+      prompts
+  ai_docs
+  PROJECT_NAME_apps
+      *name_of_frontend*frontend
+          .env.sample (for the frontend)
+          Dockerfile
+      *name_of_backend*
+          .env.sample (for the backend)
+          Dockerfile
+  scripts
+  Docker-compose.yml
+  specs
+  .env.sample (for the ai engineering layer)
+  README.md
+
+## Workflow
+
+### Setup the project structure
+1. Read the spec file at `SPEC_FILE_PATH` to understand project requirements and extract the PROJECT_NAME
+2. Create the directory structure based on `PROJECT_STRUCTURE`, replacing PROJECT_NAME with the actual project name from the spec
+3. Initialize the frontend app:
+   - Set up the frontend application in the `PROJECT_NAME_apps/frontend` directory
+   - Install necessary dependencies
+   - Create `.env.sample` with required environment variables
+   - Build 2 placeholder pages
+4. Initialize the backend app:
+   - Set up the backend application in the `PROJECT_NAME_apps/backend` directory
+   - Install necessary dependencies
+   - Create `.env.sample` with required environment variables
+   - Build 1 placeholder endpoint
+5. Create Dockerfiles:
+   - Create `PROJECT_NAME_apps/frontend/Dockerfile` for the frontend app
+   - Create `PROJECT_NAME_apps/backend/Dockerfile` for the backend app
+6. Create Docker Compose:
+   - Create `PROJECT_NAME_apps/docker-compose.yml` to orchestrate frontend and backend containers
+7. Create shell scripts in the `scripts` directory:
+   - `run_backend.sh` - Run the backend in local development mode
+   - `run_frontend.sh` - Run the frontend in local development mode
+   - `run_all.sh` - Run both frontend and backend together in local development mode
+   - `run_tests.sh` - Run the test suite
+   - `run_lint.sh` - Run linting and type checking
+   - `run_frontend_docker.sh` - Run the frontend Docker container
+   - `run_backend_docker.sh` - Run the backend Docker container
+   - `run_all_docker.sh` - Run both frontend and backend Docker containers together
+8. Create a brief README.md in the root directory with only the essential information about the project:
+   - Project name and overview
+   - Guide to setting up and installing the project 
+   - Instruction to copy the .env.sample files to the .env files and fill in the necessary   information (cp .env.sample .env)
+   - Instructions on how to run the project in development mode 
+   - Instructions on how to run the project in Docker mode 
+9. Create a specific "README.md" file in the `ai_docs` directory with the following information:
+```md
+# AI Docs
+
+>Resources to use while working on the project
+<list of URLs of the documentation for the chosen technologies and frameworks>
+```
+
+### Validation
+
+Execute each validation step sequentially. If any step fails, fix the issue before proceeding to the next step. IMPORTANT: Make sure to use the SCRIPTS/COMMANDS created in the previous step to test the project. DO NOT TEST THE PROJECT MANUALLY with "bun run" or "uv run" commands. 
+
+1. Test backend locally:
+   - Run `scripts/run_backend.sh`
+   - Verify the backend starts successfully and the placeholder endpoint responds
+   - If the script fails, fix the issue and run the script again until it succeeds.
+   - Stop the backend process
+2. Test frontend locally:
+   - Run `scripts/run_frontend.sh`
+   - Verify the frontend starts successfully and placeholder pages are accessible
+   - If the script fails, fix the issue and run the script again until it succeeds.
+   - Stop the frontend process
+3. Test combined local development:
+   - Run `scripts/run_all.sh`
+   - Verify both frontend and backend are running and communicating
+   - Use the chrome-devtools mcp tool to view the frontend in the browser
+   - If the script fails, fix the issue and run the script again until it succeeds.
+   - Stop both processes
+4. Test the test suite:
+   - Run `scripts/run_tests.sh`
+   - Verify all tests pass
+   - If the script fails, fix the issue and run the script again until it succeeds.
+5. Test linting and type checking:
+   - Run `scripts/run_lint.sh`
+   - Verify no linting or type errors
+   - If the script fails, fix the issue and run the script again until it succeeds.
+6. Test individual Docker containers:
+   - Run `scripts/run_frontend_docker.sh`
+   - Verify the frontend container starts and serves content
+   - If the script fails, fix the issue and run the script again until it succeeds.
+   - Stop the frontend container
+   - Run `scripts/run_backend_docker.sh`
+   - Verify the backend container starts and the endpoint responds
+   - If the script fails, fix the issue and run the script again until it succeeds.
+   - Stop the backend container
+7. Test combined Docker containers:
+   - Run `scripts/run_all_docker.sh`
+   - Verify both containers are running and communicating
+   - Use the chrome-devtools mcp tool to view the frontend in the browser
+   - If the script fails, fix the issue and run the script again until it succeeds.
+   - Stop both containers
+
+## Report
+
+After completing the workflow and validation, provide a summary that includes:
+
+- Project name and structure created
+- Frontend setup details (framework, dependencies, placeholder pages)
+- Backend setup details (framework, dependencies, placeholder endpoint)
+- Docker configuration summary
+- Shell scripts created and their purposes
+- Validation results for each test step (pass/fail)
+- Any issues encountered and how they were resolved
+- Instructions for the user to get started with the project

package/.codex/commands/FOB/iterate_spec.md

@@ -0,0 +1,59 @@
+---
+allowed-tools: AskUserQuestion, Read, Edit, Glob
+description: Iterate on the initial codebase specification through guided questions
+argument-hint: [CHANGE_REQUEST]
+model: opus
+---
+
+# Iterate Spec
+
+Guide the user through refining their `specs/initial-codebase-spec.md` based on the change request provided in `CHANGE_REQUEST`. Follow the `Workflow` to understand the current spec, clarify the requested changes, and apply updates. Reference the `Instructions` section for behavioral guidelines.
+
+## Variables
+
+CHANGE_REQUEST: $ARGUMENTS
+SPEC_PATH: `specs/initial-codebase-spec.md`
+
+## Instructions
+
+- Read and understand the current specification before proposing any changes
+- Use `AskUserQuestion` tool to clarify ambiguous change requests
+- Present the impact of proposed changes before applying them
+- Preserve sections of the spec that are not affected by the change request
+- Offer sensible defaults when the user is unsure about implementation details
+- Summarize each change after it's made before moving to the next
+- If a change affects multiple sections (e.g., adding a feature affects Tech Stack, Schema, and API Endpoints), identify all affected sections upfront
+- Maintain consistency with existing patterns in the spec (naming conventions, formatting, structure)
+- Give the user an option to ask for your recommendation if they are unsure about choices
+- If the `CHANGE_REQUEST` is empty or unclear, ask the user what aspect of the spec they want to modify
+
+## Workflow
+
+1. Read the current specification at `SPEC_PATH` to understand the existing project structure
+2. Analyze the `CHANGE_REQUEST` to determine which sections of the spec will be affected:
+   - Project Summary (name, purpose, users, personas)
+   - Core Features
+   - Tech Stack
+   - Documentation links
+   - Codebase Structure
+   - Database Schema
+   - API Endpoints
+   - Environment Variables
+3. If the `CHANGE_REQUEST` is ambiguous or spans multiple areas, use `AskUserQuestion` to clarify:
+   - What specific aspect they want to change
+   - The scope of the change (additive, replacement, or removal)
+   - Any constraints or preferences they have
+4. Present a summary of the proposed changes and which sections will be modified
+5. Use `AskUserQuestion` to confirm the user wants to proceed with the changes
+6. Create a new spec file in the `specs/` directory with the changes named `initial-codebase-spec-<change-number>.md`
+7. If additional changes are discovered during implementation, ask the user before making them
+8. After all changes are applied, summarize what was modified
+
+## Report
+
+After completing the workflow, respond to the user with:
+
+- A summary of all changes made to the specification
+- List of sections that were modified
+- Any follow-up considerations (e.g., "You may also want to update X if you plan to Y")
+- Confirmation that the spec has been saved

package/.codex/commands/FOB/plan_project.md

@@ -0,0 +1,142 @@
+---
+allowed-tools: AskUserQuestion, Write, Read, Bash
+description: Interactive prompt to gather project requirements and generate an initial codebase specification
+argument-hint: [USER_PROMPT]
+model: opus
+---
+
+# Plan Project
+
+Generate a `specs/initial-codebase-spec.md` file based on the user's prompt. Follow the `Workflow` in order to gather user input through structured questions and produce a complete specification document. Reference the `Instructions` section for behavioral guidelines.
+
+## Variables
+
+USER_PROMPT: $1
+PLAN_OUTPUT_DIRECTORY: `specs/`
+
+## Instructions 
+
+- Help the user plan out the project based on the `USER_PROMPT`
+- Use `AskUserQuestion` tool at each decision point to gather input
+- Present sensible defaults where appropriate (e.g., Bun for JS, UV for Python)
+- Allow the user to skip sections if they want to accept defaults
+- Summarize decisions after each major section before moving on
+- Keep the conversation focused and efficient
+- If the user provides partial information, ask clarifying follow-ups
+- Maintain a professional, collaborative tone throughout
+- Give the user an option to ask you for input on the descisions if they are unsure about the choices
+
+## Workflow 
+
+- First, welcome the user and explain that you'll be gathering requirements to create an initial codebase specification
+- Then, gather the project summary:
+  - Ask for the project name and purpose (what problem does it solve?)
+  - Ask about target users and user personas
+  - Ask for 3-5 core features the project must have
+  - Summarize project summary decisions and confirm before proceeding
+- Then, gather the tech stack decisions:
+  - Frontend: Ask about framework preference (React, NEXT.js, Vue, Svelte, etc.) - note that Bun will be used as the package manager for JS frameworks
+  - Backend: Ask about framework preference (FastAPI, Django, Express, Fastify,etc.) - note that UV will be used for Python projects
+  - Database: Ask about database type (PostgreSQL, MySQL, SQLite, MongoDB) and ORM/query layer preference
+  - Auth: Ask about authentication solution (Clerk, Auth0, Supabase Auth, custom)
+  - Hosting: Ask about hosting solution (Vercel, Railway, Render, Supabase, custom)
+  - CI/CD: Ask about CI/CD solution (GitHub Actions, GitLab CI, CircleCI, custom)
+  - Ask about any specific AI Agents or tools that the user wants to use
+  - Summarize tech stack decisions and confirm before proceeding
+- Then, spin up a subagent to use webfetch to find the documentation for the chosen technologies and frameworks.
+  - The subagent should return a list of URLs of the documentation for the chosen technologies and frameworks.
+- Then generate the `specs/initial-codebase-spec.md` 
+  - First check to see if the `specs/` directory exists. If it does not, create it.
+  - Then create the `initial-codebase-spec.md` file in the `specs/` directory in the `Output Format`
+
+## Output Format
+
+```md
+# <PROJECT_NAME> - Project Specification
+
+## Project Summary
+
+<PROJECT_NAME>
+<PROJECT_PURPOSE>
+<PROJECT_TARGET_USERS>
+<PROJECT_USER_PERSONAS>
+
+## Core Features (V0)
+
+<List of Core Features (V0)>
+
+## Tech Stack
+
+<Frontend Technology>
+<Backend Technology>
+<Database Technology>
+<Auth Technology>
+<Hosting Technology>
+<CI/CD Technology>
+<AI Agents or Tools>
+
+## Documentation
+
+<Frontend Documentation (list of URLs)>
+<Backend Documentation (list of URLs)>
+<Database Documentation (list of URLs)>
+<Auth Documentation (list of URLs)>
+<Hosting Documentation (list of URLs)>
+<CI/CD Documentation (list of URLs)>
+<AI Agents or Tools Documentation (list of URLs)>
+
+## Codebase Structure
+
+
+PROJECT_STRUCTURE: |
+├── .claude/
+│   ├── agents/
+│   ├── commands/
+│   ├── hooks/
+│   └── skills/
+├── .codex/
+│   └── prompts/
+├── .github/
+│   └── workflows/
+│       ├── ci.yml
+│       └── deploy.yml
+├── ai_docs/
+├── PROJECT_NAME_apps/
+│   ├── frontend/
+│   │   ├── .env.sample (for the frontend)
+│   │   └─── Dockerfile
+│   └── backend/
+│       ├── .env.sample (for the backend)
+│       └── Dockerfile
+├── scripts/
+├── specs/
+├── .env.sample (for the ai engineering layer)
+├── docker-compose.yml
+└── README.md
+
+
+## Database Schema
+
+<suggested DATABASE_SCHEMA>
+
+## API Endpoints
+
+<suggested API_ENDPOINTS>
+
+## Environment Variables
+
+<FRONTEND_ENV_VARIABLES>
+<BACKEND_ENV_VARIABLES>
+
+```
+
+## Report
+
+After completing the workflow, respond to the user with:
+
+- Confirmation that the specification has been saved to `/specs/initial-codebase-spec.md`
+- A brief summary of the key decisions made:
+  - Project name and purpose
+  - Core features count
+  - Tech stack overview (frontend, backend, database, auth)
+- Guidance on next steps: suggest reviewing the spec and using it to scaffold the project