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

[solomonneas]

Summary

v0.3.0 replaces the single-pick profile model with a two-axis selection so users can pick any combination of Claude Code, Codex, OpenClaw, and Hermes. Closes #4.

Three things change:

1. solo-mise init becomes interactive by default. No flags drops you into a checkbox-style picker (harnesses, depth, includes). Pass --depth / --harnesses / --include to skip the prompt for CI/scripts.
2. Per-writer handoff inboxes. Codex gets .codex/memory-handoffs/. The ingester scans every configured writer inbox.
3. .solo-mise/config.json is the per-target source of truth. doctor, ingest, and the new reconfigure subcommand all read it.

--profile <x> still works but prints a stderr deprecation note; will be removed in v0.4.0.

Implementation

Built task-by-task from docs/plans/2026-05-16-v0.3.0-harness-selection.md (18 commits in this PR). Design spec at docs/specs/2026-05-16-v0.3.0-harness-selection-design.md.

Phases:

• Foundation: Selection model + Config schema + profile_to_selection shim
• Templates: depth, harnesses, includes manifests (existing template files reused, only the codex inbox TEMPLATE.md is new on disk)
• Install engine: install_selection composes manifests, writes config, manages gitignore
• CLI: --depth/--harnesses/--owner/--include flags + --profile deprecation shim + interactive prompt + reconfigure subcommand
• Surrounding tools: doctor reads config + per-writer inbox checks + orphan warnings; ingester scans configured inboxes
• Polish: README/QUICKSTART/CONTRIBUTING reframed; CHANGELOG entry; CI matrix replaced

Test plan

• pytest -q: 115 passed (50 prior + 65 new)
• 9-combo local install+doctor smoke (the same matrix CI runs):

  repo+claude               14 checks, 0 failed
  repo+codex                14 checks, 0 failed
  ws+claude+openclaw        24 checks, 0 failed
  ws+codex+openclaw         24 checks, 0 failed
  kitchen-sink              31 checks, 0 failed, 1 manual (hermes experimental)
  ws+none                   13 checks, 0 failed
  repo+claude+publisher     14 checks, 0 failed
  legacy-workspace          16 checks, 0 failed (deprecation warning fires)
  legacy-openclaw           24 checks, 0 failed (deprecation warning fires)
  

• reconfigure --prune smoke: claude+codex install -> reconfigure --harnesses claude --prune -> .codex/ removed, config updated
• Non-TTY init guard: bare init with stdin redirected from /dev/null returns clean error pointing at flags
• CI matrix green on this PR
• After merge: tag v0.3.0, watch publish.yml, verify pip install solo-mise==0.3.0 (using rotated PyPI token)

Migration

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

The deprecation warning includes the exact equivalent flags for each invocation.

Summary by CodeRabbit

Release Notes v0.3.0

• New Features

  • Interactive solo-mise init for selecting harnesses, depth, and add-ons
  • Two-axis selection model: --depth (repo/workspace) + --harnesses (claude/codex/openclaw/hermes)
  • New reconfigure command with optional harness pruning
  • Multi-writer inbox support with separate memory-handoff directories per harness
  • Enhanced doctor checks for harness configuration validation

• Deprecations

  • --profile flag deprecated; use --depth and --harnesses flags instead

• Documentation

  • Updated README, QUICKSTART, and contribution guidelines with new selection model examples

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9cfd004b-af2c-4fe8-af0d-464e0dbbf73c

📥 Commits

Reviewing files that changed from the base of the PR and between db6eb78 and dd2416a.

📒 Files selected for processing (36)

• .github/workflows/ci.yml
• CHANGELOG.md
• CONTRIBUTING.md
• QUICKSTART.md
• README.md
• docs/plans/2026-05-16-v0.3.0-harness-selection.md
• docs/specs/2026-05-16-v0.3.0-harness-selection-design.md
• pyproject.toml
• src/solo_mise/__init__.py
• src/solo_mise/cli.py
• src/solo_mise/config.py
• src/solo_mise/doctor.py
• src/solo_mise/ingest.py
• src/solo_mise/install.py
• src/solo_mise/prompt.py
• src/solo_mise/reconfigure.py
• src/solo_mise/selection.py
• src/solo_mise/templates.py
• src/solo_mise/templates/codex/memory-handoffs/TEMPLATE.md
• src/solo_mise/templates/depth/repo.json
• src/solo_mise/templates/depth/workspace.json
• src/solo_mise/templates/harnesses/claude.json
• src/solo_mise/templates/harnesses/codex.json
• src/solo_mise/templates/harnesses/hermes.json
• src/solo_mise/templates/harnesses/openclaw.json
• src/solo_mise/templates/includes/publisher.json
• tests/test_config.py
• tests/test_doctor.py
• tests/test_fragments.py
• tests/test_gitignore.py
• tests/test_ingest.py
• tests/test_init.py
• tests/test_install.py
• tests/test_prompt.py
• tests/test_reconfigure.py
• tests/test_selection.py

---

📝 Walkthrough

Walkthrough

This release introduces a two-axis harness selection model replacing the single --profile concept, enabling per-harness inbox configuration and multi-writer support. The v0.3.0 implementation adds interactive selection prompting, persistent target configuration, multi-manifest composition, and updates the doctor and ingester to be harness-aware.

Changes

Two-axis harness selection model

Layer / File(s)	Summary
Selection data model and owner resolution src/solo_mise/selection.py, tests/test_selection.py	Selection dataclass stores depth, harnesses, owner, and includes with validation; resolve_owner() picks highest-priority harness (openclaw > hermes > codex > claude); profile_to_selection() maps legacy profiles to equivalent selections for backward compatibility.
Config file persistence src/solo_mise/config.py, tests/test_config.py	.solo-mise/config.json stores versioned Selection as single source of truth; write_config validates and pretty-prints JSON; load_config validates version/selection on read and returns None when absent.
Template manifest loading and merging src/solo_mise/templates.py, tests/test_fragments.py	load_depth_manifest, load_harness_manifest, load_include_manifest resolve extends chains and merge files (last-wins by destination) and directories (sorted unique); templates load from template_root()/{kind}/{id}.json.
Template definitions: depths, harnesses, includes src/solo_mise/templates/depth/*.json, src/solo_mise/templates/harnesses/*.json, src/solo_mise/templates/includes/*.json, src/solo_mise/templates/codex/memory-handoffs/TEMPLATE.md	repo.json and workspace.json depth templates; claude.json, codex.json, openclaw.json, hermes.json harness definitions with roles and file/directory entries; publisher.json include template; reusable Codex memory-handoff template markdown.

Selection-based installation and target management

Layer / File(s)	Summary
Install engine: manifest composition and file installation src/solo_mise/install.py, tests/test_install.py, tests/test_gitignore.py	resolve_manifests() loads and merges depth/harness/include manifests into unified file and directory lists with deduplication; install_selection() creates target, copies/renders templates with owner context, applies modes, writes config, and updates .gitignore with managed block covering all writer harnesses; build_gitignore_block() and apply_gitignore() manage inbox exclusions per selected harnesses.
Reconfiguration: modify harness selection src/solo_mise/reconfigure.py, tests/test_reconfigure.py	reconfigure() loads existing config, re-runs install with force=True, optionally prunes removed harness directories and bridge files, and reports summary of added/removed harnesses.

CLI commands and interactive selection

Layer / File(s)	Summary
Interactive prompt for bare solo-mise init src/solo_mise/prompt.py, tests/test_prompt.py	prompt_for_selection() validates TTY, collects multi-toggle harness selection (space-separated numbers), single-choice depth with default, optional includes, resolves owner, and returns Selection or raises NonInteractiveError when non-interactive.
CLI integration: new flags and commands src/solo_mise/cli.py, tests/test_init.py	Adds --depth, --harnesses, --owner, repeatable --include to init; new reconfigure subcommand with --prune flag; branches on flag presence (skip prompt if flags provided, otherwise prompt); deprecates --profile with stderr warning and translation via profile_to_selection(); imports prompt_for_selection at module level for test monkeypatching.

Runtime integration: doctor and ingester

Layer / File(s)	Summary
Doctor: harness detection and multi-inbox validation src/solo_mise/doctor.py, tests/test_doctor.py	Loads .solo-mise/config.json to derive selected harnesses; reports configured selection metadata; refactored inbox checks iterate all writer harnesses, validate TEMPLATE.md/processed/ per inbox, and check memory/cards/; added _check_orphan_inboxes() warns about inboxes for unselected harnesses; conditional openclaw/hermes checks based on selection.
Ingester: multi-inbox scanning and processing src/solo_mise/ingest.py, tests/test_ingest.py	_resolve_inbox_paths() loads config and returns sorted set of configured writer inboxes in deterministic harness order; run() processes handoffs from all resolved directories, archiving processed files into each directory's processed/ subdirectory; falls back to legacy .claude/memory-handoffs/ when config absent.

Version, CI, and documentation

Layer / File(s)	Summary
Version and CI matrix updates pyproject.toml, src/solo_mise/__init__.py, .github/workflows/ci.yml	Version bumped to 0.3.0; CI install-from-source matrix switched from profile-based to combo-based with named entries (e.g., repo+claude, workspace+codex, kitchen-sink, legacy profile combos); target directory uses combo.name and init flags come from combo.flags.
User and contributor documentation CHANGELOG.md, README.md, QUICKSTART.md, CONTRIBUTING.md	CHANGELOG documents v0.3.0 release (two-axis model, per-inbox handoffs, config persistence, doctor improvements, --profile deprecation, migration mapping); README leads with harness coverage and adds depth+harness selection tables with owner priority; QUICKSTART introduces interactive init flow, CI flag examples, doctor output interpretation, and reconfigure usage; CONTRIBUTING describes harness/depth/include additions and smoke test procedures.
Planning and design documentation docs/plans/2026-05-16-v0.3.0-harness-selection.md, docs/specs/2026-05-16-v0.3.0-harness-selection-design.md	Comprehensive phased implementation plan (phases 1-6 with tasks, tests, checklist) and design spec (CLI surface, harness contract, inbox layout, config schema, doctor behavior, ingester changes, migration shim, acceptance criteria).

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 Hops with joy at harness flexibility!
Where once the Claude was hardcoded in stone,
Now Codex, OpenClaw, Hermes claim their own,
With config saved and inboxes all sorted,
Two axes chosen, each harness supported! 🌟

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/v0.3.0-harness-selection

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}