LightconeResearch · aboucaud · Jun 3, 2026 · Jun 3, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -51,7 +51,8 @@ src/lightcone/              # namespace — NO __init__.py
 │   ├── __init__.py         # exposes main()
 │   ├── commands.py         # init, run, status, verify, build
 │   ├── plugin.py           # get_plugin_source_dir
-│   └── claude/             # force-included Claude plugin bundle (in installed wheel only)
+│   ├── harness.py          # HARNESS_REGISTRY, HarnessConfig — add new harnesses here
+│   └── plugin/             # force-included harness plugin bundle (in installed wheel only)
 ├── engine/                 # execution substrate — Snakemake-based
 │   ├── __init__.py
 │   ├── manifest.py         # write_manifest, sha256_dir, code_version — the integrity layer
@@ -66,7 +67,7 @@ src/lightcone/              # namespace — NO __init__.py
     ├── cli.py              # `lc eval` subcommand group
     ├── harness.py, sandbox.py, graders.py, build.py, report.py, models.py
 
-claude/lightcone/           # Claude plugin source — force-included into the wheel
+plugin/lightcone/           # Harness-agnostic plugin source — force-included into the wheel
 ├── skills/                 # lc-new, lc-from-code, lc-from-paper,
 │                            # lc-feedback, ralph;
 │                            # paper-reproduction bundle: lc-from-paper (entry),
@@ -75,7 +76,7 @@ claude/lightcone/           # Claude plugin source — force-included into the w
 │                            # check-sentence-by-sentence
 │                            # (see skills/README.md for the full bundle map)
 ├── agents/                 # lc-extractor
-├── templates/              # Project CLAUDE.md template
+├── templates/              # Project AGENTS.md template
 └── scripts/                # Session hooks (bash): venv activation, validate-on-save, session-start primer
 
 tests/                      # pytest — mirrors src/ structure
@@ -136,7 +137,7 @@ astra.yaml ── snakefile.generate() ──> .lightcone/Snakefile + .lightcone
 - `lc status` reads only manifests — works offline, no Snakemake or DB needed
 
 **CLI surface:**
-- `lc init` — scaffold project with .claude/, CLAUDE.md, .gitignore, .lightcone/, results/, universes/
+- `lc init` — scaffold project with .claude/, AGENTS.md, CLAUDE.md, .gitignore, .lightcone/, results/, universes/
 - `lc run [outputs...]` — generate Snakefile, invoke snakemake
 - `lc status` — manifest-driven status report
 - `lc verify` — chain integrity check
@@ -152,7 +153,8 @@ Global config (`~/.lightcone/config.yaml`) is auto-created with defaults on firs
 | Change manifest semantics | `src/lightcone/engine/manifest.py` + `tests/test_manifest.py` | Bump `SCHEMA_VERSION`; add a test |
 | Change Snakefile shape | `src/lightcone/engine/snakefile.py` + `tests/test_snakefile.py` | Includes a `snakemake -n` parse test |
 | Add container features | `src/lightcone/engine/container.py` | `compute_image_tag()`, build/resolve functions |
-| Create a skill | `claude/lightcone/skills/` | SKILL.md with YAML frontmatter (`name`, `description`, `allowed-tools`) |
+| Create a skill | `plugin/lightcone/skills/` | SKILL.md with YAML frontmatter (`name`, `description`, `allowed-tools`) |
+| Add a harness | `src/lightcone/cli/harness.py` | Add entry to `HARNESS_REGISTRY`; one PR per harness |
 
 ## Test Patterns
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -234,20 +234,39 @@ the qualified `<analysis_id>.<output_id>` form.
 
 ---
 
-## Claude Code plugin
+## Agent harness plugin
 
-The plugin lives at `claude/lightcone/`. It is force-included into the
+The plugin lives at `plugin/lightcone/`. It is force-included into the
 installed wheel via `pyproject.toml` so `lc init` can find it whether
 you're running from source or from PyPI:
 
 ```toml
 [tool.hatch.build.targets.wheel.force-include]
-"claude/lightcone" = "lightcone/cli/claude/lightcone"
+"plugin/lightcone" = "lightcone/cli/plugin/lightcone"
 ```
 
 `lightcone.cli.plugin.get_plugin_source_dir()` does the lookup: bundled
 location first, dev location (relative to the repo root) second.
 
+### Harness registry
+
+`lc init` asks which AI coding harness to install skills for (e.g. `claude`).
+The registry lives in `lightcone.cli.harness.HARNESS_REGISTRY` — one entry per
+supported tool, with `prefix` (target directory), `has_hooks`, and
+`has_settings` flags.
+
+Currently only `claude` (Claude Code, `.claude/`) is registered. Future
+harnesses are added one PR at a time so skill performance can be verified per
+tool before the next is added.
+
+- **Harness-neutral content** (skills, agents) is copied to `.<prefix>/` for
+  every selected harness.
+- **Claude-specific content** (hooks, scripts, `settings.json`) is only
+  installed when `harness.has_hooks` / `harness.has_settings` are set.
+- **`AGENTS.md`** (the project documentation file) is always written to the
+  project root. For the Claude harness a lightweight `CLAUDE.md` shim is
+  also written pointing to `AGENTS.md`.
+
 ### Permission tiers
 
 `lc init --permissions {yolo,recommended,minimal}` writes a
@@ -287,12 +306,12 @@ src/lightcone/                  # PEP 420 namespace package — NO __init__.py
 
 src/snakemake_executor_plugin_dask/   # Snakemake executor → dask.distributed
 
-claude/lightcone/               # Claude Code plugin (force-included into the wheel)
+plugin/lightcone/               # Claude Code plugin (force-included into the wheel)
 ├── skills/                     # lc-new, lc-from-code, lc-from-paper,
 │                                # lc-feedback, ralph (+ bundle siblings);
 │                                # reference skills: astra, lc-cli
 ├── agents/                     # lc-extractor (literature subagent)
-├── templates/                  # project CLAUDE.md template
+├── templates/                  # project AGENTS.md template
 └── scripts/                    # session hooks (bash): venv, validate-on-save, session-start primer
 
 tests/                          # pytest, mirrors src/

diff --git a/docs/cli/init.md b/docs/cli/init.md
@@ -1,6 +1,6 @@
 # lc init
 
-Scaffold a new ASTRA project with Claude Code integration.
+Scaffold a new ASTRA project with agent harness integration.
 
 ## Synopsis
 
@@ -16,14 +16,15 @@ Inside `DIRECTORY` (creating it if needed):
 
 ```text
 astra.yaml                    # tiny boilerplate spec with one example output
-CLAUDE.md                     # short note pointing future agents at the project
+AGENTS.md                     # harness-neutral project doc (all harnesses)
+CLAUDE.md                     # lightweight shim pointing to AGENTS.md (Claude harness only)
 .gitignore                    # Python + lightcone state
 .lightcone/
   lightcone.yaml              # currently a stub: { target: local }
 results/                      # placeholder; populated by `lc run`
 universes/                    # placeholder; populate via `astra universe generate -n …`
-.claude/                      # bundled Claude Code plugin
-  skills/, agents/, hooks/, scripts/, templates/
+.claude/                      # Claude Code plugin (when harness is 'claude')
+  skills/, agents/, scripts/, templates/
   settings.json               # the chosen permission tier
 .venv/                        # Python venv (skipped with --no-venv)
 ```
@@ -36,12 +37,12 @@ universes/                    # placeholder; populate via `astra universe genera
 |--------|---------|--------|
 | `--no-git` | off | Skip `git init`. |
 | `--no-venv` | off | Skip `python -m venv .venv`. |
-| `--permissions {yolo,recommended,minimal}` | `recommended` | Which `.claude/settings.json` permission tier to install. |
+| `--harness {claude}` | prompted | AI coding harness to install skills for. |
+| `--permissions {yolo,recommended,minimal}` | `recommended` | Which `.claude/settings.json` permission tier to install (Claude harness only). |
 
 > The historical `--target`, `--existing-project`, and `--sub-analysis`
-> flags have been removed; today's `lc init` only knows the three flags
-> above. For migrating an existing project, run `lc init` in a fresh
-> directory and use the `/lc-from-code` skill from inside Claude Code.
+> flags have been removed. For migrating an existing project, run `lc init` in
+> a fresh directory and use the `/lc-from-code` skill.
 
 ## Permission tiers
 
@@ -58,10 +59,10 @@ or change defaults.
 ## Examples
 
 ```bash
-lc init                                # scaffold in cwd, recommended tier
-lc init my-analysis                    # scaffold in ./my-analysis
-lc init my-analysis --no-git --no-venv # bare bones
-lc init . --permissions yolo           # for autonomous loops you trust
+lc init                                     # scaffold in cwd; prompts for harness
+lc init my-analysis --harness claude        # scaffold with Claude Code
+lc init my-analysis --no-git --no-venv      # bare bones
+lc init . --harness claude --permissions yolo  # for autonomous loops you trust
 ```
 
 ## Next steps

diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md
@@ -61,14 +61,14 @@ just build              # uv build
 just version            # current version (from git tags via hatch-vcs)
 ```
 
-The plugin (`claude/lightcone/`) is force-included into the wheel:
+The plugin (`plugin/lightcone/`) is force-included into the wheel:
 
 ```toml
 [tool.hatch.build.targets.wheel]
 packages = ["src/lightcone", "src/snakemake_executor_plugin_dask"]
 
 [tool.hatch.build.targets.wheel.force-include]
-"claude/lightcone" = "lightcone/cli/claude/lightcone"
+"plugin/lightcone" = "lightcone/cli/plugin/lightcone"
 ```
 
 That layout is what `lightcone.cli.plugin.get_plugin_source_dir()`
@@ -80,7 +80,7 @@ relative to the repo root.
 ```text
 src/lightcone/                       # main namespace (PEP 420; no __init__.py at the package root)
 src/snakemake_executor_plugin_dask/  # Snakemake → Dask executor plugin
-claude/lightcone/                    # Claude Code plugin (force-included into the wheel)
+plugin/lightcone/                    # Claude Code plugin (force-included into the wheel)
 tests/                               # pytest tree, mirrors src/
 evals/                               # eval task fixtures (tasks/snae/)
 docs/                                # docs site

diff --git a/docs/skills/authoring.md b/docs/skills/authoring.md
@@ -1,14 +1,14 @@
 # Authoring Skills
 
 Skills are markdown files with YAML frontmatter. Each one lives in
-`claude/lightcone/skills/<name>/SKILL.md`. Add helper scripts under
+`plugin/lightcone/skills/<name>/SKILL.md`. Add helper scripts under
 `scripts/` and any longer prompts under `assets/` next to the
 `SKILL.md`.
 
 ## File layout
 
 ```text
-claude/lightcone/skills/
+plugin/lightcone/skills/
 └── my-skill/
     ├── SKILL.md
     ├── assets/                # optional — long prompt fragments, templates

diff --git a/docs/skills/check-sentence-by-sentence.md b/docs/skills/check-sentence-by-sentence.md
@@ -6,7 +6,7 @@ results, discussion, and appendices, locate the corresponding code
 (`file:line`) or mark `NOT FOUND`. The agent does **not** run any
 code — this is a static reading audit.
 
-Source: [`claude/lightcone/skills/check-sentence-by-sentence/SKILL.md`](https://github.com/LightconeResearch/lightcone-cli/blob/main/claude/lightcone/skills/check-sentence-by-sentence/SKILL.md).
+Source: [`plugin/lightcone/skills/check-sentence-by-sentence/SKILL.md`](https://github.com/LightconeResearch/lightcone-cli/blob/main/plugin/lightcone/skills/check-sentence-by-sentence/SKILL.md).
 
 Argument hint: `[path to paper source, e.g. work/reference/source/main.tex or work/reference/document.md]`.
 

diff --git a/docs/skills/figure-comparison.md b/docs/skills/figure-comparison.md
@@ -6,7 +6,7 @@ on the right, with red flags wherever a counterpart is missing. Images
 are base64-embedded so the HTML is portable. Run from a project folder
 containing `astra.yaml`.
 
-Source: [`claude/lightcone/skills/figure-comparison/SKILL.md`](https://github.com/LightconeResearch/lightcone-cli/blob/main/claude/lightcone/skills/figure-comparison/SKILL.md).
+Source: [`plugin/lightcone/skills/figure-comparison/SKILL.md`](https://github.com/LightconeResearch/lightcone-cli/blob/main/plugin/lightcone/skills/figure-comparison/SKILL.md).
 
 Argument hint: `[path to paper reference dir, e.g. work/reference/]`.
 

diff --git a/docs/skills/index.md b/docs/skills/index.md
@@ -40,7 +40,7 @@ dispatches them by role during the reproduction.
 | [figure-comparison](figure-comparison.md) | `/figure-comparison` | Build a self-contained HTML side-by-side: paper figures, tables, and numerics vs reproduced artifacts. |
 | [check-sentence-by-sentence](check-sentence-by-sentence.md) | `/check-sentence-by-sentence` | Static audit of paper claims against code locations (`file:line` or `NOT FOUND`). |
 
-See the [bundle README](https://github.com/LightconeResearch/lightcone-cli/blob/main/claude/lightcone/skills/README.md) for the rationale behind co-location vs plugin install.
+See the [bundle README](https://github.com/LightconeResearch/lightcone-cli/blob/main/plugin/lightcone/skills/README.md) for the rationale behind co-location vs plugin install.
 
 ### Reference skills (auto-primed via session-start)
 
@@ -55,7 +55,7 @@ These intentionally stay out of the top-level README. Researchers use the projec
 
 ## How a skill is wired
 
-Each skill is a `claude/lightcone/skills/<name>/SKILL.md` file with
+Each skill is a `plugin/lightcone/skills/<name>/SKILL.md` file with
 YAML frontmatter:
 
 ```yaml
@@ -77,11 +77,11 @@ and longer prompt fragments under `assets/` when relevant.
 ## Plugin layout
 
 ```text
-claude/lightcone/
+plugin/lightcone/
 ├── skills/
 │   ├── lc-new/{SKILL.md, references/*.md}
 │   ├── lc-from-code/SKILL.md
-│   ├── lc-from-paper/{SKILL.md, references/*.md, templates/{constitution.md, CLAUDE.md}}
+│   ├── lc-from-paper/{SKILL.md, references/*.md, templates/{constitution.md, AGENTS.md}}
 │   ├── lc-feedback/SKILL.md
 │   ├── ralph/{SKILL.md, references/*.md, scripts/ralph}
 │   ├── paper-extraction/{SKILL.md, scripts/*.py}
@@ -91,7 +91,7 @@ claude/lightcone/
 │   ├── astra/SKILL.md                  # reference: astra.yaml spec
 │   └── lc-cli/SKILL.md                 # reference: lc workflow
 ├── agents/lc-extractor.md             # literature subagent for /lc-new
-├── templates/CLAUDE.md                # the project CLAUDE.md template
+├── templates/AGENTS.md                # the project AGENTS.md template
 └── scripts/*.sh                       # session lifecycle hooks (incl. session-start primer)
 ```
 
@@ -105,8 +105,8 @@ The two reference *skills* (`/astra` and `/lc-cli`) live under `skills/` and are
 
 | File | Purpose |
 |------|---------|
-| `claude/lightcone/agents/lc-extractor.md` | Literature extraction subagent invoked by `/lc-new`. |
-| `claude/lightcone/scripts/session-start.sh` | Session-start hook — surfaces validation + materialization status and primes Claude with the substrate CLIs and reference skill names. |
+| `plugin/lightcone/agents/lc-extractor.md` | Literature extraction subagent invoked by `/lc-new`. |
+| `plugin/lightcone/scripts/session-start.sh` | Session-start hook — surfaces validation + materialization status and primes Claude with the substrate CLIs and reference skill names. |
 
 ## Authoring a new skill
 

diff --git a/docs/skills/lc-feedback.md b/docs/skills/lc-feedback.md
@@ -4,7 +4,7 @@ File a GitHub issue against the right Lightcone repo from inside a
 session, with version info and error context auto-collected. Be fast —
 the user is in the middle of work.
 
-Source: [`claude/lightcone/skills/lc-feedback/SKILL.md`](https://github.com/LightconeResearch/lightcone-cli/blob/main/claude/lightcone/skills/lc-feedback/SKILL.md).
+Source: [`plugin/lightcone/skills/lc-feedback/SKILL.md`](https://github.com/LightconeResearch/lightcone-cli/blob/main/plugin/lightcone/skills/lc-feedback/SKILL.md).
 
 Argument hint: `<what went wrong>`.
 

diff --git a/docs/skills/lc-from-code.md b/docs/skills/lc-from-code.md
@@ -5,7 +5,7 @@ drafts `astra.yaml` against what the code already does, parameterizes
 its hardcoded analytical choices, and runs until outputs materialize.
 Existing logic stays intact; the edits are minimal parameter plumbing.
 
-Source: [`claude/lightcone/skills/lc-from-code/SKILL.md`](https://github.com/LightconeResearch/lightcone-cli/blob/main/claude/lightcone/skills/lc-from-code/SKILL.md).
+Source: [`plugin/lightcone/skills/lc-from-code/SKILL.md`](https://github.com/LightconeResearch/lightcone-cli/blob/main/plugin/lightcone/skills/lc-from-code/SKILL.md).
 
 ## Allowed tools