Initial commit

2026-08-19 11:03:16 +02:00
commit e8c8224b05
35 changed files with 1806 additions and 0 deletions
@@ -0,0 +1,13 @@
+# /speckit.implement — execute the task list
+
+Gate: tasks.md exists for the current feature (run `python3 speckit.py status`
+to confirm); if it is missing, stop and run /speckit.tasks first.
+
+1. Read spec.md, plan.md and tasks.md of the current feature.
+2. Work through tasks.md strictly top to bottom, phase by phase: implement
+   each task test-first, and flip its checkbox to `- [x]` only after its
+   verification actually passed.
+3. Never renumber or delete tasks; append newly discovered work as new
+   checkboxes at the end of the fitting phase.
+4. When all boxes are checked, run `python3 speckit.py check` and report the
+   result to the user together with how to run the built feature.
@@ -0,0 +1,13 @@
+# /speckit.plan — create the implementation plan
+
+Gate: the current feature must already have a completed spec.md — read it
+first; if it is missing or full of unresolved markers, stop and say so.
+
+1. Run `python3 speckit.py plan` — it seeds `plan.md` next to the spec
+   (the command refuses to run while spec.md is missing).
+2. Fill plan.md from the spec: the concrete stack in ## Technical Context,
+   the intended source layout in ## Structure, and each significant choice
+   with rationale and rejected alternative in ## Decisions.
+3. Check every decision against memory/constitution.md; justify or simplify
+   anything that violates an article.
+4. Run `python3 speckit.py status` to confirm the phase is recorded.
@@ -0,0 +1,18 @@
+# /speckit.specify — create a feature specification
+
+The user gives you a feature description. Turn it into a reviewable spec:
+
+1. Run `python3 speckit.py specify "<the description>"` from the project —
+   or, when the user provides the brief as a file, pass its path instead
+   (add `--name "<short feature name>"` when the file starts with metadata).
+   This creates `specs/NNN-slug/spec.md` and makes it the current feature.
+2. Open that spec.md and replace every placeholder section with real content:
+   prioritized user stories with acceptance scenarios (## User Stories),
+   verifiable numbered requirements and key entities (## Requirements),
+   measurable technology-agnostic outcomes (## Success Criteria), and the
+   defaults you chose for open points (## Assumptions).
+3. Where you truly cannot decide without the user, leave a marker of the form
+   NEEDS CLARIFICATION plus the question in square brackets — at most 3.
+4. Finish by running `python3 speckit.py check` and resolving any findings.
+
+Do not make technology choices here — the spec says what and why, never how.
@@ -0,0 +1,13 @@
+# /speckit.tasks — break the plan into executable tasks
+
+Gate: the current feature needs a filled plan.md — read spec.md and plan.md
+before writing anything; if plan.md is missing, stop and say so.
+
+1. Run `python3 speckit.py tasks` — it seeds `tasks.md` for the current
+   feature (refused while plan.md is missing).
+2. Replace the placeholder checkboxes with real tasks: dependency-ordered
+   phases under ## Phases, one checkbox per task, exact file paths in each
+   description, user-story order preserved (P1 first).
+3. Every task must be small enough to verify on its own; note which tasks
+   are independent enough to run in parallel.
+4. Run `python3 speckit.py status` to see the open-task count.
@@ -0,0 +1,7 @@
+{
+  "project": "pantry-planner",
+  "current_feature": "001-pantry-meal-planner",
+  "features": [
+    "001-pantry-meal-planner"
+  ]
+}
@@ -0,0 +1,13 @@
+# Quality Checklist: {{FEATURE}}
+
+*Created: {{DATE}}*
+
+Reviewer-owned quality gate for the written requirements — these boxes judge
+the spec text, not the implementation. Check an item only after actually
+reviewing it; add domain-specific items freely.
+
+- [ ] Every user story has at least one concrete acceptance scenario
+- [ ] Each requirement is verifiable (a test could pass or fail it)
+- [ ] Success criteria are measurable without naming technologies
+- [ ] All clarification markers are resolved or consciously accepted
+- [ ] Assumptions state the chosen default AND what was ruled out
@@ -0,0 +1,30 @@
+# {{PROJECT}} Constitution
+
+*Adopted: {{DATE}} — version 1.0.0*
+
+Standing principles every feature in this project must respect. Specs, plans
+and tasks are checked against these articles; a violation needs an explicit,
+written justification or the work does not proceed.
+
+## Article I — Simplicity
+
+The smallest design that satisfies the spec wins. New layers, wrappers or
+abstractions require a demonstrated need, not an anticipated one.
+
+## Article II — Tests Prove Behavior
+
+No behavior ships without a test that failed before the behavior existed.
+
+## Article III — Minimal Blast Radius
+
+Touch only what the feature requires. Leave unrelated code, files and
+interfaces unchanged.
+
+## Article IV — Honest Artifacts
+
+Specs record what is actually decided; open questions are marked, not hidden.
+Task checkboxes reflect verified reality, not intentions.
+
+## Amendments
+
+Record changes here with date, version bump and one-line rationale.
@@ -0,0 +1,33 @@
+# Implementation Plan: {{FEATURE}}
+
+*Created: {{DATE}}*
+
+Turn the spec into concrete technical decisions. Stay minimal: prefer the
+simplest structure that satisfies the spec, and justify anything that isn't.
+
+## Technical Context
+
+Language/runtime, dependencies, storage, testing approach, target platform,
+and any performance or scale constraints. Unknowns become research notes here
+— resolve them before writing tasks.
+
+- Language:
+- Dependencies:
+- Storage:
+- Testing:
+
+## Structure
+
+The intended source layout: directories, modules, and where new code lands.
+
+```
+(project tree sketch)
+```
+
+## Decisions
+
+Each significant choice with its one-line rationale and the alternative that
+was rejected. Anything that adds complexity needs a justification tied to a
+requirement.
+
+- D1: … — because …
@@ -0,0 +1,43 @@
+# Feature Specification: {{FEATURE}}
+
+*Created: {{DATE}}*
+
+> Original request: {{DESCRIPTION}}
+
+Anything genuinely undecided gets an inline marker: the words NEEDS CLARIFICATION
+plus the open question, wrapped in square brackets. Keep at most 3 of them — pick
+a sensible default for everything else and record it under Assumptions.
+
+## User Stories
+
+Describe who wants what and why. At least one story with priority P1; each story
+must be independently testable.
+
+### Story 1 — (P1)
+
+As a …, I want …, so that ….
+
+**Acceptance:** Given …, when …, then ….
+
+## Requirements
+
+Numbered, verifiable statements of what the feature must do. Name the key
+entities (data the feature reads or writes) at the end.
+
+- R1: The system must …
+
+**Entities:** …
+
+## Success Criteria
+
+Measurable, technology-agnostic outcomes that tell you the feature works
+(counts, durations, rates — things you can check without knowing the stack).
+
+- S1: …
+
+## Assumptions
+
+Defaults chosen for anything the request left open, plus explicit scope
+boundaries (what this feature deliberately does not cover).
+
+- A1: …
@@ -0,0 +1,25 @@
+# Tasks: {{FEATURE}}
+
+*Created: {{DATE}}*
+
+Dependency-ordered, checkable work items derived from the spec and plan.
+Work top to bottom; a phase starts only when the one before it is done.
+Replace the placeholder tasks below with real ones — keep the checkbox format,
+one task per line, exact file paths in the description.
+
+## Phases
+
+### Setup
+
+- [ ] T1: Prepare project scaffolding and test harness
+- [ ] T2: Create data structures / entities from the spec
+
+### Implementation
+
+- [ ] T3: Implement Story 1 happy path (test first)
+- [ ] T4: Implement edge cases and error handling for Story 1
+- [ ] T5: Wire the feature into the existing entry points
+
+### Polish
+
+- [ ] T6: Documentation touch-ups and final full test run
@@ -0,0 +1,31 @@
+# pantry-planner Constitution
+
+*Adopted: 2026-08-18 — version 1.0.0*
+
+Standing principles every feature in this project must respect. Specs, plans
+and tasks are checked against these articles; a violation needs an explicit,
+written justification or the work does not proceed.
+
+## Article I — Simplicity
+
+The smallest design that satisfies the spec wins. New layers, wrappers or
+abstractions require a demonstrated need, not an anticipated one.
+
+## Article II — Tests Prove Behavior
+
+No behavior ships without a test that failed before the behavior existed.
+
+## Article III — Minimal Blast Radius
+
+Touch only what the feature requires. Leave unrelated code, files and
+interfaces unchanged.
+
+## Article IV — Honest Artifacts
+
+Specs record what is actually decided; open questions are marked, not hidden.
+Task checkboxes reflect verified reality, not intentions.
+
+## Amendments
+
+Record changes here with date, version bump and one-line rationale.
+- 2026-08-18 — version 1.1.0: Article V — data stays in plain local files the user can read
@@ -0,0 +1,13 @@
+# Quality Checklist: 001-pantry-meal-planner
+
+*Created: 2026-08-18*
+
+Reviewer-owned quality gate for the written requirements — these boxes judge
+the spec text, not the implementation. Check an item only after actually
+reviewing it; add domain-specific items freely.
+
+- [x] Every user story has at least one concrete acceptance scenario
+- [x] Each requirement is verifiable (a test could pass or fail it)
+- [x] Success criteria are measurable without naming technologies
+- [x] All clarification markers are resolved or consciously accepted
+- [ ] Assumptions state the chosen default AND what was ruled out
@@ -0,0 +1,33 @@
+# Implementation Plan: 001-pantry-meal-planner
+
+*Created: 2026-08-18*
+
+Turn the spec into concrete technical decisions. Stay minimal: prefer the
+simplest structure that satisfies the spec, and justify anything that isn't.
+
+## Technical Context
+
+- Language: Python 3 (stdlib only)
+- Dependencies: none at runtime; pytest for tests
+- Storage: two JSON files in the project dir — pantry.json, recipes.json
+  (starter set written on first run)
+- Testing: pytest, TDD; planner logic tested against handwritten pantries
+
+## Structure
+
+```
+pantry_planner/
+  planner.py      # pantry CRUD, plan generation, shopping list derivation
+  cli.py          # argparse: pantry add/remove/list, plan, shoplist
+  recipes.json    # bundled starter set (10 recipes)
+  tests/test_planner.py
+```
+
+## Decisions
+
+- D1: Greedy day-by-day plan generation with stock simulation — because R2 only
+  demands feasibility, not optimality; rejected: constraint solver (overkill).
+- D2: JSON files over SQLite — because two flat collections with <1k entries
+  need no queries; rejected: SQLite (adds schema/migration weight).
+- D3: Shopping list = sum(plan needs) − stock, clamped at 0 per item (R3) —
+  computed on demand, never stored; rejected: persisting derived data.
@@ -0,0 +1,61 @@
+# Feature Specification: 001-pantry-meal-planner
+
+*Created: 2026-08-18*
+
+> Original request: pantry meal planner
+
+## User Stories
+
+### Story 1 — (P1)
+
+As a home cook, I want to record what is in my pantry, so that meal suggestions
+are based on what I actually have.
+
+**Acceptance:** Given an empty pantry list, when I add "500 g rice" and
+"2 cans tomatoes", then the pantry shows both items with their quantities.
+
+### Story 2 — (P1)
+
+As a home cook, I want a weekly plan of meals cookable from my pantry, so that
+I don't have to decide every evening.
+
+**Acceptance:** Given a pantry with rice, tomatoes and lentils, when I request
+a plan for 7 days, then every suggested meal uses only pantry items and no
+item is over-consumed across the week.
+
+### Story 3 — (P2)
+
+As a home cook, I want a shopping list for the gaps, so that one store visit
+covers the whole week.
+
+**Acceptance:** Given a 7-day plan that needs 3 onions while the pantry has 1,
+when I open the shopping list, then it shows "2 onions" and nothing already
+covered by the pantry.
+
+## Requirements
+
+- R1: The system must store pantry items as name + quantity + unit and support
+  add, update and remove.
+- R2: The system must generate a 7-day plan where each meal's ingredients are
+  fully covered by the current pantry stock minus what earlier meals in the
+  same plan consume.
+- R3: The system must derive a shopping list as the difference between a plan's
+  total ingredient needs and current stock.
+- R4: Recipes come from a local, user-editable recipe file; a starter set of
+  10 common recipes is bundled so the planner works out of the box.
+
+**Entities:** PantryItem (name, quantity, unit), Recipe (name, ingredients),
+MealPlan (7 ordered days -> recipe), ShoppingList (derived).
+
+## Success Criteria
+
+- S1: Recording a 10-item pantry takes under 2 minutes.
+- S2: A generated 7-day plan never references an ingredient with insufficient
+  stock at the point it is cooked.
+- S3: Buying exactly the shopping list makes every meal of the week cookable.
+
+## Assumptions
+
+- A1: Single household, single device, no sharing — fully local data.
+- A2: Quantities use metric units and piece counts; no unit conversion in v1.
+- A3: One meal per day is planned (dinner); breakfast/lunch out of scope.
@@ -0,0 +1,23 @@
+# Tasks: 001-pantry-meal-planner
+
+*Created: 2026-08-18*
+
+Dependency-ordered, checkable work items derived from the spec and plan.
+Work top to bottom; a phase starts only when the one before it is done.
+
+## Phases
+
+### Setup
+
+- [x] T1: Scaffold pantry_planner/ package with pytest harness and empty modules per plan Structure
+- [x] T2: Define PantryItem/Recipe dataclasses in pantry_planner/planner.py and JSON load/save for pantry.json + recipes.json (Story 1 entities)
+
+### Implementation
+
+- [x] T3: Story 1 — pantry CRUD in planner.py + `pantry add/remove/list` in cli.py, test-first (acceptance: add 500 g rice + 2 cans tomatoes, list shows both)
+- [ ] T4: Story 2 — 7-day plan generation with stock simulation in planner.py (test: no ingredient over-consumed across the week, R2/S2)
+- [ ] T5: Story 3 — shopping list derivation (plan needs − stock, clamp 0) + `shoplist` command (acceptance: 3 onions needed, 1 in stock → "2 onions")
+
+### Polish
+
+- [ ] T6: Bundle 10-recipe starter set (R4), README for the example, full test run