mirror of
https://github.com/sstent/foodplanner.git
synced 2026-02-16 07:45:26 +00:00
conductor(setup): Add conductor setup files
This commit is contained in:
49
conductor/code_styleguides/html-css.md
Normal file
49
conductor/code_styleguides/html-css.md
Normal file
@@ -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)*
|
||||
51
conductor/code_styleguides/javascript.md
Normal file
51
conductor/code_styleguides/javascript.md
Normal file
@@ -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)*
|
||||
37
conductor/code_styleguides/python.md
Normal file
37
conductor/code_styleguides/python.md
Normal file
@@ -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)*
|
||||
14
conductor/index.md
Normal file
14
conductor/index.md
Normal file
@@ -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/)
|
||||
16
conductor/product-guidelines.md
Normal file
16
conductor/product-guidelines.md
Normal file
@@ -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.
|
||||
26
conductor/product.md
Normal file
26
conductor/product.md
Normal file
@@ -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.
|
||||
1
conductor/setup_state.json
Normal file
1
conductor/setup_state.json
Normal file
@@ -0,0 +1 @@
|
||||
{"last_successful_step": "3.3_initial_track_generated"}
|
||||
23
conductor/tech-stack.md
Normal file
23
conductor/tech-stack.md
Normal file
@@ -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)
|
||||
8
conductor/tracks.md
Normal file
8
conductor/tracks.md
Normal file
@@ -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/)*
|
||||
5
conductor/tracks/add_calcium_20260213/index.md
Normal file
5
conductor/tracks/add_calcium_20260213/index.md
Normal file
@@ -0,0 +1,5 @@
|
||||
# Track add_calcium_20260213 Context
|
||||
|
||||
- [Specification](./spec.md)
|
||||
- [Implementation Plan](./plan.md)
|
||||
- [Metadata](./metadata.json)
|
||||
8
conductor/tracks/add_calcium_20260213/metadata.json
Normal file
8
conductor/tracks/add_calcium_20260213/metadata.json
Normal file
@@ -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"
|
||||
}
|
||||
18
conductor/tracks/add_calcium_20260213/plan.md
Normal file
18
conductor/tracks/add_calcium_20260213/plan.md
Normal file
@@ -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)
|
||||
25
conductor/tracks/add_calcium_20260213/spec.md
Normal file
25
conductor/tracks/add_calcium_20260213/spec.md
Normal file
@@ -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.
|
||||
169
conductor/workflow.md
Normal file
169
conductor/workflow.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user