brigade-cli 0.5.0__py3-none-any.whl

brigade/reconfigure.py

@@ -0,0 +1,64 @@
+"""brigade reconfigure - adjust an existing install to a new Selection."""
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+
+from .config import Config, load_config, write_config
+from .install import apply_gitignore, install_selection, resolve_manifests
+from .selection import Selection
+
+
+_WRITER_DIRS = {
+    "claude": ".claude",
+    "codex": ".codex",
+}
+_READER_DIRS = {
+    "openclaw": ".brigade/openclaw",
+    "hermes": ".brigade/hermes",
+}
+_HARNESS_BRIDGE_FILES = {
+    "claude": ["CLAUDE.md"],
+    "codex": [],
+}
+
+
+def reconfigure(target: Path, new_selection: Selection, prune: bool) -> int:
+    target = target.expanduser().resolve()
+    new_selection.validate()
+    existing = load_config(target)
+    old_harnesses = set(existing.selection.harnesses) if existing else set()
+    new_harnesses = set(new_selection.harnesses)
+
+    added = new_harnesses - old_harnesses
+    removed = old_harnesses - new_harnesses
+
+    # Re-run install with force=True to lay down baseline + new-harness files.
+    # install_selection is idempotent: unchanged files re-render identically.
+    rc = install_selection(target, new_selection, force=True)
+    if rc != 0:
+        return rc
+
+    # Prune removed harnesses if requested.
+    if prune:
+        for h in sorted(removed):
+            wdir = _WRITER_DIRS.get(h)
+            if wdir and (target / wdir).is_dir():
+                shutil.rmtree(target / wdir)
+            for bridge in _HARNESS_BRIDGE_FILES.get(h, []):
+                bp = target / bridge
+                if bp.is_file():
+                    bp.unlink()
+            rdir = _READER_DIRS.get(h)
+            if rdir and (target / rdir).is_dir():
+                shutil.rmtree(target / rdir)
+            print(f"brigade: pruned {h}")
+
+    print(f"brigade: reconfigured -> harnesses={','.join(new_selection.harnesses) or '(none)'}")
+    if added:
+        print(f"  added:   {','.join(sorted(added))}")
+    if removed:
+        verb = "pruned" if prune else "orphaned (use --prune to delete)"
+        print(f"  removed: {','.join(sorted(removed))} ({verb})")
+    return 0

brigade/registry.py

@@ -0,0 +1,39 @@
+"""The built-in station registry."""
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from . import doctor as _doctor
+from .station import Station
+
+CORE = Station(
+    name="core",
+    summary="workspace bootstrap and harness adapters",
+    aliases=("mise",),
+    doctor=_doctor.core_station_checks,
+)
+MEMORY = Station(
+    name="memory",
+    summary="handoff inbox, ingest, and memory-care",
+    aliases=("garde",),
+    doctor=_doctor.memory_station_checks,
+)
+GUARD = Station(
+    name="guard",
+    summary="publish safety and content scrub",
+    aliases=("pass",),
+    doctor=_doctor.guard_station_checks,
+)
+
+_BUILTIN: Tuple[Station, ...] = (CORE, MEMORY, GUARD)
+
+
+def all_stations() -> Tuple[Station, ...]:
+    return _BUILTIN
+
+
+def resolve(name_or_alias: str) -> Optional[Station]:
+    for station in _BUILTIN:
+        if station.matches(name_or_alias):
+            return station
+    return None

brigade/scrub.py

@@ -0,0 +1,90 @@
+"""`brigade scrub` - run the content-guard scanner against a target."""
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run(
+    target: Path,
+    policy: str = "public-repo",
+    dry_run: bool = False,
+) -> int:
+    target = target.expanduser().resolve()
+    scanner_dir = Path(
+        os.environ.get("CONTENT_GUARD_DIR", str(Path.home() / "repos" / "content-guard"))
+    )
+
+    if not scanner_dir.is_dir():
+        print(
+            f"brigade scrub: content-guard not found at {scanner_dir}",
+            file=sys.stderr,
+        )
+        print(
+            "brigade scrub: clone https://github.com/solomonneas/content-guard "
+            "or set CONTENT_GUARD_DIR",
+            file=sys.stderr,
+        )
+        return 2
+
+    try:
+        policy_path = _resolve_policy(target, scanner_dir, policy)
+    except ValueError as exc:
+        print(f"brigade scrub: {exc}", file=sys.stderr)
+        return 4
+    if not policy_path.is_file():
+        print(f"brigade scrub: policy not found: {policy_path}", file=sys.stderr)
+        return 3
+
+    cmd = [
+        sys.executable,
+        "-m",
+        "content_guard",
+        "scan",
+        str(target),
+        "--policy",
+        str(policy_path),
+    ]
+    if dry_run:
+        print("brigade scrub: would run:")
+        print(" ", " ".join(cmd))
+        print(f"  PYTHONPATH={scanner_dir / 'src'}")
+        return 0
+
+    env = os.environ.copy()
+    existing_pp = env.get("PYTHONPATH", "")
+    env["PYTHONPATH"] = (
+        f"{scanner_dir / 'src'}{os.pathsep}{existing_pp}" if existing_pp else str(scanner_dir / "src")
+    )
+    return subprocess.call(cmd, env=env)
+
+
+def _resolve_policy(target: Path, scanner_dir: Path, policy: str) -> Path:
+    """Resolve a policy name to a JSON path.
+
+    Lookup order:
+      1. If `policy` looks like a path (contains `/` or `\\` or ends in `.json`),
+         treat it as a literal file path and use it as-is.
+      2. Otherwise, treat it as a basename and search the safe lookup chain:
+         `<target>/.brigade/policies/<policy>.json`, then
+         `<scanner_dir>/policies/<policy>.json`.
+    """
+    looks_like_path = "/" in policy or "\\" in policy or policy.endswith(".json")
+    if looks_like_path:
+        return Path(policy)
+
+    # Bare name: must be a simple slug, no path segments.
+    safe = policy.strip()
+    if not safe or any(c in safe for c in ("/", "\\", "..")):
+        raise ValueError(f"unsafe policy name: {policy!r}")
+
+    candidates = [
+        target / ".brigade" / "policies" / f"{safe}.json",
+        scanner_dir / "policies" / f"{safe}.json",
+    ]
+    for c in candidates:
+        if c.is_file():
+            return c
+    return candidates[0]  # caller prints "not found" with this path

brigade/selection.py

@@ -0,0 +1,66 @@
+"""Selection data model: depth + harnesses + owner + includes."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+KNOWN_DEPTHS = ("repo", "workspace")
+KNOWN_HARNESSES = ("claude", "codex", "openclaw", "hermes")
+KNOWN_INCLUDES = ("publisher",)
+
+# Higher priority owners come first. The first harness in this list that
+# also appears in the selection becomes the canonical memory owner unless
+# the user passes --owner.
+HARNESS_PRIORITY = ["openclaw", "hermes", "claude", "codex", "this-repo"]
+
+
+@dataclass
+class Selection:
+    depth: str
+    harnesses: List[str] = field(default_factory=list)
+    owner: str = "this-repo"
+    includes: List[str] = field(default_factory=list)
+
+    def validate(self) -> None:
+        if self.depth not in KNOWN_DEPTHS:
+            raise ValueError(
+                f"unknown depth: {self.depth!r} (valid: {KNOWN_DEPTHS})"
+            )
+        for h in self.harnesses:
+            if h not in KNOWN_HARNESSES:
+                raise ValueError(
+                    f"unknown harness: {h!r} (valid: {KNOWN_HARNESSES})"
+                )
+        for inc in self.includes:
+            if inc not in KNOWN_INCLUDES:
+                raise ValueError(
+                    f"unknown include: {inc!r} (valid: {KNOWN_INCLUDES})"
+                )
+        if self.owner != "this-repo" and self.owner not in self.harnesses:
+            raise ValueError(
+                f"owner {self.owner!r} not in selected harnesses {self.harnesses}"
+            )
+
+
+def resolve_owner(harnesses: List[str], override: Optional[str] = None) -> str:
+    """Pick the canonical memory owner.
+
+    If override is provided, it must be 'this-repo' or one of the selected
+    harnesses. Otherwise the first entry in HARNESS_PRIORITY that also appears
+    in `harnesses` wins; if none match, returns 'this-repo'.
+    """
+    if override is not None:
+        if override == "this-repo":
+            return override
+        if override not in harnesses:
+            raise ValueError(
+                f"owner override {override!r} not in selected harnesses {harnesses}"
+            )
+        return override
+    for candidate in HARNESS_PRIORITY:
+        if candidate == "this-repo":
+            continue
+        if candidate in harnesses:
+            return candidate
+    return "this-repo"

brigade/station.py

@@ -0,0 +1,36 @@
+"""The station contract: a registered, health-checkable unit of Brigade."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, List, Optional, Tuple
+
+# (status, name, detail), reusing the doctor vocabulary.
+CheckResult = Tuple[str, str, str]
+
+
+@dataclass
+class DoctorContext:
+    """Resolved workspace facts shared across station doctors."""
+    target: Path
+    selection: object | None  # brigade.selection.Selection | None (avoids import cycle)
+    harnesses: List[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class Station:
+    """A unit of Brigade.
+
+    v1 stations are all built-in: their behavior lives inside the brigade
+    package and only `doctor` is exercised. Managed stations (install/wire/
+    verbs) arrive in Plan 2 and will extend this contract; do not add those
+    fields until they are needed (YAGNI).
+    """
+    name: str
+    summary: str
+    doctor: Optional[Callable[[DoctorContext], List[CheckResult]]]
+    aliases: Tuple[str, ...] = ()
+    kind: str = "builtin"
+
+    def matches(self, name_or_alias: str) -> bool:
+        return name_or_alias == self.name or name_or_alias in self.aliases

brigade/status.py

@@ -0,0 +1,24 @@
+"""`brigade status` - show which stations are present and healthy."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import doctor as _doctor
+from .registry import all_stations
+
+
+def run(target: Path) -> int:
+    ctx = _doctor.build_context(target)
+    print(f"brigade status: {ctx.target}")
+    width = max((len(s.name) for s in all_stations()), default=8)
+    for station in all_stations():
+        checks = station.doctor(ctx) if station.doctor else []
+        ok = sum(1 for s, _, _ in checks if s == _doctor.OK)
+        warn = sum(1 for s, _, _ in checks if s == _doctor.WARN)
+        fail = sum(1 for s, _, _ in checks if s == _doctor.FAIL)
+        health = "issues" if fail else ("ok" if ok else "empty")
+        print(
+            f"  {station.name.ljust(width)}  [{health}]  "
+            f"{ok} ok, {warn} warn, {fail} fail  - {station.summary}"
+        )
+    return 0

brigade/templates/claude/memory-handoffs/TEMPLATE.md

@@ -0,0 +1,57 @@
+# Memory Handoff
+
+## Type
+
+setup | workflow | bugfix | decision | security | preference | research | project-context
+
+## Title
+
+Short, specific title. No private identifiers.
+
+## Summary
+
+2-4 sentences. What happened and why it matters for future sessions.
+
+## Durable facts
+
+- Fact 1
+- Fact 2
+- Fact 3
+
+## Evidence
+
+- files changed: `path/to/file`
+- commands run: `the exact command`
+- error strings: `verbatim error`
+
+## Recommended memory action
+
+create-card | update-card | no-card
+
+## Target card
+
+card-name-if-known.md
+
+## Suggested card content
+
+If `create-card` or `update-card`, paste the exact card content here. Must start with YAML frontmatter:
+
+```markdown
+---
+topic: ...
+category: ...
+tags: [list]
+---
+
+# Card title
+
+Card body. Use ### or deeper for subsections; ## headings parse as new handoff sections.
+```
+
+## Target document
+
+If `no-card`, name one of: `TOOLS.md` | `USER.md` | `rules/<name>.md` | `.learnings/LEARNINGS.md` | `.learnings/ERRORS.md` | `.learnings/FEATURE_REQUESTS.md`
+
+## Suggested document content
+
+If `no-card`, the exact text to append. No `##` headings (use `###` or deeper).

brigade/templates/codex/memory-handoffs/TEMPLATE.md

@@ -0,0 +1,57 @@
+# Memory Handoff
+
+## Type
+
+setup | workflow | bugfix | decision | security | preference | research | project-context
+
+## Title
+
+Short, specific title. No private identifiers.
+
+## Summary
+
+2-4 sentences. What happened and why it matters for future sessions.
+
+## Durable facts
+
+- Fact 1
+- Fact 2
+- Fact 3
+
+## Evidence
+
+- files changed: `path/to/file`
+- commands run: `the exact command`
+- error strings: `verbatim error`
+
+## Recommended memory action
+
+create-card | update-card | no-card
+
+## Target card
+
+card-name-if-known.md
+
+## Suggested card content
+
+If `create-card` or `update-card`, paste the exact card content here. Must start with YAML frontmatter:
+
+```markdown
+---
+topic: ...
+category: ...
+tags: [list]
+---
+
+# Card title
+
+Card body. Use ### or deeper for subsections; ## headings parse as new handoff sections.
+```
+
+## Target document
+
+If `no-card`, name one of: `TOOLS.md` | `USER.md` | `rules/<name>.md` | `.learnings/LEARNINGS.md` | `.learnings/ERRORS.md` | `.learnings/FEATURE_REQUESTS.md`
+
+## Suggested document content
+
+If `no-card`, the exact text to append. No `##` headings (use `###` or deeper).

brigade/templates/depth/repo.json

@@ -0,0 +1,12 @@
+{
+  "id": "repo",
+  "description": "Repo-local baseline: harness-neutral bootstrap files + publish guard.",
+  "files": [
+    {"src": "workspace/AGENTS.md", "dst": "AGENTS.md"},
+    {"src": "workspace/SAFETY_RULES.md", "dst": "SAFETY_RULES.md"},
+    {"src": "workspace/INSTALL_FOR_AGENTS.md", "dst": "INSTALL_FOR_AGENTS.md"},
+    {"src": "hooks/pre-push", "dst": "hooks/pre-push", "mode": "0755"},
+    {"src": "policies/public-repo.json", "dst": ".brigade/policies/public-repo.json"}
+  ],
+  "dirs": []
+}

brigade/templates/depth/workspace.json

@@ -0,0 +1,30 @@
+{
+  "id": "workspace",
+  "description": "Full agent kitchen: extends repo baseline + memory folders + starter cards + safety files.",
+  "extends": "repo",
+  "files": [
+    {"src": "workspace/MEMORY.md", "dst": "MEMORY.md"},
+    {"src": "workspace/TOOLS.md", "dst": "TOOLS.md"},
+    {"src": "workspace/USER.md", "dst": "USER.md"},
+    {"src": "workspace/SOUL.md", "dst": "SOUL.md"},
+    {"src": "workspace/IDENTITY.md", "dst": "IDENTITY.md"},
+    {"src": "workspace/HEARTBEAT.md", "dst": "HEARTBEAT.md"},
+    {"src": "memory/cards/memory-architecture.md", "dst": "memory/cards/memory-architecture.md"},
+    {"src": "memory/cards/handoff-flow.md", "dst": "memory/cards/handoff-flow.md"},
+    {"src": "memory/cards/content-safety.md", "dst": "memory/cards/content-safety.md"},
+    {"src": "memory/cards/memory-scanner.md", "dst": "memory/cards/memory-scanner.md"},
+    {"src": "memory/cards/memory-care-staleness.md", "dst": "memory/cards/memory-care-staleness.md"},
+    {"src": "memory/cards/multi-workspace-handoff-admin.md", "dst": "memory/cards/multi-workspace-handoff-admin.md"},
+    {"src": "memory/cards/tokenjuice-output-compaction.md", "dst": "memory/cards/tokenjuice-output-compaction.md"},
+    {"src": "memory/cards/chat-surface-crawlers.md", "dst": "memory/cards/chat-surface-crawlers.md"},
+    {"src": "memory/cards/pipeline-standups.md", "dst": "memory/cards/pipeline-standups.md"},
+    {"src": "memory/cards/obsidian-notes.md", "dst": "memory/cards/obsidian-notes.md"},
+    {"src": "memory/cards/backup-restic.md", "dst": "memory/cards/backup-restic.md"},
+    {"src": "skills/note/SKILL.md", "dst": "skills/note/SKILL.md"},
+    {"src": "scripts/backup-restic.sh", "dst": "scripts/backup-restic.sh", "mode": "0755"}
+  ],
+  "dirs": [
+    "memory/cards/decay",
+    "memory/handoff-inbox"
+  ]
+}

brigade/templates/generic/harness-adapter-checklist.md

@@ -0,0 +1,55 @@
+# Harness Adapter Checklist
+
+Use this when wiring a new harness into the `brigade` contract.
+
+## 1. Bootstrap loading
+
+- [ ] Identify which file the harness loads first when starting a session.
+- [ ] Confirm the harness can be configured to load `AGENTS.md` + (its own bridge file).
+- [ ] If the harness has its own preference file (e.g. `CLAUDE.md`, `GEMINI.md`, `AGENTS.md`), keep both: ours and theirs.
+
+## 2. Memory ownership
+
+- [ ] Decide who owns canonical durable memory. Often this is the harness with the longest-lived context.
+- [ ] Configure all *other* harnesses to write handoffs, not direct memory edits.
+- [ ] If multiple harnesses think they own memory, you have a bug; pick one.
+
+## 3. Handoff inbox
+
+- [ ] Create `.claude/memory-handoffs/` in every repo the harness works in.
+- [ ] Drop the closeout instruction into the harness's instruction file.
+- [ ] Test by running a small task and looking for an emitted handoff.
+
+## 4. Routing
+
+- [ ] Confirm `brigade ingest --target <workspace> --dry-run` finds the handoffs.
+- [ ] Confirm the auto-promote rules match the handoffs the harness actually writes (filename regex + frontmatter).
+- [ ] Watch `memory/handoff-inbox/` for a week; if it fills up, refine handoff quality, do not loosen the rules.
+
+## 5. Doctor
+
+- [ ] Run `brigade doctor --target <workspace> --harness <harness>`.
+- [ ] All checks `OK` or explicitly `MANUAL ACTION NEEDED` with a follow-up step.
+
+## 6. Publish gate
+
+- [ ] `hooks/pre-push` installed.
+- [ ] `git config core.hooksPath hooks` run once.
+- [ ] `content-guard` installed and policy points at `public-repo.json` or stricter.
+
+## 7. Verification
+
+```bash
+# Bootstrap files in place
+ls AGENTS.md CLAUDE.md
+
+# Handoff infrastructure in place
+ls .claude/memory-handoffs/TEMPLATE.md
+ls memory/cards/
+
+# Ingest loop alive (after writing a sample handoff)
+brigade ingest --target . --dry-run
+
+# Publish gate live
+hooks/pre-push </dev/null || echo "(hook needs git push to exercise)"
+```

brigade/templates/generic/memory-contract.md

@@ -0,0 +1,41 @@
+# Harness Memory Contract
+
+Any harness that wants to plug into `brigade` must answer six questions.
+
+| Contract field | Meaning |
+|----------------|---------|
+| `bootstrap_files` | Files loaded into the agent's starting context |
+| `memory_owner` | System responsible for canonical durable memory |
+| `handoff_inbox` | Directory where side harnesses write handoff markdown |
+| `routing_targets` | Allowed memory outputs: cards, tools, user prefs, rules, learnings |
+| `doctor_checks` | Commands that prove the harness can see the expected files |
+| `publish_gate` | Content-guard or equivalent scan before public output leaves the repo |
+
+## Reference mapping (OpenClaw)
+
+| Field | Value |
+|-------|-------|
+| `bootstrap_files` | `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, `USER.md`, `TOOLS.md`, `MEMORY.md`, `IDENTITY.md`, `HEARTBEAT.md`, `SAFETY_RULES.md`, `INSTALL_FOR_AGENTS.md` |
+| `memory_owner` | OpenClaw workspace at `~/.openclaw/workspace/` |
+| `handoff_inbox` | `.claude/memory-handoffs/` in each repo |
+| `routing_targets` | `memory/cards/*.md`, `TOOLS.md`, `USER.md`, `rules/*.md`, `.learnings/*.md` |
+| `doctor_checks` | Existence of bootstrap files + jq queries against `openclaw.json` |
+| `publish_gate` | `content-guard` via `hooks/pre-push` |
+
+## Reference mapping (Hermes - experimental)
+
+Same shape; map `memory_owner` to your Hermes config root and `doctor_checks` to whatever Hermes exposes.
+
+## Reference mapping (generic / no orchestrator)
+
+If you do not have an orchestrator yet, the contract still works:
+
+| Field | Value |
+|-------|-------|
+| `memory_owner` | this repo until you wire one |
+| `handoff_inbox` | `.claude/memory-handoffs/` |
+| `routing_targets` | same |
+| `doctor_checks` | `brigade doctor --target . --harness generic` |
+| `publish_gate` | `brigade scrub` and `hooks/pre-push` |
+
+`brigade ingest --target .` is enough on its own; you do not need OpenClaw or Hermes installed to run the loop.

brigade/templates/harnesses/claude.json

@@ -0,0 +1,12 @@
+{
+  "id": "claude",
+  "role": "writer",
+  "description": "Claude Code bridge + handoff inbox.",
+  "files": [
+    {"src": "workspace/CLAUDE.md", "dst": "CLAUDE.md"},
+    {"src": "claude/memory-handoffs/TEMPLATE.md", "dst": ".claude/memory-handoffs/TEMPLATE.md"}
+  ],
+  "dirs": [
+    ".claude/memory-handoffs/processed"
+  ]
+}

brigade/templates/harnesses/codex.json

@@ -0,0 +1,11 @@
+{
+  "id": "codex",
+  "role": "writer",
+  "description": "Codex handoff inbox. (AGENTS.md is in the depth baseline; no separate bridge file today.)",
+  "files": [
+    {"src": "codex/memory-handoffs/TEMPLATE.md", "dst": ".codex/memory-handoffs/TEMPLATE.md"}
+  ],
+  "dirs": [
+    ".codex/memory-handoffs/processed"
+  ]
+}

brigade/templates/harnesses/hermes.json

@@ -0,0 +1,16 @@
+{
+  "id": "hermes",
+  "role": "reader",
+  "description": "Hermes adapter fragments + doctor checks. Experimental.",
+  "files": [
+    {"src": "hermes/workspace.harness.json", "dst": ".brigade/hermes/workspace.harness.json"},
+    {"src": "hermes/memory-handoff.harness.json", "dst": ".brigade/hermes/memory-handoff.harness.json"},
+    {"src": "hermes/model-lanes.harness.json", "dst": ".brigade/hermes/model-lanes.harness.json"},
+    {"src": "hermes/README.md", "dst": ".brigade/hermes/README.md"}
+  ],
+  "dirs": [],
+  "post_install_notes": [
+    "Hermes support is experimental. Validate against your real Hermes install before relying on it.",
+    "Open an issue with your config layout to help promote the adapter from experimental to tested."
+  ]
+}

brigade/templates/harnesses/openclaw.json

@@ -0,0 +1,17 @@
+{
+  "id": "openclaw",
+  "role": "reader",
+  "description": "OpenClaw config fragments + cron stubs + doctor checks.",
+  "files": [
+    {"src": "openclaw/model-aliases.openclaw.json", "dst": ".brigade/openclaw/model-aliases.openclaw.json"},
+    {"src": "openclaw/ollama-memory-search.openclaw.json", "dst": ".brigade/openclaw/ollama-memory-search.openclaw.json"},
+    {"src": "openclaw/acp-escalation.openclaw.json", "dst": ".brigade/openclaw/acp-escalation.openclaw.json"},
+    {"src": "openclaw/README.md", "dst": ".brigade/openclaw/README.md"}
+  ],
+  "dirs": [],
+  "post_install_notes": [
+    "Inspect fragments under `.brigade/openclaw/` before merging into ~/.openclaw/openclaw.json.",
+    "Run `brigade doctor --target <workspace>` to confirm wiring.",
+    "Never let `openclaw doctor --fix` (the OpenClaw tool) rewrite provider prefixes blindly."
+  ]
+}

brigade/templates/hermes/README.md

@@ -0,0 +1,25 @@
+# Hermes Adapter (Experimental)
+
+`brigade` supports Hermes through the same harness contract as OpenClaw. This adapter is **experimental** until it has been validated against a real Hermes install.
+
+## What this gives you
+
+- `workspace.harness.json` - which bootstrap files Hermes should load
+- `memory-handoff.harness.json` - the handoff inbox and routing targets
+- `model-lanes.harness.json` - suggested model alias names
+
+## What it does not do yet
+
+- Validate against the live Hermes config schema
+- Generate Hermes-specific plugin entries
+- Replace `brigade hermes doctor` with anything beyond file existence checks
+
+## Contributing
+
+If you run Hermes and have working config, open an issue at <https://github.com/solomonneas/brigade/issues> with:
+
+- the file Hermes loads as its primary bootstrap file
+- the path where Hermes expects memory handoffs (if any)
+- the command that ingests handoffs into canonical memory
+
+That lets the adapter be promoted from experimental to tested.