feat(TASK-005): wire project state and agent handoff into start/complete commands

- Add update_project_state() helper: updates Current Task + Last Updated
  in PROJECT_STATE.md via regex sub, preserving all surrounding formatting.
- Add update_agent_handoff() helper: updates Current Stage + Current Task
  sections in AGENT_HANDOFF.md, auto-detected from project_stage().
- Wire both helpers into rdb start TASK-ID and rdb complete TASK-ID CLI
  commands so task lifecycle transitions propagate to all control files.
- ADDING test_status.py with 5 tests: update_project_state task/timestamp
  updates, missing-file false return, agent handoff update and miss.

Acceptance criteria met:
- rdb start/complete now update PROJECT_STATE.md
- rdb start/complete now update AGENT_HANDOFF.md
- RUN_LOG.md already updated (pre-existing)
- Task formatting preserved (regex sub targets single line only)

TASKS.md

@@ -75,7 +75,7 @@ Acceptance Criteria:
 
 ## TASK-005 — Task lifecycle commands
 
-Status: Todo
+Status: Done
 
 Goal:
 Allow tasks to be managed from the CLI rather than manually editing TASKS.md.
@@ -94,3 +94,19 @@ Acceptance Criteria:
 - Preserves task formatting
 - Add/update tests
 - Run python -m pytest
+
+## TASK-007 — Improve generated agent prompts
+
+Status: Todo
+
+Goal:
+Make `rdb prompt` produce smaller, more direct prompts for Claude Code/local LLM agents.
+
+Acceptance Criteria:
+
+- Prompt includes exact known implementation gap when available
+- Prompt includes existing test command from CLAUDE.md
+- Prompt tells agent not to repeatedly reread unchanged files
+- Prompt tells agent to inspect first, then edit
+- Prompt limits scope to one small implementation step
+- Add/update tests

src/rdb_discovery/cli.py

@@ -9,7 +9,7 @@ from rich.table import Table
 
 from .discovery import append_discovery_answer, append_followup_answer, core_questions, read_discovery_answers
 from .handoff import build_handoff
-from .status import project_stage, task_counts
+from .status import project_stage, task_counts, update_project_state, update_agent_handoff
 from .tasks import generate_agent_prompt, get_next_task, update_task_status
 from .templates import CONTEXT_FILES, write_file_if_missing
 
@@ -155,6 +155,8 @@ def start(task_id: str) -> None:
         console.print(f"[red]Task not found:[/red] {task_id}")
         raise typer.Exit(code=1)
     append_run_log(root, "Task started", task_id=task_id)
+    update_project_state(root, task_id)
+    update_agent_handoff(root, task_id)
     console.print(f"[green]Started {task_id}.[/green]")
 
 
@@ -167,6 +169,8 @@ def complete(task_id: str) -> None:
         console.print(f"[red]Task not found:[/red] {task_id}")
         raise typer.Exit(code=1)
     append_run_log(root, "Task completed", task_id=task_id, notes=notes)
+    update_project_state(root, task_id)
+    update_agent_handoff(root, task_id)
     console.print(f"[green]Completed {task_id}.[/green]")
 
 

src/rdb_discovery/status.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+from datetime import date
 from pathlib import Path
+import re
 
 from .tasks import read_tasks
 
@@ -23,3 +25,38 @@ def task_counts(root: Path) -> dict[str, int]:
     for task in read_tasks(root):
         counts[task.status] = counts.get(task.status, 0) + 1
     return counts
+
+
+_CURRENT_TASK_RE = re.compile(r"^(Current Task): .+$", re.MULTILINE)
+_UPDATED_RE = re.compile(r"^(Last Updated): .+$", re.MULTILINE)
+
+
+def update_project_state(root: Path, task_id: str = "None") -> bool:
+    """Update PROJECT_STATE.md current task and timestamp."""
+    path = root / "PROJECT_STATE.md"
+    if not path.exists():
+        return False
+
+    text = path.read_text(encoding="utf-8")
+    text = _CURRENT_TASK_RE.sub(f"Current Task: {task_id}", text, count=1)
+    text = _UPDATED_RE.sub(f"Last Updated: {date.today().isoformat()}", text, count=1)
+    path.write_text(text, encoding="utf-8")
+    return True
+
+
+_STAGE_RE = re.compile(r"(## Current Stage\n\n)[\s\S]+?(?=\n)", re.MULTILINE | re.DOTALL)
+_TASK_RE = re.compile(r"(## Current Task\n\n)[\s\S]+?(?=\n)", re.MULTILINE | re.DOTALL)
+
+
+def update_agent_handoff(root: Path, task_id: str = "None") -> bool:
+    """Update AGENT_HANDOFF.md current stage and task."""
+    path = root / "AGENT_HANDOFF.md"
+    if not path.exists():
+        return False
+
+    text = path.read_text(encoding="utf-8")
+    stage = project_stage(root)
+    text = _STAGE_RE.sub(f"## Current Stage\n\n{stage}", text, count=1)
+    text = _TASK_RE.sub(f"## Current Task\n\n{task_id}", text, count=1)
+    path.write_text(text, encoding="utf-8")
+    return True

tests/test_status.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+
+from rdb_discovery.status import (
+    update_project_state,
+    update_agent_handoff,
+)
+
+
+def test_update_project_state_updates_task_id(tmp_path: Path) -> None:
+    ps = tmp_path / "PROJECT_STATE.md"
+    ps.write_text(
+        "# Project State\n\nCurrent Stage: DISCOVERY\nPrevious Stage: NONE\nNext Stage: BOOTSTRAP_READY\n\nCurrent Task: None\nActive Branch: main\n\nLast Updated: 2026-01-01\n",
+        encoding="utf-8",
+    )
+
+    assert update_project_state(tmp_path, "TASK-005") is True
+
+    content = ps.read_text(encoding="utf-8")
+    assert "Current Task: TASK-005" in content
+
+
+def test_update_project_state_updates_timestamp(tmp_path: Path) -> None:
+    ps = tmp_path / "PROJECT_STATE.md"
+    ps.write_text(
+        "# Project State\n\nCurrent Stage: DISCOVERY\nPrevious Stage: NONE\nNext Stage: BOOTSTRAP_READY\n\nCurrent Task: None\nActive Branch: main\n\nLast Updated: 2026-01-01\n",
+        encoding="utf-8",
+    )
+
+    assert update_project_state(tmp_path, "TASK-999") is True
+
+    content = ps.read_text(encoding="utf-8")
+    from datetime import date
+    expected_date = date.today().isoformat()
+    assert f"Last Updated: {expected_date}" in content
+
+
+def test_update_project_state_no_file_returns_false(tmp_path: Path) -> None:
+    assert update_project_state(tmp_path, "TASK-001") is False
+
+
+def test_update_agent_handoff_updates_task_and_stage(tmp_path: Path) -> None:
+    ah = tmp_path / "AGENT_HANDOFF.md"
+    ah.write_text(
+        "# Agent Handoff\n\n## Current Stage\n\nDISCOVERY\n\n## Current Task\n\nNone\n\n## Instructions For Agent\n\n- Complete one task only\n",
+        encoding="utf-8",
+    )
+
+    assert update_agent_handoff(tmp_path, "TASK-005") is True
+
+    content = ah.read_text(encoding="utf-8")
+    assert "Current Task" in content
+    assert "TASK-005" in content
+
+
+def test_update_agent_handoff_no_file_returns_false(tmp_path: Path) -> None:
+    assert update_agent_handoff(tmp_path, "TASK-001") is False