claude-dev-env 2.28.1 → 2.29.0

package/.agents/skills/orchestrator/SKILL.md

@@ -2,10 +2,11 @@
 name: orchestrator
 description: >-
   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'.
+  execute; this session is the advisor those executors consult. Hard
+  questions this session cannot settle go to the human. Triggers:
+  '/orchestrator', 'orchestrator strategy', 'run with an orchestrator',
+  'executor-advisor mode', 'orchestrator enforcement', 'agent routing',
+  'orchestrate'.
 disable-model-invocation: true
 ---
 
@@ -26,7 +27,8 @@ Under this skill the session is the orchestrator. 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 orchestrating session drives the plan, keeps the run artifacts
-and the ledger current, and routes hard decisions to the shared advisor.
+and the ledger current, and answers executor consults. Hard questions
+this session cannot settle go to the human.
 The moment it edits a file or runs a test itself, the pairing breaks —
 its own tool use stays orchestration, run-artifact writes, and light
 verification reads.
@@ -115,47 +117,33 @@ pending, or when the tool is `CronCreate`.
 
 1. **Invocation guard.** One `/orchestrator` per session. When a refresh
    one-shot is already queued (`should-reschedule` exits 1 with
-   `rearm_already_pending`), do not stack a second: reuse the live
-   advisor bind, skip step 4 and the re-arm half of step 5, and carry on
-   from step 5's dispatch — status is already active and a re-arm is
-   already latched, so a second registration would stack a duplicate
-   host schedule. (Re-asserting `set --status active` preserves
-   `rearm_pending` when already active, but still do not re-arm.)
-2. **Bind the shared advisor before any executor.** Follow
-   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
-   end to end: name the session identity, compute the floor from the
-   orchestrator consumer set — this session plus every tier in the
-   routing table (its Model floor section) — walk the ladder for that
-   host (Claude: Fable first, then Sol when Fable is out of usage;
-   Codex: Sol in-session; ThirdParty: headless Fable then Sol),
-   and fail closed when nothing binds. This session owns the advisor's
-   whole lifecycle (its Lifecycle ownership section); executors only ever
-   message the warm agent or report here, and an executor that finds the
-   advisor unreachable reports that upward — it never spawns a
-   replacement itself. A **Fable**-tier attempt carries the exact token
-   `FABLE-SPAWN-AUTHORIZED` in its spawn prompt, as the protocol's
-   warm-up rule states; `hooks/blocking/fable_spawn_gate.py` denies a
-   fable spawn whose prompt lacks it.
-3. **Write the run artifacts** (next section) before the first spawn.
-4. **Activate status_gate** when the first open ledger task exists:
+   `rearm_already_pending`), do not stack a second: skip the re-arm
+   half of step 4, and carry on from step 4's dispatch — status is
+   already active and a re-arm is already latched, so a second
+   registration would stack a duplicate host schedule. (Re-asserting
+   `set --status active` preserves `rearm_pending` when already
+   active, but still do not re-arm.)
+2. **Write the run artifacts** (next section) before the first spawn.
+3. **Activate status_gate** when the first open ledger task exists:
    `python scripts/status_gate.py set --status active`.
-5. **Dispatch the first task with its ticket** (Spawn ticket section),
+4. **Dispatch the first task with its ticket** (Spawn ticket section),
    **then register the discipline reminder** via the single-pending
    re-arm protocol (cancel matching → `should-reschedule` → one
    non-recurring delayed wake → `claim-rearm`; default delay about
    2700s). Spawn before you arm, so the run is already moving, and go
-   straight on to step 6 in the same turn — the armed wake is a later
+   straight on to step 5 in the same turn — the armed wake is a later
    reminder, not the next thing to wait for.
-6. **Orchestrate.** Hold the plan and the user conversation. Spawn each
+5. **Orchestrate.** Hold the plan and the user conversation. Spawn each
    remaining task with a ticket (Spawn ticket section), keep driving while
    executors work, and keep the ledger reconciled (Task ledger
    discipline).
-7. **Consult the advisor at hard decisions.** The trigger list, consult
-   format, and reply handling live in the protocol's "Consulting the
-   warm agent" section; both this session and every executor are
-   consumers. Replies open with one of ENDORSE, CORRECTION, PLAN, or
-   STOP — `agents/session-advisor.md` defines each signal.
-8. **Terminate when done.** When every ledger task is completed or
+6. **Answer executor consults.** Executors consult this session. The
+   trigger list, consult format, and reply handling live in
+   [`reference/consult-the-orchestrator.md`](reference/consult-the-orchestrator.md).
+   Replies open with one of ENDORSE, CORRECTION, PLAN, or STOP. When
+   this session cannot settle a question, ask the human, then reply to
+   the executor.
+7. **Terminate when done.** When every ledger task is completed or
    cancelled and no executor is running: run
    `set --status done`, cancel matching host schedules, report
    completion, and stop. Do not re-arm.
@@ -165,8 +153,8 @@ pending, or when the tool is `CronCreate`.
 Write these before the first spawn, default home `docs/plans/<run-slug>/`
 in the repo the run works on (working files, not committed):
 
-- **Run charter** — the goal, the repo root, the advisor name and host
-  profile. One file every ticket points at.
+- **Run charter** — the goal, the repo root, this session's name as
+  advisor, and the host profile. One file every ticket points at.
 - **One assignment file per task** — scope, file list, constraints, the
   acceptance check, baseline command output. The thick context goes
   here. `/prompt-generator` authors the assignment once at plan time,
@@ -196,7 +184,7 @@ Touch only: <files or globs>
 Done when: <one mechanical check — a command, a test, a diff scope>
 Return: status, artifact paths, blockers — nothing else.
 
-<Advisor block assembled per _shared/advisor/reference/advisor-block.md — advisor name filled in>
+<Consult block assembled per reference/executor-consult-block.md — orchestrator name filled in>
 ```
 
 - **Size the task by its done-check.** The right task is the largest
@@ -219,11 +207,11 @@ Return: status, artifact paths, blockers — nothing else.
   slice of work and the done-check — it does not restate the assignment.
 - **Do not restate what the agent definition carries.** The routing
   table picks the definition, and `clean-coder` already holds the code
-  discipline. The ticket adds the task, the pointers, and the Advisor
+  discipline. The ticket adds the task, the pointers, and the consult
   block only.
-- **The Advisor block is pasted, assembled text.** Assemble it at bind
-  time from the parts in
-  [`_shared/advisor/reference/advisor-block.md`](../../_shared/advisor/reference/advisor-block.md)
+- **The consult block is pasted, assembled text.** Assemble it at ticket
+  write time from the parts in
+  [`reference/executor-consult-block.md`](reference/executor-consult-block.md)
   and paste the assembled text itself into the ticket.
 
 ## Workflow Agent Routing
@@ -263,9 +251,9 @@ Routing rules:
   only; a host where no resolver is available fails closed the same
   way — the coding spawn stops and the orchestrator reports it.
 - Host detection follows
-  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)
-  (Host profiles section, `resolve_session_identity` then
-  `detect_host_profile`) — the sole detection system, with no second one.
+  [`reference/host-detect.md`](reference/host-detect.md)
+  (`resolve_session_identity` then `detect_host_profile`) — the sole
+  detection system, with no second one.
 - Resume a warm workflow agent before creating a new workflow run when
   the warm agent holds the relevant context.
 - Review and verification workflows apply the [review guide](../reviews/SKILL.md#review-workflow).
@@ -290,7 +278,7 @@ Routing rules:
   context, or a genuine task switch needs a clean context.
 - **Reuse is a cost rule, not a correctness dependency.** The run
   artifacts keep every executor replaceable (Run state section).
-- **Name the agent to resume.** When a PLAN from the shared advisor fits
+- **Name the agent to resume.** When a PLAN from this session fits
   a warm agent, name which agent to resume and where.
 
 ## Task ledger discipline
@@ -325,8 +313,8 @@ no open work remains, run `set --status done` before any re-arm attempt.
   run-artifact writes, and light verification reads.
 - Every delegated task carries a ledger entry, an assignment artifact,
   and a workflow-backed spawn with a ticket, routed by the table.
-- One shared advisor per orchestrated session, owned by this session per
-  the protocol; executors never spawn, respawn, or shut it down.
+- This session is the advisor for every executor it spawns. The human
+  is this session's advisor.
 
 ## Gotchas
 
@@ -351,17 +339,20 @@ no open work remains, run `set --status done` before any re-arm attempt.
 | File | Purpose |
 |---|---|
 | `SKILL.md` | Orchestrator strategy; pointers to run-control scripts. |
+| `reference/consult-the-orchestrator.md` | When executors consult this session; four-signal replies. |
+| `reference/executor-consult-block.md` | Paste parts for every executor spawn ticket. |
+| `reference/host-detect.md` | Host profile for worker-model routing. |
 | `scripts/status_gate.py` | Status file, latch, and re-arm gate (exit codes). |
 | `scripts/status_gate_constants/config/constants.py` | Named constants for status_gate. |
 | `scripts/test_status_gate.py` | Gate tests. |
+| `test_orchestrator_skill_contract.py` | Skill-text contract: local consult files only. |
 
 ## Folder Map
 
 - `SKILL.md` — orchestration process and routing.
 - `scripts/` — deterministic status_gate.
-- Advisor policy:
-  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).
+- `reference/` — consult contract and ticket paste parts.
 
 ## File-backed run ledger
 
-When host task tools are absent, reconcile delegated work through `scripts/grok_run_ledger.py` under the run-state directory (stable task ids, one live owner, unique advisor sessions, dependency blocking, snapshot-drift reopening).
+When host task tools are absent, reconcile delegated work through `scripts/grok_run_ledger.py` under the run-state directory (stable task ids, one live owner, unique consult threads, dependency blocking, snapshot-drift reopening).

package/.agents/skills/orchestrator/reference/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

package/.agents/skills/orchestrator/reference/AGENTS.md

@@ -0,0 +1 @@
+

package/.agents/skills/orchestrator/reference/consult-the-orchestrator.md

@@ -0,0 +1,70 @@
+# Consult the orchestrator
+
+The orchestrating session is the advisor. The human operating that session is the next hop when the orchestrator cannot decide.
+
+## When an executor consults
+
+An executor sends a consult to the orchestrating session:
+
+- after orientation and before the first write
+- before locking a plan or interpretation
+- before a hard-to-reverse action
+- when the same failure repeats or progress has stalled
+- when the chosen approach is being reconsidered
+- once writes and test output exist and the executor believes the
+  assignment is done
+
+## First-consult packet
+
+The first consult is complete. It carries:
+
+- Assignment and desired outcome
+- Constraints and exclusions
+- Actions taken in order
+- Real output and current state
+- Live decision or blocker
+- Validation evidence
+- Unresolved risks
+- Load-bearing paths or excerpts
+- Who is asking and which assignment
+
+Later consults carry only changed evidence.
+
+Re-raise something already answered only when new evidence is attached.
+After a CORRECTION or PLAN, the next consult on that topic opens with
+what happened when the executor followed it.
+
+Embed: `(Advisor: please keep your guidance under 80 words — I need a
+focused starting point, not a comprehensive plan.)`
+
+## How the executor sends it
+
+On a Claude host, send the consult with `SendMessage` to the
+orchestrating session by the name the ticket gives.
+
+On a Codex host, send the consult in-session to that same session name.
+
+On a third-party host, send the consult as a report to the session that
+assigned the ticket.
+
+## How the orchestrator replies
+
+The first line is one of:
+
+- **ENDORSE** — the plan or the finished work holds. A clean yes.
+- **CORRECTION** — a wrong step or a risk to close. Name the problem and
+  the fix.
+- **PLAN** — the approach must change. Give ordered steps the executor
+  can run.
+- **STOP** — no path satisfies the assignment. Say why, with proof.
+
+The executor treats CORRECTION and PLAN as actions to take. On STOP, or
+when the orchestrator is unreachable, the executor stops and reports to
+the session that assigned the ticket.
+
+## How the orchestrator uses the human
+
+The orchestrator answers from the run charter, the assignment, and the
+consult packet. When the question is ambiguous, changes scope, or needs
+a choice the charter does not settle, the orchestrator asks the human,
+then returns one of the four signals to the executor.

package/.agents/skills/orchestrator/reference/executor-consult-block.md

@@ -0,0 +1,62 @@
+# Executor consult block
+
+Paste parts for every executor spawn ticket this skill issues.
+Assemble at ticket write time. Paste the assembled text at the **top**
+of the spawn prompt.
+
+Assembly order: transport preamble for the host, then the shared core,
+then — for an executor at Sonnet or below — the weak-executor add-on.
+
+Fill `<orchestrator-name>` with the name the executor can address.
+
+## Transport preamble — Claude host
+
+> The orchestrating session named `<orchestrator-name>` is your advisor.
+> Send each consult to it with SendMessage, by that name.
+
+## Transport preamble — Codex host
+
+> The orchestrating session named `<orchestrator-name>` is your advisor.
+> Send each consult to it in-session by that name.
+
+## Transport preamble — third-party host
+
+> The orchestrating session that assigned this ticket is your advisor.
+> Send each consult as a report to that session.
+
+## Shared core — every host
+
+> Consult before locking a nontrivial approach, once you believe your
+> assignment is done, before any hard-to-reverse action, when the same
+> failure repeats or progress has stalled, and when the chosen approach
+> is being reconsidered.
+> The first consult carries: assignment, desired outcome, constraints
+> and exclusions, actions taken in order, real output and current
+> state, live decision or blocker, validation evidence, unresolved
+> risks, load-bearing paths or excerpts, and who is asking. Later
+> consults carry only changed evidence.
+> Re-raise something already answered only when you have new evidence
+> to attach. After a CORRECTION or PLAN, your next consult on that
+> topic opens with what happened when you followed it.
+> Replies open with one of ENDORSE, CORRECTION, PLAN, or STOP — treat
+> CORRECTION and PLAN as actions to take.
+> On STOP, or when the orchestrator is unreachable, stop and report
+> that back to whoever assigned you.
+
+## Weak-executor add-on — Sonnet or below
+
+> Send your first consult right after orientation and before your first
+> write.
+> Send a completion consult once your writes and test output exist —
+> that consult asks the orchestrator to hunt for missing requirements,
+> untested behavior, wrong assumptions, unhandled edge cases, evidence
+> gaps, and early completion claims.
+> Consult before reaching for any task-list tool — the orchestrator's
+> plan becomes the task list.
+> Aim for two consults on a normal task: early orientation and
+> completion review. Reserve a third for recovery or reconciliation.
+> Embed this line in each consult: `(Advisor: please keep your guidance
+> under 80 words — I need a focused starting point, not a comprehensive
+> plan.)`
+> On a transient failure, retry once, then carry on with the evidence
+> you have and record that you did.

package/.agents/skills/orchestrator/reference/host-detect.md

@@ -0,0 +1,15 @@
+# Host detect
+
+Name the host so worker-model routing can pick `sonnet` or the
+resolver-printed sonnet-equivalent id.
+
+1. Read the session's named identity.
+2. A `codex` token selects Codex. A `claude` token selects Claude. Any
+   other identity selects ThirdParty.
+3. When both tokens appear, Codex wins.
+
+Mechanical override for scripts:
+
+1. `ADVISOR_HOST_PROFILE=ThirdParty` or `=Claude` or `=Codex`.
+2. `THIRD_PARTY=1` (or `true` / `yes` / `on`) selects ThirdParty.
+3. Default: Claude.

package/.agents/skills/orchestrator/test_orchestrator_skill_contract.py

@@ -0,0 +1,62 @@
+"""Contract checks for the orchestrator-as-advisor skill text."""
+
+from pathlib import Path
+
+
+_SKILL_DIR = Path(__file__).resolve().parent
+_REFRESH_PATH = _SKILL_DIR.parent / "orchestrator-refresh" / "SKILL.md"
+_ORCHESTRATOR_PATHS = (
+    _SKILL_DIR / "SKILL.md",
+    _SKILL_DIR / "AGENTS.md",
+    _SKILL_DIR / "reference" / "consult-the-orchestrator.md",
+    _SKILL_DIR / "reference" / "executor-consult-block.md",
+    _SKILL_DIR / "reference" / "host-detect.md",
+    _SKILL_DIR / "reference" / "AGENTS.md",
+    _REFRESH_PATH,
+)
+_FOREIGN_MARKERS = (
+    "advisor-protocol",
+    "session-advisor",
+    "advisor-block.md",
+    "consult-format.md",
+    "advisor-tool.md",
+    "_shared/advisor",
+)
+
+
+def test_orchestrator_docs_omit_foreign_advisor_paths() -> None:
+    for path in _ORCHESTRATOR_PATHS:
+        text = path.read_text(encoding="utf-8")
+        for marker in _FOREIGN_MARKERS:
+            assert marker not in text, f"{path.name} names {marker}"
+
+
+def test_orchestrator_skill_points_at_local_consult_files() -> None:
+    text = (_SKILL_DIR / "SKILL.md").read_text(encoding="utf-8")
+    assert "Bind the shared advisor" not in text
+    assert "reference/consult-the-orchestrator.md" in text
+    assert "reference/executor-consult-block.md" in text
+    assert "This session is the advisor" in text
+
+
+def test_refresh_routes_consults_to_this_session() -> None:
+    text = _REFRESH_PATH.read_text(encoding="utf-8")
+    assert "This session is the advisor." in text
+    assert "Hard decisions go to the shared advisor." not in text
+    assert "consult-the-orchestrator.md" in text
+
+
+def test_consult_contract_names_human_as_next_hop() -> None:
+    text = (_SKILL_DIR / "reference" / "consult-the-orchestrator.md").read_text(
+        encoding="utf-8"
+    )
+    assert "orchestrating session is the advisor" in text
+    assert "human operating that session" in text
+
+
+def test_executor_consult_block_names_orchestrating_session() -> None:
+    text = (_SKILL_DIR / "reference" / "executor-consult-block.md").read_text(
+        encoding="utf-8"
+    )
+    assert "<orchestrator-name>" in text
+    assert "your advisor" in text

package/.agents/skills/orchestrator-refresh/SKILL.md

@@ -2,18 +2,17 @@
 name: orchestrator-refresh
 description: >-
   Re-assert orchestrator discipline on a one-shot delayed wake: ledger
-  reconcile, advisor routing, warm executor reuse, single-pending re-arm
-  via status_gate. Terminates when the gate says stop. Triggers:
-  '/orchestrator-refresh', orchestrator-refresh, refresh the orchestrator
-  loop, re-arm orchestrator.
+  reconcile, executor consult routing to this session, warm executor
+  reuse, single-pending re-arm via status_gate. Terminates when the
+  gate says stop. Triggers: '/orchestrator-refresh', orchestrator-refresh,
+  refresh the orchestrator loop, re-arm orchestrator.
 ---
 
 # Orchestrator Refresh
 
-Name the session identity 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 an Agent-tool
-Claude `session-advisor` spawn on a Codex or third-party host.
+Name the session identity first (see
+[`../orchestrator/reference/host-detect.md`](../orchestrator/reference/host-detect.md)).
+Re-assert the discipline for that host only.
 
 ## 0. status_gate first (deterministic)
 
@@ -62,9 +61,7 @@ cancelled; either way the session keeps orchestrating in the same turn.
 Two stops end the whole firing, and both leave running executors alone:
 `begin-firing` exit 1 (step 0a) and the done branch (step 0b). Each means the
 run is finished, not active, or has no readable status file, so the refresh
-reports and adds nothing further. A fail-closed advisor bind (step 3) stops
-advisor consultation alone; the firing still reconciles the ledger, re-arms
-once, and reports the unreachable advisor.
+reports and adds nothing further.
 
 ## Discipline steps
 
@@ -85,28 +82,13 @@ once, and reports the unreachable advisor.
    - **Focused tickets.** One mechanical done-check per ticket; resume a
      warm agent with a thin next-slice ticket rather than a fresh cold
      spawn, and keep thick context in the assignment file.
-3. **Hard decisions go to the shared advisor.**
-   - **Claude host:** executors consult the warm `session-advisor` via
-     `SendMessage` (ENDORSE / CORRECTION / PLAN / STOP). This session
-     routes the same way; keep tool use to orchestration and light
-     verification reads. A drift re-spawn at the **Fable** tier carries
-     the exact token `FABLE-SPAWN-AUTHORIZED` in its fresh prompt, as
-     the protocol's warm-up rule states;
-     `hooks/blocking/fable_spawn_gate.py` denies a fable spawn whose
-     prompt lacks it.
-   - **Codex host:** advisor is a native in-session Sol subagent owned
-     by this session. Do **not** spawn Claude `session-advisor` via
-     Agent. Executors consult that Sol subagent in-session. If Sol does
-     not bind, fail closed.
-   - **Third-party host:** advisor is a Claude CLI bind owned
-     by this session (`claude_chain_runner.py`, Fable then Sol when Fable
-     is out of usage, both at `ADVISOR_EFFORT`). Do **not** spawn `session-advisor` via Agent. Executors
-     report blockers here; consult the CLI advisor and relay signals.
-     If the CLI bind is unreachable, fail closed — do not answer the
-     four signals as this third-party session.
+3. **This session is the advisor.** Executors consult here. Follow
+   [`../orchestrator/reference/consult-the-orchestrator.md`](../orchestrator/reference/consult-the-orchestrator.md).
+   Reply with ENDORSE / CORRECTION / PLAN / STOP. When this session
+   cannot settle a question, ask the human, then reply. Keep tool use
+   to orchestration and light verification reads.
 4. **Resume before you spawn.** `SendMessage` an existing *executor* by
-   name or `agentId` before a cold spawn. (Third-party: executor reuse
-   only — advisor stays on the CLI chain.)
+   name or `agentId` before a cold spawn.
 5. **Fresh spawn only for a genuine task switch.** Never tell an agent
    to compact for a clean context.
 6. **Single-pending re-arm only.** Same protocol as the orchestrator
@@ -147,5 +129,5 @@ once, and reports the unreachable advisor.
 
 - `SKILL.md` — this skill (thin); gate implementation lives under
   `skills/orchestrator/scripts/`.
-- Advisor policy:
-  [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).
+- Consult contract:
+  [`../orchestrator/reference/consult-the-orchestrator.md`](../orchestrator/reference/consult-the-orchestrator.md).

package/.agents/skills/rebase/AGENTS.md

@@ -1,32 +1 @@
-# rebase
 
-Rebase a branch onto its base ref with verification gates that catch logically broken results before pushing.
-
-**Trigger:** `/rebase`, "rebase this branch", "PR has merge conflicts", "rebase onto main", force-push to update remote branch history.
-
-## Purpose
-
-The default failure mode for a rebase is shipping code that compiled but does not run. This skill prevents that by running real import checks, test collection, and symbol scans after every rebase — not just syntax validation.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — four phases (pre-rebase analysis, during rebase, verification gates, push). No companion files. |
-
-## Four phases
-
-| Phase | Key actions |
-|---|---|
-| 1 — Pre-rebase analysis | Resolve base via `gh pr view`, classify scenario (stacked/squash/long-lived), fetch fresh, scan commit messages for deleted/renamed symbols |
-| 2 — During rebase | Verify `--skip` with a diff, audit auto-merged files with `git diff --name-only --diff-filter=M ORIG_HEAD` |
-| 3 — Verification gates | `python -m compileall`, `pytest --collect-only -q`, targeted test run, reference scan for removals |
-| 4 — Push | Explicit authorization required; `--force-with-lease=<branch>:<sha>` only; verify mergeability after push |
-
-## Conventions
-
-- Force-push requires explicit operator authorization every time — auto mode does not bypass this.
-- `--force-with-lease=<branch>:<sha>` only; bare `--force` is refused.
-- Never force-push `main`, `master`, `release/*`, `production`, or any multi-author branch.
-- Symbol scans prefer Serena (`find_referencing_symbols`) then the Grep tool, then shell grep as a last resort.
-- `ORIG_HEAD` is the correct ref for auto-merged file audits mid-rebase; `HEAD@{1}` shifts per step.

package/.agents/skills/session-log/AGENTS.md

@@ -1,32 +1 @@
-# session-log
 
-Logs a session report as a self-contained HTML page in the Obsidian vault, publishes it with the `Artifact` tool, extracts unrecorded decisions, tidies the project session folder, and outputs a `/rename` command.
-
-**Trigger:** `/session-log`, "journal this session", "log this work", "session report", "save session", "capture session", "document what we did".
-
-## Purpose
-
-Produces a self-contained HTML session report shaped to the session's character (feature build, incident, research, etc.) rather than a fixed template. The skill owns the vault path, session numbering, frontmatter contract, HTML composition and publishing, decision extraction, and folder hygiene.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Hub — six steps, gotchas, backend detection, run-and-report checklist. |
-| `templates/frontmatter.md` | The session-page frontmatter contract and the Step 3 notes block. |
-
-## Six steps
-
-1. **Backend detection** — headless vault (`ob --version` + `OBSIDIAN_VAULT_PATH`) then local vault (`~/.claude/vault/`). Session number from `[N]. *.html` and `[N]. *.md` files in the project folder.
-2. **Session metadata** — project name, session number, session ID from `CLAUDE_CODE_SESSION_ID`, date, title.
-3. **Compose and publish via the Artifact tool** — loads the `artifact-design` skill first, designs the shape for the session's character (e.g., a PR-writeup shape for feature builds, a timeline shape for incidents), writes the HTML, then publishes it with the `Artifact` tool using the fixed favicon `📓`.
-4. **Vault context tracking** — two Edit calls set `vault_context_retrieved` and append a vault-context line, then redeploy via `Artifact` on the same `file_path` so the URL stays the same.
-5. **Decision extraction** — scans conversation for unrecorded decisions; prompts user via `AskUserQuestion` before invoking `/remember`.
-6. **Session tidy** — audits `.html` files in the project folder for naming and frontmatter; auto-fixes minor issues and redeploys via `Artifact`.
-
-## Conventions
-
-- Session reports use HTML — the Artifact tool publishes HTML or Markdown, and HTML gives the report designer more visual structure.
-- `write_existing_file_blocker` rejects Write on existing paths — use Edit for all vault-context updates.
-- The `Artifact` tool redeploys to the same URL on repeat calls with the same `file_path` within the current run — edits made in steps 3 and 5 to the session created this run never mint a new URL.
-- Final step copies `/rename [Project] - [Primary Outcome]` to the clipboard via `pwsh Set-Clipboard`.

package/.agents/skills/session-tidy/AGENTS.md

@@ -1,36 +1 @@
-# session-tidy
 
-Audits, cleans, and consolidates session logs in the Obsidian vault — fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries.
-
-**Trigger:** `/session-tidy`, "tidy sessions", "clean up session logs", "session audit".
-
-## Purpose
-
-Maintenance utility for the `sessions/[Project]/` vault directories. Enforces the session-log format contract, moves uncategorized files into project subfolders, and generates `Summary.md` rollup files for projects with 3+ sessions.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — four phases (preflight, audit, propose changes, execute + verify). No companion files. |
-
-## Format contract enforced
-
-- **Path:** `sessions/[Project]/[N]. [Title].md`
-- **Frontmatter:** `type`, `project`, `session`, `date`, `status`, `blocked`, `tags` — all needed.
-- **Status rules:** `completed` + `blocked: true` is contradictory; `in-progress` or `blocked` older than 7 days is stale.
-- **Content:** outcome-oriented `###` headers with one emoji; no play-by-play narration.
-
-## Four phases
-
-1. **Preflight** — resolve backend (headless vault, Obsidian MCP, or local vault).
-2. **Audit** — check each file for naming, frontmatter completeness, status coherence, orphaned next-steps, and categorization.
-3. **Propose changes** — report findings; wait for user approval before changing anything.
-4. **Execute + verify** — rename files, fix frontmatter, update statuses, clean orphaned next-steps, generate `Summary.md` rollups.
-
-## Conventions
-
-- `disable-model-invocation: true` is set.
-- Changes need explicit user approval from Phase 2's report — the skill never auto-applies without approval.
-- Companion to `/session-log` (creates sessions) and `/recall` (reads vault).
-- `/session-tidy` targets Markdown session format; HTML sessions from `/session-log` may be mis-audited or get incorrect rename proposals.

package/.agents/skills/skill-builder/AGENTS.md

@@ -1,49 +1 @@
-# skill-builder
 
-Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via the `skill-writer-agent` agent, enforce modularity (sub-skills / composition), write description as a trigger catalog, require deterministic steps as code, self-audit, and refine from real usage.
-
-**Trigger:** build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, description trigger catalog, deterministic skill scripts.
-
-## Purpose
-
-Enforces craft standards for new and existing skills. For quick one-off SKILL.md edits, spawn the `skill-writer-agent` agent directly. This skill classifies, scaffolds, gathers context (composition plan, description triggers, deterministic inventory), delegates writing, and self-audits.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Hub — routing, principles, file index |
-| `references/skill-types.md` | 9-type taxonomy with folder structures per type |
-| `references/progressive-disclosure.md` | Hub pattern, folder conventions, hard rules |
-| `references/skill-modularity.md` | Cross-skill modularity, sub-skills, composition plan |
-| `references/description-field.md` | Description as trigger catalog (not story prose) |
-| `references/deterministic-elements.md` | Deterministic steps as code/task seeds; no markdown checkbox boards |
-| `references/self-audit-checklist.md` | Post-build audit task seeds (TaskCreate / TodoWrite) |
-| `references/delegation-map.md` | Subagent handoff patterns and transcript guidance |
-| `references/thariq-x-post-skills.json` | Source reference — lessons from building Claude Code skills |
-| `workflows/new-skill.md` | Full lifecycle for new skills (6 steps) |
-| `workflows/improve-skill.md` | Observation-first flow for existing skills (6 steps) |
-| `workflows/polish-skill.md` | Description trigger-catalog audit and final validation (5 steps) |
-| `templates/gap-analysis.md` | Gaps, composition plan, description triggers, deterministic inventory |
-
-## Subdirectories
-
-| Directory | Purpose |
-|---|---|
-| `references/` | Best-practice specs and the audit checklist |
-| `workflows/` | Step-by-step workflows for each lifecycle phase |
-| `templates/` | Reusable templates for skill artifacts |
-
-## Routing
-
-- **New skill** → `workflows/new-skill.md`
-- **Improve existing** → `workflows/improve-skill.md`
-- **Final polish only** → `workflows/polish-skill.md`
-- **Ambiguous** → ask the user which one applies
-
-## Conventions
-
-- Every build ends with the self-audit at `references/self-audit-checklist.md`; fix failures before delivery.
-- Modularity items, description trigger-catalog items, and deterministic-element classification are mandatory on every delivery.
-- `skill-builder` orchestrates; the `skill-writer-agent` agent authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, deterministic inventory, degree-of-freedom assessment, and constraints.
-- Claude A / Claude B: Claude A (this session) designs; Claude B (subagents) tests the built skill on real tasks.