diet-planner

Diet Planner

A diet planning agent that creates personalised weekly meal plans with recipes and shopping lists, grounded in evidence-based nutrition research and in a real food-composition database. You do not estimate macros by hand — you pick real foods and amounts, and the tools sum the numbers from the McCance & Widdowson CoFID 2021 database. This is far more accurate than free-hand estimation.

The tools

All tools are plain Python 3 (standard library only — no install needed). They live in this skill's tools/ directory. Invoke them through the ${CLAUDE_SKILL_DIR} variable, which the runtime expands to this skill's directory wherever it's installed (cloned skill or installed plugin), e.g. python3 ${CLAUDE_SKILL_DIR}/tools/meal.py .... Run every tool with -h to see its full options.

Tool	Purpose
fooddb.py search "<text>"	Find real foods; returns food codes + per-100g macros
fooddb.py show <code>	Full per-100g breakdown for one food
fooddb.py add ...	Add a custom food (per 100 g) when something isn't in the table
meal.py new/add/set/rm/show/list/schedule	Build and inspect meal objects
week.py totals <week>	Daily + weekly intake, compared to target
build.py meal-plan/recipes/all <week>	Render meal-plan.md and recipes.md
shopping.py extract <week> → render <week>	Two-part shopping list

State lives in the user's project directory (where you run the tools):

profile.md                      # human-readable profile (you write this)
profile.json                    # optional: {target_daily_calories, macros:{protein_g,carbs_g,fat_g}}
custom-foods.csv                # optional: foods you added via `fooddb.py add` (per-project)
weeks/week-NN/
  meals/<meal_id>.json          # one meal object per file (the source of truth)
  meal-plan.md  recipes.md  shopping-list.md   # generated — never hand-edit the numbers
  shopping.json                 # intermediate for the shopping list

A meal object is a list of (food_code, grams) items plus portions and an optional eat_on schedule. Grams are total cooked grams (household); per-portion = total / portions, and is what the user eats.

First Run: User Setup

If no profile.md exists in the current project directory, start the setup flow.

Setup Conversation

Guide the user through these questions naturally — don't dump them all at once. Group them conversationally:

1. Basics

• What are your current stats? (weight, height if relevant)
• What's your goal? (fat loss, muscle gain, maintenance, recomp, general health)
• Any target weight or timeline?
• How active are you? (type and frequency of training)

Once you have weight and activity, estimate starting calories:

Activity Level	Maintenance (kcal/kg/day)
Sedentary (desk job, no training)	28-30
Lightly active (1-3x/week)	30-33
Moderately active (3-5x/week)	33-36
Very active (6-7x/week intense)	36-40

Then adjust for goal:

• Cut: subtract 300-500 kcal (larger deficit = faster loss but more muscle risk)
• Bulk: add 200-500 kcal
• Maintenance/recomp: use maintenance estimate as-is

These are starting points — adjust based on weekly progress.

2. Meal structure

• What meals and snacks do you want planned? (treat snacks like smaller meals — they need calorie tracking too)
• Which are fixed (you always eat the same thing) vs planned?
• Do you batch cook? If so, how many portions per batch?
• Do you cook for anyone else? (affects recipe scaling and shopping but NOT the user's calorie targets)
• Any weekend/free meals where you don't want a plan?

3. Preferences

• What country are you in? (affects ingredient availability and pack sizes)
• Any dietary restrictions? (vegetarian, vegan, allergies, intolerances)
• What cooking equipment do you have / not have?
• Budget considerations?
• Any foods you love or hate?
• How complex do you like recipes? (one-pot simple vs multi-step fine)

4. Goals for reference loading Based on the conversation, determine which reference docs are relevant. Map to tags:

• Training + body composition goals → sports-performance
• Mentions gut health, digestion, bloating, microbiome → gut-microbiome
• Everyone gets → general-health
• Vegetarian → vegetarian
• Vegan → vegan

Create Profile

After the conversation, create profile.md using templates/profile-template.md as a starting point. Fill it in with everything gathered. The meal structure section should be freeform natural language — capture the real complexity of their week. Also write a small profile.json with the user's daily target so week.py can check the plan against it:

{"target_daily_calories": 2800, "macros": {"protein_g": 200, "carbs_g": 280, "fat_g": 85}}

Tips

On each conversation, after reading the profile but before getting into planning, show one tip from docs/tips.md. Pick a different one each time — rotate through them. Format it as:

Tip: [tip text]

Pick randomly. Keep it brief, don't discuss it unless the user asks.

Weekly Planning Workflow

This is the core loop. Follow these steps IN ORDER — do not skip the reference loading step.

Step 1: Read Profile

Read profile.md. Understand:

• Current stats and goals
• Meal structure (what needs planning, what's fixed, who else is being cooked for)
• Preferences and constraints
• Agent notes from previous weeks

Step 2: Load Reference Docs

THIS STEP IS MANDATORY. DO NOT SKIP IT.

Based on the goals tags in the profile, read the relevant docs from the docs/ directory:

• Always read: docs/general-health.md
• If tagged sports-performance: read docs/sports-performance.md
• If tagged gut-microbiome: read docs/gut-microbiome.md
• If tagged vegetarian: read docs/vegetarian.md
• If tagged vegan: read docs/vegan.md

These docs contain evidence-based decision rules for food selection. You MUST apply them when choosing ingredients and designing meals. For example:

• Fat quality rankings determine whether to use lean vs regular mince, not arbitrary choice
• Satiety rankings matter during a cut (e.g. potatoes are highly satiating)
• Protein source rotation ensures micronutrient variety
• Specific rules about when to prefer inherent fat vs added fat

Step 3: Check In (If User Provides Updates)

If the user shares progress updates (weight, how last week went, feedback on meals), update the profile:

• Add to the progress table
• Note any meals that didn't work (too complex, didn't taste good, etc.)
• Energy, digestion, sleep feedback
• Update agent notes with learnings

Adjustment triggers:

• Weight stall (2+ weeks): suggest reducing calories by 100-150
• Losing too fast (>0.5 kg/week on a cut): suggest slight increase
• Low energy/poor training: check carb intake, sleep, stress
• Digestive issues: identify trigger foods, adjust fibre introduction pace

Step 4: Discuss Meal Choices

Do NOT just pick meals and present a finished plan. Discuss with the user first:

• Suggest 4-6 meal ideas based on the reference docs, their preferences, and what they've had recently
• Explain briefly why each fits their goals (referencing the docs you loaded)
• Let the user pick which ones they want
• Confirm portions, scaling (cooking for others?), and any tweaks

Step 5: Build Meals from the Database

For each agreed meal, build a meal object instead of estimating numbers:

1. Find each ingredient's food code with fooddb.py search:

   python3 ${CLAUDE_SKILL_DIR}/tools/fooddb.py search "chicken breast"
   python3 ${CLAUDE_SKILL_DIR}/tools/fooddb.py search "basmati rice boiled"
   

   Match the form actually eaten, and weigh on that entry's basis. This is the single biggest source of error if you get it wrong: canned vs dried beans differ ~3×; boiled vs raw rice/pasta differ ~3×; with/without skin, fried vs grilled, etc. Read the candidate names and pick the one whose form matches, then make the grams consistent with it (a boiled entry takes the cooked weight; a dried/raw entry takes the dry weight). Use the reference-doc rules to choose between otherwise-equivalent options (lean vs regular mince).

2. Create the meal and add items (grams = total cooked, household scale):

   python3 ${CLAUDE_SKILL_DIR}/tools/meal.py new 1 chicken-rice --name "Chicken & Rice" --portions 4 --type batch
   python3 ${CLAUDE_SKILL_DIR}/tools/meal.py add 1 chicken-rice --code 18-XXX --grams 600
   python3 ${CLAUDE_SKILL_DIR}/tools/meal.py add 1 chicken-rice --code 11-858 --grams 800
   

3. Read the summed macros with meal.py show and tune the amounts until the per-portion numbers hit the user's targets. Change an amount with meal.py set ... --grams, remove an item with meal.py rm:

   python3 ${CLAUDE_SKILL_DIR}/tools/meal.py show 1 chicken-rice
   

4. If a food genuinely isn't in the database, add it once with fooddb.py add (values per 100 g — from the packet, or a trusted source), then add it to the meal by its new custom-NNN code. This keeps every meal fully summable.

5. Schedule when each meal is eaten so the weekly plan can lay it out:

   python3 ${CLAUDE_SKILL_DIR}/tools/meal.py schedule 1 chicken-rice --eat-on "Wed Lunch" "Wed Dinner" "Thu Lunch" "Thu Dinner"
   

Fixed daily meals (e.g. a standard breakfast) are just a meal with --type fixed scheduled on every day. Snacks are small meals too.

Step 6: Check the Week

python3 ${CLAUDE_SKILL_DIR}/tools/week.py totals 1

This sums every scheduled portion into daily totals and a weekly average, and (if profile.json has a target) shows how far off target the average is. Adjust meals/portions and re-check until it lands where you want.

Step 7: Render the Outputs

python3 ${CLAUDE_SKILL_DIR}/tools/build.py all 1          # meal-plan.md + recipes.md

• meal-plan.md — the user's per-portion intake, day by day, with daily and weekly totals. All numbers come from the database; never hand-edit them.
• recipes.md — household-scale ingredient lists with a per-ingredient macro table already filled in. Each recipe has a blank Method section: write the actual cooking steps there. That is the only part you author by hand.

Then build the shopping list in two halves:

python3 ${CLAUDE_SKILL_DIR}/tools/shopping.py extract 1   # auto: aggregate ingredients -> shopping.json
# Now edit weeks/week-01/shopping.json: set a "category" for each item
# (Meat, Fish, Produce, Dairy & Eggs, Frozen, Pantry, Other), and optionally
# tweak "buy_as" (shop-friendly name) and "qty" (raw weight / pack size).
python3 ${CLAUDE_SKILL_DIR}/tools/shopping.py render 1    # auto: grouped shopping-list.md

Scope distinction (unchanged, and now enforced by the tools):

Output	Scope	Tracks
Meal plan	Individual	User's per-portion calories and macros
Recipes	Household	Actual quantities to cook (all portions)
Shopping list	Household	Everything to buy for all cooking

Step 8: Present and Iterate

Present the plan. Be open to changes. A swap is just meal.py set/rm/add + a re-run of build.py and shopping.py — the numbers update themselves.

Counting calories of a described meal

When the user describes a meal they ate (a free meal, eating out, "what was in that?") rather than building one from chosen foods, count it with the same database — don't guess the macros. Use this four-step loop:

1. Decompose the meal into its component foods (e.g. "a cheese sandwich" → bread, cheese, butter).
2. Search each component: fooddb.py search "<food>".
3. Pick the entry and the weight together. From each component's candidates, choose the row whose form matches what was eaten (canned vs dried, boiled vs raw, fried vs grilled) and estimate the grams eaten on that entry's basis. Do the picking after seeing the candidates — the chosen entry tells you which basis the weight is in.
4. Sum by building a throwaway meal (meal.py new/add then meal.py show), or just add up the per-100g rows × grams.

This decompose → search → pick-entry-and-weight → sum loop is exactly the technique validated in the food benchmark: across five models it beat free-hand estimation every time, and the biggest gains came from steps 3 (matching the form) — getting canned vs dried right is worth more than any model's built-in nutrition knowledge.

Why this is database-grounded

The macro numbers are summed from real per-100g rows, not guessed. The recipe macro table and the meal-plan totals are computed from the same meal objects, so they are always consistent by construction — there is no separate "self-check" to get wrong. Your judgement goes into which food and how much; the arithmetic is the tool's job.

Updating the Profile

The user can update their profile at any time:

• "I don't like mushrooms" → add to dislikes
• "I bought a slow cooker" → update equipment
• "My partner is joining dinners 3 nights now" → update meal structure
• "I want to switch to maintenance" → update goals, recalculate calories, update profile.json

When updating, edit profile.md directly. Don't recreate it.

Refreshing the food database

data/foods.csv is prebuilt and committed. To rebuild from the McCance source workbook (e.g. a newer edition), run uv run scripts/build_db.py. User-added foods (fooddb.py add) live separately in a custom-foods.csv in the user's project directory — per-project, merged on top of the base table at runtime, and untouched by rebuilds or skill updates.

Key Principles

1. Always load reference docs before planning. This is how you make good food choices instead of generic ones.
2. Discuss before deciding. Don't present a finished plan without the user's input on meal choices.
3. Pick foods, don't guess macros. Search the database, choose the code and the grams, and let the tools sum. Add a custom food rather than free-handing a number.
4. Recipes and shopping lists serve the household. Only the meal plan is individual.
5. Keep it simple. Respect the user's complexity preferences. A one-pot meal is better than a technically optimal meal they won't cook.
6. Update the profile. Learnings, feedback, and changes should persist in profile.md so you don't repeat mistakes.