harnex 0.5.0 → 0.6.2

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: harnex
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Jikku Jose
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-05-01 00:00:00.000000000 Z
+date: 2026-05-06 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.
@@ -19,19 +19,28 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - GUIDE.md
 - LICENSE
 - README.md
 - TECHNICAL.md
 - bin/gem-push
 - bin/harnex
+- guides/01_dispatch.md
+- guides/02_chain.md
+- guides/03_buddy.md
+- guides/04_monitoring.md
+- guides/05_naming.md
 - lib/harnex.rb
 - lib/harnex/adapters.rb
 - lib/harnex/adapters/base.rb
 - lib/harnex/adapters/claude.rb
 - lib/harnex/adapters/codex.rb
+- lib/harnex/adapters/codex_appserver.rb
 - lib/harnex/adapters/generic.rb
 - lib/harnex/cli.rb
+- lib/harnex/commands/agents_guide.rb
+- lib/harnex/commands/doctor.rb
 - lib/harnex/commands/events.rb
 - lib/harnex/commands/guide.rb
 - lib/harnex/commands/logs.rb
@@ -39,7 +48,6 @@ files:
 - lib/harnex/commands/recipes.rb
 - lib/harnex/commands/run.rb
 - lib/harnex/commands/send.rb
-- lib/harnex/commands/skills.rb
 - lib/harnex/commands/status.rb
 - lib/harnex/commands/stop.rb
 - lib/harnex/commands/wait.rb
@@ -59,12 +67,6 @@ files:
 - recipes/01_fire_and_watch.md
 - recipes/02_chain_implement.md
 - recipes/03_buddy.md
-- skills/close/SKILL.md
-- skills/harnex-buddy/SKILL.md
-- skills/harnex-chain/SKILL.md
-- skills/harnex-dispatch/SKILL.md
-- skills/harnex/SKILL.md
-- skills/open/SKILL.md
 homepage: https://github.com/jikkuatwork/harnex
 licenses:
 - MIT

data/lib/harnex/commands/skills.rb

@@ -1,226 +0,0 @@
-require "fileutils"
-
-module Harnex
-  class Skills
-    SKILLS_ROOT = File.expand_path("../../../../skills", __FILE__)
-    INSTALL_SKILLS = %w[harnex-dispatch harnex-chain harnex-buddy].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> [SKILL...] [--local]
-
-        Subcommands:
-          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.
-
-        With --local, copies each skill to .claude/skills/<skill>/
-        in the current repo and symlinks .codex/skills/<skill> to it.
-      TEXT
-    end
-
-    def initialize(argv)
-      @argv = argv.dup
-    end
-
-    def run
-      subcommand = @argv.shift
-      case subcommand
-      when "install"
-        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|
-          skill_source = resolve_skill_source(skill_name)
-          unless skill_source
-            return missing_skill(skill_name)
-          end
-
-          result = local ? install_local(skill_name, skill_source) : install_global(skill_name, skill_source)
-          return result unless result == 0
-        end
-        0
-      when "uninstall"
-        local, help, = parse_args(@argv)
-        return (puts self.class.usage; 0) if help
-
-        (INSTALL_SKILLS + DEPRECATED_SKILLS).each do |skill_name|
-          local ? uninstall_local(skill_name) : uninstall_global(skill_name)
-        end
-        0
-      when "-h", "--help", nil
-        puts self.class.usage
-        0
-      else
-        warn("harnex skills: unknown subcommand #{subcommand.inspect}")
-        puts self.class.usage
-        1
-      end
-    end
-
-    private
-
-    def parse_args(args, allow_positional: false)
-      local = false
-      help = false
-      positional = []
-
-      args.each do |arg|
-        case arg
-        when "--local"
-          local = true
-        when "-h", "--help"
-          help = true
-        when /\A-/
-          raise "harnex skills: unknown option #{arg.inspect}"
-        else
-          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, positional]
-    end
-
-    def resolve_skill_source(skill_name)
-      path = File.join(SKILLS_ROOT, skill_name)
-      File.directory?(path) ? path : nil
-    end
-
-    def missing_skill(skill_name)
-      warn("harnex skills: bundled skill #{skill_name.inspect} not found at #{SKILLS_ROOT}")
-      1
-    end
-
-    def remove_deprecated(local)
-      DEPRECATED_SKILLS.each do |skill_name|
-        local ? uninstall_local(skill_name) : uninstall_global(skill_name)
-      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)
-      codex_dir = File.join(repo_root, ".codex", "skills", skill_name)
-
-      # Copy skill to .claude/skills/<skill>/
-      if Dir.exist?(claude_dir)
-        warn("harnex skills: #{claude_dir} already exists, overwriting")
-        FileUtils.rm_rf(claude_dir)
-      end
-      FileUtils.mkdir_p(File.dirname(claude_dir))
-      FileUtils.cp_r(skill_source, claude_dir)
-      puts "installed #{claude_dir}"
-
-      # Symlink .codex/skills/<skill> -> .claude/skills/<skill>
-      codex_parent = File.dirname(codex_dir)
-      FileUtils.mkdir_p(codex_parent)
-      FileUtils.rm_rf(codex_dir) if File.exist?(codex_dir) || File.symlink?(codex_dir)
-
-      # Relative symlink so it works if the repo moves
-      relative = relative_path(from: codex_parent, to: claude_dir)
-      File.symlink(relative, codex_dir)
-      puts "symlinked #{codex_dir} -> #{relative}"
-
-      0
-    end
-
-    def install_global(skill_name, skill_source)
-      claude_dir = File.expand_path("~/.claude/skills/#{skill_name}")
-      codex_dir = File.expand_path("~/.codex/skills/#{skill_name}")
-
-      # Copy skill to ~/.claude/skills/<skill>/
-      if Dir.exist?(claude_dir)
-        warn("harnex skills: #{claude_dir} already exists, overwriting")
-        FileUtils.rm_rf(claude_dir)
-      end
-      FileUtils.mkdir_p(File.dirname(claude_dir))
-      FileUtils.cp_r(skill_source, claude_dir)
-      puts "installed #{claude_dir}"
-
-      # Symlink ~/.codex/skills/<skill> -> ~/.claude/skills/<skill>
-      codex_parent = File.dirname(codex_dir)
-      FileUtils.mkdir_p(codex_parent)
-      FileUtils.rm_rf(codex_dir) if File.exist?(codex_dir) || File.symlink?(codex_dir)
-      File.symlink(claude_dir, codex_dir)
-      puts "symlinked #{codex_dir} -> #{claude_dir}"
-
-      0
-    end
-
-    def uninstall_local(skill_name)
-      repo_root = Harnex.resolve_repo_root(Dir.pwd)
-      claude_dir = File.join(repo_root, ".claude", "skills", skill_name)
-      codex_dir = File.join(repo_root, ".codex", "skills", skill_name)
-
-      removed = false
-      if File.exist?(codex_dir) || File.symlink?(codex_dir)
-        FileUtils.rm_rf(codex_dir)
-        removed = true
-      end
-      if File.exist?(claude_dir) || File.symlink?(claude_dir)
-        FileUtils.rm_rf(claude_dir)
-        removed = true
-      end
-      puts "removed #{skill_name}" if removed
-    end
-
-    def uninstall_global(skill_name)
-      claude_dir = File.expand_path("~/.claude/skills/#{skill_name}")
-      codex_dir = File.expand_path("~/.codex/skills/#{skill_name}")
-
-      removed = false
-      if File.exist?(codex_dir) || File.symlink?(codex_dir)
-        FileUtils.rm_rf(codex_dir)
-        removed = true
-      end
-      if File.exist?(claude_dir) || File.symlink?(claude_dir)
-        FileUtils.rm_rf(claude_dir)
-        removed = true
-      end
-      puts "removed #{skill_name}" if removed
-    end
-
-    def relative_path(from:, to:)
-      from_parts = File.expand_path(from).split("/")
-      to_parts = File.expand_path(to).split("/")
-
-      # Drop common prefix
-      while from_parts.first == to_parts.first && !from_parts.empty?
-        from_parts.shift
-        to_parts.shift
-      end
-
-      ([".."] * from_parts.length + to_parts).join("/")
-    end
-  end
-end

data/skills/close/SKILL.md

@@ -1,47 +0,0 @@
----
-name: close
-description: Close a work session in this repo — update koder/STATE.md with what changed and the next step, clean up accidental or temporary repo artifacts, and leave a clear handoff. Use when the user says "close session", "wrap up", "end session", "handoff", or invokes "/close".
----
-
-# Close Session Workflow
-
-When the user asks to wrap up or close the current session, run this sequence:
-
-## 1. Review the session changes
-
-- Check `git status --short` and `git diff --stat`
-- Separate the work from this session from unrelated user changes
-- Do not revert unrelated changes you did not make
-
-## 2. Update `koder/STATE.md`
-
-- Update the `Updated:` date
-- Add or adjust concise lines in `Current snapshot` for completed work
-- Update test count if it changed
-- Update issue or plan statuses only when work was actually completed or a new blocker was clearly discovered
-- Rewrite `Next step` so the next agent can resume without reconstructing context
-
-## 3. Clean up repo artifacts
-
-- Remove temporary files, scratch notes, or mistaken tracking docs created during the session
-- Keep durable artifacts that are part of the intended result
-- If cleanup would discard ambiguous work, ask the user instead of guessing
-
-## 4. Commit and clean the repo
-
-- Stage all session changes (code, docs, STATE.md updates) and commit with a clear message summarizing the session's work
-- Do NOT stage files that look like secrets, credentials, or large binaries — flag them to the user
-- After committing, run `git status --short` to confirm a clean working tree
-- If unrelated uncommitted changes remain, leave them alone — do not revert or commit work you did not produce
-
-## 5. Verify the handoff
-
-- Run the relevant tests or verification commands if code or docs changed
-- Give the user a concise summary of what changed, the commit, and any remaining follow-up
-- The goal: the next `/open` should see a clean repo and an accurate `koder/STATE.md`
-
-## Notes
-
-- Do NOT create or close issue docs unless the user explicitly asks
-- Do NOT build, install, or publish anything unless the user explicitly asks
-- If `koder/STATE.md` is already accurate, keep the update minimal rather than churning it

data/skills/harnex/SKILL.md

@@ -1,20 +0,0 @@
----
-name: harnex
-description: Deprecated alias for harnex-dispatch. Use harnex-dispatch for active harnex collaboration guidance.
----
-
-# Deprecated Skill Alias
-
-`harnex` is deprecated.
-
-Use `harnex-dispatch` as the canonical skill for harnex collaboration,
-Fire & Watch dispatching, relay handling, and return-channel discipline.
-
-If you are installing skills, use:
-
-```bash
-harnex skills install harnex-dispatch
-```
-
-Compatibility note: `harnex skills install harnex` remains supported and
-installs `harnex-dispatch`.

data/skills/harnex-buddy/SKILL.md

@@ -1,104 +0,0 @@
----
-name: harnex-buddy
-description: Spawn an accountability partner for long-running harnex sessions. Use when the user asks to run something overnight, unattended, or for any work expected to take more than 30 minutes without supervision.
----
-
-# Buddy — Accountability Partner for Long-Running Work
-
-For any long-running or unattended work, spawn a **buddy** — a second harnex
-agent that watches the worker and nudges it if it stalls.
-
-For plain stall recovery (force-resume on inactivity), prefer
-`harnex run --watch --preset impl`. Use a buddy when you need reasoning that
-policy checks cannot provide (doc drift, semantic checks, multi-session
-correlation).
-
-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"
-- Task is expected to take more than 30 minutes unattended
-- User explicitly asks for a buddy, accountability partner, or monitoring
-- User asks to "keep an eye on" a dispatched worker
-
-## Spawn the buddy
-
-After dispatching the worker with `harnex-dispatch`, spawn a buddy alongside
-it. Keep ID/tmux naming consistent with `harnex-dispatch` (`--tmux` matches
-`--id`):
-
-```bash
-# Spawn its buddy
-harnex run claude --id buddy-42 --tmux buddy-42
-```
-
-## Write the buddy prompt
-
-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 `cx-impl-42`.
-
-Your job:
-1. Every 5 minutes, check on the worker:
-   - `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 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" "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.
-EOF
-
-harnex send --id buddy-42 --message "Read and execute /tmp/buddy-42.md"
-```
-
-Adjust the polling interval (5 min), stall threshold (10 min), and nudge
-message to match the workload.
-
-## Return channel
-
-The buddy can reach back to the invoker (your raw Claude session) via
-`$HARNEX_SPAWNER_PANE` — the stable tmux pane ID set automatically by
-harnex at spawn time:
-
-```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" "worker-42 finished" Enter
-```
-
-The invoker does NOT need to be a harnex session. It just needs to be in tmux.
-
-## Naming convention
-
-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
-
-Stop the buddy after the worker finishes:
-
-```bash
-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
-- See `recipes/03_buddy.md` for the full recipe

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.