The product context layer for your AI agent.

## UltiPad product sync (MCP: ultipad)

### One-time setup — resolve your product
list_products → pick the product for this repo. Record it here and reuse for every call:
  This repo → product: <NAME>, productId: <ID>

### GATE 1 — STOP before writing any code or editing any file
Do these steps first, every time:
1. search_ideas — find if an idea exists for this work.
2. If no match: create_idea(title, description, ideaType, productIds:[<ID>],
   functionalSpec: "<the functional spec YOU write — markdown: behaviour, edge cases, acceptance>").
   The server does not draft specs for agent-created ideas. Note the ideaId.
3. set_success_metric(ideaId, name, direction, target, baseline?) — 1–3 metrics that show
   whether this work succeeded. Required for every idea; you choose them (e.g. error rate
   for a bug fix, adoption or latency for a feature). Skip only if the idea already has them.
4. report_dev_progress(ideaId, "started", agentModel, sessionId)
If idea has an approved spec: get_agent_spec(ideaId) and implement against it.

### GATE 2 — immediately after every git commit (before anything else)
```
git show --shortstat <sha>   # get additions/deletions/filesChanged
add_commit_ref(ideaId, sha, message, additions, deletions, filesChanged,
               agentModel="<your-model-id>", sessionId="<session-id>")
```
One call per commit. Do not batch. Do not defer.
If the commit fixes a bug, also pass a fix note so the next agent learns from it:
  resolution: { problem, rootCause, fix, failedAttempts, gotchas, tags }
No secrets or customer data in fix notes.

### Before debugging — search past fixes
search_fix_notes(query: "<symptom or error text>") before investigating any bug.

### After planning — save the plan, ask before stories
save_implementation_plan(ideaId, plan) — the full plan markdown, added as a dated
section in the idea's Functional Specs (never overwrites).
After ship: record_metric_reading(...) or POST /api/metrics/readings for the metrics
  you defined in GATE 1.
Do NOT create user stories on your own: ask the user; only if yes, add_user_story.

### While building (ongoing)
- add_user_story(ideaId) — only after the user asked for stories
- update_idea_details(ideaId, notes/targetOutcomes) — plans go through save_implementation_plan
- update_idea_scores(ideaId, impact, effort, confidence) — scale: 0 1 2 3 5 8 13 20 40 100
- get_product_overview + get_roadmap — read strategy before major decisions

### GATE 3 — after shipping
report_dev_progress(ideaId, "completed", agentModel, sessionId,
  actualOutcomes: "<delivery record YOU write — what shipped, how verified, what was deferred>")
set_idea_stage(ideaId, "Done") — starts the measurement window for your metrics.
update_idea_state(ideaId, "approved") if user approved the work.
Never write to another product's roadmap.

// .claude/settings.json (in your repo) — deterministic reminder so the agent
// never forgets to record commits against UltiPad ideas.
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command // empty' | grep -q 'git commit' && echo 'REMINDER: record this commit on its UltiPad idea via the ultipad MCP add_commit_ref tool (sha + message + webUrl + additions/deletions from git show --shortstat; add a resolution fix note if it fixes a bug).' || true"
          }
        ]
      }
    ]
  }
}