multi-harness 0.1.0__py3-none-any.whl

multi_harness/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

multi_harness/agents/__init__.py

@@ -0,0 +1,13 @@
+from .antigravity import SPEC as _ANTIGRAVITY
+from .claude import SPEC as _CLAUDE
+from .codex import SPEC as _CODEX
+from .copilot import SPEC as _COPILOT
+from .opencode import SPEC as _OPENCODE
+from .spec import AgentSpec
+
+AGENT_REGISTRY: dict[str, AgentSpec] = {
+    spec.name: spec
+    for spec in (_CLAUDE, _CODEX, _OPENCODE, _COPILOT, _ANTIGRAVITY)
+}
+
+__all__ = ["AGENT_REGISTRY", "AgentSpec"]

multi_harness/agents/antigravity.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+from .spec import AgentSpec
+
+SPEC = AgentSpec(
+    name="antigravity",
+    display_name="Google Antigravity",
+    instructions_path=None,
+    skills_path=Path(".agents/skills"),
+    subagents_path=Path(".subagents"),
+    detection_paths=(Path(".agents"), Path(".subagents")),
+)

multi_harness/agents/claude.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+from .spec import AgentSpec
+
+SPEC = AgentSpec(
+    name="claude",
+    display_name="Claude Code",
+    instructions_path=Path("CLAUDE.md"),
+    skills_path=Path(".claude/skills"),
+    subagents_path=Path(".claude/agents"),
+    detection_paths=(Path("CLAUDE.md"), Path(".claude")),
+)

multi_harness/agents/codex.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+from .spec import AgentSpec
+
+SPEC = AgentSpec(
+    name="codex",
+    display_name="OpenAI Codex",
+    instructions_path=None,
+    skills_path=Path(".codex/skills"),
+    subagents_path=Path(".codex/agents"),
+    detection_paths=(Path(".codex"),),
+)

multi_harness/agents/copilot.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+from .spec import AgentSpec
+
+SPEC = AgentSpec(
+    name="copilot",
+    display_name="GitHub Copilot",
+    instructions_path=Path(".github/copilot-instructions.md"),
+    skills_path=Path(".github/skills"),
+    subagents_path=Path(".github/agents"),
+    detection_paths=(Path(".github/copilot-instructions.md"),),
+)

multi_harness/agents/opencode.py

@@ -0,0 +1,12 @@
+from pathlib import Path
+
+from .spec import AgentSpec
+
+SPEC = AgentSpec(
+    name="opencode",
+    display_name="OpenCode",
+    instructions_path=None,
+    skills_path=Path(".opencode/skills"),
+    subagents_path=Path(".opencode/agent"),
+    detection_paths=(Path(".opencode"),),
+)

multi_harness/agents/spec.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    name: str
+    display_name: str
+    instructions_path: Path | None
+    skills_path: Path
+    subagents_path: Path
+    detection_paths: tuple[Path, ...]

multi_harness/cli.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from .agents import AGENT_REGISTRY
+from .config import ConfigError, read_agent_names
+from .harness import HarnessError, add as harness_add, init as harness_init, remove as harness_remove
+from .status import check_all
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Manage projects targeting multiple coding agents from a shared harness.",
+)
+
+
+@app.callback()
+def _callback() -> None:
+    """multi-harness — shared harness for multi-agent coding projects."""
+
+
+def _parse_agents(value: Optional[str]) -> list[str]:
+    if value is None:
+        return list(AGENT_REGISTRY)
+    names = [n.strip() for n in value.split(",") if n.strip()]
+    if not names:
+        raise typer.BadParameter("--agents must list at least one agent.")
+    return names
+
+
+@app.command()
+def init(
+    path: Annotated[
+        Path,
+        typer.Argument(
+            help="Project directory to initialize. Defaults to the current dir.",
+            file_okay=False,
+            dir_okay=True,
+            exists=True,
+            resolve_path=True,
+        ),
+    ] = Path("."),
+    agents: Annotated[
+        Optional[str],
+        typer.Option(
+            "--agents",
+            help=(
+                "Comma-separated list of agents to register. "
+                f"Defaults to all supported: {','.join(AGENT_REGISTRY)}."
+            ),
+        ),
+    ] = None,
+    template: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--template",
+            help="Path to a file used to seed AGENTS.md when it doesn't already exist.",
+            file_okay=True,
+            dir_okay=False,
+            exists=True,
+            readable=True,
+            resolve_path=True,
+        ),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            help="Re-link symlinks even if .harness/ already exists. Never overwrites real files.",
+        ),
+    ] = False,
+) -> None:
+    """Bootstrap or migrate a project into the multi-harness layout."""
+    selected = _parse_agents(agents)
+    try:
+        report = harness_init(path, selected, template=template, force=force)
+    except HarnessError as exc:
+        typer.secho(f"error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    if report.detected:
+        names = ", ".join(s.display_name for s in report.detected)
+        typer.echo(f"Detected existing agent: {names}")
+    for src, dst in report.moved:
+        typer.echo(f"  moved   {src.relative_to(path)} -> {dst.relative_to(path)}")
+    for created in report.created_files:
+        typer.echo(f"  created {created.relative_to(path)}")
+    for link, result in report.symlinks:
+        typer.echo(f"  link    {link.relative_to(path)} ({result})")
+    typer.echo("Done.")
+
+
+@app.command()
+def add(
+    agents: Annotated[
+        list[str],
+        typer.Argument(help="Agent name(s) to register."),
+    ],
+    path: Annotated[
+        Path,
+        typer.Option(
+            "--path",
+            help="Project directory. Defaults to the current dir.",
+            file_okay=False,
+            dir_okay=True,
+            exists=True,
+            resolve_path=True,
+        ),
+    ] = Path("."),
+) -> None:
+    """Register one or more new agents to an existing harness."""
+    try:
+        report = harness_add(path, agents)
+    except HarnessError as exc:
+        typer.secho(f"error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    for link, result in report.symlinks:
+        typer.echo(f"  link    {link.relative_to(path)} ({result})")
+    typer.echo("Done.")
+
+
+@app.command()
+def remove(
+    agents: Annotated[
+        list[str],
+        typer.Argument(help="Agent name(s) to remove."),
+    ],
+    path: Annotated[
+        Path,
+        typer.Option(
+            "--path",
+            help="Project directory. Defaults to the current dir.",
+            file_okay=False,
+            dir_okay=True,
+            exists=True,
+            resolve_path=True,
+        ),
+    ] = Path("."),
+) -> None:
+    """Remove one or more agents from the harness."""
+    try:
+        report = harness_remove(path, agents)
+    except HarnessError as exc:
+        typer.secho(f"error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    for link in report.removed_symlinks:
+        typer.echo(f"  unlinked {link.relative_to(path)}")
+    for d in report.removed_dirs:
+        typer.echo(f"  removed  {d.relative_to(path)}")
+    for d in report.nonempty_dirs:
+        rel = d.relative_to(path)
+        if typer.confirm(f"  {rel} is not empty. Remove it?", default=False):
+            shutil.rmtree(d)
+            typer.echo(f"  removed  {rel}")
+    typer.echo("Done.")
+
+
+@app.command()
+def status(
+    path: Annotated[
+        Path,
+        typer.Argument(
+            help="Project directory to check. Defaults to the current dir.",
+            file_okay=False,
+            dir_okay=True,
+            exists=True,
+            resolve_path=True,
+        ),
+    ] = Path("."),
+) -> None:
+    """Show symlink health for all registered agents."""
+    try:
+        agent_names = read_agent_names(path)
+    except ConfigError as exc:
+        typer.secho(f"error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    statuses = check_all(path, agent_names)
+    if not statuses:
+        typer.echo("No agents registered.")
+        return
+
+    _STATUS_COLOR = {
+        "ok": typer.colors.GREEN,
+        "missing": typer.colors.YELLOW,
+        "broken": typer.colors.RED,
+        "detached": typer.colors.RED,
+    }
+    max_label = max(len(r.label) for s in statuses for r in s.rows)
+    for agent_status in statuses:
+        typer.echo(agent_status.spec.display_name)
+        for row in agent_status.rows:
+            typer.echo(f"  {row.label.ljust(max_label + 2)}", nl=False)
+            typer.secho(row.status, fg=_STATUS_COLOR[row.status])
+        typer.echo("")
+
+    if not all(s.is_ok() for s in statuses):
+        raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    app()

multi_harness/config.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+_HARNESS_DIR = Path(".harness")
+HARNESS_CONFIG = _HARNESS_DIR / "config.toml"
+
+
+class ConfigError(Exception):
+    """Raised when .harness/config.toml is absent or has unexpected structure."""
+
+
+def write_config(root: Path, agent_names: list[str]) -> None:
+    agents_repr = ", ".join(f'"{n}"' for n in agent_names)
+    (root / HARNESS_CONFIG).write_text(
+        f"[harness]\nversion = 1\nagents = [{agents_repr}]\n"
+    )
+
+
+def read_agent_names(root: Path) -> list[str]:
+    config_path = root / HARNESS_CONFIG
+    if not config_path.exists():
+        raise ConfigError(
+            f"{HARNESS_CONFIG} not found. Run `mh init` to register agents."
+        )
+    try:
+        with config_path.open("rb") as fh:
+            data = tomllib.load(fh)
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{HARNESS_CONFIG} is malformed: {exc}") from exc
+
+    try:
+        agents = data["harness"]["agents"]
+    except KeyError as exc:
+        raise ConfigError(
+            f"{HARNESS_CONFIG} is missing key {exc}. Re-run `mh init`."
+        ) from exc
+
+    if not isinstance(agents, list) or not all(isinstance(n, str) for n in agents):
+        raise ConfigError(
+            f"{HARNESS_CONFIG}: harness.agents must be a list of strings."
+        )
+
+    return agents

multi_harness/harness.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .agents import AGENT_REGISTRY, AgentSpec
+from .config import ConfigError, read_agent_names, write_config
+from .symlinks import SymlinkResult, ensure_symlink
+
+HARNESS_DIR = Path(".harness")
+HARNESS_SKILLS = HARNESS_DIR / "skills"
+HARNESS_AGENTS = HARNESS_DIR / "agents"
+AGENTS_MD = Path("AGENTS.md")
+
+
+class HarnessError(Exception):
+    """Raised when `mh init` cannot safely proceed."""
+
+
+@dataclass
+class InitReport:
+    detected: list[AgentSpec] = field(default_factory=list)
+    moved: list[tuple[Path, Path]] = field(default_factory=list)
+    created_files: list[Path] = field(default_factory=list)
+    symlinks: list[tuple[Path, SymlinkResult]] = field(default_factory=list)
+
+
+@dataclass
+class AddReport:
+    symlinks: list[tuple[Path, SymlinkResult]] = field(default_factory=list)
+
+
+@dataclass
+class RemoveReport:
+    removed_symlinks: list[Path] = field(default_factory=list)
+    removed_dirs: list[Path] = field(default_factory=list)
+    nonempty_dirs: list[Path] = field(default_factory=list)
+
+
+def detect_configured_agents(root: Path) -> list[AgentSpec]:
+    """Return registered agents whose real detection paths exist under ``root``."""
+    detected: list[AgentSpec] = []
+    for spec in AGENT_REGISTRY.values():
+        for p in spec.detection_paths:
+            candidate = root / p
+            if candidate.exists() and not candidate.is_symlink():
+                detected.append(spec)
+                break
+    return detected
+
+
+def _move(src: Path, dst: Path, report: InitReport) -> None:
+    if dst.exists() or dst.is_symlink():
+        raise HarnessError(
+            f"Cannot migrate {src} -> {dst}: destination already exists. "
+            f"Resolve the conflict and re-run."
+        )
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    src.rename(dst)
+    report.moved.append((src, dst))
+
+
+def _migrate(root: Path, spec: AgentSpec, report: InitReport) -> None:
+    if spec.instructions_path is not None:
+        src = root / spec.instructions_path
+        dst = root / AGENTS_MD
+        if src.exists() and not src.is_symlink() and src != dst:
+            _move(src, dst, report)
+
+    src_skills = root / spec.skills_path
+    if src_skills.is_dir() and not src_skills.is_symlink():
+        _move(src_skills, root / HARNESS_SKILLS, report)
+
+    src_subagents = root / spec.subagents_path
+    if src_subagents.is_dir() and not src_subagents.is_symlink():
+        _move(src_subagents, root / HARNESS_AGENTS, report)
+
+
+def init(
+    root: Path,
+    agent_names: list[str],
+    template: Path | None = None,
+    force: bool = False,
+) -> InitReport:
+    """Initialize (or re-initialize) the harness layout at ``root``.
+
+    Raises :class:`HarnessError` if the project is in a state that requires manual
+    resolution (e.g. multiple agents already configured, or `.harness/` already
+    exists without ``--force``).
+    """
+    unknown = [n for n in agent_names if n not in AGENT_REGISTRY]
+    if unknown:
+        raise HarnessError(
+            f"Unknown agent(s): {', '.join(unknown)}. "
+            f"Supported: {', '.join(AGENT_REGISTRY)}."
+        )
+
+    report = InitReport()
+    harness_existed = (root / HARNESS_DIR).exists()
+
+    if harness_existed and not force:
+        raise HarnessError(
+            f"{HARNESS_DIR}/ already exists. Pass --force to re-link symlinks idempotently."
+        )
+
+    if not harness_existed:
+        report.detected = detect_configured_agents(root)
+        if len(report.detected) > 1:
+            names = ", ".join(s.display_name for s in report.detected)
+            raise HarnessError(
+                f"More than one agent is already configured ({names}). "
+                f"Resolve manually (remove all but one) and re-run."
+            )
+        if len(report.detected) == 1:
+            _migrate(root, report.detected[0], report)
+
+    (root / HARNESS_SKILLS).mkdir(parents=True, exist_ok=True)
+    (root / HARNESS_AGENTS).mkdir(parents=True, exist_ok=True)
+
+    agents_md = root / AGENTS_MD
+    if not agents_md.exists() and not agents_md.is_symlink():
+        if template is not None:
+            agents_md.write_text(template.read_text())
+        else:
+            agents_md.touch()
+        report.created_files.append(agents_md)
+
+    for name in agent_names:
+        _create_agent_symlinks(root, AGENT_REGISTRY[name], report.symlinks)
+
+    write_config(root, agent_names)
+    return report
+
+
+def _create_agent_symlinks(
+    root: Path,
+    spec: AgentSpec,
+    out: list[tuple[Path, SymlinkResult]],
+) -> None:
+    if spec.instructions_path is not None and spec.instructions_path != AGENTS_MD:
+        link = root / spec.instructions_path
+        try:
+            result = ensure_symlink(link, root / AGENTS_MD)
+        except FileExistsError as exc:
+            raise HarnessError(str(exc)) from exc
+        out.append((link, result))
+    for link_rel, target_rel in (
+        (spec.skills_path, HARNESS_SKILLS),
+        (spec.subagents_path, HARNESS_AGENTS),
+    ):
+        link = root / link_rel
+        try:
+            result = ensure_symlink(link, root / target_rel)
+        except FileExistsError as exc:
+            raise HarnessError(str(exc)) from exc
+        out.append((link, result))
+
+
+def add(root: Path, agent_names: list[str]) -> AddReport:
+    """Register new agents to an already-initialized harness.
+
+    Raises :class:`HarnessError` if the harness is absent, any name is unknown,
+    or any agent is already registered.
+    """
+    unknown = [n for n in agent_names if n not in AGENT_REGISTRY]
+    if unknown:
+        raise HarnessError(
+            f"Unknown agent(s): {', '.join(unknown)}. "
+            f"Supported: {', '.join(AGENT_REGISTRY)}."
+        )
+
+    if not (root / HARNESS_DIR).exists():
+        raise HarnessError(f"{HARNESS_DIR}/ not found. Run `mh init` first.")
+
+    try:
+        current = read_agent_names(root)
+    except ConfigError as exc:
+        raise HarnessError(str(exc)) from exc
+
+    already = [n for n in agent_names if n in current]
+    if already:
+        raise HarnessError(
+            f"Agent(s) already registered: {', '.join(already)}. "
+            f"Run `mh remove` first if you want to re-add."
+        )
+
+    report = AddReport()
+    for name in agent_names:
+        _create_agent_symlinks(root, AGENT_REGISTRY[name], report.symlinks)
+
+    write_config(root, current + agent_names)
+    return report
+
+
+def remove(root: Path, agent_names: list[str]) -> RemoveReport:
+    """Unlink symlinks for the given agents and clean up empty parent directories.
+
+    Raises :class:`HarnessError` if the harness is absent, any name is unknown,
+    or any agent is not currently registered.
+
+    Non-empty parent directories are reported in ``RemoveReport.nonempty_dirs``
+    and left for the caller to handle (e.g. interactive prompt).
+    """
+    unknown = [n for n in agent_names if n not in AGENT_REGISTRY]
+    if unknown:
+        raise HarnessError(
+            f"Unknown agent(s): {', '.join(unknown)}. "
+            f"Supported: {', '.join(AGENT_REGISTRY)}."
+        )
+
+    if not (root / HARNESS_DIR).exists():
+        raise HarnessError(f"{HARNESS_DIR}/ not found. Run `mh init` first.")
+
+    try:
+        current = read_agent_names(root)
+    except ConfigError as exc:
+        raise HarnessError(str(exc)) from exc
+
+    not_registered = [n for n in agent_names if n not in current]
+    if not_registered:
+        raise HarnessError(
+            f"Agent(s) not registered: {', '.join(not_registered)}. "
+            f"Run `mh status` to see registered agents."
+        )
+
+    report = RemoveReport()
+    parent_dirs: set[Path] = set()
+
+    for name in agent_names:
+        spec = AGENT_REGISTRY[name]
+        links: list[Path] = []
+        if spec.instructions_path is not None and spec.instructions_path != AGENTS_MD:
+            links.append(root / spec.instructions_path)
+        links.append(root / spec.skills_path)
+        links.append(root / spec.subagents_path)
+
+        for link in links:
+            if link.is_symlink():
+                parent = link.parent
+                link.unlink()
+                report.removed_symlinks.append(link)
+                if parent != root:
+                    parent_dirs.add(parent)
+
+    for d in sorted(parent_dirs):
+        if not any(d.iterdir()):
+            d.rmdir()
+            report.removed_dirs.append(d)
+        else:
+            report.nonempty_dirs.append(d)
+
+    remaining = [n for n in current if n not in set(agent_names)]
+    write_config(root, remaining)
+    return report

multi_harness/status.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from .agents import AGENT_REGISTRY, AgentSpec
+from .harness import AGENTS_MD, HARNESS_AGENTS, HARNESS_SKILLS
+
+LinkStatus = Literal["ok", "missing", "broken", "detached"]
+
+
+def check_symlink(link: Path, expected_target: Path) -> LinkStatus:
+    if link.is_symlink():
+        resolved = (link.parent / os.readlink(link)).resolve()
+        return "ok" if resolved == expected_target.resolve() else "broken"
+    if link.exists():
+        return "detached"
+    return "missing"
+
+
+@dataclass
+class AgentStatusRow:
+    label: str
+    status: LinkStatus
+
+
+@dataclass
+class AgentStatus:
+    spec: AgentSpec
+    rows: list[AgentStatusRow]
+
+    def is_ok(self) -> bool:
+        return all(r.status == "ok" for r in self.rows)
+
+
+def check_agent(root: Path, spec: AgentSpec) -> AgentStatus:
+    rows: list[AgentStatusRow] = []
+
+    if spec.instructions_path is not None and spec.instructions_path != AGENTS_MD:
+        rows.append(AgentStatusRow(
+            label=str(spec.instructions_path),
+            status=check_symlink(root / spec.instructions_path, root / AGENTS_MD),
+        ))
+
+    rows.append(AgentStatusRow(
+        label=str(spec.skills_path),
+        status=check_symlink(root / spec.skills_path, root / HARNESS_SKILLS),
+    ))
+    rows.append(AgentStatusRow(
+        label=str(spec.subagents_path),
+        status=check_symlink(root / spec.subagents_path, root / HARNESS_AGENTS),
+    ))
+
+    return AgentStatus(spec=spec, rows=rows)
+
+
+def check_all(root: Path, agent_names: list[str]) -> list[AgentStatus]:
+    return [check_agent(root, AGENT_REGISTRY[name]) for name in agent_names]

multi_harness/symlinks.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Literal
+
+SymlinkResult = Literal["created", "ok", "replaced"]
+
+
+def ensure_symlink(link: Path, target: Path) -> SymlinkResult:
+    """Create or update a relative symlink at ``link`` pointing at ``target``.
+
+    Returns ``"created"`` if newly made, ``"ok"`` if already correct, or
+    ``"replaced"`` if an existing symlink was repointed. Raises ``FileExistsError``
+    if ``link`` exists as a real file or directory (we never overwrite user data).
+    """
+    rel = Path(os.path.relpath(target, start=link.parent))
+
+    if link.is_symlink():
+        current = Path(os.readlink(link))
+        if current == rel:
+            return "ok"
+        link.unlink()
+        link.symlink_to(rel)
+        return "replaced"
+
+    if link.exists():
+        raise FileExistsError(
+            f"{link} already exists as a real file or directory; refusing to overwrite. "
+            f"Move or remove it manually, then re-run `mh init`."
+        )
+
+    link.parent.mkdir(parents=True, exist_ok=True)
+    link.symlink_to(rel)
+    return "created"

multi_harness-0.1.0.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: multi-harness
+Version: 0.1.0
+Summary: Manage projects that target multiple coding agents from a single shared harness.
+Author-email: jslarraz <jslarraz@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# multi-harness 🔗
+
+> One project. Many coding agents. Zero duplication.
+
+`mh` is a CLI that keeps your skills, subagents, and project instructions in a single
+canonical `.harness/` directory and materialises per-agent symlinks so every agent sees
+the paths it expects — no copy-paste, no drift.
+
+**Supported agents:** Claude Code · OpenAI Codex CLI · OpenCode · GitHub Copilot · Google Antigravity
+
+---
+
+## ✨ Why multi-harness?
+
+Each coding agent looks for instructions, skills, and subagents in different places:
+`CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `.claude/skills/`, `.codex/skills/` …
+
+Without `mh` you either duplicate these files across every agent-specific location or
+keep them in sync by hand. `mh` solves this by:
+
+1. Creating one real `.harness/` directory with the canonical files.
+2. Writing relative symlinks everywhere each agent expects to look.
+3. Detecting an existing single-agent project and **migrating** it automatically.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install multi-harness
+```
+
+Verify the install:
+
+```bash
+mh --help
+```
+
+---
+
+## 🚀 Quick start
+
+```bash
+cd my-project
+mh init
+```
+
+That's it. `mh` detects which agents are already configured, migrates their files into
+`.harness/`, and creates symlinks for all five supported agents.
+
+---
+
+## 📖 Commands
+
+### `mh init` — bootstrap or migrate a project
+
+```bash
+mh init                                      # all five agents, current directory
+mh init --agents claude,codex                # register only two agents
+mh init --template ./AGENTS_TEMPLATE.md      # seed AGENTS.md from a template file
+mh init --force                              # re-create symlinks idempotently (safe)
+mh init /path/to/project                     # target a different directory
+```
+
+On first run `mh init`:
+- Creates `AGENTS.md` (or uses your `--template`) as the shared project instructions file.
+- Creates `.harness/skills/` and `.harness/agents/` as the shared canonical directories.
+- Writes relative symlinks for every registered agent (see layout below).
+- Records the registered agents in `.harness/config.toml`.
+
+If exactly **one** agent is already configured, `mh init` migrates its files into
+`.harness/` before creating symlinks — your existing work is preserved, not overwritten.
+
+---
+
+### `mh add` — register new agents
+
+```bash
+mh add copilot                               # add a single agent
+mh add opencode antigravity                  # add multiple agents at once
+```
+
+Creates the symlinks for the new agent(s) and updates `.harness/config.toml`. Requires
+`mh init` to have been run first.
+
+---
+
+### `mh remove` — unregister agents
+
+```bash
+mh remove codex                              # remove one agent
+mh remove opencode copilot                   # remove several at once
+```
+
+Removes the agent's symlinks (instructions, skills, subagents) without touching any file
+inside `.harness/`. Your shared content is never deleted.
+
+---
+
+### `mh status` — inspect symlink health
+
+```bash
+mh status                                    # check current directory
+mh status /path/to/project                   # check another directory
+```
+
+Reports the state of every symlink for every registered agent:
+
+| Status | Meaning |
+|--------|---------|
+| ✅ `ok` | Symlink exists and resolves correctly |
+| ❌ `missing` | Symlink is absent |
+| 💔 `broken` | Symlink exists but target doesn't resolve |
+| ⚠️ `detached` | A real file/dir sits where a symlink should be |
+
+---
+
+## 🗂️ Layout produced by `mh init`
+
+```
+my-project/
+├── AGENTS.md                          ← canonical shared instructions (real file)
+├── CLAUDE.md                         → AGENTS.md
+├── .harness/
+│   ├── config.toml                    ← registered agents list
+│   ├── skills/                        ← shared skills (real dir)
+│   └── agents/                        ← shared subagents (real dir)
+├── .claude/
+│   ├── skills                        → ../.harness/skills
+│   └── agents                        → ../.harness/agents
+├── .codex/
+│   ├── skills                        → ../.harness/skills
+│   └── agents                        → ../.harness/agents
+├── .opencode/
+│   ├── skills                        → ../.harness/skills
+│   └── agent                         → ../.harness/agents
+├── .github/
+│   ├── copilot-instructions.md       → ../AGENTS.md
+│   ├── skills                        → ../.harness/skills
+│   └── agents                        → ../.harness/agents
+├── .agents/
+│   └── skills                        → ../.harness/skills
+└── .subagents                        → .harness/agents
+```
+
+All symlinks are **relative**, so the tree is fully portable across machines and paths.
+
+---
+
+## 🔄 Typical workflow
+
+```bash
+# 1. Bootstrap a new project
+mh init --agents claude,codex
+
+# 2. Add an agent later
+mh add copilot
+
+# 3. Check everything is wired up correctly
+mh status
+
+# 4. Remove an agent you no longer use
+mh remove antigravity
+```
+
+Write your instructions once in `AGENTS.md`, drop skills into `.harness/skills/`, and
+place shared subagents in `.harness/agents/` — every registered agent picks them up
+automatically.
+
+---
+
+## 🛡️ Safety guarantees
+
+- **Symlinks never overwrite real files.** If a real file or directory already exists
+  where a symlink should go, `mh` aborts with an error rather than deleting your data.
+- **`--force` is safe.** It re-creates symlinks but still refuses to touch real files.
+- **Migration is non-destructive.** Files are moved into `.harness/`; nothing is deleted.

multi_harness-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+multi_harness/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+multi_harness/cli.py,sha256=SVtmA_f54VarZVaLjebLiA3L0Lt6TG2wNPG08e6mjes,6146
+multi_harness/config.py,sha256=27V5UA7u8PTCBkjvzsF3qeuth4C27V02_r3MzdnBkPw,1358
+multi_harness/harness.py,sha256=rmQc-kxDZb7sCyZxOZlIgcjr0Qk-OFTLj_bH-i9pr5g,8575
+multi_harness/status.py,sha256=6NFiv7FNfzvpKEUymnfDhhhqnh8vhDbdkYX8Iy0sW1o,1720
+multi_harness/symlinks.py,sha256=T8AisxDGW1HyWnoWwIAjTe74QYpuUKHE0LEUU6HTasc,1119
+multi_harness/agents/__init__.py,sha256=jqH76KDGwwn7t2GEcSBHdORYKCMnhWomm1_Gl-rDLaM,398
+multi_harness/agents/antigravity.py,sha256=BSUBmzEsquJ8zH6ICr_nQJPWauVkxVpeNiplz5w7Q_I,304
+multi_harness/agents/claude.py,sha256=RHmukKe5TnjpniyF2GNFCMYFT68P2Eyb8irhZf5DuQE,308
+multi_harness/agents/codex.py,sha256=X_xDHYT5IbCdLsKMPI0D6xpfneN0FNRXNNX6aHj9bhE,274
+multi_harness/agents/copilot.py,sha256=u0LgCST2ByI9QLQqRvMJItZoLTT4hijQ2uOralBUJaU,340
+multi_harness/agents/opencode.py,sha256=27iCFSc1WiwLQ1tPo9NVrFPL7A9Wlx8GzNV0Zb9jLlU,281
+multi_harness/agents/spec.py,sha256=hqqXGLW43fVBxR7s1On-Jw-WvElQYQjx3QELC2_Rm5Q,294
+multi_harness-0.1.0.dist-info/METADATA,sha256=G7dGzOkm5JsdbUJi4egjxhFTVwIwKt30pK9RSf-frqE,6084
+multi_harness-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+multi_harness-0.1.0.dist-info/entry_points.txt,sha256=uSRPViv2-Oilz9mOBvAk_n8W1r9Zr_3drrGEX10ZQeE,45
+multi_harness-0.1.0.dist-info/RECORD,,

multi_harness-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

multi_harness-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mh = multi_harness.cli:app