multi-harness 0.1.0__tar.gz

multi_harness-0.1.0/.claude/settings.local.json

@@ -0,0 +1,32 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:docs.claude.com)",
+      "WebFetch(domain:docs.github.com)",
+      "WebFetch(domain:code.visualstudio.com)",
+      "WebFetch(domain:opencode.ai)",
+      "WebFetch(domain:antigravity.google)",
+      "WebFetch(domain:docs.google.com)",
+      "WebFetch(domain:docs.anthropic.com)",
+      "WebFetch(domain:developer.cursor.so)",
+      "WebFetch(domain:cursor.com)",
+      "WebFetch(domain:www.jetbrains.com)",
+      "WebFetch(domain:codeium.com)",
+      "WebFetch(domain:windsurf.com)",
+      "WebFetch(domain:docs.openai.com)",
+      "WebFetch(domain:github.blog)",
+      "WebFetch(domain:ai.google.dev)",
+      "WebFetch(domain:developers.google.com)",
+      "WebFetch(domain:copilot.github.com)",
+      "WebFetch(domain:developer.chrome.com)",
+      "WebFetch(domain:developers.openai.com)",
+      "Bash(.venv/bin/mh --help)",
+      "Bash(.venv/bin/mh init *)",
+      "Bash(.venv/bin/mh add *)",
+      "Bash(.venv/bin/mh remove *)",
+      "Bash(.venv/bin/mh status *)"
+    ]
+  }
+}

multi_harness-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+
+.pytest_cache/
+.venv/
+.idea/
+.env
+dist/
+*.egg-info/

multi_harness-0.1.0/CLAUDE.md

@@ -0,0 +1,179 @@
+# multi-harness — project reference
+
+## What this is
+
+`mh` is a Python CLI that lets a single project share skills, subagents, and project
+instructions across multiple coding agents without duplication. It creates a canonical
+`.harness/` directory and materializes per-agent symlinks so every agent sees its
+expected paths.
+
+Console script: `mh` (installed via `pip install -e .`)
+Package: `multi_harness` — `src/` layout, `pyproject.toml` + hatchling.
+
+---
+
+## Architecture
+
+```
+src/multi_harness/
+├── cli.py          Typer app (group mode via @app.callback()).
+│                   Entry point: mh init, future: mh add/remove/status/sync
+├── harness.py      Core logic: detect_configured_agents(), init().
+│                   Owns the HARNESS_DIR / AGENTS_MD path constants.
+├── symlinks.py     ensure_symlink(link, target) — relative, idempotent, never
+│                   overwrites real files. Returns "created"/"ok"/"replaced".
+└── agents/
+    ├── spec.py     AgentSpec dataclass (frozen). Fields: name, display_name,
+    │               instructions_path (None if native AGENTS.md reader),
+    │               skills_path, subagents_path, detection_paths.
+    ├── __init__.py AGENT_REGISTRY: dict[str, AgentSpec] — add a new file here
+    │               to support a new agent.
+    ├── claude.py        Claude Code
+    ├── codex.py         OpenAI Codex CLI
+    ├── opencode.py      OpenCode
+    ├── copilot.py       GitHub Copilot
+    └── antigravity.py   Google Antigravity
+```
+
+Tests live in `tests/test_init.py`. Run with `.venv/bin/pytest`.
+
+---
+
+## Canonical layout produced by `mh init`
+
+```
+AGENTS.md               canonical project instructions (real file)
+.harness/
+  skills/               real dir — shared skills
+  agents/               real dir — shared subagents
+CLAUDE.md            -> AGENTS.md
+.claude/
+  skills               -> ../.harness/skills
+  agents               -> ../.harness/agents
+  settings.json           (untouched — agent-specific)
+.codex/
+  skills               -> ../.harness/skills
+  agents               -> ../.harness/agents
+.opencode/
+  skills               -> ../.harness/skills
+  agent                -> ../.harness/agents   (NB: singular)
+.github/
+  copilot-instructions.md -> ../AGENTS.md
+  skills               -> ../.harness/skills
+  agents               -> ../.harness/agents
+.agents/
+  skills               -> ../.harness/skills
+.subagents             -> .harness/agents       (Antigravity — root-level)
+```
+
+All symlinks are **relative** so the tree is portable across machines and paths.
+
+---
+
+## Per-agent path reference (as of 2026)
+
+| Agent | instructions_path | skills_path | subagents_path | detection_paths |
+|-------|-------------------|-------------|----------------|-----------------|
+| claude | `CLAUDE.md` | `.claude/skills` | `.claude/agents` | `CLAUDE.md`, `.claude` |
+| codex | *native AGENTS.md* | `.codex/skills` | `.codex/agents` | `.codex` |
+| opencode | *native AGENTS.md* | `.opencode/skills` | `.opencode/agent` ⚠️ | `.opencode` |
+| copilot | `.github/copilot-instructions.md` | `.github/skills` | `.github/agents` | `.github/copilot-instructions.md` |
+| antigravity | *native AGENTS.md* | `.agents/skills` | `.subagents` ⚠️ | `.agents`, `.subagents` |
+
+⚠️ opencode uses singular `agent/` (not `agents/`).  
+⚠️ Antigravity's subagent path `.subagents/` is root-level, inferred from docs as of Jun 2026 — may need revision.
+
+**Adding a new agent:** create `src/multi_harness/agents/<name>.py` with a `SPEC`
+`AgentSpec` instance, then add it to `AGENT_REGISTRY` in `agents/__init__.py`.
+
+---
+
+## Key design decisions
+
+**Detection skips symlinks.** `detect_configured_agents()` only fires when
+`.harness/` does NOT yet exist. On `--force` re-init, detection is skipped entirely
+— we never mistake our own symlinks for a natively-configured agent.
+
+**`AGENTS.md` is not a detection signal.** Three agents (codex, opencode, antigravity)
+natively read `AGENTS.md`, so its presence is ambiguous. Detection looks only at
+agent-specific dirs/files (`.codex/`, `.opencode/`, `.github/copilot-instructions.md`,
+`.agents/`, `.subagents/`, `CLAUDE.md`, `.claude/`).
+
+**`instructions_path=None` means the agent is an AGENTS.md native.** No instruction
+symlink is created for codex/opencode/antigravity — they already find the canonical
+file. Only `CLAUDE.md` and `.github/copilot-instructions.md` need symlinks.
+
+**`ensure_symlink` never deletes user data.** If the link target already exists as a
+real file or directory, it raises `HarnessError` and the whole `init()` call aborts.
+Migration happens before symlink creation, so migrated dirs are real dirs in `.harness/`
+by the time symlinks are created.
+
+**Migration is one-shot.** When exactly one agent is detected, its files are moved into
+`.harness/` and symlinks replace them. There is no "dry-run" or partial migration.
+
+---
+
+## Upcoming commands (planned)
+
+All four commands will depend on a `.harness/config.toml` that records which agents are
+registered for the project. `mh init` will write this file; subsequent commands read it.
+
+### `mh add <agent> [--agents ...]`
+Register one or more new agents to an existing harness: validate that `.harness/` exists,
+create the symlinks for the new agent(s), update config.toml.
+
+### `mh remove <agent> [--agents ...]`
+Remove an agent's symlinks (unlink instructions, skills, subagents paths) without deleting
+any `.harness/` content. Update config.toml.
+
+### `mh status`
+Read config.toml to know which agents are registered, then inspect each symlink:
+- `ok` — symlink exists and points to the right place
+- `missing` — symlink is absent (agent was added manually after init?)
+- `broken` — symlink target doesn't resolve
+- `detached` — real file/dir where a symlink should be
+Report per-agent, per-link.
+
+### `mh sync [--agents ...]`
+Re-create any missing or broken symlinks for registered agents (like `--force` but
+restricted to links that actually need repair). Reads config.toml, calls `ensure_symlink`
+for each link, skips those that are already `"ok"`.
+
+---
+
+## config.toml schema (planned)
+
+File: `.harness/config.toml`
+
+```toml
+[harness]
+version = 1
+agents = ["claude", "codex", "opencode", "copilot", "antigravity"]
+```
+
+The `agents` list is the source of truth for which agents are registered. Commands that
+need it (`status`, `sync`, `add`, `remove`) read it; `init` writes it.
+
+---
+
+## Open questions / future considerations
+
+- **Antigravity subagent path:** documented as `.subagents/` (root-level). Confirm when
+  official Antigravity docs clarify the subagents directory convention.
+- **config.toml location:** `.harness/config.toml` keeps all harness state in one place;
+  an alternative is `multi-harness.toml` at the repo root (more visible).
+- **Skill/agent file format validation:** should `mh` inspect SKILL.md frontmatter (name,
+  description fields) for correctness? Deferred for now.
+- **Per-agent instruction overlays** (`.harness/instructions/<agent>.md`) are explicitly
+  out of scope for now — one shared AGENTS.md is the intent.
+
+---
+
+## Development
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest             # 13 tests, all scenarios
+.venv/bin/mh --help
+.venv/bin/mh init --help
+```

multi_harness-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,177 @@
+# 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/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "multi-harness"
+version = "0.1.0"
+description = "Manage projects that target multiple coding agents from a single shared harness."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "jslarraz", email = "jslarraz@gmail.com" }]
+dependencies = [
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+]
+
+[project.scripts]
+mh = "multi_harness.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/multi_harness"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

multi_harness-0.1.0/src/multi_harness/__init__.py

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

multi_harness-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"),),
+)