claude-dev-env 1.93.0 → 1.94.0

package/skills/grokify/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: grokify
+description: >-
+  Grok Build execution handoff prompt, embed Claude advisor.
+---
+
+# Grokify
+
+## Principle
+
+One paste-ready handoff turns this session's work into a plan a Grok Build session can execute alone. Grok gets no access to this conversation, so the handoff carries everything: repos, findings, constraints, the phased plan, and a Claude advisor Grok reaches through the `claude` CLI.
+
+## Gotchas
+
+- Grok Build cannot spawn Claude subagents. The advisor is an out-of-process `claude -p` session — never write Agent-tool, `session-advisor`, or SendMessage instructions into the handoff.
+- A `--resume` after a usage-limit failover to another binary fails, because a session store belongs to the binary that minted it. The handoff must tell Grok to treat that failure as starting over: re-send the charter plus a compact recap, capture the new `session_id`.
+- Conversation-relative phrases ("as discussed", "the plan above", "the earlier choice") are dead text to Grok — every statement stands on its own.
+- Copy findings' measured numbers and `file:line` citations into the handoff exactly, and label each figure measured, bounded, or unverified.
+- The advisor session starts empty. The bind step must pipe the findings, constraints, and plan into the charter, or every later consult is answered from nothing.
+- `claude` sessions are project-scoped by working directory. The handoff must tell Grok to run every bind and every `--resume` with the cwd set to the repo root it names — a bind launched from the Grok sandbox cwd files the session under that other project, and a later resume from the real worktree reports `No conversation found with session ID`. Treat a session-not-found error as a wrong-cwd or expired-session signal, not a model failure.
+- `--output-format json` returns a JSON array of events, not one object. `session_id` comes from any event; the reply text is the `type == "result"` event's `.result` field. A parser expecting one top-level object reports a missing session id on a working bind.
+- The charter travels as a file piped to stdin, or as one clean argv string. Half-escaped multiline shell expansion mangles the prompt in transit and the advisor sees a fragment.
+
+## When this applies
+
+The user types `/grokify`, alone or with guidance.
+
+- Bare `/grokify`: build the handoff from the current session's context — the task in flight, its findings, plan, and constraints.
+- `/grokify <guidance>`: the guidance names or scopes the task — a plan written earlier in the session, a file to read, or a fresh instruction. Build the handoff for that.
+
+**Refusal:** no session context and no guidance — reply `What should Grok execute? One sentence.` and stop.
+
+## Process
+
+1. Collect the substance: repos and branch, established findings with `file:line` and measured numbers, hard constraints, and the phased plan with acceptance criteria. Pull from session context first, then from the guidance; read any files the guidance names.
+2. Fill `templates/handoff-template.md`. Adapt every bracketed section to the task; keep the advisor CLI commands, signal rules, and consult cadence exactly as the template writes them.
+3. Mark any decision that belongs to the user as an explicit ask-the-user fork inside the plan. The handoff never lets Grok pick silently.
+4. Deliver one fenced markdown block (four-backtick fence, so inner fences survive), then one or two sentences naming the choices you baked in.
+
+## Fixed advisor structure (never vary these parts)
+
+- **Bind once, first:** charter + findings + constraints + plan piped from a temp file into `claude -p --model fable --effort high --output-format json`; parse and save `session_id` from the JSON reply.
+- **Consult:** brief piped into `claude -p --resume <session_id> --model fable --effort high --output-format json`.
+- **ConsultB** If fable is unavailable, use opus with max effort: `claude -p --resume <session_id> --model opus --effort max --output-format json`.
+- **Signals:** every advisor reply opens with exactly one of ENDORSE, CORRECTION, PLAN, or STOP. CORRECTION and PLAN are actions to take, with a report-back in the next consult on that topic. STOP halts that line of work and surfaces it to the user. When the CLI is unreachable, Grok stops and says so — it never self-endorses in the advisor's place.
+- **Cadence, mandatory:** after planning and before any edit; per phase before implementation (TDD red + approach) and after (diff, tests, acceptance evidence); before every `git commit` and `git push`; on every user-facing fork before asking; on any twice-repeated failure or stall.
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Trigger, process, fixed advisor structure. |
+| `templates/handoff-template.md` | Section-by-section skeleton of the handoff prompt. |
+
+## Folder map
+
+- `SKILL.md` — the whole workflow.
+- `templates/` — the handoff skeleton.

package/skills/grokify/templates/handoff-template.md

@@ -0,0 +1,92 @@
+# Handoff template
+
+Fill every `[bracketed]` part from the session. Keep the advisor sections word-for-word except the charter's mission sentences.
+
+````markdown
+# Execution Handoff (Grok Build): [task title]
+
+You are Grok, executing this plan yourself on Grok Build. You write the code, run the
+tests, and run the checks. You do NOT decide alone: a standing Claude advisor (Fable High
+tier, or Opus MAX if Fable is unavailable, reached via CLI) reviews every significant step at the cadence below.
+
+## Repos and branch
+
+- [repo, working-tree path, and the branch to develop on; push and PR rules]
+- [any read-only sibling repos and what they are for]
+
+## Established findings (treat as settled)
+
+[Each finding on its own bullet with file:line citations and measured numbers, each
+labeled measured, bounded, or unverified. Include refuted hypotheses so Grok does not
+re-fix them.]
+
+## Hard constraints
+
+[Non-negotiables: values that stay fixed, behavior that stays, repo conventions
+(commit style, test-first rules, where constants live), anything out of scope.
+CONFIRM THESE WITH THE USER FIRST, VIA ASKUSERQUESTION, BEFORE EMBEDDING]
+
+## The advisor: Claude Fable High / Opus MAX via CLI (bind FIRST, before any change)
+
+**Bind (once, at run start):**
+0. `cd` to the repo root named under Repos and branch — and do the same before every
+   later consult. `claude` sessions are project-scoped by working directory; a bind
+   or resume run from any other cwd (your sandbox, a temp dir) files the session
+   under a different project and later resumes report "No conversation found".
+1. Write the charter to a temp file. Charter text: "You are the standing advisor for a
+   Grok executor working on [one-sentence mission]. You never edit files or run
+   commands; you only answer. Open every reply with exactly one signal word: ENDORSE,
+   CORRECTION, PLAN, or STOP. Each consult brings the delta since the last consult
+   (real output, never a full recap), the live decision or blocker, and load-bearing
+   paths or excerpts. If a consult re-raises something you already answered with
+   nothing new attached, restate the prior answer and name it a restatement." Then
+   append the full Established findings, Hard constraints, and Plan sections of this
+   document to the same file.
+2. Bind: `claude -p --model fable --effort high --output-format json < <charter-file>`
+2a. If 2 fails, replace fable with opus, effort high to max.
+3. The JSON output is an array of events, not one object. Take `session_id` from any
+   event; the reply text is the `type == "result"` event's `.result` field. Persist
+   `session_id`, the repo root, and the cwd to a state file at once.
+4. If the primary `claude` binary is usage-limited, fall back through
+   `python "$HOME/.claude/scripts/claude_chain_runner.py" -- -p --model fable --effort high --output-format json`.
+   A failover does NOT carry the session_id. On ANY resume failure — failover,
+   session-not-found, expiry — first confirm the cwd is the repo root, then re-bind
+   once from there with the charter plus a three-line recap of consults so far, and
+   persist the new session_id. A session-not-found error is a wrong-cwd or expired
+   session, not a model failure.
+
+**Consult (every time):** write the brief to a temp file, then
+`claude -p --resume <session_id> --model fable (or opus) --effort high (max for opus) --output-format json < <brief-file>`.
+Act on the reply's opening signal: ENDORSE — proceed. CORRECTION — apply it first;
+your next consult on that topic opens with what happened. PLAN — adopt it; same
+report-back rule. STOP — halt that line of work and surface it to the user. Never
+proceed past a mandatory checkpoint on an unread or unanswered consult; if the CLI
+and its fallback both fail, stop and tell the user rather than self-endorsing.
+
+**Mandatory consult cadence:**
+1. After binding, before touching any file: your concrete per-phase execution plan.
+2. Per phase, BEFORE implementation: the failing tests you wrote and your approach.
+3. Per phase, AFTER implementation: diff summary, test results, acceptance evidence.
+4. Before EVERY `git commit` and EVERY `git push`.
+5. On any user-facing fork: your proposed framing, before asking the user.
+6. Any time the same failure repeats twice, progress stalls, or you reconsider an
+   approach.
+
+## Plan
+
+[Numbered phases. Each phase: what to change (with paths), how to prove it worked
+(acceptance criteria with commands or counts), and its blast radius. A decision that
+belongs to the user is its own phase, marked USER DECISION — never pick silently. End
+with a verify-and-land phase: re-run the baseline check, gates green, advisor ENDORSE,
+then commit and push.]
+
+## Execution discipline
+
+- Track each phase as an explicit task; mark it complete only when its acceptance
+  evidence exists and the advisor has seen it.
+- Every progress claim rests on command output from this run; label anything
+  unverified as unverified.
+- Keep a consult log (checkpoint, signal received) and include it in the final report.
+- Final message: outcome first (evidence, phases landed, commits pushed), then the
+  decisions taken, then honest gaps.
+````

package/skills/orchestrator/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: orchestrator
 description: >-
-  Advisor-orchestrator mode: plan and delegate while workflow-backed agents
+  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',
@@ -24,7 +24,7 @@ than a solo frontier agent held to the same verification rigor, with
 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
+is the 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
@@ -79,12 +79,16 @@ session drives the plan and routes hard decisions to the shared advisor
    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
+   Routing table below (for example, max(Sonnet, Opus) = Opus when those are
+   the tiers in play). That floor is a lower bound only — the Claude spawn walk
+   tries top-down from Fable down to that floor per
+   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md);
+   it is not a "spawn only at the floor" rule. 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

package/skills/orchestrator-refresh/SKILL.md

@@ -15,9 +15,9 @@ Detect the host profile first (see Host profiles in
 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.
+1. **You are the 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,