harnex 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c56e3cb64f20e24e32b7f46c4be98b23715407f5f990f79ba1b702720a5130b
-  data.tar.gz: 1c88ad05842287252453878522baba77db4b8388fa6166d3ef7eaf8127b0eaa1
+  metadata.gz: e5db22a80eebc5f0441437c96a2f949f0dd117cf78a2cc0810f24172c7af7cd4
+  data.tar.gz: 3ad9ed119b373258b1e8c56ea80b27ea49dad028031e19bd4ee0697996a45046
 SHA512:
-  metadata.gz: 281b2f232bddcaf24d391a68fc331c73f7d43809d2f40d18848e417da9e50b999c330105a474f99ffa080528ccbeb6139da31c785604cffaab6ce76f4fe16584
-  data.tar.gz: 4e36010a2d17c5541e95c75179941b9fa282d2093237aabd0d1748d5b5c5c374eb4e67852d1d06b674ab039cdc7106c8f71de9bf64b9a99a737ec6e861b58fc6
+  metadata.gz: 1dd3ad5ef1cf5bb17d6a92ea6b27b746ef47a8e1a8e58b1e2a98936946f63f58d8d297d7493ffc3ab3968e25ac26415ae73c44524423a83f36c5951b4e729813
+  data.tar.gz: 39cf0ed49b278a10ff57767d6cc166232e7c30ca9eed31853d079a2a437dcd0ee4709a8a13959e91bd106d8ce7b1e1b043b64a6df0fd24988a925266c488769a

data/TECHNICAL.md

@@ -503,19 +503,21 @@ and `Inbox` classes use `ConditionVariable` for signaling.
 
 ## Skill Files
 
-Harnex ships a skill file that teaches AI agents how to use
-harnex commands. The file lives at:
+Harnex ships bundled skills that teach agents the orchestration workflow and
+dispatch discipline. The canonical collaboration skill is:
 
 ```
-skills/harnex/SKILL.md
+skills/harnex-dispatch/SKILL.md
 ```
 
 ### What's in the skill
 
-The skill tells agents:
+The dispatch skill tells agents:
 
 - How to detect they're inside a harnex session (env vars)
-- How to send messages, check status, spawn workers
+- How to define return channels before delegation
+- How to send short, file-referenced tasks with explicit reply instructions
+- How to send messages, check status, spawn workers, and stop safely
 - How to use `--context`, `--force`, `--no-wait`
 - Relay header format and behavior
 - Collaboration patterns (reply, supervisor, file watch)
@@ -531,8 +533,8 @@ Skill files use YAML frontmatter:
 
 ```yaml
 ---
-name: harnex
-description: Collaborate with other AI agents...
+name: harnex-dispatch
+description: Fire & Watch dispatch pattern...
 allowed-tools: Bash(harnex *)
 ---
 ```
@@ -540,41 +542,36 @@ allowed-tools: Bash(harnex *)
 The `allowed-tools` field grants the agent permission to run
 `harnex` commands without asking for approval each time.
 
-### Symlinking the skill
+### Installing bundled skills
 
-To make the skill available globally (not just in the harnex
-repo), symlink it into each agent's skill directory:
+Use the installer command instead of manual symlinks:
 
 ```bash
-# For Claude Code
-ln -s /path/to/harnex/skills/harnex \
-      ~/.claude/skills/harnex
-
-# For Codex
-ln -s /path/to/harnex/skills/harnex \
-      ~/.codex/skills/harnex
+harnex skills install            # all canonical skills
+harnex skills install harnex     # compatibility alias -> harnex-dispatch
+harnex skills install --local    # install into current repo only
 ```
 
-After symlinking, any Claude or Codex session — in any repo —
-can use harnex commands. The skill activates automatically
-when the user mentions agent collaboration or when a relay
-message arrives.
+Compatibility aliases accepted by the installer:
+
+- `harnex` -> `harnex-dispatch`
+- `dispatch` -> `harnex-dispatch`
+- `chain-implement` -> `harnex-chain`
 
 ### Skill directory structure
 
 ```
  ~/.claude/skills/
-   └── harnex -> /path/to/harnex/skills/harnex
+   └── harnex-dispatch
          └── SKILL.md
 
  ~/.codex/skills/
-   └── harnex -> /path/to/harnex/skills/harnex
+   └── harnex-dispatch -> ~/.claude/skills/harnex-dispatch
          └── SKILL.md
 ```
 
-The symlink points to the `skills/harnex/` directory (not the
-file directly), so updates to `SKILL.md` in the repo are
-picked up immediately.
+Deprecated installed names (`harnex`, `dispatch`, `chain-implement`) are
+cleaned automatically during install and uninstall.
 
 ## Known Limitations
 

data/lib/harnex/commands/skills.rb

@@ -4,20 +4,26 @@ module Harnex
   class Skills
     SKILLS_ROOT = File.expand_path("../../../../skills", __FILE__)
     INSTALL_SKILLS = %w[harnex-dispatch harnex-chain harnex-buddy].freeze
-    DEPRECATED_SKILLS = %w[dispatch chain-implement].freeze
+    DEPRECATED_SKILLS = %w[harnex dispatch chain-implement].freeze
+    SKILL_ALIASES = {
+      "harnex" => "harnex-dispatch",
+      "dispatch" => "harnex-dispatch",
+      "chain-implement" => "harnex-chain"
+    }.freeze
 
     def self.usage
       <<~TEXT
-        Usage: harnex skills <subcommand> [--local]
+        Usage: harnex skills <subcommand> [SKILL...] [--local]
 
         Subcommands:
-          install     Install bundled skills (globally by default)
+          install     Install bundled skills (globally by default; optional skill names)
           uninstall   Remove installed skills (globally by default)
 
         Options:
           --local     Target the current repo instead of global ~/.claude/
 
         Installs: #{INSTALL_SKILLS.join(', ')}
+        Aliases: harnex|dispatch -> harnex-dispatch, chain-implement -> harnex-chain
 
         By default, copies each skill to ~/.claude/skills/<skill>/
         and symlinks ~/.codex/skills/<skill> to it.
@@ -35,12 +41,13 @@ module Harnex
       subcommand = @argv.shift
       case subcommand
       when "install"
-        local, help = parse_args(@argv)
+        local, help, requested_skills = parse_args(@argv, allow_positional: true)
         return (puts self.class.usage; 0) if help
 
         remove_deprecated(local)
+        install_skills = requested_skills.empty? ? INSTALL_SKILLS : canonical_skill_names(requested_skills)
 
-        INSTALL_SKILLS.each do |skill_name|
+        install_skills.each do |skill_name|
           skill_source = resolve_skill_source(skill_name)
           unless skill_source
             return missing_skill(skill_name)
@@ -51,7 +58,7 @@ module Harnex
         end
         0
       when "uninstall"
-        local, help = parse_args(@argv)
+        local, help, = parse_args(@argv)
         return (puts self.class.usage; 0) if help
 
         (INSTALL_SKILLS + DEPRECATED_SKILLS).each do |skill_name|
@@ -70,9 +77,10 @@ module Harnex
 
     private
 
-    def parse_args(args)
+    def parse_args(args, allow_positional: false)
       local = false
       help = false
+      positional = []
 
       args.each do |arg|
         case arg
@@ -83,12 +91,16 @@ module Harnex
         when /\A-/
           raise "harnex skills: unknown option #{arg.inspect}"
         else
-          warn("harnex skills: unexpected argument #{arg.inspect}")
-          raise "harnex skills takes no positional arguments"
+          if allow_positional
+            positional << arg
+          else
+            warn("harnex skills: unexpected argument #{arg.inspect}")
+            raise "harnex skills takes no positional arguments"
+          end
         end
       end
 
-      [local, help]
+      [local, help, positional]
     end
 
     def resolve_skill_source(skill_name)
@@ -107,6 +119,14 @@ module Harnex
       end
     end
 
+    def canonical_skill_names(skill_names)
+      skill_names.map { |name| canonical_skill_name(name) }.uniq
+    end
+
+    def canonical_skill_name(skill_name)
+      SKILL_ALIASES.fetch(skill_name, skill_name)
+    end
+
     def install_local(skill_name, skill_source)
       repo_root = Harnex.resolve_repo_root(Dir.pwd)
       claude_dir = File.join(repo_root, ".claude", "skills", skill_name)

data/lib/harnex/version.rb

@@ -1,4 +1,4 @@
 module Harnex
-  VERSION = "0.3.3"
-  RELEASE_DATE = "2026-04-23"
+  VERSION = "0.3.4"
+  RELEASE_DATE = "2026-04-24"
 end

data/skills/harnex/SKILL.md

@@ -1,348 +1,20 @@
 ---
 name: harnex
-description: Collaborate with other AI agents (Codex, Claude) via harnex. Use when the user asks to send a message to another agent, check agent sessions, spawn workers, relay instructions, or coordinate multi-agent work. Also activates when incoming messages contain "[harnex relay" headers.
-allowed-tools: Bash(harnex *)
+description: Deprecated alias for harnex-dispatch. Use harnex-dispatch for active harnex collaboration guidance.
 ---
 
-# Harnex — Cross-Agent Collaboration
+# Deprecated Skill Alias
 
-If this is your first time using harnex, run `harnex guide` for the full
-getting started walkthrough, and `harnex recipes` for tested workflow patterns.
+`harnex` is deprecated.
 
-Harnex wraps interactive terminal agents (Claude Code, Codex) and opens a local
-control plane so they can discover and message each other. You use it to **send
-messages to a peer agent**, **check session status**, **spawn worker sessions**,
-and **wait for them to finish**.
+Use `harnex-dispatch` as the canonical skill for harnex collaboration,
+Fire & Watch dispatching, relay handling, and return-channel discipline.
 
-## Detect your context
-
-Check environment variables to understand your role:
-
-| Variable | Meaning |
-|----------|---------|
-| `HARNEX_SESSION_CLI` | Which CLI you are (`claude` or `codex`) |
-| `HARNEX_ID` | Your session ID |
-| `HARNEX_SESSION_REPO_ROOT` | Repo root this session is scoped to |
-| `HARNEX_SESSION_ID` | Internal instance identifier |
-| `HARNEX_SPAWNER_PANE` | Tmux pane ID (`%N`) of whoever spawned this session |
-
-If these are set, you are **inside a harnex session** and can send messages to
-peer sessions or spawn new worker sessions.
-
-`HARNEX_SPAWNER_PANE` is the stable tmux pane ID of the invoker — use it to
-reach back to the session that launched you, even if that session is not
-harnex-managed:
-
-```bash
-# Read the invoker's screen
-tmux capture-pane -t "$HARNEX_SPAWNER_PANE" -p
-
-# Type into the invoker
-tmux send-keys -t "$HARNEX_SPAWNER_PANE" "done — results in /tmp/result.md" Enter
-```
-
-## Mode preference
-
-When starting another agent session for the user, default to a visible tmux
-session via `harnex run <cli> --tmux`. That is the preferred interactive mode
-because the user can watch the peer's work live.
-
-Use other modes only when the user asks for them or when visibility is not
-wanted:
-
-- prefer `--tmux` over a hidden foreground PTY for peer-agent work
-- use plain foreground `harnex run` only when the current terminal is meant to
-  become that peer's UI
-- use `--detach` only for explicitly headless/background workflows
-
-## Return channel first
-
-Before you start a peer session or send it work, decide how the result will get
-back to you.
-
-Preferred pattern when you are inside harnex:
-- Use your own `HARNEX_ID` as the return address
-- Tell the peer to send its final result back with `harnex send --id <YOUR_ID>`
-- Wait for the peer's reply; do not rely on scraping logs or tmux panes as the
-  primary way to collect the answer
-
-Fallback when you are not inside harnex:
-- Define another explicit return channel before delegating, such as a known file
-  path in the repo
-
-Do not launch a worker/reviewer without an explicit completion contract.
-
-## Two rules for every send
-
-**1. Keep messages short — use file references for long prompts.**
-Long inline prompts can stall delivery (PTY buffer limits) and break shell
-quoting. Instead, write the full task to a file and tell the peer to read it:
-
-```bash
-# Write the task to a file
-cat > /tmp/task-impl1.md <<'EOF'
-Implement phase 2 from koder/plans/03_output_streaming.md.
-... detailed instructions ...
-EOF
-
-# Send a short message pointing to it
-harnex send --id impl-1 --message "Read and execute /tmp/task-impl1.md. When done, send results back: harnex send --id $HARNEX_ID --message '<summary>'"
-```
-
-If the task is already written down (a plan file, issue, koder doc), just
-reference it directly — no need for a temp file.
-
-**2. Always tell the peer how to reply.**
-Every delegated task must include a return path. Without it, the peer finishes
-silently and you have no way to collect the result:
-
-```bash
-# Always end with the reply instruction
-harnex send --id impl-1 --message "Review src/auth.rb. When done: harnex send --id $HARNEX_ID --message '<your findings>'"
-```
-
-## Core commands
-
-### Send a message to a peer agent
-
-```bash
-harnex send --id <ID> --message "<text>"
-```
-
-- `--id` targets a specific session by its unique ID
-- `--message` is the prompt text injected into the peer's terminal
-- Message is auto-submitted (peer receives it as a prompt)
-- `--no-submit` types without pressing Enter
-- `--force` sends even if peer UI is not at a prompt (bypasses queue)
-- `--submit-only` sends only Enter (submit what's already in the input box)
-- `--wait-for-idle` blocks until the agent finishes processing (prompt→busy→prompt)
-- `--no-wait` returns immediately with a message_id (don't wait for delivery)
-- `--cli` filters by CLI type when multiple sessions share resolution scope
-
-When the target agent is busy, the message is **queued** (HTTP 202) and
-delivered automatically when the agent returns to a prompt. The sender polls
-until delivery completes using one overall `--timeout` budget (default 120s).
-
-### Atomic send+wait (recommended for orchestration)
-
-Use `--wait-for-idle` instead of separate `send` + `sleep` + `wait` commands:
+If you are installing skills, use:
 
 ```bash
-# Instead of:
-harnex send --id cx-1 --message "implement the plan"
-sleep 5
-harnex wait --id cx-1 --until prompt --timeout 600
-
-# Use:
-harnex send --id cx-1 --message "implement the plan" --wait-for-idle --timeout 600
-```
-
-This eliminates the race condition where `wait --until prompt` sees the stale
-prompt state before the agent starts working. The `--timeout` budget covers
-the entire lifecycle (lookup + send + idle wait).
-
-**Multi-line messages** (when a file reference isn't practical): use a heredoc:
-
-```bash
-harnex send --id worker-1 --message "$(cat <<'EOF'
-Line one of the message.
-Line two of the message.
-EOF
-)"
-```
-
-### Check session status
-
-```bash
-harnex status            # sessions for current repo
-harnex status --all      # sessions across all repos
-```
-
-Shows live sessions with their ID, CLI, port, PID, age, and input state.
-
-### Inspect a specific session
-
-```bash
-harnex status --id <ID> --json
-```
-
-Returns JSON with input state, agent state, inbox stats, description,
-watch config, and timestamps.
-
-### Only when explicitly requested: spawn a detached worker session
-
-```bash
-# Headless (no terminal)
-harnex run codex --id impl-1 --detach -- --cd /path/to/worktree
-
-# In a tmux window (observable)
-harnex run codex --id impl-1 --tmux cx-p1 -- --cd /path/to/worktree
+harnex skills install harnex-dispatch
 ```
 
-- `--detach` starts the session in the background, returns JSON with pid/port
-- `--tmux` creates a tmux window (implies `--detach`)
-- `--tmux NAME` sets a custom window title (keep names terse: `cx-p3`, `cl-r3`)
-- `--context TEXT` sets an initial prompt with session ID auto-included
-- `--description TEXT` stores a short session description in the registry/API
-- Returns immediately; use `harnex send` to inject work, `harnex wait` to block
-
-Do this only if the user explicitly asks for detached/background execution.
-
-#### Using `--context` to orient spawned agents
-
-`--context` prepends a context string as the agent's initial prompt, with the
-session ID automatically included as `[harnex session id=<ID>]`. The spawner
-decides what context to provide — harnex only adds the session ID.
-
-```bash
-# Fire-and-forget: give the task upfront
-harnex run codex --id impl-1 --tmux cx-p1 \
-  --context "Implement the feature in koder/plans/03_auth.md. Commit when done." \
-  -- --cd /path/to/worktree
-
-# Fire-and-wait: give context, then send work separately
-harnex run codex --id reviewer --tmux cx-rv \
-  --context "You are a code reviewer. Wait for instructions via harnex relay messages." \
-  -- --cd /path/to/repo
-harnex send --id reviewer --message "Review the changes in src/auth.rb"
-harnex wait --id reviewer
-```
-
-The context string is the spawner's responsibility — tailor it to the use case.
-
-### Wait for a session to exit
-
-```bash
-harnex wait --id impl-1
-harnex wait --id impl-1 --timeout 300
-```
-
-Blocks until the session process exits. Returns JSON with exit code and timing.
-Exit code 124 on timeout.
-
-## Relay headers
-
-When you send from inside a harnex session to a **different** session, harnex
-automatically prepends a relay header:
-
-```
-[harnex relay from=claude id=supervisor at=2026-03-14T12:00:00+04:00]
-<your message>
-```
-
-The peer sees this header and knows the message came from another agent. When
-you **receive** a message with a `[harnex relay ...]` header, treat it as a
-prompt from the peer agent — read the body and respond to it.
-
-Control relay behavior:
-- `--relay` forces the header even outside a session
-- `--no-relay` suppresses the header
-
-## Collaboration patterns
-
-### Reply to a peer
-
-When the user (or a relay message) asks you to reply to the other agent:
-
-```bash
-harnex send --id <TARGET_ID> --message "Your response here"
-```
-
-### Delegate work and get the answer back
-
-When you ask a peer agent to do work, include the return path in the task
-itself.
-
-Preferred when you are inside harnex:
-
-```bash
-harnex send --id reviewer --message "$(cat <<EOF
-Review the current working tree.
-
-Return your final findings to me with:
-harnex send --id $HARNEX_ID --message '<findings>'
-
-Use findings-first format with file paths and line numbers where possible.
-EOF
-)"
-```
-
-Then wait for the peer to answer you. Do not assume you can reconstruct the
-result later from detached logs or tmux capture.
-
-### Supervisor pattern
-
-Use this only when the user explicitly wants detached/background workers.
-
-A supervisor session spawns workers, sends them tasks, and waits for completion:
-
-```bash
-# Spawn workers
-harnex run codex --id impl-1 --tmux cx-p1 -- --cd ~/repo/wt-feature-a
-harnex run codex --id impl-2 --tmux cx-p2 -- --cd ~/repo/wt-feature-b
-
-# Send work and wait for completion (atomic)
-harnex send --id impl-1 --message "implement plan 150" --wait-for-idle --timeout 600
-harnex send --id impl-2 --message "implement plan 151" --wait-for-idle --timeout 600
-
-# Review phase
-harnex run claude --id review-1 --tmux cl-r1
-harnex send --id review-1 --message "review changes in wt-feature-a"
-harnex wait --id review-1
-```
-
-### File watch hook
-
-Sessions can watch a shared file (e.g. `--watch ./tmp/tick.jsonl`). When the
-file changes, harnex injects a `file-change-hook: read <path>` message. If you
-receive this hook, read the file and act on its contents.
-
-## Buddy pattern — accountability for long-running work
-
-For any work that will take a long time (overnight pipelines, multi-hour
-implementations, unattended batch jobs), spawn a **buddy** — a second harnex
-session that watches the worker and nudges it if it stalls.
-
-```bash
-# Spawn the worker
-harnex run codex --id worker-42 --tmux worker-42
-harnex send --id worker-42 --message "Read and execute /tmp/task-42.md"
-
-# Spawn a buddy to watch it
-harnex run claude --id buddy-42 --tmux buddy-42
-harnex send --id buddy-42 --message "Read and execute /tmp/buddy-42.md"
-```
-
-The buddy's prompt tells it: poll `harnex pane` and `harnex status` every N
-minutes, nudge with `harnex send` if the worker stalls, report back to
-`$HARNEX_SPAWNER_PANE` when done.
-
-See `recipes/03_buddy.md` for the full pattern.
-
-**When to spawn a buddy:**
-- The user says "do this overnight" or "run this while I'm away"
-- The task is expected to take more than 30 minutes unattended
-- The user explicitly asks for a buddy or accountability partner
-
-**When NOT to spawn a buddy:**
-- Short tasks you're actively watching
-- The user hasn't asked for long-running autonomy
-
-## Important rules
-
-1. **Always confirm with the user before sending** unless they explicitly asked
-   you to send a specific message. Sending injects a prompt into the peer's
-   terminal — it's an action visible to others.
-2. **Never auto-loop** relay conversations. One send per user request unless
-   told otherwise.
-3. **Check status first** if unsure whether a peer is running: `harnex status`
-4. **Use `--force` sparingly** — it bypasses the inbox queue and adapter
-   readiness checks. Can corrupt peer input if it's mid-response.
-5. **Relay headers are automatic** when sending from inside a session. Don't
-   manually prepend them.
-6. When composing a message to send, be concise and actionable — the peer agent
-   receives it as a prompt and will act on it.
-7. Do not spawn detached or tmux-backed sessions unless the user explicitly
-   asked for detached/background execution.
-8. Before delegating work, define the result return path. Prefer a reply back to
-   your own `HARNEX_ID` over logs, pane capture, or other indirect collection.
+Compatibility note: `harnex skills install harnex` remains supported and
+installs `harnex-dispatch`.

data/skills/harnex-buddy/SKILL.md

@@ -11,6 +11,9 @@ agent that watches the worker and nudges it if it stalls.
 The buddy is an LLM, so it has intelligence for free. It reads the worker's
 screen, reasons about whether it's stuck, and composes a meaningful nudge.
 
+Dispatch workers via `harnex-dispatch` first. This skill owns only buddy
+behavior after the worker is already running.
+
 ## When to activate
 
 - User says "do this overnight" or "run this while I'm away"
@@ -20,12 +23,11 @@ screen, reasons about whether it's stuck, and composes a meaningful nudge.
 
 ## Spawn the buddy
 
-After dispatching the worker, spawn a buddy alongside it:
+After dispatching the worker with `harnex-dispatch`, spawn a buddy alongside
+it. Keep ID/tmux naming consistent with `harnex-dispatch` (`--tmux` matches
+`--id`):
 
 ```bash
-# Worker already running
-harnex run codex --id worker-42 --tmux worker-42
-
 # Spawn its buddy
 harnex run claude --id buddy-42 --tmux buddy-42
 ```
@@ -36,17 +38,17 @@ Write a task file with the watching instructions, then send it:
 
 ```bash
 cat > /tmp/buddy-42.md <<'EOF'
-You are an accountability partner for harnex session `worker-42`.
+You are an accountability partner for harnex session `cx-impl-42`.
 
 Your job:
 1. Every 5 minutes, check on the worker:
-   - `harnex pane --id worker-42 --lines 30`
-   - `harnex status --id worker-42 --json`
+   - `harnex pane --id cx-impl-42 --lines 20`
+   - `harnex status --id cx-impl-42 --json`
 2. If the worker appears stuck at a prompt for more than 10 minutes
    with no progress, nudge it:
-   - `harnex send --id worker-42 --message "You appear to have stalled. Continue with your current task."`
+   - `harnex send --id cx-impl-42 --message "You appear to have stalled. Continue with your current task."`
 3. If the worker has exited, report back to the invoker:
-   - `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "worker-42 has exited. Check results." Enter`
+   - `tmux send-keys -t "$HARNEX_SPAWNER_PANE" "cx-impl-42 has exited. Check results." Enter`
 4. Keep watching until the worker finishes or is stopped.
 
 Do not interfere with work in progress. Only nudge when clearly stalled.
@@ -76,12 +78,8 @@ The invoker does NOT need to be a harnex session. It just needs to be in tmux.
 
 ## Naming convention
 
-| Role | ID pattern | Example |
-|------|-----------|---------|
-| Worker | `worker-NN` | `worker-42` |
-| Buddy | `buddy-NN` | `buddy-42` |
-
-Match the buddy ID to the worker it watches.
+Use naming from `harnex-dispatch`: set `--tmux <same-as-id>` for every
+session and keep the buddy ID paired with the worker step ID.
 
 ## Cleanup
 
@@ -93,6 +91,8 @@ harnex stop --id buddy-42
 
 ## Notes
 
+- For chain orchestration, phase gates, and the 5-concurrent parallel planning
+  cap, see `harnex-chain`.
 - One buddy per worker, or one buddy watching multiple sessions
 - The buddy is a regular harnex session — stop, inspect, log it like any other
 - Tune polling and thresholds in the buddy's prompt, not in harnex config

data/skills/harnex-chain/SKILL.md

@@ -1,234 +1,132 @@
 ---
 name: harnex-chain
-description: End-to-end workflow from issue to shipped plans via harnex agents. Covers mapping, plan extraction, and the serial plan → review → implement → review → fix loop.
+description: End-to-end workflow from issue to shipped plans via harnex agents. Covers mapping, plan extraction, and the serial plan -> review -> implement -> review -> fix loop.
 ---
 
 # Chain Implement
 
-Take an issue from design through to shipped code via harnex agents. Designed
-so the user can walk away after triggering the chain.
+Take an issue from design through to shipped code via harnex agents. This
+skill defines chain semantics (phase order, quality gates, escalation), while
+spawn/watch/stop mechanics come from `harnex-dispatch`.
 
-## Guiding Principle
+For naming (`--tmux <same-as-id>`) and worktree operational rules, use
+`harnex-dispatch`.
+
+## Orchestrator Role
 
-Keep each agent invocation inside its **safe context zone** (< 40% of context
-window). Agents produce their smartest work when they aren't overloaded. Large
-issues get split into smaller plans because massive plans degrade agent output.
+- Claude is the orchestrator only: dispatches sessions, watches progress,
+  decides stop/resume/escalate, and enforces phase gates.
+- Codex performs all production work: plan writing, plan reviews,
+  implementation, code reviews, and fixes.
+- The orchestrator does not implement or review directly except emergency
+  intervention to recover a blocked chain.
+
+## Guiding Principle
 
-**Scale the process to the work:**
-- Small issue, one coherent change → skip mapping, write one plan, implement
-- Medium issue, a few moving parts → one plan with phases is fine
-- Large issue, many files/seams/sequencing → mapping plan + extracted plans
+Keep each agent invocation inside its safe context zone (< 40% of context
+window). Large issues should be split into smaller plans so each worker has a
+narrow, testable scope.
 
-The phases below describe the **full** workflow. Skip phases that aren't needed.
+Scale to the issue size:
+- Small issue: skip mapping, one plan, one serial loop.
+- Medium issue: one phased plan is usually enough.
+- Large issue: mapping plus extracted thin-layer plans.
 
-## Workflow Overview
+## Workflow Overview (Serial Default)
 
 ```
-Issue (user + agent chat)
+Issue (user + orchestrator chat)
   ↓
-[Mapping Plan] → [Map Review] → [Fix Map]     ← skip if scope is small
+[Mapping Plan] -> [Map Review] -> [Fix Map]     <- optional for large scope
   ↓
-[Plan Extraction] → thin-layer plans           ← skip if one plan suffices
+[Plan Extraction] -> thin-layer plans            <- optional if one plan suffices
   ↓
-Per plan (serial):
-  Plan (codex) → Plan Review (claude) → Fix Plan (codex)
-    → Implement (codex) → Code Review (claude) → Fix Code (codex)
-    → Commit → next plan
+Per plan (serial on main):
+  Plan -> Plan Review -> Fix Plan
+    -> Implement -> Code Review -> Fix Code
+    -> Commit -> next plan
 ```
 
-### Why two review phases?
-
-The plan review catches design problems before code is written. The code review
-catches implementation problems after. Skipping plan review leads to wasted
-implementation cycles when the plan itself is flawed. This was validated in
-production — adversarial plan/review cycles consistently produce better outcomes
-than jumping straight to implementation.
+The serial loop is the default path. For each step, use `harnex-dispatch`
+Fire & Watch for lifecycle operations and stop-after-commit timing.
 
 ## Phase 1: Issue
 
-The user and the agent have a detailed design chat. From that, a structured
-issue is filed (e.g., `koder/issues/NN_label/INDEX.md`).
-
-The issue captures:
-- The problem and motivation
+User and orchestrator converge on a concrete issue document
+(e.g., `koder/issues/NN_label/INDEX.md`) with:
+- Problem and motivation
 - Design decisions and trade-offs
 - Acceptance criteria
-- Known open questions
-
-This phase is interactive — the user is present and driving.
-
-## Phase 2: Mapping Plan (optional — for large issues)
+- Open questions
 
-Skip if the issue is small enough for a single implementation plan. Use when
-the scope crosses many files, involves sequencing constraints, or has open
-design questions that would block an away user.
+## Phase 2: Mapping Plan (Optional)
 
-A **mapping plan** doesn't produce code. It produces a detailed technical map:
-- Exact files, functions, and seams involved
-- Sequencing constraints (what depends on what)
-- Questions that need user input before implementation
+Use when scope is broad, has sequencing constraints, or still contains
+user-blocking questions. Skip for small, coherent issues.
 
-### Why mapping is its own phase
-
-- **Surfaces blockers early** — user-blocking decisions come out here, not
-  halfway through implementation
-- **Creates shared context** — the mapping plan becomes the reference for all
-  subsequent plans
-- **Separates research from decomposition** — mapping agent focuses on
-  understanding, extraction focuses on scoping
-
-### Dispatch
-
-```bash
-harnex run codex --id cx-map-NN --tmux cx-map-NN \
-  --context "Write a mapping plan for koder/issues/NN_label/INDEX.md. \
-Produce a detailed technical map: files, seams, sequencing, open questions. \
-Write to koder/plans/NN_mapping.md."
-```
-
-Poll every 30s with `harnex pane --id cx-map-NN --lines 20`.
-
-### Map Review
-
-```bash
-harnex run claude --id cl-rev-map-NN --tmux cl-rev-map-NN \
-  --context "Review koder/plans/NN_mapping.md. Check: unresolved user questions? \
-Accurate file/function analysis? Sequencing constraints identified? \
-Write review to koder/reviews/NN_mapping.md"
-```
+Outputs:
+- Technical map of files/functions/seams
+- Sequencing constraints
+- Explicit user-blocking questions
 
-**If user-blocking questions exist**, stop the chain and surface them.
+Gate:
+- If map review finds user-blocking questions, stop the chain and return to
+  user.
 
-## Phase 3: Plan Extraction (optional)
+## Phase 3: Plan Extraction (Optional)
 
-Skip if the mapping plan describes one coherent change, or if you skipped
-mapping entirely.
+Use when the mapping plan should be decomposed into thin-layer plans.
+Each extracted plan must be one independently testable capability and ordered
+by dependency.
 
-Extract thin-layer implementation plans from the mapping plan. Each plan is:
-- **One capability** — testable independently
-- **Self-contained** — the implementing agent reads only that plan file
-- **Ordered** — respects sequencing constraints from the mapping plan
-
-```bash
-harnex run codex --id cx-extract-NN --tmux cx-extract-NN \
-  --context "Read koder/plans/NN_mapping.md. Extract thin-layer plans. \
-Each plan is one independently testable capability. Write to koder/plans/."
-```
-
-## Phase 4: Serial Plan Loop
-
-Each plan goes through the full cycle. This is the walk-away part.
-
-### Per-plan cycle
-
-```
-1. Plan (codex)        — write/refine the plan if not already extracted
-2. Plan Review (claude) — check plan against codebase, flag issues
-3. Fix Plan (codex)    — address review findings
-4. Implement (codex)   — write code, run tests, commit per phase
-5. Code Review (claude) — review implementation against plan
-6. Fix Code (codex)    — address review findings if needed
-7. Commit              — final state on master
-8. → next plan
-```
-
-Steps 1-3 can be skipped if the plan was already extracted and reviewed during
-the mapping phase, or if the issue is simple enough that the plan is obviously
-correct.
-
-### Dispatch pattern
-
-For each plan NN, use the Fire & Watch pattern from the `harnex-dispatch` skill:
-
-```bash
-# Steps 1-3: Plan convergence (skip if plan already extracted and reviewed)
-harnex run codex --id cx-plan-NN --tmux cx-plan-NN \
-  --context "Refine koder/plans/NN_label.md based on current codebase state."
-# Poll every 30s: harnex pane --id cx-plan-NN --lines 20
-# When done: harnex stop --id cx-plan-NN
-
-harnex run claude --id cl-rev-plan-NN --tmux cl-rev-plan-NN \
-  --context "Review koder/plans/NN_label.md. Check: accurate file/function refs? \
-Sequencing correct? Acceptance criteria testable? \
-Write review to koder/reviews/NN_label.md"
-# Poll → stop → if NEEDS FIXES, dispatch cx-fix-plan-NN
-
-# Step 4: Implement
-harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
-  --context "Implement koder/plans/NN_label.md. Run tests when done. Commit after each phase."
-# Poll every 30s: harnex pane --id cx-impl-NN --lines 20
-# When done: harnex stop --id cx-impl-NN
-
-# Steps 5-6: Code review + fix
-harnex run claude --id cl-rev-NN --tmux cl-rev-NN \
-  --context "Review implementation of plan NN against koder/plans/NN_label.md. \
-Write review to koder/reviews/NN_label.md"
-# Poll every 30s: harnex pane --id cl-rev-NN --lines 20
-# When done: harnex stop --id cl-rev-NN
-# If NEEDS FIXES → dispatch cx-fix-NN
-# If PASS → next plan
-
-# Fix (if needed)
-harnex run codex --id cx-fix-NN --tmux cx-fix-NN \
-  --context "Fix findings in koder/reviews/NN_label.md for plan NN. Run tests. Commit."
-# Poll, stop, re-review if needed
-```
-
-### Poll cadence
-
-Checking is cheap — 20 lines is a few hundred bytes:
-
-| Elapsed | Interval | Rationale |
-|---------|----------|-----------|
-| 0–2 min | 30s | Catch fast completions and early errors |
-| 2–10 min | 60s | Steady state for typical work |
-| 10+ min | 120s | Long-running, reduce noise |
-
-```bash
-harnex pane --id cx-impl-NN --lines 20
-```
+## Phase 4: Serial Plan Loop (Default)
 
-### Naming conventions
+Per plan:
+1. Plan (Codex)
+2. Plan Review (Codex)
+3. Fix Plan (Codex) when review finds issues
+4. Implement (Codex)
+5. Code Review (Codex)
+6. Fix Code (Codex) when review finds issues
+7. Commit and advance to next plan
 
-| Step | ID pattern | Example |
-|------|-----------|---------|
-| Mapping plan | `cx-map-NN` | `cx-map-42` |
-| Map review | `cl-rev-map-NN` | `cl-rev-map-42` |
-| Plan extraction | `cx-extract-NN` | `cx-extract-42` |
-| Plan write/refine | `cx-plan-NN` | `cx-plan-184` |
-| Plan review | `cl-rev-plan-NN` | `cl-rev-plan-184` |
-| Plan fix | `cx-fix-plan-NN` | `cx-fix-plan-184` |
-| Implement | `cx-impl-NN` | `cx-impl-184` |
-| Code review | `cl-rev-NN` | `cl-rev-184` |
-| Code fix | `cx-fix-NN` | `cx-fix-184` |
+Gating rules:
+- Do not start implementation with unresolved P1 plan-review findings.
+- Do not advance to the next plan with unresolved P1 code-review findings.
+- Keep plan-fix and code-fix loops active until the review gate passes.
 
-**Rule**: Fresh instance per step. Don't reuse agents across steps — clean
-context avoids bleed.
+## Parallel Variant
 
-## Worktree Option
+Parallelism is allowed only for planning passes. Keep implementation serial
+on `main` unless the user explicitly requests worktrees.
 
-By default, all work happens serially on master. Use worktrees only when:
-- The user explicitly requests isolation
-- You need to work on something else while a plan is being implemented
+Approved parallel lanes:
+- Parallel plan-writing sessions (one plan file per Codex session)
+- Parallel plan-review sessions (one review file per Codex session)
 
-See the `harnex-dispatch` skill for worktree setup and caveats.
+Capacity rule:
+- Run at most 5 concurrent Codex sessions total across all active lanes
+  (global cap, not per lane).
 
-## When Things Go Wrong
+Lifecycle rule:
+- Use `harnex-dispatch` Fire & Watch, including poll cadence and stop timing.
 
-**Plan review finds user-blocking question**: Stop the chain. Surface the
-question. Resume after the user answers. This is exactly what the plan review
-phase is for — catching these before implementation begins.
+Implementation rule:
+- Serial implementation on `main` is the default.
+- Parallel implementation is allowed only with explicit user request and
+  worktree isolation (see `harnex-dispatch` worktree guidance).
 
-**Plan review finds P1**: Dispatch a plan fix agent (`cx-fix-plan-NN`).
-Re-review the plan. Do not proceed to implementation with unresolved P1s.
+## Unattended Monitoring
 
-**Code review finds P1**: Dispatch a code fix agent (`cx-fix-NN`). Re-review
-after fix. Do not skip to the next plan with unresolved P1s.
+For overnight, unattended, or >30-minute steps, use `harnex-buddy`.
+Buddy activation criteria, monitoring loop (poll/stall/nudge), return channel
+via `$HARNEX_SPAWNER_PANE`, and buddy cleanup are canonical in
+`harnex-buddy`.
 
-**Implementation diverges from plan**: The implementer may discover the plan
-is wrong. If the divergence is minor (P3), note it and continue. If major,
-stop and re-plan.
+## Failure and Escalation
 
-**Agent gets stuck**: Check `harnex pane --lines 20`. If blocked on a
-permission prompt or trust dialog, intervene. If confused, stop the agent and
-dispatch a fresh one with clearer instructions.
+- User-blocking question in plan/map review: stop and ask user; do not guess.
+- Review returns P1: dispatch the corresponding fix step and re-review.
+- Implementation diverges materially from plan: stop and re-plan.
+- Worker is stuck or blocked by prompt/dialog: intervene, then continue with a
+  fresh worker if needed.

data/skills/harnex-dispatch/SKILL.md

@@ -1,11 +1,96 @@
 ---
 name: harnex-dispatch
 description: Fire & Watch — the standard pattern for launching and monitoring harnex agent sessions. Use when dispatching implementation, review, or fix agents.
+allowed-tools: Bash(harnex *)
 ---
 
 # Dispatch — Fire & Watch
 
 Every harnex agent dispatch follows three phases: **spawn**, **watch**, **stop**.
+Before spawn, always decide the return channel and message contract.
+
+`harnex-dispatch` is the canonical home for lifecycle mechanics only.
+For orchestrator role boundaries, phase gates, and chain-level parallel policy,
+see `harnex-chain`.
+
+## Detect your context
+
+Check env vars first to know whether you are inside a harnex-managed session:
+
+| Variable | Meaning |
+|----------|---------|
+| `HARNEX_SESSION_CLI` | Which CLI this session is (`claude` or `codex`) |
+| `HARNEX_ID` | Your session ID |
+| `HARNEX_SESSION_REPO_ROOT` | Repo root the session is scoped to |
+| `HARNEX_SESSION_ID` | Internal harnex instance ID |
+| `HARNEX_SPAWNER_PANE` | tmux pane ID (`%N`) of the invoker |
+
+If these are present, you can coordinate peers directly with `harnex send`,
+`harnex status`, and `harnex wait`. `HARNEX_SPAWNER_PANE` is the fallback
+return channel to the invoker via `tmux send-keys`.
+
+## Return Channel First
+
+Define how results come back before delegating work.
+
+- Inside harnex: require peers to send final results back to your own
+  `HARNEX_ID` via `harnex send --id "$HARNEX_ID" ...`
+- Outside harnex: require a concrete return path (for example a specific file
+  in the repo or an explicit tmux pane message)
+
+Do not delegate work without an explicit completion contract.
+
+## Send Hygiene
+
+### Keep prompts short; reference files for long instructions
+
+```bash
+cat > /tmp/task-impl-NN.md <<'EOF'
+Detailed instructions here...
+EOF
+
+harnex send --id cx-impl-NN --message "Read /tmp/task-impl-NN.md. Reply with final status to harnex id $HARNEX_ID."
+```
+
+Long inline messages are brittle in PTYs. Use plan/issue files or temp files.
+
+### Require explicit reply instruction in every delegated task
+
+```bash
+harnex send --id cl-rev-NN --message "Review koder/plans/NN_name.md. When done send findings to harnex id $HARNEX_ID."
+```
+
+## Relay Headers
+
+Messages sent from one harnex session to another are auto-wrapped:
+
+```
+[harnex relay from=<cli> id=<sender_id> at=<timestamp>]
+<message body>
+```
+
+When you receive a relay header, treat it as an actionable prompt from the
+peer. Respond using `harnex send --id <sender_id> ...` unless instructed
+otherwise.
+
+## Practical Reply/Delegate Patterns
+
+Reply to a peer:
+
+```bash
+harnex send --id <TARGET_ID> --message "<result>"
+```
+
+Delegate and force a return path:
+
+```bash
+harnex send --id cx-impl-NN --message "$(cat <<EOF
+Implement koder/plans/NN_name.md.
+Run tests before finishing.
+When done, send one summary line back to harnex id $HARNEX_ID.
+EOF
+)"
+```
 
 ## 1. Spawn
 
@@ -81,6 +166,8 @@ harnex pane --id cx-impl-NN --lines 20 --follow
 
 When the agent is done (at prompt, work committed):
 
+Stop each completed session as soon as its commit lands.
+
 ```bash
 harnex stop --id cx-impl-NN
 ```
@@ -100,11 +187,16 @@ harnex stop --id cx-impl-NN
 
 | Step | ID pattern | tmux window | Example |
 |------|-----------|-------------|---------|
+| Mapping | `cx-map-NN` | `cx-map-NN` | `cx-map-42` |
+| Map review | `cx-rev-map-NN` | `cx-rev-map-NN` | `cx-rev-map-42` |
+| Map fix | `cx-fix-map-NN` | `cx-fix-map-NN` | `cx-fix-map-42` |
 | Implement | `cx-impl-NN` | `cx-impl-NN` | `cx-impl-42` |
 | Review | `cl-rev-NN` | `cl-rev-NN` | `cl-rev-42` |
 | Fix | `cx-fix-NN` | `cx-fix-NN` | `cx-fix-42` |
 | Plan write | `cx-plan-NN` | `cx-plan-NN` | `cx-plan-42` |
+| Plan review | `cx-rev-plan-NN` | `cx-rev-plan-NN` | `cx-rev-plan-42` |
 | Plan fix | `cx-fix-plan-NN` | `cx-fix-plan-NN` | `cx-fix-plan-42` |
+| Buddy | `buddy-NN` | `buddy-NN` | `buddy-42` |
 
 **Rule**: Always use `--tmux <same-as-id>` so the tmux window name matches
 the session ID. Never use a different tmux name.
@@ -139,7 +231,7 @@ git commit -m "docs(plan-NN): add plan"
 
 # Create worktree
 WORKTREE="$(pwd)/../$(basename $(pwd))-plan-NN"
-git worktree add ${WORKTREE} -b plan/NN_name master
+git worktree add ${WORKTREE} -b plan/NN_name main
 
 # Launch from worktree
 cd ${WORKTREE}
@@ -164,19 +256,17 @@ harnex status --all     # all repos
 ## Buddy for Long-Running Dispatches
 
 If the dispatched work is expected to take a long time (overnight, multi-hour)
-or the user asks for unattended execution, spawn a buddy alongside the worker:
+or the user asks for unattended execution, spawn a buddy alongside the worker.
+Dispatch mechanics stay here; buddy monitoring mechanics live in
+`harnex-buddy`.
 
 ```bash
-# Worker
-harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
-  --context "Implement koder/plans/NN_name.md. Run tests when done."
-
-# Buddy to watch it
 harnex run claude --id buddy-NN --tmux buddy-NN
-harnex send --id buddy-NN --message "Watch session cx-impl-NN. Poll every 5 min with harnex pane --id cx-impl-NN --lines 20. Nudge with harnex send if stuck for >10 min. Report back to \$HARNEX_SPAWNER_PANE when done."
+harnex send --id buddy-NN --message "Watch session cx-impl-NN. Follow skills/harnex-buddy/SKILL.md and report completion to \$HARNEX_SPAWNER_PANE."
 ```
 
-The buddy replaces manual Fire & Watch polling. See `recipes/03_buddy.md`.
+For activation conditions, poll/stall/nudge loop, return channel details, and
+buddy cleanup, use `harnex-buddy`.
 
 ## What NOT to Do
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-23 00:00:00.000000000 Z
+date: 2026-04-24 00:00:00.000000000 Z
 dependencies: []
 description: A local PTY harness that wraps terminal AI agents (Claude, Codex) and
   adds a control plane for discovery, messaging, and coordination.