Refactor wrapper surface to skill and externalize prompts

.gitignore

@@ -3,3 +3,10 @@
 result
 worktrees/
 .direnv/
+
+# Test artifacts from e2e agent tests
+solo-*.txt
+e2e-*.txt
+skill-*.txt
+pair-*.txt
+todo-run-cmd-*.md

README.md

@@ -2,26 +2,27 @@
 
 Step-by-step coordinator for multi-agent coding sessions.
 
-## Command Wrappers
+## Skill Wrappers
 
 Rally now provides a wrapper-oriented command surface:
 
-- `rally command install --target <codex|droid|pi|claude-code|factory|all>`
-- `rally command run ...` (canonical wrapper entrypoint)
-- `rally command exec ...` (alias for `run`)
-- `rally command doctor --target ...`
-- `rally command uninstall --target ...`
+- `rally skill install --target <codex|droid|pi|claude-code|all>`
+- `rally skill run ...` (canonical wrapper entrypoint)
+- `rally skill exec ...` (alias for `run`)
+- `rally skill agent-howto ...` (prints the current detailed agent loop instructions)
+- `rally skill doctor --target ...`
+- `rally skill uninstall --target ...`
 
 Install wrappers everywhere:
 
 ```bash
-rally command install --target all
+rally skill install --target all
 ```
 
 Installed `/rally` wrappers are thin adapters that delegate back to Rally core:
 
 ```bash
-rally command run "$@"
+rally skill agent-howto "$@"
 ```
 
 ## /rally Usage
@@ -33,7 +34,7 @@ Typical wrapper invocations:
 - `/rally build reviewer`
 - `/rally <invite-code>`
 
-`rally command run` resolves context in this order:
+`rally skill run` resolves context in this order:
 
 1. explicit args (`--session`, `--as`, positional selectors)
 2. invite token input
@@ -45,7 +46,7 @@ Typical wrapper invocations:
 Use doctor to inspect path/status per target:
 
 ```bash
-rally command doctor --target all
+rally skill doctor --target all
 ```
 
-For details and target path mapping, see [docs/command-install-run.md](docs/command-install-run.md).
+For details and target path mapping, see [docs/skill-install-run.md](docs/skill-install-run.md).

docs/manual-qa-command-install-run.md → docs/manual-qa-skill-install-run.md

@@ -1,47 +1,47 @@
-# Manual QA: Command Install/Run
+# Manual QA: Skill Install/Run
 
 Date: 2026-03-02
 
 Environment:
 
 - Rally binary: `/Users/justin/code/rally/target/debug/rally`
-- Workspace: `/Users/justin/code/rally/worktrees/command-install-run`
+- Workspace: `/Users/justin/code/rally/worktrees/skill-install-run`
 - Temporary HOME used for isolated QA harness roots
 
 ## Scenario 1: Install wrappers for two targets
 
 Commands:
 
 ```bash
-HOME="$TMP_HOME" rally command install --target codex
-HOME="$TMP_HOME" rally command install --target droid
+HOME="$TMP_HOME" rally skill install --target codex
+HOME="$TMP_HOME" rally skill install --target droid
 ```
 
 Observed:
 
-- `~/.codex/commands/rally.md` created
-- `~/.droid/commands/rally.md` created
+- `~/.codex/skills/rally/SKILL.md` created
+- `~/.factory/skills/rally/SKILL.md` created
 
 ## Scenario 2: `/rally` routing behavior
 
-Created implement session `qa-command-install-run-1772430801` with a single step.
+Created implement session `qa-skill-install-run-1772430801` with a single step.
 
 Commands and observed results:
 
 ```bash
-HOME="$TMP_HOME" rally command run --session "$SESSION" --as implementer --non-interactive
+HOME="$TMP_HOME" rally skill run --session "$SESSION" --as implementer --non-interactive
 ```
 
 - Routed to implement instruction (`Implement step 1: Validate wrapper routing`)
 
 ```bash
-HOME="$TMP_HOME" rally command run build --non-interactive
+HOME="$TMP_HOME" rally skill run build --non-interactive
 ```
 
 - Routed through saved context fallback and printed same instruction
 
 ```bash
-HOME="$TMP_HOME" rally command run "rly:${SESSION}:implementer" --non-interactive
+HOME="$TMP_HOME" rally skill run "rly:${SESSION}:implementer" --non-interactive
 ```
 
 - Invite-token resolution worked and printed same instruction
@@ -51,39 +51,39 @@ HOME="$TMP_HOME" rally command run "rly:${SESSION}:implementer" --non-interactiv
 Doctor output validated per-target status/path reporting:
 
 ```bash
-HOME="$TMP_HOME" rally command doctor --target all
+HOME="$TMP_HOME" rally skill doctor --target all
 ```
 
 Created unmanaged custom file:
 
 ```bash
-echo "custom user wrapper" > "$TMP_HOME/.pi/commands/rally.md"
+echo "custom user wrapper" > "$TMP_HOME/.pi/agent/skills/rally/SKILL.md"
 ```
 
 Confirmed non-destructive install behavior:
 
 ```bash
-HOME="$TMP_HOME" rally command install --target pi
+HOME="$TMP_HOME" rally skill install --target pi
 ```
 
 - Failed as expected without `--force` and did not overwrite custom file
 
 Verified uninstall behavior:
 
 ```bash
-HOME="$TMP_HOME" rally command uninstall --target all --dry-run
-HOME="$TMP_HOME" rally command uninstall --target all
+HOME="$TMP_HOME" rally skill uninstall --target all --dry-run
+HOME="$TMP_HOME" rally skill uninstall --target all
 ```
 
 - Managed codex/droid wrappers removed
-- Unmanaged `~/.pi/commands/rally.md` preserved
+- Unmanaged `~/.pi/agent/skills/rally/SKILL.md` preserved
 
 Reinstall check:
 
 ```bash
-HOME="$TMP_HOME" rally command install --target codex
-HOME="$TMP_HOME" rally command install --target droid
-HOME="$TMP_HOME" rally command doctor --target all --dry-run
+HOME="$TMP_HOME" rally skill install --target codex
+HOME="$TMP_HOME" rally skill install --target droid
+HOME="$TMP_HOME" rally skill doctor --target all --dry-run
 ```
 
 - Managed wrappers recreated cleanly

docs/command-install-run.md → docs/skill-install-run.md

@@ -1,4 +1,4 @@
-# Rally Command Install/Run
+# Rally Skill Install/Run
 
 This document describes Rally's wrapper entrypoint for harness slash commands.
 
@@ -7,35 +7,35 @@ This document describes Rally's wrapper entrypoint for harness slash commands.
 Install wrapper artifacts for one harness:
 
 ```bash
-rally command install --target codex
+rally skill install --target codex
 ```
 
 Install for all supported harnesses:
 
 ```bash
-rally command install --target all
+rally skill install --target all
 ```
 
 Supported targets:
 
-- `codex` -> `~/.codex/commands/rally.md`
-- `droid` -> `~/.droid/commands/rally.md`
-- `pi` -> `~/.pi/commands/rally.md`
-- `claude-code` -> `~/.claude/commands/rally.md`
-- `factory` -> `~/.factory/commands/rally.md`
+- `codex` -> `~/.codex/skills/rally/SKILL.md`
+- `droid` -> `~/.factory/skills/rally/SKILL.md`
+- `pi` -> `~/.pi/agent/skills/rally/SKILL.md`
+- `claude-code` -> `~/.claude/skills/rally/SKILL.md`
 
 Each wrapper is Rally-managed content and delegates back to:
 
 ```bash
-rally command run "$@"
+rally skill agent-howto "$@"
 ```
 
 ## Wrapper Behavior
 
 The generated `/rally` wrapper is intentionally thin:
 
 - accepts wrapper arguments unchanged
-- forwards arguments to `rally command run`
+- forwards arguments to `rally skill agent-howto`
+- keeps the mutable prompt in Rally source code (`prompts/skill-agent-howto.md`)
 - keeps orchestration logic centralized in Rally
 
 Examples:
@@ -45,28 +45,38 @@ Examples:
 - `/rally build reviewer`
 - `/rally <invite-code>`
 
-## `rally command run` Patterns
+## `rally skill` Patterns
+
+`agent-howto` prints the current instruction loop and exact follow-up run command:
+
+```bash
+rally skill agent-howto
+rally skill agent-howto implement todos/create-todo.md implement
+```
 
 `run` and `exec` are equivalent:
 
 ```bash
-rally command run
-rally command exec
+rally skill run
+rally skill exec
 ```
 
 Resolution precedence:
 
 1. explicit args (`--session`, `--as`, positional selectors)
 2. invite token (for example `rly:<session>:<agent>`, `rally://<session>/<agent>`)
-3. saved workspace context (`~/.rally/command-context.json`)
+3. saved workspace context (`~/.rally/skill-context.json`)
 4. interactive fallback prompt
 
+Backward compatibility note:
+- If `skill-context.json` is missing, Rally falls back to reading legacy `command-context.json`.
+
 ## Troubleshooting with Doctor
 
 Inspect current installation health:
 
 ```bash
-rally command doctor --target all
+rally skill doctor --target all
 ```
 
 Doctor reports per target:
@@ -79,28 +89,28 @@ Doctor reports per target:
 For preview mode:
 
 ```bash
-rally command doctor --target all --dry-run
+rally skill doctor --target all --dry-run
 ```
 
 ## Uninstall Behavior
 
 Remove Rally-managed wrappers only:
 
 ```bash
-rally command uninstall --target all
+rally skill uninstall --target all
 ```
 
 Unmanaged user files are never removed.
 
 Preview removal decisions:
 
 ```bash
-rally command uninstall --target all --dry-run
+rally skill uninstall --target all --dry-run
 ```
 
 ## Mapping to Rally Core Commands
 
-Wrappers map to Rally core loop behavior through `rally command run`, which then joins/polls the existing session workflows:
+Wrappers map to Rally core loop behavior through `rally skill run`, which then joins/polls existing session workflows:
 
 - registration path: `rally join --session <name> --as <agent>` (as needed)
 - instruction polling path: `rally next --session <name> --as <agent>`

flake.nix

@@ -93,6 +93,7 @@
             pkgs.just
             pkgs.git
             pkgs.jq
+            pkgs.python3
           ];
 
           RUST_SRC_PATH = "${rustToolchain}/lib/rustlib/src/rust/library";

justfile

@@ -12,9 +12,11 @@ pre-merge: nix-check
 test-agents:
     ./tests/e2e-agents.sh
 
-# Test full 2-agent implement protocol end-to-end
-test-implement:
-    ./tests/e2e-implement.sh
+# Run the full e2e agent test matrix (solo + pairs, concurrent)
+test-matrix *ARGS:
+    cargo install --path . --quiet
+    rally skill install --target all --force
+    python3 tests/e2e_matrix.py {{ARGS}}
 
 # Pick a todo and print copy-pasteable prompts for implement session agents
 implement:

prompts/skill-agent-howto.md

@@ -0,0 +1,20 @@
+# Rally Agent How-To
+
+IMPORTANT: You MUST run bash commands to participate in this session. Do NOT try to do the work without running rally commands first.
+
+FIRST, run this bash command immediately:
+
+```bash
+{{RUN_COMMAND}}
+```
+
+This will print your instruction. Then follow this loop:
+
+1. READ the instruction printed by the command above.
+2. DO exactly what it says - write files, run tests, git commit, etc.
+3. RUN the follow-up commands listed at the end of your instruction (checkpoint, review, etc). Run them ALL, in order.
+4. RUN `{{RALLY_BIN}} skill run` again with no arguments to get your next instruction.
+5. REPEAT from step 1. Do NOT stop until the output says "session complete; stop working".
+
+If the command prints "Waiting for ..." - keep waiting. Another agent needs to act first.
+If the command exits with code 2 or prints "session complete" - you are done. Stop.

prompts/skill-wrapper.md

@@ -0,0 +1,15 @@
+---
+name: rally
+description: "Run rally multi-agent coding sessions. Use when the user invokes /rally or asks to run a rally workflow."
+rally-managed: true
+---
+
+# Rally
+
+Run this command first with the user's arguments:
+
+```bash
+{{RALLY_BIN}} skill agent-howto $ARGUMENTS
+```
+
+Then follow the printed instructions exactly.

solo-claude-1772595331697.txt

@@ -0,0 +1 @@
+hello claude

solo-codex-1772595331697.txt

@@ -0,0 +1 @@
+hello codex

solo-pi-1772595331697.txt

@@ -0,0 +1 @@
+hello pi