Kitchen Compass

Build and operate a portable Kitchen Compass meal-planning workspace. Use when setting up a Kitchen Compass household data root, converting recipes into the...

Security Scan

The skill is internally coherent: a local, portable meal-planning toolkit that operates on a user-specified data root and does not request credentials or hidden installs.

Purpose & Capability

The name/description (meal-planning, portable engine + household data root) matches the included files and scripts: recipe catalog builder, planner, inventory management, deal brief tooling and setup helpers. No unrelated binaries, cloud credentials, or surprising capabilities are declared.

Instruction Scope

SKILL.md instructs the agent/operator to run the provided Python scripts against a household data root and to keep user data outside the skill directory — which is appropriate. Two minor notes: (1) the docs describe the agent 'reading a web page' when adding recipes and there are per-store 'source-url' fields for weekly deals, meaning the agent or operator may fetch external URLs if you supply them; (2) SKILL.md references optional env vars like KITCHEN_COMPASS_DATA_ROOT, FOOD_BRAIN_DATA_ROOT (deprecated), and KITCHEN_COMPASS_VERBOSE even though requires.env lists none. These are optional behavior knobs rather than required secrets, but they are an inconsistency between declared requirements and runtime docs.

Install Mechanism

No install spec is provided (instruction-only install), and the package contains local Python scripts and docs. Nothing is pulled from arbitrary URLs or package managers at install time. This is low-risk from an install mechanism perspective.

Credentials

The skill requests no environment variables or credentials. The SKILL.md does mention optional env vars (data-root and verbosity) but they are not required. There are no credential-like env vars or config paths declared. This is proportionate to the stated purpose.

Persistence & Privilege

always:false (not force-included) and default autonomous invocation is allowed (normal). The skill interacts with a user-specified data root and writes files there (setup/bootstrap scripts create recipe, inventory, history files) — expected for this type of tool. It does not request system-wide configuration changes or modify other skills.

Assessment

This skill looks like a straightforward, local meal-planning engine. Before installing or enabling it: 1) Keep the household data root outside the skill directory (SKILL.md recommends this) so your personal recipes/inventory stay separate from the shipped engine. 2) Inspect manage_deal_sources.py / prepare_weekly_deal_scan.py (or any script that accepts a 'source-url') if you plan to supply external URLs — those scripts or your agent may fetch and parse pages you give them. If you don't want any network activity, don't provide URLs and avoid the deal-scan flows. 3) The SKILL.md refers to optional env vars (KITCHEN_COMPASS_DATA_ROOT, KITCHEN_COMPASS_VERBOSE and a deprecated FOOD_BRAIN_DATA_ROOT) even though none are required; these are just convenience knobs. 4) Because the agent (host) will be given filesystem access to the specified data root, make sure the host environment is trusted and isolate the data root from sensitive system paths. 5) If you are risk-averse, run the included scripts locally yourself (the README gives a quick verification sequence) and read the small number of scripts that handle network inputs to confirm they behave how you expect. Overall there are no hidden credential requests, remote installs, or other red flags.

Use this skill to keep the reusable Kitchen Compass engine separate from household data.

Operating rules

• Keep the skill directory portable. Do not store a user's real recipes, inventory, or history inside the skill.
• Treat the user-data root as the authored source of truth. Generated files are rebuildable.
• Inventory changes must be explicit; never silently subtract or fabricate real-time stock state.
• Treat the installed skill directory as the canonical source for portable engine logic, templates, and contract docs. If a separate live or development copy exists, sync changes deliberately instead of editing both copies independently.
• Preserve the frozen recipe contract. Exact recipe labels, section order, enum sets, and composition semantics live in references/recipe-schema.md.
• Preserve runtime assumptions and history shape from references/runtime-contract.md.
• If machine-used contract constants must change, update scripts/contract.py deliberately and then keep the reference docs aligned.
• Stay conservative: this v1 engine only guarantees dinner + side query/planner support.

Decide what to read first

• For setup or folder creation, read references/setup-flow.md.
• For recipe editing, migration, validation, or exact field values, read references/recipe-schema.md.
• For history editing or runtime expectations, read references/runtime-contract.md.
• For optional weekly deal brief setup or output shape, read references/weekly-deal-brief.md.
• For portability questions or boundary rules, read references/user-data-layout.md and references/live-vs-portable-boundary.md.

Use the bundled scripts

Assume the shell is currently in the installed kitchen-compass skill directory:

cd /path/to/kitchen-compass

Then run scripts from scripts/ against a household data root.

Initialize a new household data root

python3 scripts/setup_household.py --data-root /path/to/kitchen-compass-data

This creates the canonical user-data layout and copies the bundled sample recipes under assets/sample-household/ plus _recipe-template.md. The legacy FOOD_BRAIN_DATA_ROOT env var still works but is deprecated — prefer KITCHEN_COMPASS_DATA_ROOT.

Build the query catalog

python3 scripts/build_recipe_query_index.py --data-root /path/to/kitchen-compass-data

The index builder validates every recipe against the frozen contract before writing the catalog and exits nonzero on any failure. Pass --skip-validation to bypass in a pinch; normal usage should leave it on.

Query recipes

python3 scripts/query_recipes.py --data-root /path/to/kitchen-compass-data --meal-type dinner --wants-side

Add or update remembered inventory

python3 scripts/manage_inventory.py --data-root /path/to/kitchen-compass-data add --label "Ground beef" --location freezer --kind protein --amount 3 --unit lb
python3 scripts/manage_inventory.py --data-root /path/to/kitchen-compass-data use --item freezer-ground-beef --amount 1 --unit lb --confirmed

Build a weekly plan

python3 scripts/build_weekly_plan.py --data-root /path/to/kitchen-compass-data --preset balanced

Manage optional weekly deal sources

python3 scripts/manage_deal_sources.py --data-root /path/to/kitchen-compass-data show
python3 scripts/manage_deal_sources.py --data-root /path/to/kitchen-compass-data add-store --label "Giant - Boot Rd" --retailer giant --source-type circular-url --source-url "https://example.com/circular" --retrieval-step "Resolve saved store before trusting the flyer" --default
python3 scripts/manage_deal_sources.py --data-root /path/to/kitchen-compass-data set-scan-schedule --day-of-week friday --time-local 12:00 --timezone America/New_York

Prepare the weekly deal scan and combine store outputs

python3 scripts/prepare_weekly_deal_scan.py --data-root /path/to/kitchen-compass-data --week-of 2026-04-21
python3 scripts/render_combined_weekly_deal_sheet.py --data-root /path/to/kitchen-compass-data

Render a manual single-store weekly deal brief

python3 scripts/render_weekly_deal_brief.py --data-root /path/to/kitchen-compass-data

Record history

python3 scripts/record_meal_history.py --data-root /path/to/kitchen-compass-data --event-type made --recipe burger-bowls

Duplicate events — same (date, recipe, meal_slot, event_type) — are skipped by default with a warning. Pass --allow-duplicate to write anyway, or --replace to substitute the existing event in place.

Quiet / verbose flags

Every script supports --verbose to print the resolved data root to stderr; alternatively set KITCHEN_COMPASS_VERBOSE=1. Mutation scripts (manage_inventory, manage_deal_sources, record_meal_history, prepare_weekly_deal_scan) support --quiet for a one-line confirmation and --silent for no stdout output.

Workflow

1. Initialize or inspect the user-data root.
2. Add or normalize recipe markdown files using the frozen template.
3. Validate recipes against the frozen contract.
4. Rebuild the query catalog after recipe changes.
5. Query or plan from generated outputs.
6. Optionally add or confirm inventory state.
7. Optionally configure manual weekly deal brief store/source setup and preferred scan schedule.
8. Prepare the weekly deal scan packet, curate per-store briefs, and render the combined weekly deal sheet.
9. Record meal history so planning can use recency.

Assets

• assets/recipe-template.md is the reusable authored template.
• assets/sample-household/ is seed content only. It ships with nine sample recipes spanning four protein families, both dinner and side meal types, and a mix of statuses so presets and pairing intel have real data to work with. Replace or expand the set with real household data as needed.