feat: v0.3.0 harness selection (two-axis depth+harnesses) (#5)

* docs(spec): v0.3.0 harness selection design

Approved design for v0.3.0: split init into depth + harnesses axes,
let users pick any combination of claude / codex / openclaw / hermes,
introduce .solo-mise/config.json as the source of truth, keep legacy
--profile working through v0.3.0 with deprecation note, remove in
v0.4.0. Tracks issue #4.

* docs(plan): v0.3.0 harness selection implementation plan

20-task implementation plan derived from the v0.3.0 design spec.
Phases: foundation (Selection model, config.json, profile shim),
template manifests (depth/harnesses/includes), install engine,
CLI surface (flags + deprecation shim + interactive prompt),
surrounding tools (doctor, ingester, reconfigure), and ship
(docs, CHANGELOG, CI matrix, release).

* feat(selection): add Selection model + owner-priority resolver

* feat(config): add .solo-mise/config.json read/write

* feat(selection): add profile_to_selection legacy shim

* feat(templates): add depth manifests (repo, workspace)

* feat(templates): add per-harness manifests + codex inbox template

* feat(templates): add include manifests (publisher)

* feat(install): add install_selection engine that composes manifests

* feat(install): gitignore block adapts to selected writer harnesses

* feat(cli): add --depth, --harnesses, --owner, --include flags

* feat(cli): --profile becomes a deprecation shim translating to new flags

* feat(prompt): zero-dep interactive harness/depth/include picker

* feat(cli): route to interactive prompt when no selection flags given

* feat(doctor): read config.json + per-writer inbox checks + orphan warnings

* feat(ingest): scan all configured writer inboxes, not just .claude/

* feat(reconfigure): add subcommand to adjust selection on existing target

* docs: reframe around two-axis depth + harnesses model

* release: prepare v0.3.0

* ci: matrix replaces single profiles with depth+harnesses combos

Author: solomonneas

.github/workflows/ci.yml

@@ -51,7 +51,25 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        profile: [repo, workspace, openclaw, hermes, generic, publisher]
+        combo:
+          - name: "repo+claude"
+            flags: "--depth repo --harnesses claude"
+          - name: "repo+codex"
+            flags: "--depth repo --harnesses codex"
+          - name: "workspace+claude+openclaw"
+            flags: "--depth workspace --harnesses claude,openclaw"
+          - name: "workspace+codex+openclaw"
+            flags: "--depth workspace --harnesses codex,openclaw"
+          - name: "kitchen-sink"
+            flags: "--depth workspace --harnesses claude,codex,openclaw,hermes"
+          - name: "workspace+none"
+            flags: "--depth workspace --harnesses none"
+          - name: "repo+claude+publisher"
+            flags: "--depth repo --harnesses claude --include publisher"
+          - name: "legacy-workspace"
+            flags: "--profile workspace"
+          - name: "legacy-openclaw"
+            flags: "--profile openclaw"
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -64,17 +82,9 @@ jobs:
           solo-mise --version
       - name: Init + doctor
         run: |
-          target="/tmp/ci-smoke-${{ matrix.profile }}"
+          target="/tmp/sm-${{ matrix.combo.name }}"
           rm -rf "$target"
           mkdir -p "$target"
-          # The 'repo' profile installs a pre-push hook; that wants a git repo.
-          # Other profiles do not require one but it is harmless.
           git init -q -b main "$target"
-          solo-mise init --target "$target" --profile ${{ matrix.profile }}
-          # Doctor is harness-aware. Map the profile to the right --harness value.
-          case "${{ matrix.profile }}" in
-            openclaw) harness=openclaw ;;
-            hermes)   harness=hermes ;;
-            *)        harness=generic ;;
-          esac
-          solo-mise doctor --target "$target" --harness "$harness"
+          solo-mise init --target "$target" ${{ matrix.combo.flags }}
+          solo-mise doctor --target "$target"

CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-05-16
+
+### Added
+- Two-axis selection model: `--depth {repo,workspace}` + `--harnesses {claude,codex,openclaw,hermes}` + `--include publisher`. Pick any combination of harnesses.
+- Interactive prompt on bare `solo-mise init` (no flags). Defaults to claude + repo + no includes.
+- `.solo-mise/config.json` is now the per-target source of truth for selection state. Read by `doctor`, `ingest`, and `reconfigure`.
+- `solo-mise reconfigure --target . [--prune]` adjusts an existing install to a new selection. `--prune` removes orphaned files for deselected harnesses.
+- Per-writer handoff inboxes: `.codex/memory-handoffs/` for Codex (in addition to existing `.claude/memory-handoffs/`).
+- Ingester now scans all configured writer inboxes.
+- Doctor reports apparent harness shape, checks per-writer inbox, warns on orphaned inbox dirs from unselected harnesses.
+
+### Changed
+- README reframed around the two-axis model. New "Picking your harnesses" section walks through four common combos.
+- CONTRIBUTING.md "Adding a profile" replaced by "Adding a harness" + "Adding a depth" + "Adding an include".
+
+### Deprecated
+- `solo-mise init --profile <x>` still works but prints a stderr deprecation note pointing at the new flags. Will be removed in v0.4.0.
+
+### Migration
+
+If you have v0.2.0 scripts using `--profile`:
+
+| v0.2.0 | v0.3.0+ |
+|---|---|
+| `--profile repo` | `--depth repo --harnesses claude` |
+| `--profile workspace` | `--depth workspace --harnesses claude` |
+| `--profile openclaw` | `--depth workspace --harnesses claude,openclaw` |
+| `--profile hermes` | `--depth workspace --harnesses claude,hermes` |
+| `--profile generic` | `--depth workspace --harnesses none` |
+| `--profile publisher` | `--depth repo --harnesses claude --include publisher` |
+
 ## [0.2.0] - 2026-05-16
 
 ### Added
@@ -60,6 +91,7 @@ Initial release.
 - OpenClaw adapter fragments and harness-aware doctor checks.
 - Experimental Hermes adapter fragments.
 
-[Unreleased]: https://github.com/solomonneas/solo-mise/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/solomonneas/solo-mise/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/solomonneas/solo-mise/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/solomonneas/solo-mise/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/solomonneas/solo-mise/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -5,14 +5,14 @@ solo-mise is the installable kit behind [Solomon's Cookbook](https://github.com/
 ## What kinds of changes land easily
 
 - **Bug fixes** for `solo-mise init`, `doctor`, `scrub`, or the ingester.
-- **Profile improvements**: new bootstrap content, sharper post-install notes, better defaults.
-- **New harness adapters** (with doctor checks) under `src/solo_mise/templates/<harness>/`.
+- **Harness / depth / include improvements**: new bootstrap content, sharper post-install notes, better defaults.
+- **New harness adapters** (with doctor checks) under `src/solo_mise/templates/harnesses/<id>.json`.
 - **Doctor checks** that catch real, observed failure modes.
 - **Test coverage** for any of the above.
 
 ## What needs a conversation first
 
-- **A new top-level profile.** Open an issue first describing the user story. Profiles are the public surface and renaming or splitting them later is painful.
+- **A new top-level harness, depth, or include.** Open an issue first describing the user story. These are the public surface and renaming or splitting them later is painful.
 - **Breaking changes** to template paths, the handoff TEMPLATE.md fields, or the ingester routing rules.
 - **Anything that adds a runtime dependency.** solo-mise has zero runtime deps on purpose, and we want to keep it that way.
 
@@ -32,25 +32,36 @@ pip install -e ".[dev]"
 pytest -q
 ```
 
-To smoke-test a profile end-to-end the same way CI does:
+To smoke-test an install end-to-end the same way CI does:
 
 ```bash
 target=/tmp/solo-mise-smoke
 rm -rf "$target" && mkdir -p "$target" && git init -q "$target"
-python -m solo_mise init --target "$target" --profile workspace
+python -m solo_mise init --target "$target" --depth workspace --harnesses claude,codex,openclaw
 python -m solo_mise doctor --target "$target"
 ```
 
-## Adding a profile
+## Adding a harness
 
-A profile is a single JSON manifest in `src/solo_mise/templates/profiles/<id>.json` and any template files it references. Manifests support `extends` for inheritance. See `publisher.json` (extends `repo`) for the simplest example.
+A harness is a manifest under `src/solo_mise/templates/harnesses/<id>.json` plus any template files it references. The manifest declares `role: "writer"` (gets an inbox) or `role: "reader"` (gets adapter fragments).
 
-When you add a profile:
+To add a harness:
 
-1. Add it to the `choices=[...]` list in `src/solo_mise/cli.py` (the `--profile` flag).
-2. Add a row to the profile table in `README.md`.
-3. Add it to the matrix in `.github/workflows/ci.yml` so the smoke job exercises it.
-4. If it has post-install steps, list them in `post_install_notes`. They are printed at the end of `solo-mise init`.
+1. Create the manifest at `src/solo_mise/templates/harnesses/<id>.json`.
+2. Add template files under a harness-named directory (e.g. `src/solo_mise/templates/<id>/`).
+3. Add the harness id to `KNOWN_HARNESSES` in `src/solo_mise/selection.py`.
+4. Update `HARNESS_PRIORITY` if the new harness should be an owner candidate (readers usually want to land near OpenClaw/Hermes in the priority list).
+5. If it's a writer, add it to `_WRITER_INBOXES` in `src/solo_mise/install.py`, `src/solo_mise/doctor.py`, and `src/solo_mise/ingest.py`.
+6. Add the harness to the CI matrix in `.github/workflows/ci.yml`.
+7. Add a row to the harness table in `README.md`.
+
+## Adding a depth
+
+Depths live at `src/solo_mise/templates/depth/<id>.json` and may use `extends` to inherit from another depth. Add the id to `KNOWN_DEPTHS` in `selection.py` and to the `--depth` choices in `cli.py`.
+
+## Adding an include
+
+Includes live at `src/solo_mise/templates/includes/<id>.json`. Add the id to `KNOWN_INCLUDES` in `selection.py`.
 
 ## Adding a doctor check
 
@@ -68,7 +79,7 @@ Open a PR with all three and we'll land it.
 
 ## Filing issues
 
-Please use the templates under `.github/ISSUE_TEMPLATE/` - they exist to save you from re-typing the version and profile every time.
+Please use the templates under `.github/ISSUE_TEMPLATE/` - they exist to save you from re-typing the version and install shape every time.
 
 The `ingester-misclassified` template is the most useful one to file early. If a handoff that should have promoted to a card got bounced (or vice versa), that is a real bug in the routing rules, not a corner case. We want to see it.
 

QUICKSTART.md

@@ -15,96 +15,82 @@ python3 -m pip install --user pipx
 python3 -m pipx ensurepath
 ```
 
-## 2. Pick a profile
+## First install
 
-The default `repo` profile adds the handoff flow and a publish guard to an existing project.
+The fastest path is to run `solo-mise init` with no flags and answer the prompts:
 
-The `workspace` profile creates a home-style agent workspace from scratch.
-
-## 3. Initialize
+```bash
+$ solo-mise init --target ~/agent-kitchen
 
-### Repo profile (lightest)
+Which harnesses do you use? (type numbers separated by space/comma to toggle, enter to confirm)
+  [x] 1. Claude Code
+  [ ] 2. Codex
+  [ ] 3. OpenClaw
+  [ ] 4. Hermes (experimental)
 
-In a project you already work in:
+Depth? (type a number, enter for default)
+  * 1. repo       (handoff flow + publish guard)
+    2. workspace  (full home: MEMORY.md, TOOLS.md, USER.md, ...)
 
-```bash
-cd ~/repos/your-project
-solo-mise init --target .
+Add-ons? (type numbers separated by space/comma to toggle, enter to confirm)
+  [ ] 1. publisher  (content-guard policies for blog/social/docs)
 ```
 
-This creates:
-
-```text
-your-project/
-  AGENTS.md
-  CLAUDE.md
-  .claude/memory-handoffs/
-    TEMPLATE.md
-  hooks/
-    pre-push
-  .gitignore     # adds a managed solo-mise block (handoffs, daily logs, review inbox)
-```
+Defaults are claude harness, repo depth, no includes. Enter ships the install.
 
-The `.gitignore` block is bounded by `# >>> solo-mise gitignore block >>>` markers so re-running `init` is idempotent and your hand-written rules outside the block are preserved. Pass `--no-gitignore` to skip the gitignore step.
+## CI / scripted install
 
-Enable the pre-push hook once:
+Pass flags directly to skip the prompt:
 
 ```bash
-git config core.hooksPath hooks
-```
+# Claude Code + Codex + OpenClaw, full workspace
+solo-mise init --target ~/agent-kitchen \
+  --depth workspace \
+  --harnesses claude,codex,openclaw
 
-### Workspace profile
+# Codex-only project, minimal install
+solo-mise init --target ./my-project --depth repo --harnesses codex
 
-```bash
-solo-mise init --target ~/agent-kitchen --profile workspace
+# Generic layout, no harness-specific files
+solo-mise init --target ./my-project --harnesses none
 ```
 
-This creates the full bootstrap file set: `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, `USER.md`, `TOOLS.md`, `MEMORY.md`, `IDENTITY.md`, `HEARTBEAT.md`, `SAFETY_RULES.md`, `INSTALL_FOR_AGENTS.md`, plus `memory/cards/` with starter cards, a `.claude/memory-handoffs/` inbox, and the publish hook.
+## Verifying
 
-## 4. Verify
+After install, `solo-mise doctor --target <path>` reports the apparent harness shape and checks every configured inbox and adapter:
 
-```bash
-solo-mise doctor --target ~/agent-kitchen
 ```
-
-The doctor checks that the bootstrap files exist, the handoff inbox is in place, and (if you chose `--profile openclaw`) the OpenClaw config can see your workspace. It prints `OK` or `MANUAL ACTION NEEDED` per check; it never edits your config.
-
-## 5. Write your first handoff
-
-```bash
-solo-mise handoff-template --target ~/agent-kitchen > \
-  ~/agent-kitchen/.claude/memory-handoffs/$(date -u +%Y-%m-%dT%H%MZ)-first-handoff.md
+solo-mise doctor: target /home/you/agent-kitchen
+  harnesses: claude, codex, openclaw (owner=openclaw, depth=workspace)
+  [ok]   bootstrap: AGENTS.md   /home/you/agent-kitchen/AGENTS.md
+  [ok]   handoff: claude inbox  /home/you/agent-kitchen/.claude/memory-handoffs
+  [ok]   handoff: codex inbox   /home/you/agent-kitchen/.codex/memory-handoffs
+  [ok]   openclaw: config        /home/you/.openclaw/openclaw.json
+  ...
 ```
 
-Edit the file with whatever durable knowledge your agent just produced.
+A `[fail]` line means the install is incomplete; `[warn]` is informational; `[todo]` means the check needs your attention (e.g. Hermes is experimental).
 
-## 6. Ingest
+## Reconfiguring
 
-```bash
-solo-mise ingest --target ~/agent-kitchen --dry-run
-solo-mise ingest --target ~/agent-kitchen
-```
+To change which harnesses are installed on an existing target:
 
-The ingester is conservative. Handoffs with `Recommended memory action: create-card` and a safe filename + frontmatter become memory cards. Handoffs that route to `TOOLS.md`, `USER.md`, `rules/*.md`, or `.learnings/*.md` get appended. Anything ambiguous lands in `memory/handoff-inbox/` for manual review.
-
-If you administer multiple agent setups, keep one canonical owner and pull remote handoffs into staging directories before ingesting them. See `memory/cards/multi-workspace-handoff-admin.md`.
+```bash
+# Add a harness
+solo-mise reconfigure --target . --harnesses claude,codex
 
-## 7. Scrub before publishing
+# Drop one (without removing its files)
+solo-mise reconfigure --target . --harnesses claude
 
-```bash
-solo-mise scrub --target . --dry-run
+# Drop one and remove its files
+solo-mise reconfigure --target . --harnesses claude --prune
 ```
 
-If you have [content-guard](https://github.com/solomonneas/content-guard) installed, the pre-push hook will block pushes that contain private IPs, secrets, or AI attribution trailers. `solo-mise scrub` is the deterministic counterpart that runs the same scanner with the public-repo policy.
-
-## 8. OpenClaw users
+## The handoff flow
 
-```bash
-solo-mise doctor --target ~/.openclaw/workspace --harness openclaw
-solo-mise openclaw-fragments --out ./openclaw-fragments
-```
+The starter handoff template lives at `<inbox>/TEMPLATE.md`. Copy it to a new dated file (e.g. `2026-05-16-1430-fixed-X.md`), fill it in, and the ingester promotes safe card handoffs into `memory/cards/`, appends targeted updates to the right file, and kicks ambiguous material to the review inbox.
 
-The fragments are JSON files you can inspect and merge into your `openclaw.json` by hand. `solo-mise` never mutates your live OpenClaw config.
+See the [Solo Cookbook](https://github.com/solomonneas/solos-cookbook) for the longer-form guidance on what makes a good handoff and when to use which routing.
 
 ## Next steps