open-xmen 0.1.0

package/.cerebro/schemas/team-run.schema.json

@@ -0,0 +1,234 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Cerebro Team Run Manifest",
+  "description": "Coordination audit log for a single OpenCode-managed Cerebro run. Task progress lives in .cerebro/team-runs/{run_id}.tasks.json via cerebro_task_* tools.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "run_id",
+    "command",
+    "status",
+    "lead",
+    "team_name",
+    "objective",
+    "risk_level",
+    "started_at",
+    "updated_at",
+    "teammates",
+    "ownership",
+    "mailbox_decisions",
+    "approvals",
+    "verification",
+    "cleanup"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "run_id": {
+      "type": "string",
+      "description": "YYYYMMDD-HHMMSS-{slug}",
+      "minLength": 1
+    },
+    "command": {
+      "type": "string",
+      "enum": ["/to-me-my-x-men", "/cerebro-plan", "/cerebro-start-work", "/cerebro-index", "/cerebro-doctor", "/cerebro-reset", "/cerebro-upgrade"]
+    },
+    "status": {
+      "type": "string",
+      "enum": ["planning", "running", "blocked", "completed", "cleaned_up"]
+    },
+    "lead": {
+      "type": "string",
+      "const": "cerebro"
+    },
+    "team_name": {
+      "type": "string",
+      "description": "Stable team/session name used to group Cerebro tasks, mailbox messages, checkpoints, and pending todos",
+      "minLength": 1
+    },
+    "objective": {
+      "type": "string",
+      "minLength": 1
+    },
+    "risk_level": {
+      "type": "string",
+      "enum": ["LOW", "MEDIUM", "HIGH"]
+    },
+    "started_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "updated_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "teammates": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/teammate"
+      }
+    },
+    "ownership": {
+      "type": "array",
+      "description": "File ownership assignments — prevent two writers on the same file",
+      "items": {
+        "$ref": "#/$defs/ownership_entry"
+      }
+    },
+    "mailbox_decisions": {
+      "type": "array",
+      "description": "Decisions recorded via cerebro_mailbox_send that resolve cross-agent conflicts or assumptions",
+      "items": {
+        "$ref": "#/$defs/mailbox_decision"
+      }
+    },
+    "approvals": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/approval"
+      }
+    },
+    "verification": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/verification_entry"
+      }
+    },
+    "cleanup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["team_stopped", "pending_todos_clear", "notes"],
+      "properties": {
+        "team_stopped": {
+          "type": "boolean"
+        },
+        "pending_todos_clear": {
+          "type": "boolean"
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "teammate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "agent_type", "status", "responsibility", "last_signal"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "agent_type": {
+          "type": "string",
+          "enum": ["cerebro", "legion", "cypher", "cyclops", "wolverine", "storm", "professor-x", "beast", "emma-frost", "nightcrawler", "sage", "forge"]
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "active", "idle", "done", "blocked"]
+        },
+        "responsibility": {
+          "type": "string"
+        },
+        "last_signal": {
+          "type": "string"
+        }
+      }
+    },
+    "ownership_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "owner", "reviewer", "notes"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reviewer": {
+          "type": "string"
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "mailbox_decision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["at", "from", "to", "decision", "notes"],
+      "properties": {
+        "at": {
+          "type": "string",
+          "minLength": 1
+        },
+        "from": {
+          "type": "string",
+          "minLength": 1
+        },
+        "to": {
+          "type": "string",
+          "minLength": 1
+        },
+        "decision": {
+          "type": "string",
+          "minLength": 1
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "approval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["gate", "status", "decided_at", "notes"],
+      "properties": {
+        "gate": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "approved", "rejected"]
+        },
+        "decided_at": {
+          "type": ["string", "null"]
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "verification_entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "status", "by", "notes"],
+      "properties": {
+        "command": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": ["NOT RUN", "PASS", "FAIL", "BLOCKED"]
+        },
+        "by": {
+          "type": "string",
+          "minLength": 1
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/.cerebro/schemas/upgrade-manifest.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Cerebro Upgrade Manifest",
+  "description": "Declares file ownership for /cerebro-upgrade. Controls which files are overwritten, merged, or left untouched during a template sync.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "entries"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "entries": {
+      "type": "array",
+      "description": "Ordered list of ownership declarations. Earlier entries take precedence for overlapping globs.",
+      "items": {
+        "$ref": "#/$defs/entry"
+      },
+      "minItems": 1
+    }
+  },
+  "$defs": {
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "ownership"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "Glob pattern or exact path relative to the project root",
+          "minLength": 1
+        },
+        "ownership": {
+          "type": "string",
+          "description": "template: overwrite silently (Gate C fires in --strict mode); merge: show unified diff, Gate A on conflict; user: never touched",
+          "enum": ["template", "merge", "user"]
+        },
+        "notes": {
+          "type": "string",
+          "description": "Human-readable rationale for this ownership classification"
+        }
+      }
+    }
+  }
+}

package/.cerebro/schemas/upgrade-state.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Cerebro Upgrade State",
+  "description": "Baseline record written after each successful /cerebro-upgrade run. Drives accurate change detection on the next upgrade.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "applied_ref", "applied_sha", "applied_at", "hashes"],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "applied_ref": {
+      "type": "string",
+      "description": "The git tag or commit SHA that was passed to /cerebro-upgrade",
+      "minLength": 1
+    },
+    "applied_sha": {
+      "type": "string",
+      "description": "Full 40-character SHA of the upstream commit that was applied",
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "applied_at": {
+      "type": "string",
+      "description": "ISO-8601 timestamp when the upgrade was applied",
+      "minLength": 1
+    },
+    "hashes": {
+      "type": "object",
+      "description": "Map of relative file path to SHA-256 hex digest of post-upgrade local file content. Covers all template-owned and merge-owned files present in the local tree after the upgrade.",
+      "additionalProperties": {
+        "type": "string",
+        "description": "SHA-256 hex digest (64 lowercase hex characters)",
+        "pattern": "^[0-9a-f]{64}$"
+      }
+    }
+  }
+}

package/.cerebro/scripts/check-agent-teams-enabled.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+"""Legacy compatibility check for Claude Code agent-team settings.
+
+The active OpenCode runtime uses `.opencode/` agents, Cerebro custom tools,
+and child sessions instead of Claude Code experimental agent teams. Keep this
+script only for repositories that still validate legacy `.claude/` material.
+"""
+
+import json
+from pathlib import Path
+
+
+def main() -> int:
+    settings = json.loads(Path(".claude/settings.json").read_text())
+    env = settings.get("env", {})
+    if env.get("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS") != "1":
+        print("missing CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1")
+        return 1
+    print("agent teams enabled")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.cerebro/scripts/ensure-upgrade-cache-gitignored.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python3
+"""Ensure .cerebro/.gitignore ignores Cerebro upgrade cache files."""
+
+from pathlib import Path
+
+
+LINE = "upgrade-cache/"
+
+
+def main() -> int:
+    path = Path(".cerebro/.gitignore")
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    lines = text.splitlines()
+    if LINE in lines:
+        print("upgrade cache already ignored")
+        return 0
+
+    prefix = text
+    if prefix and not prefix.endswith("\n"):
+        prefix += "\n"
+    path.write_text(prefix + LINE + "\n", encoding="utf-8")
+    print("added upgrade-cache/ to .cerebro/.gitignore")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.cerebro/scripts/fetch-upstream-ref.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Fetch a Cerebro upstream ref into the local upgrade cache and print its SHA."""
+
+import argparse
+import re
+import subprocess
+from pathlib import Path
+
+
+REF_RE = re.compile(r"^[A-Za-z0-9._/-]+$")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("ref")
+    parser.add_argument("--upstream", default="https://github.com/yelaco/claude-xmen.git")
+    args = parser.parse_args()
+
+    if args.ref in {"HEAD", "main", "master"}:
+        print("ref must be an explicit tag or commit SHA, not HEAD/main/master")
+        return 1
+    if not REF_RE.match(args.ref):
+        print(f"ref contains unsupported characters: {args.ref!r}")
+        return 1
+
+    cache_dir = Path(".cerebro/upgrade-cache") / args.ref
+    try:
+        if cache_dir.is_dir():
+            subprocess.run(
+                ["git", "-C", str(cache_dir), "fetch", "--depth=1", "origin", "tag", args.ref],
+                check=True,
+            )
+            subprocess.run(["git", "-C", str(cache_dir), "checkout", args.ref], check=True)
+        else:
+            cache_dir.parent.mkdir(parents=True, exist_ok=True)
+            subprocess.run(
+                [
+                    "git",
+                    "clone",
+                    "--filter=blob:none",
+                    "--depth=1",
+                    "--branch",
+                    args.ref,
+                    args.upstream,
+                    str(cache_dir),
+                ],
+                check=True,
+            )
+        result = subprocess.run(
+            ["git", "-C", str(cache_dir), "rev-parse", "HEAD"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        print("git is required for /cerebro-upgrade - install git and retry")
+        return 1
+    except subprocess.CalledProcessError:
+        print(f"Could not fetch ref {args.ref!r} from {args.upstream}")
+        return 1
+
+    print(result.stdout.strip())
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.cerebro/scripts/reset-runtime.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+"""Scan, reset, and verify Cerebro runtime state."""
+
+import argparse
+import shutil
+from pathlib import Path
+
+
+RUNTIME = {
+    "boulder.json": Path(".cerebro/boulder.json"),
+    ".pending-todos": Path(".cerebro/.pending-todos"),
+    "pending-todos/": Path(".cerebro/pending-todos"),
+    "plans/": Path(".cerebro/plans"),
+    "notepads/": Path(".cerebro/notepads"),
+    "team-runs/": Path(".cerebro/team-runs"),
+}
+TARGETS = list(RUNTIME.values())
+STUB_DIRS = [
+    Path(".cerebro/plans"),
+    Path(".cerebro/notepads"),
+    Path(".cerebro/team-runs"),
+]
+EMPTY_DIRS = [
+    *STUB_DIRS,
+    Path(".cerebro/pending-todos"),
+]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser("scan")
+    reset_parser = subparsers.add_parser("reset")
+    reset_parser.add_argument("--confirm", required=True)
+    subparsers.add_parser("verify")
+    args = parser.parse_args()
+
+    if args.command == "scan":
+        scan()
+        return 0
+    if args.command == "reset":
+        if args.confirm != "YES":
+            print("Reset aborted. No files were changed.")
+            return 1
+        reset()
+        return 0
+    if args.command == "verify":
+        return verify()
+    raise AssertionError(args.command)
+
+
+def scan() -> None:
+    for label, path in RUNTIME.items():
+        if not path.exists():
+            print(f"  {label:<20} absent - nothing to remove")
+            continue
+        if path.is_file():
+            print(f"  {label:<20} FILE  {path.stat().st_size} bytes")
+            continue
+        items = [item for item in path.rglob("*") if item.is_file() and item.name != ".gitkeep"]
+        print(f"  {label:<20} DIR   {len(items)} runtime file(s)")
+
+
+def reset() -> None:
+    removed = []
+    skipped = []
+    for path in TARGETS:
+        if not path.exists():
+            skipped.append(str(path))
+            continue
+        if path.is_file():
+            path.unlink()
+        else:
+            shutil.rmtree(path)
+        removed.append(str(path))
+
+    for path in EMPTY_DIRS:
+        path.mkdir(parents=True, exist_ok=True)
+    for path in STUB_DIRS:
+        (path / ".gitkeep").touch()
+
+    print("Removed:")
+    for path in removed:
+        print(f"  {path}")
+    if skipped:
+        print("Skipped (absent):")
+        for path in skipped:
+            print(f"  {path}")
+
+
+def verify() -> int:
+    checks = {
+        "boulder.json absent": not Path(".cerebro/boulder.json").exists(),
+        ".pending-todos absent": not Path(".cerebro/.pending-todos").exists(),
+        "pending-todos/ absent or empty": _absent_or_has_only_gitkeep(Path(".cerebro/pending-todos")),
+        "plans/ clean": _has_only_gitkeep_or_less(Path(".cerebro/plans")),
+        "notepads/ clean": _has_only_gitkeep_or_less(Path(".cerebro/notepads")),
+        "team-runs/ clean": _has_only_gitkeep_or_less(Path(".cerebro/team-runs")),
+    }
+
+    all_pass = True
+    for label, ok in checks.items():
+        status = "PASS" if ok else "FAIL"
+        if not ok:
+            all_pass = False
+        print(f"  {status}  {label}")
+
+    if not all_pass:
+        return 1
+    print("Runtime clean.")
+    return 0
+
+
+def _has_only_gitkeep_or_less(path: Path) -> bool:
+    if not path.is_dir():
+        return False
+    return all(item.name == ".gitkeep" for item in path.iterdir())
+
+
+def _absent_or_has_only_gitkeep(path: Path) -> bool:
+    return not path.exists() or _has_only_gitkeep_or_less(path)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.cerebro/scripts/setup-status.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""Report Cerebro OpenCode setup status."""
+
+import argparse
+import json
+import subprocess
+from pathlib import Path
+
+
+OPENCODE_INSTRUCTIONS = [
+    Path("AGENTS.md"),
+    Path(".cerebro/cerebro-identity.md"),
+    Path(".cerebro/opencode/model-routing.md"),
+]
+DEFAULT_UPSTREAM = "https://github.com/yelaco/claude-xmen.git"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--upstream", default=DEFAULT_UPSTREAM)
+    parser.add_argument("--skip-upstream", action="store_true")
+    args = parser.parse_args()
+
+    instruction_status = instruction_files_status()
+    plugin_status = "PRESENT" if Path(".opencode/plugins/open-xmen.ts").is_file() else "MISSING"
+    installed = installed_version()
+    latest = "unreachable" if args.skip_upstream else latest_upstream_tag(args.upstream)
+    upgrade_needed = compare_versions(installed, latest)
+
+    missing = [str(path) for path, status in instruction_status.items() if status == "MISSING"]
+    if missing:
+        print(f"Missing OpenCode instruction files: {', '.join(missing)}")
+        print("Run `open-xmen install --reset` or `/cerebro-upgrade <latest-tag>` to restore managed runtime files.")
+
+    if latest == "unreachable":
+        print("Could not reach upstream - skipping version check. Check your connection and try again.")
+    elif upgrade_needed == "NO":
+        print(f"Cerebro installation is current at {installed}. No upgrade needed.")
+    elif upgrade_needed == "YES":
+        print(f"Upstream has {latest} - you are on {installed}. Run /cerebro-upgrade {latest} to sync.")
+    else:
+        print(
+            f"Installed version is unknown (no upgrade-state.json). Latest upstream is {latest}. "
+            f"Run /cerebro-upgrade {latest} to initialize upgrade tracking."
+        )
+
+    print()
+    for path, status in instruction_status.items():
+        print(f"{str(path):24} - {status}")
+    print("plugin bridge            - " + plugin_status)
+    print("installed version        - " + ("unknown" if installed == "none" else installed))
+    print("latest upstream          - " + latest)
+    print("upgrade needed           - " + upgrade_needed)
+    return 0 if not missing and plugin_status == "PRESENT" else 1
+
+
+def instruction_files_status() -> dict[Path, str]:
+    return {path: ("PRESENT" if path.is_file() else "MISSING") for path in OPENCODE_INSTRUCTIONS}
+
+
+def installed_version() -> str:
+    state_path = Path(".cerebro/upgrade-state.json")
+    if not state_path.exists():
+        return "none"
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return "unknown"
+    return state.get("applied_ref", "unknown")
+
+
+def latest_upstream_tag(upstream: str) -> str:
+    try:
+        result = subprocess.run(
+            ["git", "ls-remote", "--tags", "--sort=-version:refname", upstream, "refs/tags/v*"],
+            check=True,
+            capture_output=True,
+            text=True,
+            timeout=20,
+        )
+    except (subprocess.SubprocessError, FileNotFoundError):
+        return "unreachable"
+
+    for line in result.stdout.splitlines():
+        if "refs/tags/" in line:
+            return line.rsplit("refs/tags/", 1)[1].removesuffix("^{}")
+    return "unreachable"
+
+
+def compare_versions(installed: str, latest: str) -> str:
+    if latest == "unreachable":
+        return "UNKNOWN"
+    if installed in {"none", "unknown"}:
+        return "UNKNOWN"
+    if installed == latest:
+        return "NO"
+    return "YES"
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())