docs: align agent workflow with MVP planning

Update the live agent workflow to use the MVP implementation backlog and clarify how agents should handle MVP-scoped work.

- add MVP planning references to AGENTS.md
- expand docs/agent-workflow.md with task classification, scope control, docs-only validation, open-question corroboration, and multi-agent coordination guidance
- add plans/mvp-gap-analysis.md as the current-state assessment companion to the MVP scope and backlog

Author: juanmardefago

AGENTS.md

@@ -89,6 +89,15 @@ if err != nil {
 - Do not make insecure transport the default for code paths that may later be used outside local/demo workflows.
 - If plaintext or insecure TLS behavior is needed for local development, gate it behind explicit configuration and keep production-oriented defaults secure.
 
+## MVP Planning References
+
+For MVP-scoped work:
+
+- Use `docs/mvp-scope.md` as the target-state definition.
+- Use `plans/mvp-gap-analysis.md` for current-state assessment.
+- Use `plans/mvp-implementation-backlog.md` as the active execution backlog.
+- Treat `plans/implementation-backlog.md` as historical context unless explicitly requested.
+
 ## Notes
 
 - All builds must pass before committing

docs/agent-workflow.md

@@ -3,23 +3,79 @@
 This repo contains two complementary process documents:
 
 - `AGENTS.md`: repo-specific rules (commands, Go conventions, CLI flag validation patterns).
-- `plans/implementation-backlog.md`: the task list with per-task **Done when** + **Verify** criteria and a status table.
+- `plans/mvp-implementation-backlog.md`: the active MVP task list with per-task **Done when** + **Verify** criteria and a status table.
 
 This document defines the **step-by-step workflow** to implement backlog tasks consistently (human or LLM).
 
+Note on the backlog switch:
+
+- `plans/mvp-implementation-backlog.md` is now the active implementation backlog for MVP-scoped work.
+- `plans/implementation-backlog.md` remains useful historical context, but agents should not treat it as the primary task source for current MVP execution.
+
+## Scope of This Workflow
+
+This workflow defines the default execution behavior for MVP-scoped work.
+
+Authoritative planning documents for MVP work:
+
+- `docs/mvp-scope.md`: target-state definition
+- `plans/mvp-gap-analysis.md`: current-state assessment
+- `plans/mvp-implementation-backlog.md`: active execution backlog
+
+Historical context only:
+
+- `plans/implementation-backlog.md`
+
+Agents should treat `plans/mvp-implementation-backlog.md` as the primary task source unless the user explicitly asks for historical or pre-MVP planning context.
+
 ---
 
 ## 1) Pick a Task
 
-- Choose an `SDS-###` item from `plans/implementation-backlog.md`.
+- Choose an `MVP-###` item from `plans/mvp-implementation-backlog.md`.
 - Read its **Context**, **Done when**, and **Verify** sections.
 - If the task requires cross-repo coordination, confirm owners and dependencies first.
 
 ---
 
+## 1.5) Classify the Task Before Acting
+
+Before making changes, determine which kind of backlog item you are working on:
+
+- **Implementation task**:
+  - goal is code and behavior change
+  - complete the smallest change that satisfies **Done when**
+- **Open-question task**:
+  - goal is a documented decision, narrowed contract, or explicit recorded deferral
+  - do not silently choose an implementation-specific interpretation in code
+- **Validation/review task**:
+  - goal is to verify, review, or corroborate behavior against the backlog and current code
+  - do not broaden into implementation unless explicitly asked
+
+For every task, first extract and restate:
+
+- task ID
+- dependencies
+- assumptions
+- **Done when**
+- **Verify**
+- relevant MVP scenarios
+
+Keep this restatement brief and execution-oriented. It should be a short working summary, not a long analysis section.
+
+If a dependency is still unresolved and the current task cannot be completed safely without inventing semantics, mark the task `blocked` instead of coding around it.
+
+When an `open_question` task needs information beyond the repo:
+
+- use repo context first
+- when external research is available, prefer primary sources
+- record whether the result is a final decision, a narrowed contract, or a recommendation awaiting confirmation
+
+---
+
 ## 2) Update Status First
 
-In `plans/implementation-backlog.md`:
+In `plans/mvp-implementation-backlog.md`:
 
 - Set the chosen task `Status` to `in_progress` in the Status Tracker table.
 - If you cannot proceed, set `blocked` and add a short reason in the task’s section.
@@ -32,6 +88,15 @@ In `plans/implementation-backlog.md`:
 - Prefer fixing root causes over adding workarounds.
 - Keep changes narrowly scoped to the selected task (avoid drive-by refactors).
 
+### Scope Control Rules
+
+- Prefer one `MVP-###` task per implementation pass unless the backlog already makes a tightly-coupled dependency unavoidable.
+- Small supporting edits are acceptable when they are strictly necessary to satisfy the selected task’s **Done when** or **Verify** criteria.
+- Do not solve adjacent backlog items unless they are strictly required to satisfy the selected task’s **Done when** criteria.
+- Do not absorb a second meaningful backlog item just because it touches the same files or component.
+- Do not introduce new abstractions, helpers, configuration, or refactors unless they are necessary for the selected task.
+- If you discover a missing prerequisite or unresolved contract, stop, document it, and update the backlog/task state instead of embedding an implicit decision in code.
+
 Before writing code, run these quick checks:
 
 - **Domain type check**: is there already a repo-level type/helper for this domain (`sds.GRT`, address/signature helpers, etc.)?
@@ -67,6 +132,11 @@ Follow `AGENTS.md` guidance:
   - `go test ./...`
   - `go vet ./...`
 
+For docs-only, planning-only, or other non-code tasks:
+
+- run the task-specific verification that actually applies
+- do not treat `gofmt`, `go test ./...`, or `go vet ./...` as mandatory unless code changed
+
 If validation fails:
 
 - Fix the failure if it’s caused by your changes.
@@ -80,11 +150,18 @@ If validation fails:
 - Confirm the expected outcomes (return codes, error codes, logs, state changes).
 - If “Verify” is missing or insufficient, update the backlog entry to make it reproducible.
 
+If the task is an `open_question` item, corroboration should include the concrete output artifact:
+
+- updated docs or contract text
+- narrowed decision record
+- explicit deferral recorded in the backlog or docs
+- downstream task references updated to point at that output when needed
+
 ---
 
 ## 7) Mark Done
 
-In `plans/implementation-backlog.md`:
+In `plans/mvp-implementation-backlog.md`:
 
 - Set `Status` to `done` in the Status Tracker table.
 - Tick the task checkbox in its detailed section.
@@ -99,6 +176,20 @@ In `plans/implementation-backlog.md`:
 
 ---
 
+## 8.5) Multi-Agent Coordination
+
+When using multiple agents in parallel:
+
+- assign one primary `MVP-###` task per agent
+- use separate git worktrees when parallel agents may edit code concurrently
+- avoid overlapping file ownership unless one agent is review-only
+- assign one owner for updates to shared planning/status documents when multiple agents are active
+- only the assigned document owner should update shared status tables unless explicitly coordinated otherwise
+- prefer splitting by dependency boundary or component boundary, not by arbitrary file count
+- if a task changes shared contracts or protobufs, finish and merge that work before starting dependent implementation tasks
+
+---
+
 ## 9) Incorporate Review Learnings
 
 If you are implementing or revisiting code after reviewer feedback: