Merge pull request #16 from escoffier-labs/feat/brigade-work-sessions

feat: add brigade work sessions

Author: solomonneas

.gitignore

@@ -59,11 +59,12 @@ memory/20[0-9][0-9]-[0-1][0-9]-[0-3][0-9].md
 # Review inbox: ambiguous handoffs awaiting human triage. Private.
 memory/handoff-inbox/
 
-# brigade local state (logs, scrub cache, dogfood runs).
+# brigade local state (logs, scrub cache, dogfood runs, work sessions).
 .brigade/dogfood.toml
 .brigade/logs/
 .brigade/runs/
 .brigade/scrub-cache/
+.brigade/work/
 .solo-mise/logs/
 .solo-mise/scrub-cache/
 # <<< brigade gitignore block <<<

CHANGELOG.md

@@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `brigade runs latest` to show the newest run summary without copying a run path from `brigade runs list`.
 - `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.
 - 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

@@ -135,6 +135,8 @@ brigade dogfood
 brigade dogfood next
 brigade dogfood --target /path/to/repo
 brigade work status
+brigade work start "next slice"
+brigade work end --note "tests passed"
 ```
 
 `--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`.
@@ -156,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.
+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`.
 
 Inspect a completed run without opening each JSON file:
 

src/brigade/cli.py

@@ -114,6 +114,13 @@ def _build_parser() -> argparse.ArgumentParser:
     p_work_status = work_sub.add_parser("status", help="Show current repo and dogfood work state.")
     p_work_status.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace to inspect.")
     p_work_status.add_argument("--limit", type=int, default=12, help="Maximum dirty file entries to show.")
+    p_work_start = work_sub.add_parser("start", help="Start a local Brigade work session.")
+    p_work_start.add_argument("title", nargs="*", help="Optional session title.")
+    p_work_start.add_argument("--target", "-t", type=Path, default=Path("."), help="Repo or workspace for the session.")
+    p_work_start.add_argument("--force", action="store_true", help="Replace an existing active session pointer.")
+    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.")
 
     # run
     p_run = sub.add_parser("run", help="Run a bounded cross-model orchestration task.")
@@ -386,6 +393,11 @@ def main(argv=None) -> int:
 
         if args.work_command == "status":
             return work_cmd.status(target=args.target, limit=args.limit)
+        if args.work_command == "start":
+            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)
         parser.error(f"unknown work command: {args.work_command}")
         return 2
     if cmd == "run":

src/brigade/install.py

@@ -58,11 +58,12 @@ def build_gitignore_block(selection: Selection) -> str:
         "# Review inbox: ambiguous handoffs awaiting human triage.",
         "memory/handoff-inbox/",
         "",
-        "# brigade local state (logs, scrub cache, dogfood runs).",
+        "# brigade local state (logs, scrub cache, dogfood runs, work sessions).",
         ".brigade/dogfood.toml",
         ".brigade/logs/",
         ".brigade/runs/",
         ".brigade/scrub-cache/",
+        ".brigade/work/",
         GITIGNORE_END,
         "",
     ])

src/brigade/work_cmd.py

@@ -1,10 +1,14 @@
 """Daily work session helpers."""
 from __future__ import annotations
 
+import json
+import re
 import shutil
 import subprocess
 import sys
+from datetime import datetime, timezone
 from pathlib import Path
+from typing import Any
 
 from . import dogfood_cmd
 
@@ -34,6 +38,115 @@ def _short(text: str, limit: int = 96) -> str:
     return rendered[: limit - 3].rstrip() + "..."
 
 
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _slug(text: str) -> str:
+    value = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return value[:48].strip("-") or "work-session"
+
+
+def _work_root(target: Path) -> Path:
+    return target / ".brigade" / "work"
+
+
+def _current_path(target: Path) -> Path:
+    return _work_root(target) / "current"
+
+
+def _git_snapshot(target: Path) -> dict[str, Any]:
+    repo_root = _git_value(target, "rev-parse", "--show-toplevel")
+    if repo_root is None:
+        return {"available": False, "dirty_files": []}
+    branch = _git_value(target, "branch", "--show-current")
+    if branch is None:
+        branch = _git_value(target, "rev-parse", "--short", "HEAD") or "unknown"
+        branch = f"detached:{branch}"
+    status_out = _git_value(target, "status", "--short") or ""
+    return {
+        "available": True,
+        "repo": repo_root,
+        "branch": branch,
+        "dirty_files": status_out.splitlines(),
+    }
+
+
+def _dogfood_snapshot(target: Path) -> dict[str, Any]:
+    try:
+        effective_target, artifacts_dir, cfg = dogfood_cmd._load_effective_paths(target)
+    except (FileNotFoundError, ValueError) as exc:
+        return {"ready": False, "error": str(exc)}
+    latest = dogfood_cmd._latest_run(artifacts_dir)
+    snapshot: dict[str, Any] = {
+        "ready": dogfood_cmd.config_path(target).exists() and shutil.which("codex") is not None,
+        "config": str(dogfood_cmd.config_path(target)),
+        "target": str(effective_target),
+        "artifacts_dir": str(artifacts_dir),
+        "handoff_inbox": str(cfg.handoff_inbox) if cfg and cfg.handoff_inbox is not None else None,
+    }
+    if latest is None:
+        snapshot["latest_run"] = None
+        snapshot["next"] = None
+        return snapshot
+    latest_path, latest_meta = latest
+    snapshot["latest_run"] = {
+        "path": str(latest_path),
+        "started_at": latest_meta.get("started_at"),
+        "status": latest_meta.get("status"),
+        "task": latest_meta.get("task"),
+    }
+    snapshot["next"] = dogfood_cmd.extract_next_step(dogfood_cmd._read_final(latest_path))
+    return snapshot
+
+
+def _session_snapshot(target: Path) -> dict[str, Any]:
+    return {
+        "git": _git_snapshot(target),
+        "dogfood": _dogfood_snapshot(target),
+    }
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n")
+
+
+def _write_session_markdown(path: Path, *, title: str, payload: dict[str, Any], key: str) -> None:
+    snapshot = payload[key]
+    git = snapshot.get("git", {})
+    dogfood = snapshot.get("dogfood", {})
+    lines = [
+        f"# {title}",
+        "",
+        f"- Session: {payload['id']}",
+        f"- Target: {payload['target']}",
+        f"- Started: {payload['started_at']}",
+    ]
+    if payload.get("ended_at"):
+        lines.append(f"- Ended: {payload['ended_at']}")
+    if payload.get("title"):
+        lines.append(f"- Title: {payload['title']}")
+    if payload.get("note"):
+        lines.append(f"- Note: {payload['note']}")
+    lines.extend(["", "## Git", ""])
+    if git.get("available"):
+        lines.append(f"- Branch: {git.get('branch')}")
+        dirty = git.get("dirty_files") or []
+        lines.append(f"- Dirty files: {len(dirty)}")
+        for item in dirty[:20]:
+            lines.append(f"  - `{item}`")
+    else:
+        lines.append("- unavailable")
+    lines.extend(["", "## Dogfood", ""])
+    lines.append(f"- Ready: {dogfood.get('ready')}")
+    if dogfood.get("latest_run"):
+        latest = dogfood["latest_run"]
+        lines.append(f"- Latest run: {latest.get('started_at')} [{latest.get('status')}] {latest.get('path')}")
+    if dogfood.get("next"):
+        lines.append(f"- Next: {dogfood['next']}")
+    path.write_text("\n".join(lines) + "\n")
+
+
 def _print_dirty(lines: list[str], *, limit: int) -> None:
     print(f"dirty_files: {len(lines)}")
     for line in lines[:limit]:
@@ -43,6 +156,72 @@ def _print_dirty(lines: list[str], *, limit: int) -> None:
         print(f"  ... {remaining} more")
 
 
+def start(*, target: Path, title: str | None = None, force: bool = False) -> int:
+    target = target.expanduser().resolve()
+    if not target.is_dir():
+        print(f"error: --target is not a directory: {target}", file=sys.stderr)
+        return 2
+
+    root = _work_root(target)
+    current = _current_path(target)
+    if current.exists() and not force:
+        print(f"error: work session already active: {current.read_text().strip()}", file=sys.stderr)
+        return 2
+
+    started = _now()
+    session_id = f"{started.strftime('%Y%m%d-%H%M%S')}-{_slug(title or 'work-session')}"
+    session_dir = root / session_id
+    session_dir.mkdir(parents=True, exist_ok=False)
+    payload: dict[str, Any] = {
+        "id": session_id,
+        "title": title,
+        "target": str(target),
+        "status": "active",
+        "started_at": started.isoformat(),
+        "start": _session_snapshot(target),
+    }
+    _write_json(session_dir / "session.json", payload)
+    _write_session_markdown(session_dir / "start.md", title="Brigade Work Session Start", payload=payload, key="start")
+    current.write_text(session_id + "\n")
+    print(f"session: {session_dir}")
+    print(f"status: active")
+    return 0
+
+
+def end(*, target: Path, note: str | None = None) -> int:
+    target = target.expanduser().resolve()
+    if not target.is_dir():
+        print(f"error: --target is not a directory: {target}", file=sys.stderr)
+        return 2
+
+    current = _current_path(target)
+    if not current.exists():
+        print(f"error: no active work session in {_work_root(target)}", file=sys.stderr)
+        return 1
+    session_id = current.read_text().strip()
+    session_dir = _work_root(target) / session_id
+    session_json = session_dir / "session.json"
+    try:
+        payload = json.loads(session_json.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"error: invalid active work session: {exc}", file=sys.stderr)
+        return 2
+    if not isinstance(payload, dict):
+        print("error: invalid active work session: session.json must contain an object", file=sys.stderr)
+        return 2
+
+    payload["status"] = "ended"
+    payload["ended_at"] = _now().isoformat()
+    payload["note"] = note
+    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")
+    current.unlink()
+    print(f"session: {session_dir}")
+    print("status: ended")
+    return 0
+
+
 def status(*, target: Path, limit: int = 12) -> int:
     if limit < 1:
         print("error: --limit must be a positive integer", file=sys.stderr)

tests/test_gitignore.py

@@ -27,6 +27,7 @@ def test_init_creates_gitignore_when_missing(tmp_target: Path):
     assert "memory/handoff-inbox/" in gi
     assert ".brigade/dogfood.toml" in gi
     assert ".brigade/runs/" in gi
+    assert ".brigade/work/" in gi
 
 
 def test_init_appends_block_to_existing_gitignore(tmp_target: Path):
@@ -106,6 +107,7 @@ def test_gitignore_block_includes_claude_section_when_selected():
     assert "!.claude/memory-handoffs/TEMPLATE.md" in block
     assert ".brigade/dogfood.toml" in block
     assert ".brigade/runs/" in block
+    assert ".brigade/work/" in block
     assert ".codex/memory-handoffs" not in block
 
 
@@ -135,3 +137,4 @@ def test_install_writes_gitignore_block(tmp_path):
     assert ".codex/memory-handoffs/*" in gi
     assert ".brigade/dogfood.toml" in gi
     assert ".brigade/runs/" in gi
+    assert ".brigade/work/" in gi