harnex 0.3.3 → 0.4.0

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
 
@@ -34,11 +119,27 @@ harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
   --context "Read and execute /tmp/task-impl-NN.md"
 ```
 
+### Built-in monitoring (`--watch`)
+
+For unattended implementation runs where you only need stall policy (not
+Claude-side reasoning), bundle dispatch and monitoring in one command:
+
+```bash
+harnex run codex --id cx-impl-42 --tmux cx-impl-42 --watch --preset impl
+```
+
+`--preset impl` applies the standard 8m stall threshold with one forced resume.
+Trade-off: `--watch` is foreground-blocking and policy-only (`stall-after` +
+`max-resumes`). Use pane polling (and buddy when needed) for richer reasoning.
+
 ## 2. Watch
 
 Poll the agent's screen with `harnex pane`. Checking is cheap — a 20-line
 tail is a few hundred bytes.
 
+For structured orchestration, prefer `harnex events --id <id>` over pane-text
+scraping.
+
 **Default: poll every 30 seconds.** This is fine for most work. The check
 itself costs almost nothing and catches completion quickly.
 
@@ -81,6 +182,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 +203,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 +247,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 +272,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.4.0
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-23 00:00:00.000000000 Z
+date: 2026-04-29 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.
@@ -32,6 +32,7 @@ files:
 - lib/harnex/adapters/codex.rb
 - lib/harnex/adapters/generic.rb
 - lib/harnex/cli.rb
+- lib/harnex/commands/events.rb
 - lib/harnex/commands/guide.rb
 - lib/harnex/commands/logs.rb
 - lib/harnex/commands/pane.rb
@@ -42,6 +43,8 @@ files:
 - lib/harnex/commands/status.rb
 - lib/harnex/commands/stop.rb
 - lib/harnex/commands/wait.rb
+- lib/harnex/commands/watch.rb
+- lib/harnex/commands/watch_presets.rb
 - lib/harnex/core.rb
 - lib/harnex/runtime/api_server.rb
 - lib/harnex/runtime/file_change_hook.rb