docs: tmuxinator/teamocil parity analysis and feature comparison

.claude/commands/check/parity.md

@@ -0,0 +1,80 @@
+# /check:parity — Feature Parity Analysis
+
+Deep-dive analysis of tmuxp vs tmuxinator and teamocil. Updates comparison docs and parity notes.
+
+This command produces three artifacts:
+- Feature parity notes (`notes/parity-*.md`)
+- Import behavior notes (`notes/import-*.md`)
+- Auto-detection heuristics (in `docs/comparison.md`)
+
+## Workflow
+
+1. **Read source code** of all three projects (see `.claude/commands/implement.md` for shared reference codebase paths). Focus on `src/tmuxp/workspace/`, `tmuxinator/lib/tmuxinator/{project,window,pane}.rb` + `hooks/` + `assets/template.erb`, and `teamocil/lib/teamocil/tmux/{session,window,pane}.rb`.
+
+2. **Read existing docs** for baseline:
+   - `docs/about.md` — tmuxp's own feature description
+   - `docs/comparison.md` — feature comparison table (create if missing)
+   - `notes/parity-tmuxinator.md` — tmuxinator parity analysis (create if missing)
+   - `notes/parity-teamocil.md` — teamocil parity analysis (create if missing)
+
+3. **Update `docs/comparison.md`** with tabular feature comparison:
+   - Overview table (language, min tmux, config format, architecture)
+   - Configuration keys table (every key across all three, with ✓/✗)
+   - CLI commands table (side-by-side)
+   - Architecture comparison (ORM vs script generation vs command objects)
+   - Include version numbers for each project
+
+4. **Update `notes/parity-tmuxinator.md`** with:
+   - Features tmuxinator has that tmuxp lacks (with source locations)
+   - Import behavior analysis (what the current importer handles vs misses)
+   - WorkspaceBuilder requirements for 100% feature support
+   - Code quality issues in current importer
+
+5. **Update `notes/parity-teamocil.md`** with:
+   - Features teamocil has that tmuxp lacks (with source locations)
+   - v0.x vs v1.4.2 format differences (current importer targets v0.x only)
+   - Import behavior analysis
+   - WorkspaceBuilder requirements for full parity
+
+6. **Commit each file separately**
+
+## Key areas to verify
+
+- Check `importers.py` line-by-line against actual tmuxinator/teamocil config keys
+- Verify `load_workspace()` actually reads config keys it claims to support
+- Cross-reference CHANGELOGs for version-specific features
+- Check test fixtures match real-world configs
+
+---
+
+# Import Behavior
+
+Study tmuxp, teamocil, and tmuxinator source code. Find any syntax they support that tmuxp's native syntax doesn't.
+
+Create/update:
+- `notes/import-teamocil.md`
+- `notes/import-tmuxinator.md`
+
+## Syntax Level Differences / Limitations
+
+For each config key and syntax pattern discovered, classify as:
+
+### Differences (Translatable)
+
+Syntax that differs but can be automatically converted during import. Document the mapping.
+
+### Limitations (tmuxp needs to add support)
+
+Syntax/features that cannot be imported because tmuxp lacks the underlying capability. For each, note:
+1. What the feature does in the source tool
+2. Why it can't be imported
+3. What tmuxp would need to add
+
+---
+
+# WorkspaceBuilder
+
+Analyze what WorkspaceBuilder needs to:
+
+1. **Auto-detect config format** — Determine heuristics to identify tmuxinator vs teamocil vs tmuxp configs transparently
+2. **100% feature support** — List every feature/behavior needed for complete compatibility, including behavioral idiosyncrasies

.claude/commands/check/shortcomings.md

@@ -0,0 +1,51 @@
+# /check:shortcomings — API Limitations Analysis
+
+Second-step command that reads parity analysis and outputs API blockers to `notes/plan.md`.
+
+## Input Files (from /check:parity)
+
+- `notes/parity-tmuxinator.md`
+- `notes/parity-teamocil.md`
+- `notes/import-tmuxinator.md`
+- `notes/import-teamocil.md`
+
+## Workflow
+
+1. **Read parity analysis files** to understand feature gaps
+
+2. **Explore libtmux** at `~/work/python/libtmux/`:
+   - What APIs are missing? (e.g., no `pane.set_title()`)
+   - What's hardcoded? (e.g., `shutil.which("tmux")`)
+
+3. **Explore tmuxp** at `~/work/python/tmuxp/`:
+   - What config keys are dead data?
+   - What keys are missing from loader/builder?
+   - What CLI flags are missing?
+
+4. **Update `notes/plan.md`** with:
+   - libtmux limitations (what Server/Pane/Window/Session can't do)
+   - tmuxp limitations (what WorkspaceBuilder/loader/cli can't do)
+   - Dead config keys (imported but ignored)
+   - Required API additions for each gap
+   - Non-breaking implementation notes
+
+5. **Commit** `notes/plan.md`
+
+## Output Structure
+
+notes/plan.md should follow this format:
+
+### libtmux Limitations
+Per-limitation:
+- **Blocker**: What API is missing/hardcoded
+- **Blocks**: What parity feature this prevents
+- **Required**: What API addition is needed
+
+### tmuxp Limitations
+Per-limitation:
+- **Blocker**: What's missing/broken
+- **Blocks**: What parity feature this prevents
+- **Required**: What change is needed
+
+### Implementation Notes
+Non-breaking approach for each limitation.

.claude/commands/implement.md

@@ -0,0 +1,155 @@
+# /implement — Plan and Implement from notes/plan.md
+
+Orchestrates the full implementation workflow: plan → implement → test → verify → commit → document.
+
+## Reference Codebases
+
+- **tmuxinator**: `~/study/ruby/tmuxinator/`
+- **teamocil**: `~/study/ruby/teamocil/`
+- **tmux**: `~/study/c/tmux/`
+- **libtmux**: `~/work/python/libtmux/`
+- **tmuxp**: `~/work/python/tmuxp/`
+
+## Workflow
+
+### Phase 1: Planning Mode
+
+1. **Read the plan**: Load `notes/plan.md` to understand what needs to be implemented
+2. **Select a task**: Pick the highest priority incomplete item from the plan
+3. **Research**:
+   - Read relevant tmuxinator/teamocil Ruby source for behavior reference
+   - Read libtmux Python source for available APIs
+   - Read tmuxp source for integration points
+   - **Study existing tests** for similar functionality (see Testing Pattern below)
+4. **Create implementation plan**: Design the specific changes needed
+5. **Exit planning mode** with the finalized approach
+
+### Phase 2: Implementation
+
+1. **Make changes**: Edit the necessary files
+2. **Follow conventions**: Match existing code style, use type hints, add docstrings
+
+### Phase 3: Write Tests
+
+**CRITICAL**: Before running verification, write tests for new functionality.
+
+1. **Find similar tests**: Search `tests/` for existing tests of similar features
+2. **Follow the project test pattern** (see Testing Pattern below)
+3. **Add test cases**: Cover normal cases, edge cases, and error conditions
+
+### Phase 4: Verification
+
+Run the full QA suite:
+
+```bash
+uv run ruff check . --fix --show-fixes
+uv run ruff format .
+uv run mypy
+uv run py.test --reruns 0 -vvv
+```
+
+All checks must pass before proceeding.
+
+### Phase 5: Commit Implementation
+
+**Source and tests must be in separate commits.**
+
+1. **Commit source code first**: Implementation changes only (e.g., `fix(cli): Read socket_name/path and config from workspace config`)
+2. **Commit tests second**: Test files only (e.g., `tests(cli): Add config key precedence tests for load_workspace`)
+
+Follow the project's commit conventions (e.g., `feat:`, `fix:`, `refactor:` for source; `tests:` or `tests(<scope>):` for tests).
+
+### Phase 6: Update Documentation
+
+1. **Update `notes/completed.md`**: Add entry for what was implemented
+   - Date
+   - What was done
+   - Files changed
+   - Any notes or follow-ups
+
+2. **Update `notes/plan.md`**: Mark the item as complete or remove it
+
+3. **Commit notes separately**: Use message like `notes: Mark <feature> as complete`
+
+---
+
+## Testing Pattern
+
+This project uses a consistent test pattern. **Always follow this pattern for new tests.**
+
+### 1. NamedTuple Fixture Class
+
+```python
+import typing as t
+
+class MyFeatureTestFixture(t.NamedTuple):
+    """Test fixture for my feature tests."""
+
+    # pytest (internal): Test fixture name
+    test_id: str
+
+    # test params
+    input_value: str
+    expected_output: str
+    expected_error: str | None = None
+```
+
+### 2. Fixture List
+
+```python
+TEST_MY_FEATURE_FIXTURES: list[MyFeatureTestFixture] = [
+    MyFeatureTestFixture(
+        test_id="normal-case",
+        input_value="foo",
+        expected_output="bar",
+    ),
+    MyFeatureTestFixture(
+        test_id="edge-case-empty",
+        input_value="",
+        expected_output="",
+    ),
+    MyFeatureTestFixture(
+        test_id="error-case",
+        input_value="bad",
+        expected_output="",
+        expected_error="Invalid input",
+    ),
+]
+```
+
+### 3. Parametrized Test Function
+
+```python
+@pytest.mark.parametrize(
+    "test",
+    TEST_MY_FEATURE_FIXTURES,
+    ids=[test.test_id for test in TEST_MY_FEATURE_FIXTURES],
+)
+def test_my_feature(test: MyFeatureTestFixture) -> None:
+    """Test my feature with various inputs."""
+    result = my_function(test.input_value)
+    assert result == test.expected_output
+
+    if test.expected_error:
+        # check error handling
+        pass
+```
+
+See `CLAUDE.md` "Testing Guidelines" for the project-wide test conventions (function tests only, real fixtures, `tmp_path`, `monkeypatch`).
+
+---
+
+## Output
+
+After completion, report:
+- What was implemented
+- Files changed (including test files)
+- Test results summary
+- What remains in the plan
+
+## Notes
+
+- If tests fail, fix the issues before committing
+- If libtmux changes are needed, note them but don't modify libtmux in this workflow
+- One logical change per run — don't implement multiple unrelated items
+- **Always write tests** — No implementation is complete without tests

CHANGES

@@ -39,6 +39,96 @@ $ pipx install \
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### New features — tmuxinator/teamocil parity (#1014)
+
+These additions close the remaining feature gaps with tmuxinator and
+teamocil, so configs from either tool now have a tmuxp-native equivalent.
+
+**New config keys**
+
+- **`synchronize`** (window-level) — sync keystrokes across the panes of a
+  window. Accepts `before` / `true` (turn `synchronize-panes` on before
+  pane commands run) or `after` (turn it on once each pane has finished
+  setup). Mirrors tmuxinator.
+- **`enable_pane_titles`**, **`pane_title_position`** (default `top`),
+  **`pane_title_format`** (default `"#{pane_index}: #{pane_title}"`)
+  (session-level) plus per-pane **`title`**. Renders pane titles in the
+  border bar. tmuxinator's named-pane shorthand (`{name: command}`) is
+  imported as both a title and the pane command.
+- **`shell_command_after`** (window-level) — list of commands sent to
+  every pane after each pane's main `shell_command` has run. Mirrors
+  teamocil's `filters.after`.
+- **`on_project_start`**, **`on_project_first_start`**,
+  **`on_project_restart`**, **`on_project_exit`**, **`on_project_stop`**
+  (session-level) — lifecycle hooks. Each accepts a string or list. Hooks
+  reuse tmuxp's existing script executor: no `shell=True`, so pipes and
+  redirects need a real script file. `start` fires on every load,
+  `first_start` only on a brand-new session, `restart` only when
+  attaching to an existing one, `exit` after attach, and `stop` runs from
+  `tmuxp stop`.
+
+**New CLI flags on `tmuxp load`**
+
+- **`--here`** — load the workspace into the current tmux session
+  instead of creating a new one. Mutually exclusive with `--append`;
+  refuses to run outside a tmux session.
+- **`--no-shell-command-before`** — skip every `shell_command_before`
+  (session, window, and pane). Slightly broader than tmuxinator's
+  `--no-pre-window`, which only suppresses `pre_window`.
+- **`--dry-run`** — execute the build on an isolated tmux socket so your
+  main tmux server is untouched. tmuxp surfaces libtmux's
+  `tmux command dispatched` log at INFO so you can see the exact tmux
+  call sequence; the temporary server is killed when the run finishes.
+- **`-D KEY=VALUE` / `--var KEY=VALUE`** (repeatable) — substitute
+  `${var}` and `${var:-default}` placeholders in the workspace YAML
+  before parsing, matching tmuxinator's ERB-before-YAML order. Bare
+  `$name` is intentionally not handled here so `loader.expandshell` can
+  keep handling environment-variable expansion on specific config keys
+  after parsing. Stdlib-only — no Jinja2 dependency.
+
+**New CLI commands**
+
+- **`tmuxp stop <name>`** — fire `on_project_stop` and kill the matching
+  session. Idempotent: a no-op if the session isn't running. Mirrors
+  tmuxinator's `stop` command.
+- **`tmuxp new <name>`** — create a starter workspace YAML in your
+  tmuxp config directory and open it in `$EDITOR`.
+- **`tmuxp copy <src> <dst>`** — copy an existing workspace and open the
+  copy in `$EDITOR`. Prompts before overwriting.
+- **`tmuxp delete <name>...`** — delete one or more workspaces, with a
+  per-name confirmation unless `-y` is supplied.
+- **`tmuxp implode`** — delete every workspace in every tmuxp config
+  directory (legacy `~/.tmuxp/` and XDG `~/.config/tmuxp/`). Single
+  confirmation; `-y` skips it.
+
+### Behavior changes — tmuxinator/teamocil import (#1014)
+
+- **tmuxinator**: `pre` now correctly maps to `before_script` (was: per-pane
+  `shell_command_before`). Importer warns when `pre` contains shell
+  constructs like pipes/redirects since `before_script` runs without
+  `shell=True`. Combo `pre` + `pre_window` previously dropped `pre`
+  entirely; both keys now map independently.
+- **tmuxinator**: `cli_args`/`tmux_options` now use `shlex` parsing.
+  `-L` (socket name) and `-S` (socket path) are extracted (were silently
+  dropped). Paths containing `-f` no longer corrupt the config value.
+  Unknown flags and missing-value flags warn.
+- **tmuxinator**: new key translations — `rvm`, `pre_tab`,
+  `startup_window`, `startup_pane`, `on_project_first_start`,
+  `socket_path`. `attach: false` warns and directs to `tmuxp load -d`.
+  `startup_window`/`startup_pane` resolve by name OR integer index to
+  set `focus: true` on the matching window/pane.
+- **teamocil**: v1.x format now supported. Importer auto-dispatches to
+  v0.x or v1.x based on `session:` wrapper, `splits`/`filters`/`cmd`
+  markers. v1.x handles bare-string panes, `commands`, per-window/pane
+  `focus`, window `options`. v1.x pane dicts with no recognizable keys
+  produce empty panes and warn.
+- **teamocil**: v0.x configs now emit `environment: {TEAMOCIL: "1"}` by
+  default (matches `with_env_var: true` from teamocil 0.4-stable).
+  Suppress with `with_env_var: false` (also accepts the YAML-quoted
+  string `"false"`).
+- **teamocil**: v0.x pane `width`/`height`/`target` keys now drop with a
+  WARNING (were silently dropped or passed through as dead data).
+
 ### Documentation
 
 - Visual improvements to API docs from [gp-sphinx](https://gp-sphinx.git-pull.com)-based Sphinx packages (#1035)