282 lines
13 KiB
Markdown
282 lines
13 KiB
Markdown
# Agent Instructions
|
||
|
||
This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
|
||
|
||
## Build & Test
|
||
|
||
```bash
|
||
cargo build --release # Build binary
|
||
cargo test # Run unit tests
|
||
./target/release/nutrition-mcp # Run server (needs env vars)
|
||
```
|
||
|
||
### Smoke Test
|
||
|
||
```bash
|
||
# Start server
|
||
NUTRITION_MCP_BIND=127.0.0.1:9432 NUTRITION_MCP_API_KEY=test \
|
||
NUTRITION_MCP_DB_PATH=/tmp/test.db ./target/release/nutrition-mcp &
|
||
|
||
# Health check
|
||
curl http://127.0.0.1:9432/health
|
||
|
||
# MCP initialize
|
||
curl -X POST http://127.0.0.1:9432/mcp \
|
||
-H "Authorization: Bearer test" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Accept: application/json, text/event-stream" \
|
||
-d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}},"id":1}'
|
||
```
|
||
|
||
## Architecture Overview
|
||
|
||
MCP server exposing 13 tools for personal nutrition tracking. Streamable HTTP transport with Bearer token auth.
|
||
|
||
### Module Map
|
||
|
||
```
|
||
src/
|
||
├── main.rs — Entry point: axum server, auth middleware, /health endpoint
|
||
├── config.rs — Config struct from env vars (bind, api_key, db_path, user_agent)
|
||
├── db.rs — SQLite schema, migrations, DbPool type, TRACKED_NUTRIENTS const, DEFAULT_GOALS_JSON
|
||
├── api.rs — OffClient: Search-a-licious + v3 barcode + SQLite cache (FTS5)
|
||
└── tools.rs — NutritionServer: 13 MCP tools via #[tool_router] + ServerHandler impl
|
||
```
|
||
|
||
### SQLite Schema
|
||
|
||
- **products** — OFF cache: code (PK), product_name, brands, nutriments (JSON), serving_quantity, serving_size, image_url
|
||
- **products_fts** — FTS5 virtual table on product_name (synced via triggers)
|
||
- **entries** — Food log: id, date, meal, product_code, food_name, grams, servings, nutriments (JSON, scaled to portion)
|
||
- **daily_goal** — Single row (id=1), goals JSON with 14 nutrient targets
|
||
- **weight_log** — id, date, weight_kg
|
||
|
||
### Nutrient Storage
|
||
|
||
All nutrients stored as JSON blob in `nutriments` TEXT column (verbatim from OFF API). Daily summaries use `json_extract()` or Rust-side parsing to aggregate the 14 tracked nutrients.
|
||
|
||
### Portion Scaling
|
||
|
||
Nutrients are stored per-100g in OFF data. When logging, `scale_nutriments()` multiplies each value by `grams / 100.0`. For servings, grams = `servings * serving_quantity`.
|
||
|
||
### Meal Auto-Detection
|
||
|
||
- breakfast: before 11:00
|
||
- lunch: 11:00–15:00
|
||
- dinner: 15:00–21:00
|
||
- snack: after 21:00
|
||
|
||
## Conventions & Patterns
|
||
|
||
- **JSON nutriments** — Never hardcode nutrient columns. Store OFF nutriments verbatim as JSON, query at runtime.
|
||
- **"no data" vs 0** — Micronutrients (potassium, calcium, magnesium) are sparse in OFF. Summary shows `"no data"` when no entries have the nutrient, not 0.
|
||
- **Env vars only** — No config files. All settings via environment variables.
|
||
- **API-first** — Always check SQLite cache first, fall back to OFF API, cache results.
|
||
- **User-Agent** — Always send custom User-Agent to OFF API (good citizenship).
|
||
|
||
## Tracked Nutrients (14)
|
||
|
||
```
|
||
energy_kcal → energy-kcal_100g
|
||
protein → proteins_100g
|
||
carbohydrates → carbohydrates_100g
|
||
fat → fat_100g
|
||
fiber → fiber_100g
|
||
sugars → sugars_100g
|
||
saturated_fat → saturated-fat_100g
|
||
salt → salt_100g
|
||
fructose → fructose_100g (gout)
|
||
alcohol → alcohol_100g (gout)
|
||
potassium → potassium_100g (hypertension)
|
||
calcium → calcium_100g (hypertension)
|
||
magnesium → magnesium_100g (hypertension)
|
||
cholesterol → cholesterol_100g (hypertension)
|
||
```
|
||
|
||
## Non-Interactive Shell Commands
|
||
|
||
**ALWAYS use non-interactive flags** to avoid hanging on confirmation prompts.
|
||
|
||
```bash
|
||
cp -f source dest # NOT: cp source dest
|
||
rm -f file # NOT: rm file
|
||
```
|
||
|
||
## Session Completion
|
||
|
||
1. **File issues for remaining work** - `bd create` for follow-up items
|
||
2. **Run quality gates** - `cargo build --release && cargo test`
|
||
3. **Close completed issues** - `bd close <id1> <id2> ...`
|
||
4. **PUSH** - `git add -A && git commit -m "..." && git push`
|
||
5. **Verify** - `git status` must show clean working tree
|
||
|
||
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:970c3bf2 -->
|
||
## Beads Issue Tracker
|
||
|
||
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
|
||
|
||
### Quick Reference
|
||
|
||
```bash
|
||
bd ready # Find available work
|
||
bd show <id> # View issue details
|
||
bd update <id> --claim # Claim work
|
||
bd close <id> # Complete work
|
||
```
|
||
|
||
### Rules
|
||
|
||
- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
|
||
- Run `bd prime` for detailed command reference and session close protocol
|
||
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
|
||
|
||
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
|
||
|
||
## Agent Context Profiles
|
||
|
||
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
|
||
|
||
- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
|
||
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
|
||
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
|
||
|
||
## Session Completion
|
||
|
||
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
|
||
|
||
1. **File issues for remaining work** - Create beads for anything that needs follow-up
|
||
2. **Run quality gates** (if code changed) - Tests, linters, builds
|
||
3. **Update issue status** - Close finished work, update in-progress items
|
||
4. **Handle git/sync by active profile**:
|
||
```bash
|
||
# Conservative/minimal/default: report status and proposed commands; wait for approval.
|
||
git status
|
||
|
||
# Team-maintainer opt-in only, unless current instructions forbid it:
|
||
git pull --rebase
|
||
bd dolt push
|
||
git push
|
||
git status
|
||
```
|
||
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
|
||
|
||
**Critical rules:**
|
||
- Explicit user or orchestrator instructions override this Beads block.
|
||
- Do not commit or push without clear authority from the active profile or the current user request.
|
||
- If a required sync or push is blocked, stop and report the exact command and error.
|
||
<!-- END BEADS INTEGRATION -->
|
||
|
||
<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
|
||
## Beads Issue Tracker
|
||
|
||
Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations.
|
||
|
||
### Quick Reference
|
||
|
||
```bash
|
||
bd ready # Find available work
|
||
bd show <id> # View issue details
|
||
bd update <id> --claim # Claim work
|
||
bd close <id> # Complete work
|
||
bd prime # Refresh Beads context
|
||
```
|
||
|
||
### Rules
|
||
|
||
- Use `bd` for all task tracking; do not create markdown TODO lists.
|
||
- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them.
|
||
- Keep persistent project memory in Beads via `bd remember`; do not create ad hoc memory files.
|
||
|
||
**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
|
||
<!-- END BEADS CODEX SETUP -->
|
||
|
||
<!-- bv-agent-instructions-v3 -->
|
||
|
||
---
|
||
|
||
## Beads Workflow Integration
|
||
|
||
This project uses [beads_rust](https://github.com/Dicklesworthstone/beads_rust) (`br`) for issue tracking and [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) (`bv`) for graph-aware triage. Issues are stored in `.beads/` and tracked in git. Current `br` workspaces normally export `.beads/issues.jsonl`; older `bd`/legacy workspaces may use `.beads/beads.jsonl`. `bv` auto-discovers the supported JSONL files, so agents should use `br`/`bv` commands instead of hard-coding a single filename.
|
||
|
||
### Using bv as an AI sidecar
|
||
|
||
bv is a graph-aware triage engine for Beads projects. Instead of parsing .beads/issues.jsonl / .beads/beads.jsonl directly or hallucinating graph traversal, use robot flags for deterministic, dependency-aware outputs with precomputed metrics (PageRank, betweenness, critical path, cycles, HITS, eigenvector, k-core).
|
||
|
||
**Scope boundary:** bv handles *what to work on* (triage, priority, planning). `br` handles creating, modifying, and closing beads.
|
||
|
||
**CRITICAL: Use ONLY --robot-* flags. Bare bv launches an interactive TUI that blocks your session.**
|
||
|
||
#### The Workflow: Start With Triage
|
||
|
||
**`bv --robot-triage` is your single entry point.** It returns everything you need in one call:
|
||
- `quick_ref`: at-a-glance counts + top 3 picks
|
||
- `recommendations`: ranked actionable items with scores, reasons, unblock info
|
||
- `quick_wins`: low-effort high-impact items
|
||
- `blockers_to_clear`: items that unblock the most downstream work
|
||
- `project_health`: status/type/priority distributions, graph metrics
|
||
- `commands`: copy-paste shell commands for next steps
|
||
|
||
```bash
|
||
bv --robot-triage # THE MEGA-COMMAND: start here
|
||
bv --robot-next # Minimal: just the single top pick + claim command
|
||
|
||
# Token-optimized output (TOON) for lower LLM context usage:
|
||
bv --robot-triage --format toon
|
||
```
|
||
|
||
Before claiming, verify current state with `br show <id> --json` or `br ready --json`. `recommendations` can include graph-important blocked or assigned work; only `quick_ref.top_picks` and non-empty `claim_command` fields represent claimable work.
|
||
|
||
#### Other bv Commands
|
||
|
||
| Command | Returns |
|
||
|---------|---------|
|
||
| `--robot-plan` | Parallel execution tracks with unblocks lists |
|
||
| `--robot-priority` | Priority misalignment detection with confidence |
|
||
| `--robot-insights` | Full metrics: PageRank, betweenness, HITS, eigenvector, critical path, cycles, k-core |
|
||
| `--robot-alerts` | Stale issues, blocking cascades, priority mismatches |
|
||
| `--robot-suggest` | Hygiene: duplicates, missing deps, label suggestions, cycle breaks |
|
||
| `--robot-diff --diff-since <ref>` | Changes since ref: new/closed/modified issues |
|
||
| `--robot-graph [--graph-format=json\|dot\|mermaid]` | Dependency graph export |
|
||
|
||
#### Scoping & Filtering
|
||
|
||
```bash
|
||
bv --robot-plan --label backend # Scope to label's subgraph
|
||
bv --robot-insights --as-of HEAD~30 # Historical point-in-time
|
||
bv --recipe actionable --robot-plan # Pre-filter: ready to work (no blockers)
|
||
bv --recipe high-impact --robot-triage # Pre-filter: top PageRank scores
|
||
```
|
||
|
||
### br Commands for Issue Management
|
||
|
||
```bash
|
||
br ready --json # Show issues ready to work (no blockers)
|
||
br list --status=open --json # All open issues
|
||
br show <id> --json # Full issue details with dependencies
|
||
br create --title="..." --type=task --priority=2 --json
|
||
br update <id> --status=in_progress --json
|
||
br close <id> --reason="Completed" --json
|
||
br close <id1> <id2> --reason="Completed" --json
|
||
br sync --flush-only # Export DB to JSONL after Beads mutations
|
||
```
|
||
|
||
### Workflow Pattern
|
||
|
||
1. **Triage**: Run `bv --robot-triage` to find the highest-impact actionable work
|
||
2. **Claim**: Use `br update <id> --status=in_progress --json`
|
||
3. **Work**: Implement the task
|
||
4. **Complete**: Use `br close <id> --reason="Completed" --json`
|
||
5. **Sync**: Run `br sync --flush-only` after Beads mutations so the JSONL export is current
|
||
|
||
### Key Concepts
|
||
|
||
- **Dependencies**: Issues can block other issues. `br ready --json` shows only unblocked work.
|
||
- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
|
||
- **Types**: task, bug, feature, epic, chore, docs, question
|
||
- **Blocking**: `br dep add <issue> <depends-on>` to add dependencies
|
||
|
||
### Git Policy
|
||
|
||
`br` never commits or pushes. Follow this repository's own git instructions before staging, committing, or pushing. If the repository says "commit only when asked," that rule overrides any generic workflow advice.
|
||
|
||
<!-- end-bv-agent-instructions -->
|