docs: tmuxinator/teamocil parity analysis and feature comparison

.claude/commands/check/parity.md

@@ -0,0 +1,78 @@
+# /check:parity — Feature Parity Analysis
+
+Deep-dive analysis of tmuxp vs tmuxinator and teamocil. Updates comparison docs and parity notes.
+
+## Workflow
+
+1. **Read source code** of all three projects:
+   - tmuxp: `src/tmuxp/workspace/` (builder.py, loader.py, importers.py), `src/tmuxp/cli/load.py`
+   - tmuxinator: `~/study/ruby/tmuxinator/lib/tmuxinator/` (project.rb, window.rb, pane.rb, hooks/, assets/template.erb)
+   - teamocil: `~/study/ruby/teamocil/lib/teamocil/tmux/` (session.rb, window.rb, 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,160 @@
+# /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
+```
+
+### Key Rules
+
+- **Function tests only** — No `class TestFoo:` groupings (per CLAUDE.md)
+- **Use fixtures from `tests/fixtures/`** — Prefer real tmux fixtures over mocks
+- **Use `tmp_path`** — Not Python's `tempfile`
+- **Use `monkeypatch`** — Not `unittest.mock`
+
+---
+
+## 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