claude-dev-env 1.92.0 → 1.93.0

package/skills/pr-loop-lifecycle/SKILL.md

@@ -1,15 +1,11 @@
 ---
 name: pr-loop-lifecycle
 description: >-
-  Opens and closes a PR-loop run: the .claude/** permission grant (with the
-  auto-mode AskUserQuestion escalation when the classifier blocks it),
-  worktree preflight and cwd routing, then the ordered close — conditional
-  TeamDelete for team callers, worktree teardown, working-tree clean, PR
-  description rewrite composed by the lead, the always-run permission
-  revoke, and the caller-parameterized final report. Invoked by PR-loop
-  orchestrators (bugteam, pr-converge, autoconverge, qbug) at run start and
-  run end, including error exits; not for general git cleanup or permission
-  management outside a PR loop.
+  Opens and closes a PR-loop run: the .claude/** permission grant, worktree
+  preflight, and cwd routing at the start; teardown, permission revoke, and
+  final report at the end. Invoked by PR-loop orchestrators (bugteam,
+  pr-converge, autoconverge, qbug); not for general git cleanup outside a PR
+  loop.
 ---
 
 # PR Loop Lifecycle

package/skills/pr-scope-resolve/SKILL.md

@@ -2,12 +2,9 @@
 name: pr-scope-resolve
 description: >-
   Resolves the audit/fix target for a PR-loop skill: owner, repo, PR number,
-  head ref, base ref, PR URL, and starting head SHA — via
-  pull_request_read(method="get"), a search_pull_requests branch fallback, then a
-  git merge-base upstream-diff fallback, ending in the canonical refusal line
-  when no target exists. Invoked by PR-loop orchestrators (pr-converge,
-  bugteam, qbug, findbugs, fixbugs) as their first step; not for general git
-  questions or branch management.
+  head and base refs, PR URL, and head SHA, with a canonical refusal when no
+  target exists. Invoked by PR-loop orchestrators (pr-converge, bugteam, qbug,
+  findbugs, fixbugs) first; not for general git questions.
 ---
 
 # PR Scope Resolve

package/skills/privacy-hygiene/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: privacy-hygiene
+description: Full-repo sweep for personal data and secrets before commit or durable GitHub post. Use when preparing a PR, cleaning a leak, or when `pii_prevention_blocker` denies a write, post, or commit. Triggers on "privacy hygiene", "personal data", "secret sweep", "sanitize repository", "/privacy-hygiene".
+---
+
+# privacy-hygiene
+
+## Overview
+
+Find and remove personal data and high-confidence secrets before they land in git history or a durable GitHub post. The `pii_prevention_blocker` hook blocks the common cases at write, post, and commit time. This skill is the full sweep when you need a broader pass or a remediation plan.
+
+**Announce at start:** "Running privacy-hygiene sweep."
+
+## When to run a full sweep
+
+- Before the first push of a branch that touched logs, screenshots, config samples, or machine-local paths
+- After a hook block on email, home path, LAN address, or secret material
+- Before opening a PR to a repository that is public (or will be made public)
+- After pasting support tickets, env dumps, or terminal transcripts into the tree
+
+## What the automated gate blocks
+
+| Category | Blocked examples | Allowed residual |
+|---|---|---|
+| Email | `person@company.io` | `user@example.com`, `user@example.org`, `user@example.net` |
+| Home path | `C:/Users/realname/...`, `/Users/realname/...`, `/home/realname/...` | `C:/Users/example/...`, `C:/Users/<you>/...`, `/Users/alice/...` |
+| LAN address | Unlisted `10.x` / `172.16–31.x` / `192.168.x` | Public addresses; product NAS `192.168.1.100`; other entries in `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` |
+| Secret | `ghp_…`, `github_pat_…`, `AKIA…`, PEM private-key headers | Public keys, redacted `***`, env var names without values |
+
+Surfaces:
+
+1. **Write / Edit / MultiEdit** — payload text about to land on disk (via PreToolUse dispatcher)
+2. **Durable posts** — `gh pr/issue create|comment|edit|review` bodies and GitHub MCP body/comment fields (Bash and PowerShell)
+3. **git commit** — staged blob text (non-exempt paths) on Bash and PowerShell, including `git.exe` and flag forms (`--no-verify`, `-c`, `-C`). Commit message bodies (`-m` / `-F`) are out of scope for the automated gate
+
+## Sweep procedure
+
+### 1. Scope the tree
+
+```
+git status -sb
+git diff --stat
+git diff --cached --stat
+```
+
+Prefer the branch diff vs `origin/main` for PR prep:
+
+```
+git fetch origin main
+git diff --name-only origin/main...HEAD
+```
+
+### 2. Search for high-confidence patterns
+
+Run from the repo root (PowerShell-friendly example):
+
+```
+rg -n --hidden -g '!node_modules' -g '!.git' -e '@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' -e 'Users[/\\][^/\\]+' -e '/home/[^/]+' -e '\b(10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[0-1])\.\d+\.\d+)\b' -e '\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b' -e '\bgithub_pat_[A-Za-z0-9_]{20,}\b' -e '\bAKIA[0-9A-Z]{16}\b' -e '-----BEGIN [A-Z ]*PRIVATE KEY-----'
+```
+
+Review each hit. Ignore:
+
+- Test fixtures under `test_*.py` / `*_test.py` / `/tests/` (synthetic only)
+- `LICENSE` / copyright notice identity that is intentional and public
+- This package's own `pii_scanner` / `pii_prevention_constants` modules
+- Documented placeholders (`user@example.com`, `C:/Users/<you>/`)
+
+### 3. Remediate
+
+| Hit | Fix |
+|---|---|
+| Real email | Replace with `user@example.com` or remove |
+| Home path | Use `Path.home()`, `~`, or `C:/Users/<you>/` |
+| LAN address | Remove, use a hostname, or add to `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` only when tooling requires it |
+| Credential material | Remove from the tree; rotate the credential; load from env/secret store |
+| Already committed | Rewrite is not enough if already pushed — rotate secrets; scrub history only with explicit user approval |
+
+### 4. Re-check before commit / post
+
+- Stage only clean files
+- Prefer `--body-file` for `gh` posts (also required by the gh-body-file rule)
+- Let `pii_prevention_blocker` re-run on the next Write / commit / post
+
+## Accepted residual (do not over-scrub)
+
+- LICENSE copyright lines naming a legal person or org that owns the work
+- Intentional public maintainer identity published on purpose
+- Example domains reserved for documentation (`example.com` and siblings)
+- Placeholder home users (`example`, `user`, `alice`, `<you>`, `YOUR_USER`)
+- Product NAS host `192.168.1.100` (allowlisted for the NAS SSH rule/hook)
+- Public addresses and docs that name private ranges without a live host (still prefer hostnames)
+
+## Enable on any machine / public repository
+
+Install or reinstall the package so hooks and this skill land under `~/.claude/`:
+
+```
+cd packages/claude-dev-env
+node bin/install.mjs
+```
+
+Hooks register via `hooks/hooks.json` into `~/.claude/settings.json`. Once installed, the same gates apply in every repository the agent touches — private or public.
+
+## Open knobs
+
+- **NAS / LAN allowlist:** Unlisted private IPs are blocked. `192.168.1.100` is allowlisted for the NAS SSH enforcer. Add further hosts to `ALL_ALLOWLISTED_PRIVATE_IP_ADDRESSES` only when tooling requires them.
+- **Public maintainer identity:** when a real email or name is intentional product surface, keep it and note that in the PR body so reviewers do not treat it as a leak.
+
+## What this skill does not do
+
+- Does not rewrite git history without explicit user approval
+- Does not rotate credentials for you
+- Does not replace the write-time hook — it complements it
+- Does not scan commit-message text (`-m` / `-F`); keep messages free of secrets yourself

package/skills/qbug/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: qbug
 description: >-
-  Required baseline review for every new PR. Runs the /bugteam audit → fix →
-  commit → push cycle via one clean-coder subagent (not a full team), looping
-  until convergence or stuck. Uses the same CODE_RULES gate, A–P category
-  rubric, and per-loop PR review shape as /bugteam — without TeamCreate,
-  teammates, per-loop clean-room, or a loop cap. Invoke /bugteam instead for
-  larger PRs that need per-loop bias isolation or a hard loop cap. Triggers:
-  '/qbug', 'quick bug audit', 'solo bug audit', 'baseline PR review',
-  'bugteam without a team'.
+  Required baseline review for every new PR: runs the /bugteam audit, fix,
+  commit, and push cycle through one clean-coder subagent (not a full team),
+  looping until convergence or stuck. Triggers: '/qbug', 'quick bug audit',
+  'solo bug audit', 'baseline PR review', 'bugteam without a team'.
 ---
 
 # qbug
@@ -25,6 +21,10 @@ Shared artifacts with /bugteam are referenced below by path, using the `${CLAUDE
 - **Audit contract** (finding schema, proof-of-absence, adversarial pass, Haiku secondary, post-fix self-audit, diagnostics JSON): [`_shared/pr-loop/audit-contract.md`](../../_shared/pr-loop/audit-contract.md)
 - PR comment lifecycle shape: [`bugteam/SKILL.md`](../bugteam/SKILL.md#audit-posting)
 
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first and route every `gh` operation in this skill through its substitution matrix.
+
 ## When this skill applies
 
 `/qbug` once authorizes the full cycle (no loop cap — runs until `converged` or `stuck`; user can interrupt at any time).

package/skills/rebase/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: rebase
-description: Rebase a branch onto its base ref with the verification gates needed to catch logically broken results before pushing. Use when the user invokes `/rebase`, says "rebase this branch", "PR has merge conflicts", "rebase onto main", or asks for a force-push to update a remote branch's history. Critical for stacked PRs where the base merged via squash, and for any rebase that includes deletions or renames.
+description: >-
+  Rebases a branch onto its base ref with the verification gates that catch
+  logically broken results before pushing. Use when the user invokes `/rebase`,
+  says 'rebase this branch', 'PR has merge conflicts', or 'rebase onto main', or
+  asks for a force-push to update a remote branch's history.
 ---
 
 # /rebase

package/skills/refine/SKILL.md

@@ -1,11 +1,10 @@
 ---
 name: refine
 description: >-
-  Interview-driven plan refiner with built-in audit loop: fans out research agents,
-  interviews via AskUserQuestion (mandatory — survives no-question directives), writes
-  the plan to the Obsidian vault under Research/<topic>/<slug>.md, then loops audit and
-  fix until clean. Triggers: /refine, "refine this", "turn this into a plan", "flesh
-  this out", "make a spec for this", "let's plan this out", or any vague idea to mature
+  Interview-driven plan refiner: fans out research agents, interviews through
+  AskUserQuestion, writes to the Obsidian vault, then loops audit and fix.
+  Triggers: /refine, 'refine this', 'turn this into a plan', 'flesh this out',
+  'make a spec for this', 'let's plan this out', or any vague idea to mature
   into a plan.
 ---
 

package/skills/reviewer-gates/SKILL.md

@@ -1,16 +1,10 @@
 ---
 name: reviewer-gates
 description: >-
-  Runs the availability gates a PR-loop orchestrator checks before engaging an
-  external reviewer: the CLAUDE_REVIEWS_DISABLED opt-out parse (bugbot,
-  bugteam, and copilot tokens via reviews_disabled.py), the once-per-run
-  Copilot premium-quota pre-check (copilot_quota.py with copilot_down
-  semantics), and the Cursor Bugbot trigger/acknowledge/CI-detect flow
-  (check_bugbot_ci.py with the literal `bugbot run` comment). Invoked by
-  PR-loop orchestrators — pr-converge, autoconverge, bugteam, qbug, findbugs,
-  copilot-review, monitor-open-prs — at run start and at each reviewer
-  engagement point. Not a general code-review skill; it decides whether a
-  reviewer runs, never what the reviewer finds.
+  Runs the availability gates a PR-loop orchestrator checks before it starts an
+  external reviewer: the CLAUDE_REVIEWS_DISABLED opt-out, the once-per-run
+  Copilot quota pre-check, and the Cursor Bugbot trigger, acknowledge, and
+  CI-detect flow. Decides whether a reviewer runs, never what it finds.
 ---
 
 # Reviewer Gates
@@ -34,13 +28,15 @@ The `CLAUDE_REVIEWS_DISABLED` environment variable is a comma-separated token li
 | `bugbot` | Cursor Bugbot triggering and polling |
 | `copilot` | GitHub Copilot review requests and polling |
 
+Cursor Bugbot is off by default: it runs only when `CLAUDE_REVIEWS_ENABLED` lists `bugbot`, and a `bugbot` token in `CLAUDE_REVIEWS_DISABLED` keeps it off even when the opt-in lists it.
+
 Run the shared parser — never an inline shell parse:
 
 ```bash
 python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer <bugbot|bugteam|copilot>
 ```
 
-- **Exit 0** — the named reviewer is opted out. A skill whose whole run depends on that reviewer responds with its refusal line and stops. The template: `/<caller> is disabled via CLAUDE_REVIEWS_DISABLED.` A loop that merely includes the reviewer as one gate marks the reviewer down (`bugbot_down = true`, `copilot_down = true`) and continues on its remaining signals.
+- **Exit 0** — the named reviewer is disabled for this run (opted out, or, for Bugbot, off by default without the `CLAUDE_REVIEWS_ENABLED` opt-in). A skill whose whole run depends on that reviewer responds with its refusal line and stops. A copilot- or bugteam-dependent caller names the opt-out: `/<caller> is disabled via CLAUDE_REVIEWS_DISABLED.` A Bugbot-dependent caller off by default names the opt-in the run needs: `/<caller> is disabled: Cursor Bugbot needs a bugbot token in CLAUDE_REVIEWS_ENABLED.` A loop that merely includes the reviewer as one gate marks the reviewer down (`bugbot_down = true`, `copilot_down = true`) and continues on its remaining signals.
 - **Exit 1** — the reviewer is available; continue.
 
 ## Gate 2: Copilot quota pre-check (once per run)

package/skills/session-log/SKILL.md

@@ -1,7 +1,10 @@
 ---
 name: session-log
 description: >-
-  Log a session report by composing a self-contained HTML page and publishing it with the Artifact tool, then track vault context, extract unrecorded decisions, tidy the project's session folder, and output a /rename command. Use when the user says /session-log, journal this session, log this work, session report, or any variation of "summarize/log/record this session". Also triggers on "save session", "capture session", or "document what we did".
+  Logs a session report as an HTML page, tracks vault context, extracts
+  decisions, and outputs a /rename command. Use for /session-log, 'journal this
+  session', 'log this work', 'session report', 'summarize/log/record this
+  session', 'save session', 'capture session', or 'document what we did'.
 ---
 
 # Session Log

package/skills/skill-builder/SKILL.md

@@ -1,12 +1,9 @@
 ---
 name: skill-builder
 description: >-
-  Orchestrates the complete skill-building lifecycle using best-practice-driven
-  development. Routes through type classification, folder scaffolding, skill
-  writing (via skill-writer), self-audit against a 38-point checklist, and
-  iterative refinement from real usage observations. Use when creating new
-  skills, improving existing skills, or optimizing skill descriptions.
-  Triggers: 'build a skill', 'new skill workflow', 'improve this skill',
+  Runs the skill-building lifecycle: type classification, scaffolding, writing
+  through skill-writer, self-audit against a checklist, and refinement from real
+  usage. Triggers: 'build a skill', 'new skill workflow', 'improve this skill',
   'optimize skill description', 'skill development lifecycle'.
 ---
 

package/skills/structure-prompt/SKILL.md

@@ -1,11 +1,10 @@
 ---
 name: structure-prompt
 description: >-
-  Restructure a user-provided prompt: order blocks, replace persona framing with task
-  constraints, enforce per-category dispositions, expand placeholder tokens via the
-  sibling rubric or AskUserQuestion, add file:line citations, mark the canonical
-  sub-bucket, sharpen adversarial-pass phrasing. Triggers: /structure-prompt, "optimize
-  this prompt", "minimally invasive edit" to a prompt artifact, "tighten this prompt".
+  Restructures a user-provided prompt: orders blocks, swaps persona framing for
+  task constraints, expands placeholder tokens, and adds file:line citations.
+  Triggers: /structure-prompt, 'optimize this prompt', 'minimally invasive edit'
+  to a prompt artifact, or 'tighten this prompt'.
 ---
 
 # structure-prompt

package/skills/team-advisor/SKILL.md

@@ -1,188 +1,56 @@
 ---
 name: team-advisor
 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 /team-advisor-refresh loop. Adapts
-  Anthropic's coordinator pattern (plan big, execute small) to Claude Code.
-  Triggers: '/team-advisor', 'team advisor strategy', 'run with a team
-  advisor', 'executor-advisor mode', 'team advisor enforcement', 'agent
-  routing', 'orchestrate'.
+  Spawn one warm session-advisor at the strongest reachable tier and consult
+  it before big decisions, completion, commits, or when stuck. Triggers:
+  'team-advisor', 'team advisor', 'second opinion', 'advisor', 'consult',
+  'verify', 'validate', 'commit', 'push'.
 ---
 
-# Team Advisor Strategy
+# Team Advisor
 
 ## Principle
 
-A frontier model plans and synthesizes while cheap workers do the
-token-heavy reading and doing — Anthropic's coordinator pattern, source:
-https://github.com/anthropics/claude-cookbooks/blob/main/managed_agents/CMA_plan_big_execute_small.ipynb
-("Coordinator pattern: big models for planning, small models for
-execution"). On the cookbook's own measured run, a coordinator
-delegating to Sonnet-5 workers came out cheaper and faster
-than a solo frontier agent held to the same verification rigor, with
-84-98% of the team's input tokens billed at the worker rate.
+One warm, addressable advisor available at the strongest model tier the session can reach. The session sends concise briefs when a decision benefits from a second opinion: before acting on a plan, at completion, before commits, when stuck, when reconsidering the approach, or when an agent deems it necessary and beneficial to the user's goals.
 
-Claude Code has no `multiagent` coordinator field or Managed-Agents-style
-`create_agent`/`send_to_agent` primitives; this skill reaches the same
-shape with the tools Claude Code already has. Under this skill the session
-is the advisor-orchestrator. In Claude Code the user always talks to the session and never to a
-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.
+## Follow the shared protocol
 
-## Gotchas
+**Detect the host profile first** (Host profiles in
+[`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
+— e.g. `ADVISOR_HOST_PROFILE` or `GROK_BUILD`). Do not start a model-floor
+walk until the host is known.
 
-- **Double invocation duplicates the reminder loop.** A second `/team-advisor`
-  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.
-- **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.
-- **Wrong agent or model is an enforcement failure.** If a task category maps
-  to `clean-coder` on `opus`, a `general-purpose` Sonnet spawn is not a cost
-  optimization; it is the wrong executor for the contract.
-- **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.
+This session is the shared advisor's sole consumer, so its model floor is
+simply this session's own tier — no routing table to take a max against.
 
+**Claude host:** follow the shared protocol for the model-floor walk, the
+warm-up spawn and charter, the consult format and cadence, drift-respawn, and
+the CLI fallback — using `team-advisor-agent` as the name and this session as
+the only consumer (skip the "who you are and your assignment" opener in each
+consult; a single-consumer session doesn't need it).
 
-## 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.
-
-2. **Register the discipline reminder.** By default, schedule it with
-   `ScheduleWakeup` at `delaySeconds: 1200`, prompt `/team-advisor-refresh`,
-   where each refresh re-schedules the next one — a 1200-second wakeup costs
-   one prompt-cache miss per firing and nothing more (see Gotchas). The loop
-   mechanism (`/loop 20m /team-advisor-refresh`) is the escape hatch when
-   `ScheduleWakeup` is not available. Either way the reminder is the
-   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
-   workflow-backed spawns or resumes using the routing table below, and keep
-   driving while they work. Your own tool use stays orchestration and light
-   verification reads. Keep your task list updated religiously.
-
-## Workflow Agent Routing
-
-Every delegated task runs through a workflow-backed agent invocation. Do not
-spawn a flat subagent directly when a workflow invocation or workflow resume is
-available.
-
-| Work | Agent type | Model |
-|---|---|---|
-| Feature, bug, and refactor coding | `clean-coder` | `opus` |
-| Verification passes | `code-verifier` | `opus` |
-| Script runs, GitHub posting, and backfill driving | `general-purpose` runner | `sonnet` |
-| PR descriptions | `pr-description-writer` | `sonnet`, 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:
-
-- Use a workflow invocation or resume for each row above. The workflow prompt
-  must name the selected agent type, model, work category, task scope, and
-  expected output.
-- Resume a warm workflow agent before creating a new workflow run when the warm
-  agent holds the relevant context.
-- `clean-coder` owns code edits. `code-verifier` owns verification. The same
-  workflow agent never grades work it wrote.
-- PR-description workflows include the actual changed-file list in the prompt
-  and verify the final body against that file list before posting or returning
-  it.
-- 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
-  cached tokens; a fresh spawn starts cold and pays to rebuild both.
-  Resume the existing workflow agent by name or `agentId` when it holds
-  relevant context. Prefer that path every time an existing workflow agent
-  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.
+**Grok host:** use the self-as-advisor path in the shared protocol: this
+session answers ENDORSE / CORRECTION / PLAN / STOP itself. Do not spawn a
+Claude `session-advisor` subagent and do not walk the Claude multi-tier
+ladder.
 
 ## Constraints
 
-- One `/team-advisor` 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.
-- 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.
-- Reuse a warm agent over a cold spawn whenever one holds relevant context.
+- One `team-advisor-agent` per session, owned by this session for its whole
+  lifecycle (spawn, drift-respawn, shutdown) — see
+  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).
+- Never spawn the warm agent, or its CLI fallback, at a tier below this
+  session's own tier.
+- The warm agent (or its CLI equivalent) only answers. It never edits a
+  file, never runs a build or test, and never posts anything on the
+  session's behalf.
 
 ## File Index
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Advisor strategy, workflow routing contract, consultation protocol, reuse rules, and constraints. |
+| `SKILL.md` | Pointer to the shared advisor protocol; this session's consumer-specific wiring and constraints. |
 
 ## Folder Map
 
-- `SKILL.md` — complete advisor workflow instructions.
+- `SKILL.md` — complete team-advisor workflow instructions.

package/skills/test_markdown_link_integrity.py

@@ -1,9 +1,10 @@
-"""Link-integrity check for the skills tree and the shared pr-loop docs.
+"""Link-integrity check for the skills tree and shared protocol docs.
 
-Walks every markdown file under ``skills/`` and ``_shared/pr-loop/`` and
-resolves each relative markdown link target against the linking file's
-directory. A link whose target file or directory does not exist on disk is
-reported with its source file and line number, and the test fails.
+Walks every markdown file under ``skills/``, ``_shared/pr-loop/``, and
+``_shared/advisor/`` and resolves each relative markdown link target against
+the linking file's directory. A link whose target file or directory does not
+exist on disk is reported with its source file and line number, and the test
+fails.
 """
 
 from __future__ import annotations
@@ -14,6 +15,7 @@ from pathlib import Path
 
 SKILLS_ROOT = Path(__file__).parent
 SHARED_PR_LOOP_ROOT = SKILLS_ROOT.parent / "_shared" / "pr-loop"
+SHARED_ADVISOR_ROOT = SKILLS_ROOT.parent / "_shared" / "advisor"
 
 MARKDOWN_LINK_PATTERN = re.compile(r"\]\(([^)\s]+)\)")
 FENCE_MARKER = "```"
@@ -34,10 +36,12 @@ def _iter_markdown_files() -> list[Path]:
     """List every markdown file the integrity check covers.
 
     Returns:
-        All ``.md`` files under the skills tree and the shared pr-loop tree.
+        All ``.md`` files under the skills tree, the shared pr-loop tree, and
+        the shared advisor tree.
     """
     all_markdown_files = sorted(SKILLS_ROOT.rglob("*.md"))
     all_markdown_files.extend(sorted(SHARED_PR_LOOP_ROOT.rglob("*.md")))
+    all_markdown_files.extend(sorted(SHARED_ADVISOR_ROOT.rglob("*.md")))
     return all_markdown_files
 
 

package/skills/update/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: update
-description: Fast-forwards a local git repository's main branch to a remote's main, after confirming both the local repo path and the source remote through AskUserQuestion. Fetches the chosen remote, checks that the move is a true fast-forward (never a force, never a merge commit), and updates main whether or not main is the checked-out branch. When main is not the checked-out branch, it then offers to switch the checkout to main so the update reaches the files on disk. Use when the user says "/update", "update main", "fast-forward main", "sync main from origin", "pull latest main into <path>", or "bring main up to date". Triggers on "/update", "update main", "fast-forward main", "sync main".
+description: >-
+  Fast-forwards a local repository's main branch to a remote's main after
+  confirming the repo path and source remote through AskUserQuestion. Use when
+  the user says '/update', 'update main', 'fast-forward main', 'sync main from
+  origin', 'pull latest main into <path>', or 'bring main up to date'.
 ---
 
 # update

package/skills/usage-pause/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: usage-pause
-description: Waits out the account's 5-hour usage window in ScheduleWakeup stages that keep every agent context warm. Resolves the window's reset time and remaining headroom by probing the OAuth usage endpoint, or takes a manual override ('/usage-pause 10:20pm', '/usage-pause 74m'). Warns and stops when the weekly limit is near its cap. Each wakeup pings live and idle-warm agents with a one-line no-new-work checkpoint and records finished results; the final wakeup restores the crons the skill cancelled at pause time. Triggers: '/usage-pause', 'pause until the usage window resets', 'wait out the usage limit', 'usage limit pause'.
+description: >-
+  Waits out the account's 5-hour usage window in ScheduleWakeup stages that keep
+  every agent context warm. Accepts a manual override like '/usage-pause
+  10:20pm' or '/usage-pause 74m'. Triggers: '/usage-pause', 'pause until the
+  usage window resets', 'wait out the usage limit', 'usage limit pause'.
 argument-hint: "[reset time like 10:20pm | duration like 74m]"
 ---
 
@@ -39,16 +43,21 @@ On exit 2 the script prints `{"error": ...}`. Ask the user for a manual reset ti
 
 ### Probe mechanism
 
-The resolver reads the Claude Code CLI's OAuth access token from `~/.claude/.credentials.json` (`claudeAiOauth.accessToken`, honored only while its `expiresAt` sits in the future) and sends `GET https://api.anthropic.com/api/oauth/usage` with `Authorization: Bearer <token>` and `anthropic-beta: oauth-2025-04-20`. This is the same endpoint the interactive `/usage` panel reads. The response carries a `five_hour` bucket and a `seven_day` bucket, each with `utilization` (percent spent) and `resets_at`.
+The resolver gets a bearer token from one of two sources and sends `GET https://api.anthropic.com/api/oauth/usage` with `Authorization: Bearer <token>` and `anthropic-beta: oauth-2025-04-20`. This is the same endpoint the interactive `/usage` panel reads. The response carries a `five_hour` bucket and a `seven_day` bucket, each with `utilization` (percent spent) and `resets_at`.
 
-Fallbacks, in order: an expired or unreadable stored token, a failed request, or a response with no readable `five_hour` reset time all end in exit 2 — the manual-override ask above. The manual path works with no probe at all, so the skill functions even when the credential file is stale.
+Token sources, in order:
+
+- The Claude Code CLI's OAuth access token in `~/.claude/.credentials.json` (`claudeAiOauth.accessToken`, honored only while its `expiresAt` sits in the future).
+- The session ingress token in the file named by the `CLAUDE_SESSION_INGRESS_TOKEN_FILE` environment variable, read when the credential file token is unavailable. Claude Code cloud sessions set this variable and omit the credential file.
+
+Fallbacks, in order: no usable token from either source, a failed request, or a response with no readable `five_hour` reset time all end in exit 2 — the manual-override ask above. The manual path works with no probe at all, so the skill functions even when both token sources are stale.
 
 Why this probe and not the others:
 
 - The interactive `/usage` panel shows the same data but has no scriptable output.
 - `claude -p --output-format json` spends usage to answer and its metadata reports per-call token counts, not the account window clock.
 - `anthropic-ratelimit-*` response headers cover API-key Messages traffic, not the subscription session window, and reading them also costs a request.
-- Refreshing the OAuth token from a script is out of scope: token rotation would desync the refresh token the CLI has on disk and log the CLI out. The resolver only ever reads the credential file.
+- Refreshing the OAuth token from a script is out of scope: token rotation would desync the refresh token the CLI has on disk and log the CLI out. The resolver only ever reads its token sources.
 
 ## Weekly limit guard
 
@@ -101,7 +110,7 @@ Fill each `<slot>` at schedule time: `<remaining_stage_durations>` is the tail o
 | `SKILL.md` | This flow: resolve, weekly guard, stage chain, templates |
 | `scripts/resolve_usage_window.py` | The window resolver and stage planner CLI |
 | `scripts/test_resolve_usage_window.py` | Behavioral tests for parsing, staging, token reading, extraction, CLI |
-| `scripts/usage_pause_constants/resolve_usage_window_constants.py` | Endpoint, credential keys, stage sizing, thresholds, result keys |
+| `scripts/usage_pause_constants/resolve_usage_window_constants.py` | Endpoint, credential keys, the session ingress token env var, stage sizing, thresholds, result keys |
 
 ## Gotchas