feat: write brigade work handoffs

Author: solomonneas

CHANGELOG.md

@@ -29,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `brigade runs show <run-dir>` to print a readable summary of one run artifact directory.
 - `brigade work status` to report the current repo branch, dirty files, dogfood readiness, latest run, and extracted next step for daily work sessions.
 - `brigade work start` and `brigade work end` to create local `.brigade/work/` session artifacts for normal daily work loops.
+- `brigade work end --handoff` to write a Memory Handoff from closed work session artifacts.
 - Roster-level and per-agent `timeout_seconds` controls for bounded CLI calls.
 - `brigade run --read-only` prompt policy for planning and review runs that should inspect and recommend only, with native `codex exec --sandbox read-only` enforcement for Codex agents.
 

README.md

@@ -136,7 +136,7 @@ brigade dogfood next
 brigade dogfood --target /path/to/repo
 brigade work status
 brigade work start "next slice"
-brigade work end --note "tests passed"
+brigade work end --note "tests passed" --handoff
 ```
 
 `--dry-run` prints the planned assignments as JSON and stops before worker dispatch. `--show-plan` prints assignments before a normal run. `--verbose` prints the plan, worker statuses, and synthesis status. `--cwd` sets the working directory for the agent CLI calls and defaults to the current directory. `--handoff` writes a Memory Handoff for a successful non-dry run. `--inspect` prints the same readable artifact summary as `brigade runs show` after the run completes. `--read-only` tells the orchestrator and workers to inspect and recommend only, without modifying files or external state. For `codex` agents, Brigade also passes `codex exec --sandbox read-only`; other adapters receive the prompt policy only. The `cli` values are adapters for installed command-line tools: `codex`, `claude`, and `ollama:<model>`. Pick the ones you already use. Brigade shells out to those tools and keeps no provider keys. `brigade roster doctor` validates the roster syntax and reports which CLIs are present on `PATH`.
@@ -158,7 +158,7 @@ CLI runs write artifacts by default under `.brigade/runs/<id>` below `--cwd`; do
 
 Use `--output-dir <path>` to pick the artifact directory, or `--no-artifacts` for a throwaway run.
 
-Use `brigade work status` as the quick daily dashboard for a repo. It reports the current branch, dirty files, dogfood readiness, configured dogfood paths, latest dogfood run, and extracted next step without starting a new orchestration. `brigade work start "title"` opens a local work session under `.brigade/work/<id>/`, records the starting git and dogfood context, and writes `start.md`. `brigade work end --note "what happened"` closes the active session, records ending context, and writes `end.md`.
+Use `brigade work status` as the quick daily dashboard for a repo. It reports the current branch, dirty files, dogfood readiness, configured dogfood paths, latest dogfood run, and extracted next step without starting a new orchestration. `brigade work start "title"` opens a local work session under `.brigade/work/<id>/`, records the starting git and dogfood context, and writes `start.md`. `brigade work end --note "what happened"` closes the active session, records ending context, and writes `end.md`. Add `--handoff` to also write a Memory Handoff for the closed session; it defaults to the configured dogfood handoff inbox or `.claude/memory-handoffs`.
 
 Inspect a completed run without opening each JSON file:
 

src/brigade/cli.py

@@ -121,6 +121,13 @@ def _build_parser() -> argparse.ArgumentParser:
     p_work_end = work_sub.add_parser("end", help="End the active local Brigade work session.")
     p_work_end.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace for the session.")
     p_work_end.add_argument("--note", default=None, help="Optional closing note.")
+    p_work_end.add_argument("--handoff", action="store_true", help="Write a Memory Handoff for the ended session.")
+    p_work_end.add_argument(
+        "--handoff-inbox",
+        type=Path,
+        default=None,
+        help="Memory Handoff inbox. Defaults to configured dogfood inbox or .claude/memory-handoffs.",
+    )
 
     # run
     p_run = sub.add_parser("run", help="Run a bounded cross-model orchestration task.")
@@ -397,7 +404,12 @@ def main(argv=None) -> int:
             title = " ".join(args.title) if args.title else None
             return work_cmd.start(target=args.target, title=title, force=args.force)
         if args.work_command == "end":
-            return work_cmd.end(target=args.target, note=args.note)
+            return work_cmd.end(
+                target=args.target,
+                note=args.note,
+                handoff=args.handoff,
+                handoff_inbox=args.handoff_inbox,
+            )
         parser.error(f"unknown work command: {args.work_command}")
         return 2
     if cmd == "run":

src/brigade/work_cmd.py

@@ -9,6 +9,7 @@
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
+from uuid import uuid4
 
 from . import dogfood_cmd
 
@@ -147,6 +148,95 @@ def _write_session_markdown(path: Path, *, title: str, payload: dict[str, Any],
     path.write_text("\n".join(lines) + "\n")
 
 
+def _handoff_inbox(target: Path, payload: dict[str, Any], override: Path | None) -> Path:
+    if override is not None:
+        return override.expanduser()
+    dogfood = payload.get("end", {}).get("dogfood", {})
+    configured = dogfood.get("handoff_inbox")
+    if isinstance(configured, str) and configured:
+        return Path(configured).expanduser()
+    return target / ".claude" / "memory-handoffs"
+
+
+def _write_work_handoff(target: Path, session_dir: Path, payload: dict[str, Any], inbox: Path) -> Path:
+    ended = payload.get("ended_at") or _now().isoformat()
+    ended_slug = re.sub(r"[^0-9]", "", str(ended))[:12] or _now().strftime("%Y%m%d%H%M")
+    title = payload.get("title") or payload.get("id") or "work-session"
+    path = inbox / f"{ended_slug}-brigade-work-{_slug(str(title))}-{uuid4().hex[:6]}.md"
+    end_snapshot = payload.get("end", {})
+    git = end_snapshot.get("git", {})
+    dogfood = end_snapshot.get("dogfood", {})
+    dirty = git.get("dirty_files") if isinstance(git, dict) else []
+    dirty_lines = "\n".join(f"  - `{item}`" for item in dirty[:20]) if isinstance(dirty, list) else "  - unavailable"
+    latest = dogfood.get("latest_run") if isinstance(dogfood, dict) else None
+    latest_line = "- latest run: none"
+    if isinstance(latest, dict):
+        latest_line = f"- latest run: `{latest.get('path')}` ({latest.get('status')})"
+    next_step = dogfood.get("next") if isinstance(dogfood, dict) else None
+    next_line = f"- next: {next_step}" if next_step else "- next: none extracted"
+    note = payload.get("note") or ""
+    document_content = f"""### Brigade work session: {payload.get('id')}
+- target: `{target}`
+- session artifacts: `{session_dir}`
+- branch: {git.get('branch') if isinstance(git, dict) else 'unknown'}
+- dirty files: {len(dirty) if isinstance(dirty, list) else 'unknown'}
+{latest_line}
+{next_line}
+"""
+    if note:
+        document_content += f"- note: {note}\n"
+    body = f"""# Memory Handoff
+
+## Type
+
+workflow
+
+## Title
+
+Brigade work session ended: {_slug(str(title))}
+
+## Summary
+
+A Brigade work session was ended and local session artifacts were written. This handoff captures the session path, final git state, latest dogfood run, and extracted next step so the memory owner can route durable workflow context.
+
+## Durable facts
+
+- session: `{payload.get('id')}`
+- target: `{target}`
+- session artifacts: `{session_dir}`
+- status: {payload.get('status')}
+- started: {payload.get('started_at')}
+- ended: {payload.get('ended_at')}
+- note: {note or 'none'}
+- branch: {git.get('branch') if isinstance(git, dict) else 'unknown'}
+- dirty files:
+{dirty_lines}
+{latest_line}
+{next_line}
+
+## Evidence
+
+- session.json: `{session_dir / 'session.json'}`
+- start summary: `{session_dir / 'start.md'}`
+- end summary: `{session_dir / 'end.md'}`
+
+## Recommended memory action
+
+no-card
+
+## Target document
+
+.learnings/LEARNINGS.md
+
+## Suggested document content
+
+{document_content.strip()}
+"""
+    inbox.mkdir(parents=True, exist_ok=True)
+    path.write_text(body)
+    return path
+
+
 def _print_dirty(lines: list[str], *, limit: int) -> None:
     print(f"dirty_files: {len(lines)}")
     for line in lines[:limit]:
@@ -188,7 +278,7 @@ def start(*, target: Path, title: str | None = None, force: bool = False) -> int
     return 0
 
 
-def end(*, target: Path, note: str | None = None) -> int:
+def end(*, target: Path, note: str | None = None, handoff: bool = False, handoff_inbox: Path | None = None) -> int:
     target = target.expanduser().resolve()
     if not target.is_dir():
         print(f"error: --target is not a directory: {target}", file=sys.stderr)
@@ -216,8 +306,15 @@ def end(*, target: Path, note: str | None = None) -> int:
     payload["end"] = _session_snapshot(target)
     _write_json(session_json, payload)
     _write_session_markdown(session_dir / "end.md", title="Brigade Work Session End", payload=payload, key="end")
+    if handoff:
+        inbox = _handoff_inbox(target, payload, handoff_inbox)
+        handoff_path = _write_work_handoff(target, session_dir, payload, inbox)
+        payload["handoff"] = str(handoff_path)
+        _write_json(session_json, payload)
     current.unlink()
     print(f"session: {session_dir}")
+    if handoff:
+        print(f"handoff: {payload['handoff']}")
     print("status: ended")
     return 0
 

tests/test_work_cmd.py

@@ -126,6 +126,32 @@ def test_work_end_closes_active_session(tmp_path, monkeypatch, capsys):
     assert "done for now" in (session_dir / "end.md").read_text()
 
 
+def test_work_end_can_write_handoff(tmp_path, monkeypatch, capsys):
+    _init_git_repo(tmp_path)
+    times = iter(
+        [
+            datetime(2026, 5, 26, 12, 0, 0, tzinfo=timezone.utc),
+            datetime(2026, 5, 26, 13, 0, 0, tzinfo=timezone.utc),
+        ]
+    )
+    monkeypatch.setattr(work_cmd, "_now", lambda: next(times))
+    assert work_cmd.start(target=tmp_path, title="Build Work Loop") == 0
+
+    inbox = tmp_path / "handoffs"
+    assert work_cmd.end(target=tmp_path, note="done for now", handoff=True, handoff_inbox=inbox) == 0
+    out = capsys.readouterr().out
+    assert "handoff:" in out
+    handoffs = list(inbox.glob("*-brigade-work-build-work-loop-*.md"))
+    assert len(handoffs) == 1
+    handoff = handoffs[0].read_text()
+    assert "# Memory Handoff" in handoff
+    assert "Brigade work session ended" in handoff
+    assert "done for now" in handoff
+    session_dir = tmp_path / ".brigade" / "work" / "20260526-120000-build-work-loop"
+    payload = json.loads((session_dir / "session.json").read_text())
+    assert payload["handoff"] == str(handoffs[0])
+
+
 def test_work_end_reports_no_active_session(tmp_path, capsys):
     _init_git_repo(tmp_path)
 
@@ -161,8 +187,31 @@ def fake_end(**kwargs):
     monkeypatch.setattr(work_cmd, "end", fake_end)
 
     assert cli.main(["work", "start", "Build", "Loop", "--target", str(tmp_path), "--force"]) == 0
-    assert cli.main(["work", "end", "--target", str(tmp_path), "--note", "done"]) == 0
+    assert (
+        cli.main(
+            [
+                "work",
+                "end",
+                "--target",
+                str(tmp_path),
+                "--note",
+                "done",
+                "--handoff",
+                "--handoff-inbox",
+                str(tmp_path / "handoffs"),
+            ]
+        )
+        == 0
+    )
     assert seen == [
         ("start", {"target": tmp_path, "title": "Build Loop", "force": True}),
-        ("end", {"target": tmp_path, "note": "done"}),
+        (
+            "end",
+            {
+                "target": tmp_path,
+                "note": "done",
+                "handoff": True,
+                "handoff_inbox": tmp_path / "handoffs",
+            },
+        ),
     ]