conductor(setup): Add conductor setup files

2026-04-05 04:24:38 +00:00 · 2026-02-13 14:31:21 -08:00
parent fe06c40a29
commit 9574994abb
14 changed files with 450 additions and 0 deletions
--- a/conductor/code_styleguides/html-css.md
+++ b/conductor/code_styleguides/html-css.md
@@ -0,0 +1,49 @@
 # Google HTML/CSS Style Guide Summary
 This document summarizes key rules and best practices from the Google HTML/CSS Style Guide.
 ## 1. General Rules
 - **Protocol:** Use HTTPS for all embedded resources.
 - **Indentation:** Indent by 2 spaces. Do not use tabs.
 - **Capitalization:** Use only lowercase for all code (element names, attributes, selectors, properties).
 - **Trailing Whitespace:** Remove all trailing whitespace.
 - **Encoding:** Use UTF-8 (without a BOM). Specify `<meta charset="utf-8">` in HTML.
 ## 2. HTML Style Rules
 - **Document Type:** Use `<!doctype html>`.
 - **HTML Validity:** Use valid HTML.
 - **Semantics:** Use HTML elements according to their intended purpose (e.g., use `<p>` for paragraphs, not for spacing).
 - **Multimedia Fallback:** Provide `alt` text for images and transcripts/captions for audio/video.
 - **Separation of Concerns:** Strictly separate structure (HTML), presentation (CSS), and behavior (JavaScript). Link to CSS and JS from external files.
 - **`type` Attributes:** Omit `type` attributes for stylesheets (`<link>`) and scripts (`<script>`).
 ## 3. HTML Formatting Rules
 - **General:** Use a new line for every block, list, or table element, and indent its children.
 - **Quotation Marks:** Use double quotation marks (`""`) for attribute values.
 ## 4. CSS Style Rules
 - **CSS Validity:** Use valid CSS.
 - **Class Naming:** Use meaningful, generic names. Separate words with a hyphen (`-`).
  - **Good:** `.video-player`, `.site-navigation`
  - **Bad:** `.vid`, `.red-text`
 - **ID Selectors:** Avoid using ID selectors for styling. Prefer class selectors.
 - **Shorthand Properties:** Use shorthand properties where possible (e.g., `padding`, `font`).
 - **`0` and Units:** Omit units for `0` values (e.g., `margin: 0;`).
 - **Leading `0`s:** Always include leading `0`s for decimal values (e.g., `font-size: 0.8em;`).
 - **Hexadecimal Notation:** Use 3-character hex notation where possible (e.g., `#fff`).
 - **`!important`:** Avoid using `!important`.
 ## 5. CSS Formatting Rules
 - **Declaration Order:** Alphabetize declarations within a rule.
 - **Indentation:** Indent all block content.
 - **Semicolons:** Use a semicolon after every declaration.
 - **Spacing:**
  - Use a space after a property name's colon (`font-weight: bold;`).
  - Use a space between the last selector and the opening brace (`.foo {`).
  - Start a new line for each selector and declaration.
 - **Rule Separation:** Separate rules with a new line.
 - **Quotation Marks:** Use single quotes (`''`) for attribute selectors and property values (e.g., `[type='text']`).
 **BE CONSISTENT.** When editing code, match the existing style.
 *Source: [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)*
--- a/conductor/code_styleguides/javascript.md
+++ b/conductor/code_styleguides/javascript.md
@@ -0,0 +1,51 @@
 # Google JavaScript Style Guide Summary
 This document summarizes key rules and best practices from the Google JavaScript Style Guide.
 ## 1. Source File Basics
 - **File Naming:** All lowercase, with underscores (`_`) or dashes (`-`). Extension must be `.js`.
 - **File Encoding:** UTF-8.
 - **Whitespace:** Use only ASCII horizontal spaces (0x20). Tabs are forbidden for indentation.
 ## 2. Source File Structure
 - New files should be ES modules (`import`/`export`).
 - **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.**
 - **Imports:** Do not use line-wrapped imports. The `.js` extension in import paths is mandatory.
 ## 3. Formatting
 - **Braces:** Required for all control structures (`if`, `for`, `while`, etc.), even single-line blocks. Use K&R style ("Egyptian brackets").
 - **Indentation:** +2 spaces for each new block.
 - **Semicolons:** Every statement must be terminated with a semicolon.
 - **Column Limit:** 80 characters.
 - **Line-wrapping:** Indent continuation lines at least +4 spaces.
 - **Whitespace:** Use single blank lines between methods. No trailing whitespace.
 ## 4. Language Features
 - **Variable Declarations:** Use `const` by default, `let` if reassignment is needed. **`var` is forbidden.**
 - **Array Literals:** Use trailing commas. Do not use the `Array` constructor.
 - **Object Literals:** Use trailing commas and shorthand properties. Do not use the `Object` constructor.
 - **Classes:** Do not use JavaScript getter/setter properties (`get name()`). Provide ordinary methods instead.
 - **Functions:** Prefer arrow functions for nested functions to preserve `this` context.
 - **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for multi-line strings or complex interpolation.
 - **Control Structures:** Prefer `for-of` loops. `for-in` loops should only be used on dict-style objects.
 - **`this`:** Only use `this` in class constructors, methods, or in arrow functions defined within them.
 - **Equality Checks:** Always use identity operators (`===` / `!==`).
 ## 5. Disallowed Features
 - `with` keyword.
 - `eval()` or `Function(...string)`.
 - Automatic Semicolon Insertion.
 - Modifying builtin objects (`Array.prototype.foo = ...`).
 ## 6. Naming
 - **Classes:** `UpperCamelCase`.
 - **Methods & Functions:** `lowerCamelCase`.
 - **Constants:** `CONSTANT_CASE` (all uppercase with underscores).
 - **Non-constant Fields & Variables:** `lowerCamelCase`.
 ## 7. JSDoc
 - JSDoc is used on all classes, fields, and methods.
 - Use `@param`, `@return`, `@override`, `@deprecated`.
 - Type annotations are enclosed in braces (e.g., `/** @param {string} userName */`).
 *Source: [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)*
--- a/conductor/code_styleguides/python.md
+++ b/conductor/code_styleguides/python.md
@@ -0,0 +1,37 @@
 # Google Python Style Guide Summary
 This document summarizes key rules and best practices from the Google Python Style Guide.
 ## 1. Python Language Rules
 - **Linting:** Run `pylint` on your code to catch bugs and style issues.
 - **Imports:** Use `import x` for packages/modules. Use `from x import y` only when `y` is a submodule.
 - **Exceptions:** Use built-in exception classes. Do not use bare `except:` clauses.
 - **Global State:** Avoid mutable global state. Module-level constants are okay and should be `ALL_CAPS_WITH_UNDERSCORES`.
 - **Comprehensions:** Use for simple cases. Avoid for complex logic where a full loop is more readable.
 - **Default Argument Values:** Do not use mutable objects (like `[]` or `{}`) as default values.
 - **True/False Evaluations:** Use implicit false (e.g., `if not my_list:`). Use `if foo is None:` to check for `None`.
 - **Type Annotations:** Strongly encouraged for all public APIs.
 ## 2. Python Style Rules
 - **Line Length:** Maximum 80 characters.
 - **Indentation:** 4 spaces per indentation level. Never use tabs.
 - **Blank Lines:** Two blank lines between top-level definitions (classes, functions). One blank line between method definitions.
 - **Whitespace:** Avoid extraneous whitespace. Surround binary operators with single spaces.
 - **Docstrings:** Use `"""triple double quotes"""`. Every public module, function, class, and method must have a docstring.
  - **Format:** Start with a one-line summary. Include `Args:`, `Returns:`, and `Raises:` sections.
 - **Strings:** Use f-strings for formatting. Be consistent with single (`'`) or double (`"`) quotes.
 - **`TODO` Comments:** Use `TODO(username): Fix this.` format.
 - **Imports Formatting:** Imports should be on separate lines and grouped: standard library, third-party, and your own application's imports.
 ## 3. Naming
 - **General:** `snake_case` for modules, functions, methods, and variables.
 - **Classes:** `PascalCase`.
 - **Constants:** `ALL_CAPS_WITH_UNDERSCORES`.
 - **Internal Use:** Use a single leading underscore (`_internal_variable`) for internal module/class members.
 ## 4. Main
 - All executable files should have a `main()` function that contains the main logic, called from a `if __name__ == '__main__':` block.
 **BE CONSISTENT.** When editing code, match the existing style.
 *Source: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)*
--- a/conductor/index.md
+++ b/conductor/index.md
@@ -0,0 +1,14 @@
 # Project Context
 ## Definition
 - [Product Definition](./product.md)
 - [Product Guidelines](./product-guidelines.md)
 - [Tech Stack](./tech-stack.md)
 ## Workflow
 - [Workflow](./workflow.md)
 - [Code Style Guides](./code_styleguides/)
 ## Management
 - [Tracks Registry](./tracks.md)
 - [Tracks Directory](./tracks/)
--- a/conductor/product-guidelines.md
+++ b/conductor/product-guidelines.md
@@ -0,0 +1,16 @@
 # Product Guidelines - FoodPlanner
 ## Visual Identity & Tone
 - **Minimalist and Focused:** The interface should be clean and distraction-free, highlighting one primary task at a time to reduce cognitive load.
 - **Data Clarity:** Prioritize a high-contrast, readable layout that makes nutritional values easy to scan.
 ## User Interface Principles
 - **Page-Specific Nutritional Awareness:**
    - **Global Context:** Use a subtle, persistent summary (e.g., a sticky header) to keep total macros/calories visible for continuous goal tracking.
    - **Local Context:** On list-heavy pages (like Food Search or Meal Building), integrate nutritional data directly with the items for immediate decision-making.
 - **Task-Oriented "Empty States":** When a user encounters an empty view (no foods, no plans), provide clear, actionable instructions and buttons within that space to guide them to the next step.
 ## Interaction & Behavior
 - **Immediate & Reactive:** Every user action (adjusting quantities, adding items) must trigger an instant UI update to the relevant nutritional totals.
 - **Unambiguous Validation:** Use Modal Alerts for errors that require immediate attention or could result in data loss, ensuring critical issues are never overlooked.
 - **Low Friction:** Design interactions to minimize the number of clicks required for common tasks like portion adjustments or food selection.
--- a/conductor/product.md
+++ b/conductor/product.md
@@ -0,0 +1,26 @@
 # Initial Concept\nAn existing Meal Planner application built with FastAPI, SQLAlchemy, and Jinja2 for managing foods, meals, and nutritional plans.
 # Product Definition - FoodPlanner
 ## Vision
 A performance-oriented meal planning application designed for health-conscious households (specifically 2-person units) to hit precise nutritional and macronutrient targets. The application prioritizes speed, data reliability, and structured planning over complex external integrations.
 ## Target Users
 - **Macro-Trackers:** Individuals who meticulously track their caloric and macronutrient intake.
 - **2-Person Households:** Users who need to coordinate meal plans for a small, consistent group.
 ## Core Goals
 - **Nutritional Precision:** Enable users to reach specific daily and weekly macro/calorie goals through structured 2-week planning.
 - **Efficiency:** Reduce the friction of meal prep by providing tools to save, reuse, and template successful plans and meals.
 - **Reliability:** Provide a fast, local-first experience with robust data storage (SQLite/PostgreSQL).
 ## Key Features
 - **Nutritional Totaling:** Automated, real-time calculation of macros and calories for individual foods, combined meals, and full daily/weekly plans.
 - **Detailed Daily Planner:** A granular view of each day to visualize meal distribution and ensure macro balance across the day.
 - **Meals Library:** A centralized repository to create and save custom meals from individual food components.
 - **Template System:** Save and apply successful daily or weekly structures to future plans to minimize repetitive data entry.
 - **Open Food Facts Integration:** Rapidly expand the local food database by importing data directly from the Open Food Facts API.
 ## Technical Philosophy
 - **Local-First & Fast:** The UI must be highly responsive, prioritizing a smooth user experience for frequent data entry.
 - **Structured Data:** Use a relational database to ensure data integrity across foods, meals, and plans.
--- a/conductor/setup_state.json
+++ b/conductor/setup_state.json
@@ -0,0 +1 @@
 {"last_successful_step": "3.3_initial_track_generated"}
--- a/conductor/tech-stack.md
+++ b/conductor/tech-stack.md
@@ -0,0 +1,23 @@
 # Tech Stack - FoodPlanner
 ## Core Backend
 - **Language:** Python 3.7+
 - **Web Framework:** FastAPI (Asynchronous, high-performance web framework)
 - **Data Validation:** Pydantic (Used for schema definition and request/response validation)
 ## Data Layer
 - **ORM:** SQLAlchemy (Using 2.0+ patterns for database interactions)
 - **Database:** Support for SQLite (local development) and PostgreSQL (production)
 - **Migrations:** Alembic (Handles database schema evolution)
 ## Frontend & UI
 - **Templating:** Jinja2 (Server-side rendering for HTML templates)
 - **Frontend Logic:** Minimal JavaScript for reactive UI updates and modal management
 ## External Integrations
 - **Food Data:** Open Food Facts API (For importing nutritional information)
 - **AI/Extraction:** OpenAI API (Used for extracting food data from unstructured text)
 ## Quality Assurance
 - **E2E Testing:** Playwright (For browser-based integration tests)
 - **Unit/Integration Testing:** pytest (For backend logic and API testing)
--- a/conductor/tracks.md
+++ b/conductor/tracks.md
@@ -0,0 +1,8 @@
 # Project Tracks
 This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder.
 ---
 - [ ] **Track: Add Calcium bottom row of "Daily Totals" on the tracker page**
  *Link: [./tracks/add_calcium_20260213/](./tracks/add_calcium_20260213/)*
--- a/conductor/tracks/add_calcium_20260213/index.md
+++ b/conductor/tracks/add_calcium_20260213/index.md
@@ -0,0 +1,5 @@
 # Track add_calcium_20260213 Context
 - [Specification](./spec.md)
 - [Implementation Plan](./plan.md)
 - [Metadata](./metadata.json)
--- a/conductor/tracks/add_calcium_20260213/metadata.json
+++ b/conductor/tracks/add_calcium_20260213/metadata.json
@@ -0,0 +1,8 @@
 {
  "track_id": "add_calcium_20260213",
  "type": "feature",
  "status": "new",
  "created_at": "2026-02-13T00:00:00Z",
  "updated_at": "2026-02-13T00:00:00Z",
  "description": "Add Calcium bottom row of 'Daily Totals' on the tracker page"
 }
--- a/conductor/tracks/add_calcium_20260213/plan.md
+++ b/conductor/tracks/add_calcium_20260213/plan.md
@@ -0,0 +1,18 @@
 # Implementation Plan - Add Calcium to Tracker Totals
 This plan follows the Test-Driven Development (TDD) process as outlined in `conductor/workflow.md`.
 ## Phase 1: Infrastructure and Red Phase
 - [ ] Task: Create a failing E2E test for Calcium display
    - [ ] Define a new test in `tests/calcium_display.spec.js` that navigates to the tracker and expects a "Calcium" label and a numeric value in the Daily Totals section.
    - [ ] Execute the test and confirm it fails (Red Phase).
 ## Phase 2: Implementation (Green Phase)
 - [ ] Task: Update tracker template to include Calcium
    - [ ] Modify `templates/tracker.html` to add a fourth column to the third row of the "Daily Totals" card.
    - [ ] Update existing `col-4` classes in that row to `col-3` to accommodate the new column.
    - [ ] Bind the display to `day_totals.calcium` with a `0` decimal place filter and "mg" unit.
 - [ ] Task: Verify implementation
    - [ ] Execute the E2E test created in Phase 1 and confirm it passes (Green Phase).
    - [ ] Run existing backend tests to ensure no regressions in nutrition calculations.
 - [ ] Task: Conductor - User Manual Verification 'Implementation' (Protocol in workflow.md)
--- a/conductor/tracks/add_calcium_20260213/spec.md
+++ b/conductor/tracks/add_calcium_20260213/spec.md
@@ -0,0 +1,25 @@
 # Specification - Add Calcium to Tracker Totals
 ## Overview
 This track adds a Calcium display to the "Daily Totals" section of the tracker page. This allows users to track their calcium intake (in mg) alongside other micronutrients and macronutrients.
 ## Functional Requirements
 - **Display Calcium:** Add a new column to the third row of the "Daily Totals" card on the `tracker.html` page.
 - **Unit of Measurement:** Calcium shall be displayed in milligrams (mg).
 - **Precision:** Calcium values shall be rounded to the nearest whole number (0 decimal places).
 - **Data Source:** Use the `day_totals.calcium` value provided by the backend, which is already correctly calculated in `calculate_day_nutrition_tracked`.
 ## Non-Functional Requirements
 - **UI Consistency:** The new Calcium display should match the style of the existing Sugar, Fiber, and Sodium displays (border, padding, centered text, small muted label).
 - **Responsiveness:** The layout should remain functional on various screen sizes. Adding a fourth column to the row may require adjusting column widths (e.g., from `col-4` to `col-3`).
 ## Acceptance Criteria
 - [ ] A "Calcium" box is visible in the "Daily Totals" section of the tracker page.
 - [ ] The value displayed matches the sum of calcium from all tracked foods for that day.
 - [ ] The unit "mg" is displayed next to or below the value.
 - [ ] The layout of the "Daily Totals" card remains clean and balanced.
 ## Out of Scope
 - Adding Calcium to individual food or meal breakdown tables.
 - Updating Open Food Facts import logic (unless found to be missing Calcium data during verification).
 - Adding Calcium targets or progress bars.
--- a/conductor/workflow.md
+++ b/conductor/workflow.md
@@ -0,0 +1,169 @@
 # Project Workflow
 ## Guiding Principles
 1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md`
 2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation
 3. **Test-Driven Development:** Write unit tests before implementing functionality
 4. **High Code Coverage:** Aim for >80% code coverage for all modules
 5. **User Experience First:** Every decision should prioritize user experience
 6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution.
 ## Task Workflow
 All tasks follow a strict lifecycle:
 ### Standard Task Workflow
 1. **Select Task:** Choose the next available task from `plan.md` in sequential order
 2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]`
 3. **Write Failing Tests (Red Phase):**
   - Create a new test file for the feature or bug fix.
   - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task.
   - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests.
 4. **Implement to Pass Tests (Green Phase):**
   - Write the minimum amount of application code necessary to make the failing tests pass.
   - Run the test suite again and confirm that all tests now pass. This is the "Green" phase.
 5. **Refactor (Optional but Recommended):**
   - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior.
   - Rerun tests to ensure they still pass after refactoring.
 6. **Verify Coverage:** Run coverage reports using the project's chosen tools (e.g., `pytest --cov=app`). Target: >80% coverage for new code.
 7. **Document Deviations:** If implementation differs from tech stack:
   - **STOP** implementation
   - Update `tech-stack.md` with new design
   - Add dated note explaining the change
   - Resume implementation
 8. **Record Completion in Plan:** Update `plan.md`, find the line for the completed task, and update its status from `[~]` to `[x]`. 
   *Note: Committing code and plan updates is deferred until the entire phase is complete.*
 ### Phase Completion Verification and Checkpointing Protocol
 **Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`.
 1.  **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
 2.  **Ensure Test Coverage for Phase Changes:**
    -   **Step 2.1: Determine Phase Scope:** Identify files changed since the last phase checkpoint.
    -   **Step 2.2: List Changed Files:** Execute `git diff --name-only <previous_checkpoint_sha> HEAD` (or since first commit if no previous checkpoint).
    -   **Step 2.3: Verify and Create Tests:** Ensure all new code has corresponding tests following project conventions.
 3.  **Execute Automated Tests with Proactive Debugging:**
    -   Announce and run the automated test suite (e.g., `pytest` and `playwright test`).
    -   If tests fail, debug and fix (maximum two attempts before seeking guidance).
 4.  **Propose a Detailed, Actionable Manual Verification Plan:**
    -   Analyze `product.md`, `product-guidelines.md`, and `plan.md` to define user-facing goals.
    -   Present a step-by-step verification plan with expected outcomes.
 5.  **Await Explicit User Feedback:**
    -   Pause for the user to confirm: "Does this meet your expectations?"
 6.  **Create Phase Checkpoint Commit:**
    -   Stage all code changes and the updated `plan.md`.
    -   Perform a single commit for the entire phase with a message like `feat(phase): Complete <Phase Name>`.
 7.  **Attach Consolidated Task Summary using Git Notes:**
    -   **Step 7.1: Draft Note Content:** Create a detailed summary for *all* tasks completed in this phase, including verification results.
    -   **Step 7.2: Attach Note:** Use `git notes add -m "<summary>" <checkpoint_commit_hash>`.
 8.  **Get and Record Phase Checkpoint SHA:**
    -   Obtain the hash of the checkpoint commit and update the phase heading in `plan.md` with `[checkpoint: <sha>]`.
 9. **Commit Plan Update:**
    - Stage `plan.md` and commit with `conductor(plan): Mark phase '<PHASE NAME>' as complete`.
 10. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created.
 ## Quality Gates
 Before marking any task complete, verify:
 - [ ] All tests pass
 - [ ] Code coverage meets requirements (>80%)
 - [ ] Code follows project's code style guidelines
 - [ ] All public functions/methods are documented
 - [ ] Type safety is enforced (Pydantic models, type hints)
 - [ ] No linting or static analysis errors
 - [ ] Documentation updated if needed
 - [ ] No security vulnerabilities introduced
 ## Development Commands
 ### Setup
 ```bash
 python -m venv venv
 source venv/bin/activate
 pip install -r requirements.txt
 npm install
 ```
 ### Daily Development
 ```bash
 # Start FastAPI server
 uvicorn main:app --reload
 # Run Backend Tests
 pytest
 # Run E2E Tests
 npx playwright test
 ```
 ### Before Committing
 ```bash
 # Run all checks
 pytest && npx playwright test
 ```
 ## Testing Requirements
 ### Unit Testing
 - Every module must have corresponding tests in `tests/`.
 - Use `pytest` fixtures for database and app setup.
 - Mock external APIs (Open Food Facts, OpenAI).
 ### Integration Testing
 - Test complete API flows using `httpx`.
 - Verify database state after operations.
 ### E2E Testing
 - Use Playwright to test critical user journeys (Creating Plans, Adding Foods).
 ## Commit Guidelines
 ### Message Format
 ```
 <type>(<scope>): <description>
 [optional body]
 [optional footer]
 ```
 ### Types
 - `feat`: New feature
 - `fix`: Bug fix
 - `docs`: Documentation only
 - `style`: Formatting, missing semicolons, etc.
 - `refactor`: Code change that neither fixes a bug nor adds a feature
 - `test`: Adding missing tests
 - `chore`: Maintenance tasks
 ## Definition of Done
 A task is complete when:
 1. All code implemented to specification
 2. Unit tests written and passing
 3. Code coverage meets project requirements
 4. Documentation complete (if applicable)
 5. Code passes all configured linting and static analysis checks
 6. Implementation notes recorded for the phase summary
 7. Phase changes committed and summarized with Git Notes
		`@@ -0,0 +1 @@`
							`{"last_successful_step": "3.3_initial_track_generated"}`