@doidor/agentrig 0.5.3

package/knowledge/templates/scripts/repair-worktrees.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# Hermetic per-agent worktrees (principle 7) + safe crash recovery.
+# Adapted from epichan's repair_agent_worktrees.py.
+#
+# Usage:
+#   repair-worktrees.sh add <agent-id> [branch]   Create/reuse an isolated worktree, print its path
+#   repair-worktrees.sh repair [--apply]          Prune stale metadata + safely recover worktrees
+#                                                 (dry-run unless --apply)
+#   repair-worktrees.sh                            Same as `repair` (dry-run)
+#
+# Safety rules for `repair` (so we never corrupt a live agent session):
+#   - Stale .git/index.lock / HEAD.lock are removed ONLY if older than LOCK_MIN_AGE_SECONDS AND not
+#     currently open (checked via lsof when available).
+#   - A worktree with open files (lsof) is treated as ACTIVE and skipped entirely.
+#   - Before any `git reset --hard` / `git clean -fd`, dirty files are ARCHIVED to
+#     ~/.agentrig/worktree-archives/<timestamp>/<agent>/ so interrupted work is recoverable.
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+WORKTREE_BASE="${AGENTRIG_WORKTREE_BASE:-$HOME/.agentrig/worktrees/$(basename "$REPO_ROOT")}"
+ARCHIVE_BASE="${AGENTRIG_WORKTREE_ARCHIVE:-$HOME/.agentrig/worktree-archives}"
+LOCK_MIN_AGE_SECONDS="${AGENTRIG_LOCK_MIN_AGE_SECONDS:-120}"
+LOCK_NAMES=("index.lock" "HEAD.lock")
+
+mkdir -p "$WORKTREE_BASE"
+
+path_has_open_files() {
+  # Returns 0 (true) if lsof reports any open handle under the path. If lsof is absent, assume not.
+  local target="$1"
+  command -v lsof >/dev/null 2>&1 || return 1
+  if [ -d "$target" ]; then
+    lsof +D "$target" >/dev/null 2>&1
+  else
+    lsof "$target" >/dev/null 2>&1
+  fi
+}
+
+file_age_seconds() {
+  local f="$1" now mtime
+  now="$(date +%s)"
+  # GNU stat (-c) then BSD/macOS stat (-f).
+  mtime="$(stat -c %Y "$f" 2>/dev/null || stat -f %m "$f" 2>/dev/null || echo "$now")"
+  echo "$(( now - mtime ))"
+}
+
+cmd_add() {
+  local agent_id="${1:?usage: repair-worktrees.sh add <agent-id> [branch]}"
+  local branch="${2:-agentrig/$agent_id}"
+  # Prune stale metadata BEFORE every add (the classic "worktree add refuses" crash).
+  git -C "$REPO_ROOT" worktree prune --expire now
+  local dir="$WORKTREE_BASE/$agent_id"
+  if git -C "$REPO_ROOT" worktree list --porcelain | grep -q "^worktree $dir$"; then
+    echo "Reusing worktree: $dir" >&2
+  else
+    git -C "$REPO_ROOT" worktree add -B "$branch" "$dir" >/dev/null
+    echo "Created worktree: $dir (branch $branch)" >&2
+  fi
+  echo "$dir"
+}
+
+cmd_repair() {
+  local apply="${1:-}"
+  local do_apply=0
+  [ "$apply" = "--apply" ] && do_apply=1
+
+  echo "Pruning stale worktree metadata…" >&2
+  [ "$do_apply" -eq 1 ] && git -C "$REPO_ROOT" worktree prune --expire now || git -C "$REPO_ROOT" worktree prune --expire now --dry-run || true
+
+  [ -d "$WORKTREE_BASE" ] || { echo "No worktrees under $WORKTREE_BASE"; return 0; }
+
+  local ts; ts="$(date +%Y%m%d-%H%M%S)"
+  for dir in "$WORKTREE_BASE"/*/; do
+    [ -d "$dir" ] || continue
+    dir="${dir%/}"
+    local agent; agent="$(basename "$dir")"
+
+    if path_has_open_files "$dir"; then
+      echo "[skip-active] $agent (open files present)"
+      continue
+    fi
+
+    # Remove stale, unopened lock files only.
+    local gitdir="$dir/.git"
+    [ -f "$dir/.git" ] && gitdir="$(sed -n 's/^gitdir: //p' "$dir/.git")"
+    for lock in "${LOCK_NAMES[@]}"; do
+      local lock_path="$gitdir/$lock"
+      [ -f "$lock_path" ] || continue
+      if path_has_open_files "$lock_path"; then
+        echo "[skip-active-lock] $agent/$lock"
+      elif [ "$(file_age_seconds "$lock_path")" -ge "$LOCK_MIN_AGE_SECONDS" ]; then
+        echo "[remove-lock] $agent/$lock"
+        [ "$do_apply" -eq 1 ] && rm -f "$lock_path"
+      else
+        echo "[skip-young-lock] $agent/$lock"
+      fi
+    done
+
+    # Archive dirty files before any reset/clean.
+    if [ -n "$(git -C "$dir" status --porcelain 2>/dev/null)" ]; then
+      local archive="$ARCHIVE_BASE/$ts/$agent"
+      echo "[archive+reset] $agent (dirty) -> $archive"
+      if [ "$do_apply" -eq 1 ]; then
+        mkdir -p "$archive"
+        git -C "$dir" status --porcelain -z | while IFS= read -r -d '' entry; do
+          local f="${entry:3}"
+          [ -f "$dir/$f" ] || continue
+          mkdir -p "$archive/$(dirname "$f")"
+          cp -p "$dir/$f" "$archive/$f" 2>/dev/null || true
+        done
+        git -C "$dir" reset --hard >/dev/null 2>&1 || true
+        git -C "$dir" clean -fd >/dev/null 2>&1 || true
+      fi
+    else
+      echo "[clean] $agent"
+    fi
+  done
+  [ "$do_apply" -eq 1 ] || echo "(dry-run — re-run with --apply to make changes)"
+}
+
+case "${1:-repair}" in
+  add) shift; cmd_add "$@" ;;
+  repair) shift; cmd_repair "${1:-}" ;;
+  *) cmd_repair "${1:-}" ;;
+esac

package/knowledge/templates/skills/fix-ci/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: fix-ci
+description: Diagnose and fix a failing CI run for the current branch, then re-verify.
+triggers:
+  - check_suite.completed.failure
+  - "user asks to fix CI / a red build"
+allowed-tools: Bash Read Grep Glob
+argument-hint: "[run-url|run-id]"
+---
+
+# fix-ci (principles 5, 8)
+
+1. Fetch the failing job logs (prefer `gh run view --log-failed`).
+2. Reproduce locally with the smallest command that fails.
+3. Fix the root cause — not the symptom. Avoid disabling tests to go green.
+4. Re-run `self-verify`. Iterate up to 3 times; otherwise self-park.
+5. If a rule or skill should have prevented this failure, run `skill-improver`.

package/knowledge/templates/skills/harness-eval/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: harness-eval
+description: Evaluate THIS repository's agent harness — a deterministic structure audit plus an independent, rubric-driven dynamic eval (run/spec/review) with A/B variant comparison.
+triggers:
+  - "evaluate the harness"
+  - pre_merge hook
+  - "did my harness change make things better or worse?"
+allowed-tools: Bash Read Grep Glob
+argument-hint: "[--static|--dynamic] [--scenario id] [--variant v]"
+---
+
+# harness-eval (principle 6 — evaluate the harness itself)
+
+A harness you cannot measure is a harness you cannot improve. This skill scores the harness on two
+complementary layers and writes results to `.agentrig/eval/results/` (validated, never hand-edited).
+
+## Layer A — static audit (deterministic, no model)
+Each of the 12 principles maps to concrete checks in `.agentrig/eval/checks.json`, scored 0/0.5/1.0.
+
+```bash
+node .agentrig/eval/static-audit.mjs            # human-readable report + aggregate score
+node .agentrig/eval/static-audit.mjs --json     # machine-readable, for CI gates
+```
+
+Use this in CI and as a fast pre-merge gate. It needs no model and no network.
+
+## Layer B — dynamic behavioral eval (agentic, independent judge)
+Run scenarios in `.agentrig/eval/scenarios/*.md` through the harness, then score as an **independent
+judge** (a different model than the producer) against `.agentrig/eval/RUBRIC.md` and the registry in
+`.agentrig/eval/axes.json`.
+
+**Sandbox:** obey `.agentrig/eval/sandbox/eval-rules.md` — work in a throwaway worktree; never push,
+open PRs, or merge.
+
+**Lifecycle:** score the whole lifecycle, not just the patch. Use the rubric `--type` that matches
+the scenario: `spec` (task quality), `run` (implementation), `review` (the reviewer's behavior).
+Link them with a shared `--task` id.
+
+**Rules (enforced by score.mjs):** strict 0/0.5/1.0 tiers; any axis < 1.0 needs an issue code from
+that axis's registry **plus** an evidence string; unobserved axes are `=na`; rollups are recomputed
+from axis data.
+
+```bash
+node .agentrig/eval/score.mjs save --type run --task <id> --scenario <id> --judge <model> \
+  --axis 'correctness=1.0' \
+  --axis 'scope=0.5:OQ-SCOPE-CHURN:left build artifacts in the diff' \
+  --axis 'tests=na'
+node .agentrig/eval/score.mjs report
+```
+
+**Artifacts:** for each run, save `diff.patch`, a short `output` transcript, and `meta.json`
+(scenario, base_commit, variant, model, duration) next to the score so regressions are inspectable.
+
+## Comparing harness changes (A/B)
+To know whether a prompt/skill/rule change helped, run the **same** scenario before and after under
+different `--variant`s, then:
+
+```bash
+node .agentrig/eval/score.mjs compare --scenario <id>
+```
+
+A change that lowers the aggregate is a regression even if it "feels" better. A static score < 1.0
+on a principle points at a missing/weak artifact — fix the artifact, then re-audit.
+
+## Does the harness actually help? (with vs without)
+The most important question for a consumer: *does installing AgentRig's harness make agents better
+in THIS repo?* Measure it by running the same scenarios twice and comparing:
+
+```bash
+# 1) Harness ON (the agent uses AGENTS.md + rules + skills as installed)
+agentrig eval --dynamic --scenario <id> --variant harness
+
+# 2) Baseline — harness OFF (a bare agent; ignore AGENTS.md/.agents/instructions surfaces)
+agentrig eval --dynamic --scenario <id> --variant baseline
+
+# 3) Report the lift (per-axis + aggregate delta + a HELPS/HURTS verdict)
+node .agentrig/eval/score.mjs compare --scenario <id> --baseline baseline
+```
+
+For a rigorous baseline, run the harness-off trial in a sandbox/worktree with the harness + compiled
+surfaces moved aside (`AGENTS.md`, `.agents/`, `.github/instructions/`, `CLAUDE.md`, `.cursor/`), so
+the agent genuinely has no harness guidance. A positive aggregate delta means the harness helps in
+this repo; track it over time as you tune rules/skills/prompts.

package/knowledge/templates/skills/self-verify/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: self-verify
+description: Run the project's own build/test/lint and converge before handing work to a reviewer.
+triggers:
+  - before requesting review
+  - before opening a PR
+allowed-tools: Bash Read Grep Glob
+argument-hint: "[--max-iterations N]"
+---
+
+# self-verify (principle 5)
+
+After producing changes, **verify your own work before handoff**. Do not invoke the reviewer until
+this loop converges.
+
+## Steps
+1. Run the install/build/test/lint commands recorded in `AGENTS.md` (the `commands` block).
+2. If all green → **continue** to review.
+3. If red → read the failure, fix, and re-run. Cap at **N=3** iterations (default).
+4. If still red after N → **self-park**: leave a precise note (what failed, what you tried) and
+   move the task to `parked`. Never hand a red build to a reviewer.
+
+## Notes
+- Pin verification to your own HEAD; do not trust stale CI from an earlier commit.
+- Record any new gotcha in `.agents/wiki/`.

package/knowledge/templates/skills/skill-authoring/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: skill-authoring
+description: Admission bar and structure for writing a new skill, so the skill library stays lean and discoverable.
+triggers:
+  - "create / add a new skill"
+  - "this procedure keeps coming up"
+allowed-tools: Read Edit Grep Glob
+argument-hint: "<skill-name>"
+---
+
+# skill-authoring (principle 4, 8)
+
+Skills are procedural memory. A bloated skill library is as useless as no library, so new skills
+must clear an admission bar.
+
+## Admission test (all must hold)
+1. **Reusable, not one-off.** It encodes how to do *one recurring thing* well — not a single task.
+2. **Not already covered.** Search `.agents/skills/`; if an existing skill is close, **sharpen it**
+   instead of adding a near-duplicate.
+3. **A procedure, not a reflex.** Passive, always-on constraints belong in `.agents/rules/`, not a
+   skill.
+
+## Structure
+- `SKILL.md` with YAML frontmatter: `name`, a `description` **< 250 chars**, `triggers`,
+  `allowed-tools` (scope the blast radius), and an optional `argument-hint`.
+- Body: short, imperative steps. Cap iteration loops and state the fallback.
+- Put long reference material in a sibling `references/` file and link to it, so the skill itself
+  stays small and the agent loads detail only on demand.
+- Scope `allowed-tools` to the minimum (e.g. `Bash Read Grep Glob`).
+
+## Keep surfaces in sync
+When you add or remove a skill, update the skills inventory in `AGENTS.md` (the
+`AGENTRIG:skills-inventory` block) so every surface advertises the same set. If the repo mirrors
+skills across vendor dirs (`.claude`/`.copilot`/`.agents`/…), they should all point at one canonical
+source (AgentRig wires these as symlinks).

package/knowledge/templates/skills/skill-improver/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: skill-improver
+description: Turn a reviewer/judge failure into an instruction-surface change that passes a prevention test.
+triggers:
+  - "a mistake recurred"
+  - "reviewer feedback points at a missing rule/skill"
+allowed-tools: Read Edit Grep Glob
+argument-hint: "<short description of the failure>"
+---
+
+# skill-improver (principle 8)
+
+Every mistake is a prompt bug. Convert it into a durable instruction change.
+
+## Procedure
+1. Identify the **instruction surface** that should have prevented the failure (a rule, a skill, or
+   `AGENTS.md` Critical Rules).
+2. Propose the minimal wording change.
+3. **Prevention test (mandatory):** would this new wording have changed the *original* failure? If
+   not, the change is rejected.
+4. **Admission test:** does an existing rule already cover this? If yes, do not duplicate — sharpen
+   the existing one. Duplication is what kills wikis.
+5. Record the gotcha in `.agents/wiki/` (central, committed) or the local wiki if repo-specific.

package/knowledge/templates/skills/verify-loop/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: verify-loop
+description: General wait → inspect → fix (max 3) → self-park loop for any post-action verification (build, tests, CI, visual, lint).
+triggers:
+  - after pushing changes / before requesting review
+  - "an async check (CI, visual, e2e) needs to be waited on and acted upon"
+allowed-tools: Bash Read Grep Glob
+argument-hint: "[--max-iterations N] [--check <command-or-workflow>]"
+---
+
+# verify-loop (principle 5, generalized)
+
+A reusable decision loop for converging on *any* verification signal before handoff. Generalizes the
+visual-self-verify pattern to builds, tests, CI runs, lint, or e2e.
+
+## Loop
+1. **Trigger** the check (or wait for the async one pinned to your own HEAD — never trust a stale
+   result from an earlier commit).
+2. **Inspect** the result:
+   - **Green / no unintended change →** *continue* (proceed to review/handoff).
+   - **Red / unintended change →** go to step 3.
+   - **Intended but human-gated change →** *self-park* (see below). Do not iterate.
+3. **Fix** the root cause and re-run. Cap at **N = 3** iterations (default).
+4. **After N failures →** stop iterating and take a recovery path: self-park with a precise note, or
+   escalate. Do not loop indefinitely.
+
+## Self-park
+When the right next step needs a human (low reversibility, an intended diff behind a human-only
+gate, or repeated failure), leave a clear note describing what you saw and what you tried, move the
+task to `parked`, and **never apply the human-only label yourself**.
+
+## Notes
+- Pin every check to your current HEAD.
+- Record any new gotcha in `.agents/wiki/`.
+- This is the engine behind `self-verify`; use `verify-loop` whenever the signal is asynchronous.

package/knowledge/templates/wiki/README.md

@@ -0,0 +1,23 @@
+# Agent wiki — tiered memory (principle 8)
+
+Every mistake is a prompt bug. This is where durable gotchas live.
+
+## Tiers
+1. **Central wiki (this directory, committed):** repo-wide, reviewed gotchas. CODEOWNERS-gate it.
+2. **Local wiki (git-ignored):** machine/contributor-specific notes. Add `*.local.md` to
+   `.gitignore`.
+3. **Session scratch:** ephemeral working notes (e.g. `plan.md`); never a substitute for the wiki.
+
+## Admission test (strict — duplication kills wikis)
+Before adding an entry, confirm no existing entry covers it. If one does, **sharpen it** instead of
+adding a near-duplicate. Each entry should be: a title, the symptom, the root cause, the fix, and a
+one-line prevention.
+
+## Entry template
+```markdown
+### <short title>
+- **Symptom:** what went wrong / how it showed up
+- **Cause:** the real root cause
+- **Fix:** the change that resolved it
+- **Prevention:** the rule/skill wording that would have stopped it (feed to skill-improver)
+```

package/knowledge/templates/wiki/_TEMPLATE.md

@@ -0,0 +1,16 @@
+# <short, greppable title>
+
+> Copy this file to `.agents/wiki/<slug>.md` for a new gotcha. Keep the four sections.
+
+## Symptoms
+What it looked like / how it surfaced (error text, behavior). Make it greppable.
+
+## Root cause
+The real underlying cause — not the symptom.
+
+## Fix
+The exact change that resolved it. Include commands/snippets where useful.
+
+## Prevention
+The rule/skill wording that would have stopped this. If a rule or skill should have caught it, feed
+this to `skill-improver`. Add a `## Related` section with links if relevant.

package/knowledge/templates/wiki/index.md

@@ -0,0 +1,29 @@
+# Agent wiki — index & routing
+
+This wiki holds **learned gotchas and war stories** — durable lessons an agent discovered the hard
+way. It is **not** a mirror of the docs or skills.
+
+## What belongs where
+| Kind of knowledge | Goes in |
+|-------------------|---------|
+| A gotcha / non-obvious failure + its fix | **this wiki** (`.agents/wiki/<slug>.md`) |
+| A repeatable procedure ("how to do X") | a skill (`.agents/skills/`) |
+| A passive, always-on constraint | a rule (`.agents/rules/`) |
+| Repo-wide policy / critical rules | `AGENTS.md` |
+| Common error → fix lookups | `troubleshooting.md` (in this dir) |
+
+If a gotcha becomes a reusable procedure, **promote it to a skill** and leave a one-line pointer
+here.
+
+## Tiers (principle 8)
+1. **Central wiki (this dir, committed):** repo-wide, reviewed gotchas. CODEOWNERS-gate it.
+2. **Local wiki (git-ignored `*.local.md`):** machine/contributor-specific notes.
+3. **Session scratch:** ephemeral working notes; never a substitute for the wiki.
+
+## Index
+_Add a one-line link per entry as you create it, newest first._
+- (none yet)
+
+## Admission test (strict — duplication kills wikis)
+Before adding an entry, confirm no existing entry covers it. If one does, **sharpen it** instead of
+adding a near-duplicate. Use the format in `_TEMPLATE.md`.

package/knowledge/templates/wiki/troubleshooting.md

@@ -0,0 +1,14 @@
+# Troubleshooting — common errors and fixes
+
+A shared, living list of errors agents (and humans) hit in this repo and the fix that worked. Prefer
+adding here over re-debugging the same thing twice. Keep each entry tight.
+
+## Format
+```
+### <error message or symptom, greppable>
+- **When:** the situation it shows up in
+- **Fix:** the exact thing that resolves it
+```
+
+## Entries
+_None yet. Add new entries below this line (newest first)._

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@doidor/agentrig",
+  "version": "0.5.3",
+  "description": "AgentRig — an agentic meta-harness. A CLI that investigates a repository and installs (and evaluates) a best-practice agent harness.",
+  "type": "module",
+  "bin": {
+    "agentrig": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "knowledge",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doidor/agentrig.git"
+  },
+  "homepage": "https://github.com/doidor/agentrig#readme",
+  "bugs": {
+    "url": "https://github.com/doidor/agentrig/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "clean": "rm -rf dist",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run clean && npm run build && npm test",
+    "start": "node dist/cli.js",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "selftest": "node dist/cli.js eval --static . || true",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
+  },
+  "keywords": [
+    "agent",
+    "harness",
+    "copilot",
+    "agentic",
+    "scaffold",
+    "evaluation",
+    "ai"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@github/copilot-sdk": "^1.0.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.7.0",
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}