harnex 0.6.0 → 0.6.3

data/skills/harnex-chain/SKILL.md

@@ -1,132 +0,0 @@
----
-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.
----
-
-# Chain Implement
-
-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`.
-
-For naming (`--tmux <same-as-id>`) and worktree operational rules, use
-`harnex-dispatch`.
-
-## Orchestrator Role
-
-- 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
-
-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.
-
-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 (Serial Default)
-
-```
-Issue (user + orchestrator chat)
-  ↓
-[Mapping Plan] -> [Map Review] -> [Fix Map]     <- optional for large scope
-  ↓
-[Plan Extraction] -> thin-layer plans            <- optional if one plan suffices
-  ↓
-Per plan (serial on main):
-  Plan -> Plan Review -> Fix Plan
-    -> Implement -> Code Review -> Fix Code
-    -> Commit -> next plan
-```
-
-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
-
-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
-- Open questions
-
-## Phase 2: Mapping Plan (Optional)
-
-Use when scope is broad, has sequencing constraints, or still contains
-user-blocking questions. Skip for small, coherent issues.
-
-Outputs:
-- Technical map of files/functions/seams
-- Sequencing constraints
-- Explicit user-blocking questions
-
-Gate:
-- If map review finds user-blocking questions, stop the chain and return to
-  user.
-
-## Phase 3: Plan Extraction (Optional)
-
-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.
-
-## Phase 4: Serial Plan Loop (Default)
-
-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
-
-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.
-
-## Parallel Variant
-
-Parallelism is allowed only for planning passes. Keep implementation serial
-on `main` unless the user explicitly requests worktrees.
-
-Approved parallel lanes:
-- Parallel plan-writing sessions (one plan file per Codex session)
-- Parallel plan-review sessions (one review file per Codex session)
-
-Capacity rule:
-- Run at most 5 concurrent Codex sessions total across all active lanes
-  (global cap, not per lane).
-
-Lifecycle rule:
-- Use `harnex-dispatch` Fire & Watch, including poll cadence and stop timing.
-
-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).
-
-## Unattended Monitoring
-
-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`.
-
-## Failure and Escalation
-
-- 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,294 +0,0 @@
----
-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
-
-Launch the agent in a tmux window so the user can observe it live:
-
-```bash
-harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
-  --context "Implement koder/plans/NN_name.md. Run tests when done. Commit after each phase."
-```
-
-For reviews (Claude):
-
-```bash
-harnex run claude --id cl-rev-NN --tmux cl-rev-NN \
-  --context "Review the implementation of plan NN against the spec in koder/plans/NN_name.md. Write findings to koder/reviews/NN_name.md"
-```
-
-For complex task prompts, write to a temp file and reference it:
-
-```bash
-cat > /tmp/task-impl-NN.md <<'EOF'
-Detailed instructions here...
-EOF
-
-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.
-
-**Progressive intervals** when you expect longer work:
-
-| Elapsed | Interval | Rationale |
-|---------|----------|-----------|
-| 0–2 min | 30s | Catch fast completions and early errors |
-| 2–10 min | 60s | Steady state for typical implementations |
-| 10+ min | 120s | Long-running work, reduce noise |
-
-```bash
-# Quick check — last 20 lines is enough to see if done or stuck
-harnex pane --id cx-impl-NN --lines 20
-
-# JSON metadata (includes capture timestamp)
-harnex pane --id cx-impl-NN --lines 20 --json
-```
-
-When checking, look for:
-- **At prompt** → agent finished, read last output for results
-- **Still working** → agent is reading files, running tests, editing code
-- **Error/stuck** → agent hit a blocker, may need intervention
-- **Permission prompt** → agent waiting for user approval, intervene
-
-### Background poll from Claude Code
-
-```bash
-# Run as a background task, check result when notified
-harnex pane --id cx-impl-NN --lines 20
-```
-
-Or use `--follow` for continuous monitoring:
-
-```bash
-harnex pane --id cx-impl-NN --lines 20 --follow
-```
-
-## 3. Stop
-
-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
-```
-
-Always verify the agent's work landed before stopping:
-
-```bash
-# Quick sanity check
-harnex pane --id cx-impl-NN --lines 20
-# Confirm commits exist
-git log --oneline -5
-# Then stop
-harnex stop --id cx-impl-NN
-```
-
-## Naming Conventions
-
-| 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.
-
-## Full Dispatch Lifecycle
-
-```
-1. Mark plan IN_PROGRESS, commit
-2. harnex run codex --id cx-impl-NN --tmux cx-impl-NN
-3. Poll with harnex pane --lines 20 every 30s
-4. When done: verify commits, harnex stop
-5. harnex run claude --id cl-rev-NN --tmux cl-rev-NN (review)
-6. Poll with harnex pane --lines 20 every 30s
-7. When done: harnex stop, read review
-8. If NEEDS FIXES: harnex run codex --id cx-fix-NN (fix pass)
-9. If PASS: done
-```
-
-## Worktree Option
-
-Use worktrees only when you need **parallel isolation** — e.g., implementing
-one plan while another is being reviewed, or when the user explicitly asks.
-Do not default to worktrees for serial work.
-
-### Worktree Setup
-
-```bash
-# Commit all files the agent will need BEFORE creating the worktree
-# (untracked files don't carry over)
-git add koder/plans/NN_name.md
-git commit -m "docs(plan-NN): add plan"
-
-# Create worktree
-WORKTREE="$(pwd)/../$(basename $(pwd))-plan-NN"
-git worktree add ${WORKTREE} -b plan/NN_name main
-
-# Launch from worktree
-cd ${WORKTREE}
-harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
-  --context "Implement koder/plans/NN_name.md. Run tests when done."
-```
-
-### Worktree Caveats
-
-- **cd first**: launch and manage sessions from the worktree directory
-- **Merge conflicts**: `koder/` state files may diverge — on merge, keep
-  master's versions of session-state files
-- **Cleanup**: `git worktree remove <path>` then `git branch -d plan/<branch>`
-
-## Checking Status
-
-```bash
-harnex status           # current repo sessions
-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.
-Dispatch mechanics stay here; buddy monitoring mechanics live in
-`harnex-buddy`.
-
-```bash
-harnex run claude --id buddy-NN --tmux buddy-NN
-harnex send --id buddy-NN --message "Watch session cx-impl-NN. Follow skills/harnex-buddy/SKILL.md and report completion to \$HARNEX_SPAWNER_PANE."
-```
-
-For activation conditions, poll/stall/nudge loop, return channel details, and
-buddy cleanup, use `harnex-buddy`.
-
-## What NOT to Do
-
-- **Never** launch agents with raw `tmux send-keys` or `tmux new-window`
-- **Never** use `--tmux NAME` where NAME differs from `--id`
-- **Never** pass `-- --cd <path>` to Claude sessions (unsupported flag)
-- **Never** poll with raw `tmux capture-pane` — use `harnex pane`
-- **Never** rely on `--wait-for-idle` alone — always use Fire & Watch
-- **Never** use `c-zai-dangerous` or direct CLI spawning outside harnex

data/skills/open/SKILL.md

@@ -1,32 +0,0 @@
----
-name: open
-description: Open a work session in this repo — read koder/STATE.md first, inspect the current worktree, align on the active issue or plan, and establish the starting point before editing. Use when the user says "open session", "start work", "initialize", "orient yourself", or invokes "/open".
----
-
-# Open Session Workflow
-
-When the user asks to initialize or open the session, run this sequence:
-
-## 1. Read the handoff
-
-- Read `koder/STATE.md` first
-- Note the `Current snapshot`, open issues and plans, and `Next step`
-- Open only the issue or plan files relevant to the current task
-
-## 2. Inspect the repo state
-
-- Run `git status --short`
-- Notice modified or untracked files before editing
-- Do not revert unrelated changes you did not make
-
-## 3. Establish the starting point
-
-- Summarize the important context for this session: relevant issue or plan, repo state, and the immediate next step
-- If the user already asked for implementation, continue into the work instead of stopping at orientation
-- Update `koder/STATE.md` during open only if it is clearly stale enough to mislead the session
-
-## Notes
-
-- Treat `koder/STATE.md` as the handoff document between sessions
-- Prefer updating existing issue or plan docs over creating new tracking files
-- Do NOT create issue docs unless the user explicitly asks