claude-dev-env 1.92.1 → 1.93.0

package/skills/gotcha/SKILL.md

@@ -22,7 +22,7 @@ The caller provides the obstacle context. Distill it into:
 - **What the user had to do** to resolve it.
 - **What to do differently next time** (the actionable gotcha).
 
-Determine which repo the skill lives in. Usually this is `claude-code-config`, but if the skill is in another repo (e.g. a project-specific `.claude/skills/` directory), use that repo instead.
+Determine which repo the skill lives in. Usually this is `claude-dev-env`, but if the skill is in another repo (e.g. a project-specific `.claude/skills/` directory), use that repo instead.
 
 ### Step 2 — Delegate to bg-agent
 
@@ -62,11 +62,11 @@ If a `## Gotchas` section already exists, append to it. If not, create it at the
 
 | Skill location | Repo |
 |---|---|
-| `packages/claude-dev-env/skills/<name>/` | `jl-cmd/claude-code-config` |
-| `~/.claude/skills/<name>/` | `jl-cmd/claude-code-config` (user skills) |
+| `packages/claude-dev-env/skills/<name>/` | `jl-cmd/claude-dev-env` |
+| `~/.claude/skills/<name>/` | `jl-cmd/claude-dev-env` (user skills) |
 | Project `.claude/skills/<name>/` | That project's repo |
 
-When unsure, ask the user which repo. Otherwise, default to `claude-code-config`.
+When unsure, ask the user which repo. Otherwise, default to `claude-dev-env`.
 
 ## Gotchas
 

package/skills/log-audit/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: log-audit
 description: >-
-  Watches this repo's own logs for patterns worth acting on. Use for /log-audit,
-  "audit the logs", "what keeps failing", or "what's getting slower". Reads the
-  hook block log and the diagnostic extractor pipeline, clusters recurring errors
-  and timing regressions, opens a grouped fix PR or a tracked optimization issue
-  per real finding, and mines the defects Copilot and Bugbot keep catching into
-  skill-edit proposals. Runs as a background agent that resumes after a restart.
+  Watches this repo's own logs for patterns worth acting on: clusters recurring
+  errors and timing regressions, then opens a grouped fix PR or a tracked
+  optimization issue per real finding. Use for /log-audit, 'audit the logs',
+  'what keeps failing', or 'what's getting slower'.
 ---
 
 # log-audit

package/skills/monitor-open-prs/CLAUDE.md

@@ -22,7 +22,7 @@ Discovers every open pull request across the `jl-cmd/*` and `JonEcho/*` owner sc
 ## Workflow summary
 
 1. Call `discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho"])` to get the full open-PR list.
-2. For each PR, invoke `/bugteam --bugbot-retrigger <pr_number>` (omit `--bugbot-retrigger` if `CLAUDE_REVIEWS_DISABLED` has `bugbot`).
+2. For each PR, invoke `/bugteam <pr_number>`; include `--bugbot-retrigger` only when bugbot is enabled (`reviews_disabled.py --reviewer bugbot` exits 1).
 3. After each bugteam run, poll for new bugbot comments on a 60s → 120s → 240s → 480s → 960s backoff. Re-invoke bugteam if new findings appear.
 4. Emit a sweep summary when all PRs exit polling.
 

package/skills/monitor-open-prs/SKILL.md

@@ -15,12 +15,17 @@ description: >-
 
 ## Contents
 
+- Transport check — gh presence and auth route the sweep local or through the cloud transport
 - When this skill applies — refusal cases and trigger conditions
 - Discovery — `scripts/discover_open_prs.py` queries via `gh search prs` across both owner scopes
 - Dispatch — `/bugteam --bugbot-retrigger <pr_numbers...>`
 - Post-convergence polling — bugbot replies and re-invocation
 - `scripts/discover_open_prs.py` — the discovery helper
 
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; for each PR the sweep dispatches, `gh api repos/<owner>/<repo> --jq .permissions.push` must print `true`. When any check fails, run the `pr-loop-cloud-transport` skill first and route every `gh` operation in this skill through its substitution matrix, including the discovery query (`mcp__github__search_pull_requests` with `perPage` in place of `gh search prs`).
+
 ## When this skill applies
 
 `/monitor-open-prs` authorizes one full sweep over all open PRs in both owner scopes.
@@ -41,7 +46,7 @@ Call `scripts/discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho
 For each discovered PR:
 
 1. Resolve the PR's repo checkout (existing worktree or fresh `git clone`).
-2. From that checkout, invoke `/bugteam --bugbot-retrigger <pr_number>`. When `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot` exits 0 (bugbot disabled), omit `--bugbot-retrigger` from the dispatched command so the bugbot leg sits out the run.
+2. From that checkout, invoke `/bugteam <pr_number>`. Include `--bugbot-retrigger` only when bugbot is enabled for the run — when `python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer bugbot` exits 1. On exit 0 (bugbot disabled — the default) omit `--bugbot-retrigger` so the bugbot leg sits out the run.
 3. The `--bugbot-retrigger` flag tells bugteam to post `bugbot run` as an issue comment after every successful FIX push so Cursor's bugbot re-evaluates the new commit.
 4. Bugteam runs its own 20-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below).
 

package/skills/orchestrator/SKILL.md

@@ -1,20 +1,11 @@
 ---
 name: orchestrator
 description: >-
-  Turns the session into the advisor-orchestrator — the user's sole interface,
-  to plan
-  and delegate while workflow-backed agent spawns do the token-heavy
-  execution with the required agent type and model for each work category.
-  Executors do the code editing, verification, script driving, PR
-  descriptions, and searches; the advisor answers blockers with one of three
-  brief signals — a plan, a correction, or a stop. The advisor never edits
-  code or runs tests itself. Caps consultations per task (default 5), reuses
-  warm workflow agents before spawning new ones, and re-asserts the
-  discipline every 20 minutes through the /orchestrator-refresh loop. Adapts
-  Anthropic's coordinator pattern (plan big, execute small) to Claude Code.
-  Triggers: '/orchestrator', 'orchestrator strategy', 'run with an
-  orchestrator', 'executor-advisor mode', 'orchestrator enforcement', 'agent
-  routing', 'orchestrate'.
+  Advisor-orchestrator mode: plan and delegate while workflow-backed agents
+  execute; a shared session-advisor answers hard decisions with endorse,
+  correction, plan, or stop. Triggers: '/orchestrator', 'orchestrator
+  strategy', 'run with an orchestrator', 'executor-advisor mode',
+  'orchestrator enforcement', 'agent routing', 'orchestrate'.
 ---
 
 # Orchestrator Strategy
@@ -37,8 +28,9 @@ is the advisor-orchestrator. In Claude Code the user always talks to the session
 subagent, so the session is the user's sole interface: all user-facing
 communication flows through it. It spawns and resumes executor subagents
 — `clean-coder` and the like — and those executors do every bit of the
-execution: the code edits, the build runs, the test runs. The advisor
-drives the plan and answers the executors when they get stuck.
+execution: the code edits, the build runs, the test runs. The orchestrating
+session drives the plan and routes hard decisions to the shared advisor
+(Claude: warm `session-advisor`; Grok: this session self-as-advisor).
 
 ## Gotchas
 
@@ -46,10 +38,12 @@ drives the plan and answers the executors when they get stuck.
   in the same session schedules a second refresh loop. Check whether the loop
   is already running before you schedule one (see the invocation guard in
   Process step 1).
-- **The advisor never executes.** The moment it edits a file or runs the tests
-  itself, the pairing breaks and the executor's warm context is wasted. Hand
-  every code edit and every build or test run to an executor; keep the
-  advisor's own tool use to orchestration and light verification reads.
+- **The orchestrating session never executes.** The moment it edits a file or
+  runs the tests itself, the pairing breaks and the executor's warm context is
+  wasted. Hand every code edit and every build or test run to an executor; keep
+  the orchestrating session's own tool use to orchestration and light
+  verification reads. Hard decisions go to the shared advisor (Claude:
+  `session-advisor` via SendMessage; Grok: this session inline).
 - **Flat ad hoc spawns bypass routing.** Every execution task goes through a
   workflow-backed spawn or workflow resume so the required agent type, model,
   prompt packet, and sidecar metadata stay attached to the work.
@@ -59,16 +53,16 @@ drives the plan and answers the executors when they get stuck.
 - **Resuming an unnamed background agent needs its agentId.** A background
   spawn returns an `agentId` (format `a...-...`); keep it so `SendMessage` can
   reach that agent later. A named agent is reachable by name.
-- **Consultations past the cap signal a scoping problem.** When five
-  consultations do not clear the blocker, the task needs re-scoping or a
-  hand-off to the user — not a sixth round of advice.
-
+- **Only the orchestrating session owns the shared advisor's lifecycle.** An
+  executor that finds the advisor unreachable (Claude warm agent, or this
+  session on Grok) reports that upward; it never spawns a replacement itself.
 
 ## Process
 
 1. **Check whether the refresh loop is already running this
-   session. If it is, skip straight to orchestration — do not schedule a
-   second loop.
+   session.** If it is, do not schedule a second loop. Reuse any live
+   shared advisor bind (Claude warm `session-advisor`, or Grok self-bind —
+   run step 3 only when none exists yet), then skip straight to step 4.
 
 2. **Register the discipline reminder.** By default, schedule it with
    `ScheduleWakeup` at `delaySeconds: 1200`, prompt `/orchestrator-refresh`,
@@ -79,11 +73,48 @@ drives the plan and answers the executors when they get stuck.
    enforcement surface: each firing re-asserts the discipline while the run is
    in flight.
 
-3. **Orchestrate the task.** Hold the plan and the user conversation. Execute
+3. **Bind the shared advisor before any executor.** Detect the host profile
+   first (see Host profiles in
+   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)).
+   On a **Claude host**, follow the Warm-up procedure in that doc (Agent spawn
+   of `session-advisor`). Compute the model floor as the max of the
+   orchestrating session's own tier and the highest model in the Workflow Agent
+   Routing table below (today: max(Sonnet, Opus) = Opus). Paste the **Claude
+   host** Advisor block from that doc, with the resolved agent name filled in,
+   into every executor's spawn prompt. On a **Grok host**, skip that spawn —
+   use the protocol's self-as-advisor path (this session *is* the advisor;
+   single tier `Grok`, attempt result `self`). Paste the **Grok host** Advisor
+   block from that doc into every executor's spawn prompt — never the Claude
+   SendMessage block. Every row in the routing table is a consumer of the
+   shared advisor, not just this session. The orchestrating session owns the
+   shared advisor's lifecycle end to end (spawn or self-bind, drift handling
+   per the shared doc, shutdown at task end); executors only ever SendMessage
+   the warm agent (Claude) or report to this session (Grok).
+
+4. **Orchestrate the task.** Hold the plan and the user conversation. Execute
    workflow-backed spawns or resumes using the routing table below, and keep
-   driving while they work. Your own tool use stays orchestration and light
+   driving while they work. Every executor spawn includes the host-matched
+   Advisor block from step 3. Your own tool use stays orchestration and light
    verification reads. Keep your task list updated religiously.
 
+5. **Consult the shared advisor at hard decisions.** Every consumer — each
+   executor and this session — consults when one of these holds (same list as
+   the protocol and Advisor block):
+   - A nontrivial plan is about to be locked in and acted on.
+   - The consumer believes its assigned work is finished.
+   - A commit, push, or other hard-to-reverse action is about to run.
+   - The same failure has come back more than once, or progress has stalled.
+   - The chosen approach is being reconsidered.
+
+   **Claude host:** consult the shared `session-advisor` via `SendMessage`.
+   **Grok host:** executors report to this orchestrating session; this session
+   answers the four signals inline (self-as-advisor — no Agent, no
+   SendMessage-to-`session-advisor`). Every consult gets back one of four
+   signals (ENDORSE, CORRECTION, PLAN, or STOP). See
+   `agents/session-advisor.md` for what each signal means and
+   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
+   for the consult format.
+
 ## Workflow Agent Routing
 
 Every delegated task runs through a workflow-backed agent invocation. Do not
@@ -93,11 +124,10 @@ available.
 | Work | Agent type | Model |
 |---|---|---|
 | Feature, bug, and refactor coding | `clean-coder` | `opus` |
-| Verification passes | `code-verifier` | `opus` |
+| Verification passes | `code-verifier` | `sonnet` |
 | Script runs, GitHub posting, and backfill driving | `general-purpose` runner | `sonnet` |
-| PR descriptions | `pr-description-writer` | `sonnet`, with file-list grounding check |
+| PR descriptions | `pr-description-writer` | `haiku`, with file-list grounding check |
 | Fan-out searches and checklist verification reads | `Explore` | `haiku`; use `sonnet` when judgment-heavy |
-| Escalated blockers needing a second opinion beyond the orchestrator's own judgment | `code-advisor` | Fable preferred (matches the orchestrating session); opus if Fable is unavailable. |
 
 Routing rules:
 
@@ -114,45 +144,6 @@ Routing rules:
 - Exploration workflows return file paths, line numbers, and direct evidence;
   they do not write code or mutate repo state.
 
-4. **Executors consult at a hard decision.** Each executor's spawn prompt tells
-   it to stop and message you — with the task, what it tried, and the exact
-   blocker (plus any short code excerpt that helps) — when one of these holds:
-   - It has tried the same problem twice or more and it still fails.
-   - A decision changes the deliverable's scope or a contract that is hard to
-     reverse.
-   - Two constraints conflict and it cannot satisfy both.
-   - It is unsure whether to stop or keep going.
-
-5. **Answer with one signal.** On a consultation, reply with exactly one
-   signal, brief (about 400 to 700 tokens):
-   - **PLAN** — a different approach, as concrete ordered steps the executor
-     can run. When a warm agent fits the plan, name which one to resume.
-   - **CORRECTION** — the executor's approach is right, one thing is wrong;
-     name the wrong step and the fix.
-   - **STOP** — no path satisfies the task as assigned; say why so it can be
-     reported upward.
-   The executor resumes the moment your reply lands.
-
-   A worked consultation:
-
-   ```
-   Executor → advisor
-   Task: add a retry to the upload client.
-   Tried: wrapped upload() in a three-attempt loop; the second attempt
-   double-posts.
-   Blocker: the server takes no idempotency key, so a retry after a timeout
-   creates a duplicate record.
-
-   Advisor → executor
-   CORRECTION — the retry loop is right; the missing piece is a stable request
-   id. Generate one client-side on the first attempt and send the same id on
-   every retry, so the server treats the retries as one request.
-   ```
-
-   For a decision the advisor itself cannot settle, it may use a workflow
-   escalation to the tool-less `code-advisor` agent for a second opinion — an
-   optional escalation, not a required step.
-
 ## Agent reuse (non-negotiable)
 
 - **Resume before you spawn, always.** A warm agent carries its context and
@@ -162,27 +153,32 @@ Routing rules:
   matches the routing table.
 - **Spawn a fresh agent only when** no existing agent holds relevant context,
   or a genuine task switch needs a clean context.
-- **Name the agent to resume.** When you answer with a PLAN and a warm agent
-  fits, say which agent to resume and where.
+- **Name the agent to resume.** When a PLAN from the shared advisor fits a warm
+  agent, name which agent to resume and where.
 
 ## Constraints
 
 - One `/orchestrator` per session; the invocation guard blocks a second
   reminder loop.
-- The advisor orchestrates and advises but never edits code or runs a build or
-  test itself — executors do that.
+- The orchestrating session orchestrates and routes hard decisions to the
+  shared advisor (host-matched path in step 5), but never edits code or runs a
+  build or test itself — executors do that.
 - Delegated execution uses workflow-backed agent invocations and follows the
   Workflow Agent Routing table exactly.
-- Consultations are capped at five per task by default. At the cap, re-scope
-  or hand off; do not keep answering.
+- One shared advisor per orchestrated session, owned by the orchestrating
+  session (see
+  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md))
+  — on Claude, executors consult a warm `session-advisor` via SendMessage; on
+  Grok, this session is the advisor and executors report here. Executors never
+  spawn or respawn the advisor.
 - Reuse a warm agent over a cold spawn whenever one holds relevant context.
 
 ## File Index
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Advisor strategy, workflow routing contract, consultation protocol, reuse rules, and constraints. |
+| `SKILL.md` | Orchestrator strategy, workflow routing contract, shared-advisor consult protocol, reuse rules, and constraints. |
 
 ## Folder Map
 
-- `SKILL.md` — complete advisor workflow instructions.
+- `SKILL.md` — complete orchestrator workflow instructions.

package/skills/orchestrator-refresh/SKILL.md

@@ -2,22 +2,34 @@
 name: orchestrator-refresh
 description: >-
   Fired by the /orchestrator loop reminder about every 20 minutes to
-  re-assert the advisor discipline mid-run. A compressed restatement of
-  /orchestrator: orchestrate rather than execute, answer a blocked executor
-  with a plan, correction, or stop, and reuse warm agents before spawning new
-  ones. Triggers: '/orchestrator-refresh'.
+  re-assert the advisor discipline mid-run: orchestrate, route hard decisions
+  to the shared advisor (ENDORSE / CORRECTION / PLAN / STOP — SendMessage on
+  Claude, self-as-advisor on Grok), reuse warm agents. Triggers:
+  '/orchestrator-refresh'.
 ---
 
 # Orchestrator Refresh
 
-1. **You are the advisor.** Orchestrate and hold the user conversation; spawn
-   executor subagents to do all the work — every code edit and build or test
-   run.
-2. **An executor blocked twice on the same thing?** Answer it with one signal
-   — a plan, a correction, or a stop — brief. Never take over the edit or the
-   tests yourself.
-3. **Resume before you spawn.** `SendMessage` an existing agent by name or
-   `agentId` to reuse its warm context; prefer that over a cold spawn.
+Detect the host profile first (see Host profiles in
+[`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)).
+Re-assert the discipline for that host only — do not invent a Claude
+`session-advisor` spawn on a Grok host.
+
+1. **You are the advisor-orchestrator.** Orchestrate and hold the user
+   conversation; spawn executor subagents to do all the work — every code edit
+   and build or test run.
+2. **Hard decisions go to the shared advisor.**
+   - **Claude host:** executors consult the warm `session-advisor` via
+     `SendMessage` and receive one of four signals — ENDORSE, CORRECTION, PLAN,
+     or STOP. The orchestrating session routes its own hard decisions the same
+     way and keeps its tool use to orchestration and light verification reads.
+   - **Grok host:** this session *is* the advisor (self-as-advisor). Do **not**
+     spawn `session-advisor` and do **not** tell executors to SendMessage a
+     separate advisor agent. Executors report blockers to this session; answer
+     with ENDORSE / CORRECTION / PLAN / STOP inline.
+3. **Resume before you spawn.** `SendMessage` an existing *executor* agent by
+   name or `agentId` to reuse its warm context; prefer that over a cold spawn.
+   (On Grok this is executor reuse only — not an advisor spawn.)
 4. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
    subagent's context, so a clean context comes from a fresh spawn — never tell
    an agent to compact.

package/skills/post-audit-findings/SKILL.md

@@ -1,15 +1,11 @@
 ---
 name: post-audit-findings
 description: >-
-  Publishes an audit pass as one GitHub PR review via the shared
-  post_audit_thread.py: maps audit findings to the {path, line, side,
-  severity, description, fix_summary} JSON shape (splitting failure_mode at
-  the literal `Fix:` heading), partitions anchored vs unanchored findings so
-  one bad anchor cannot reject the whole POST, handles the self-PR reviewer
-  toggle via BUGTEAM_REVIEWER_ACCOUNT, and harvests finding comment ids and
-  PRRT thread node ids for the fix loop. Invoked by audit skills (bugteam,
-  qbug, findbugs) after each audit pass, CLEAN or DIRTY; not for ad-hoc PR
-  comments or review replies.
+  Publishes an audit pass as a GitHub PR review through post_audit_thread.py:
+  maps findings to the review-comment JSON shape, splits anchored from
+  unanchored, and collects the comment and thread ids for the fix loop. Invoked
+  by audit skills (bugteam, qbug, findbugs) after each pass; not for ad-hoc
+  comments.
 ---
 
 # Post Audit Findings

package/skills/pr-consistency-audit/SKILL.md

@@ -1,7 +1,11 @@
 ---
 name: pr-consistency-audit
 description: >-
-  Audits a PR for cross-file inconsistencies. Finds wrong argument names, missing required args, references to files or scripts that do not exist, stale feature remnants, docstring-vs-implementation mismatches, placeholder text, cross-file contradictions, parameter naming convention violations, and cross-platform bugs. Use when the user says "audit this PR", "find inconsistencies", "cross-reference docs against scripts", "check for stale references", "PR consistency audit".
+  Audits a PR for cross-file inconsistencies: wrong arguments, missing files or
+  scripts, stale remnants, docstring mismatches, and cross-platform bugs. Use
+  when the user says 'audit this PR', 'find inconsistencies', 'cross-reference
+  docs against scripts', 'check for stale references', or 'PR consistency
+  audit'.
 ---
 
 # PR Consistency Audit

package/skills/pr-converge/CLAUDE.md

@@ -1,6 +1,6 @@
 # pr-converge skill
 
-Drives a draft PR to convergence by looping Cursor Bugbot, a code-review pass, a second-opinion bug audit (`bugteam`), and Copilot — applying TDD fixes, posting inline replies, and re-triggering reviewers each tick until all reviewers are clean on the same HEAD and the PR is mergeable.
+Drives a draft PR to convergence by driving the internal passes to clean first — a code-review pass and a bugteam audit — then running Cursor Bugbot and Copilot as terminal confirmation gates, applying TDD fixes, posting inline replies, and re-triggering the external reviewers each tick until all are clean on the same HEAD and the PR is mergeable.
 
 **Trigger:** `/pr-converge`, "drive PR to convergence", "loop bugbot and bugteam", "babysit bugbot and bugteam", "until both are clean", "converge this PR".