claude-dev-env 2.13.0 → 2.14.1

package/skills/pr-converge/scripts/AGENTS.md

@@ -0,0 +1,46 @@
+# pr-converge/scripts
+
+Python helper scripts for the `pr-converge` skill, plus their tests and a PowerShell/AutoHotkey toolset for advancing Cursor agents.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `check_bugbot_ci.py` | Checks bugbot CI check-run status on a given SHA |
+| `check_convergence.py` | Evaluates whether all convergence gates pass on the current HEAD |
+| `check_convergence_availability.py` | Resolves reviewer waivers from flag, disk-authoritative settings (env fallback), and the availability/quota probe, with waived / enforced / probe_error_reason states |
+| `check_convergence_gates.py` | GitHub REST leaf checks (review and Bugbot) the convergence gates call |
+| `check_convergence_thread_gates.py` | GitHub GraphQL and REST leaf checks (review threads and pending reviewers) the convergence gates call |
+| `check_pending_reviews.py` | Fetches pending review requests and reviewer states |
+| `fetch_copilot_reviews.py` | Fetches Copilot reviewer reviews filtered to the current HEAD |
+| `post_fix_reply.py` | Posts an inline reply to a review comment thread |
+| `reflow_skill_md.py` | Reformats `SKILL.md` to enforce a line width limit |
+| `README.md` | MCP tool reference for PR operations used by the scripts |
+| `_pr_converge_path_setup.py` | Adds the scripts directory to `sys.path` for direct script imports |
+| `conftest.py` | Puts the scripts directory on `sys.path` so pytest collects the suite |
+| `test_check_bugbot_ci.py` | Tests for `check_bugbot_ci.py` |
+| `test_check_convergence.py` | Tests for `check_convergence.py` |
+| `test_check_convergence_availability.py` | Tests for `check_convergence_availability.py` |
+| `test_check_convergence_contract.py` | Contract pins for `check_convergence.py` gate wiring |
+| `test_check_convergence_gates.py` | Tests for `check_convergence_gates.py` |
+| `test_check_convergence_thread_gates.py` | Tests for `check_convergence_thread_gates.py` |
+| `test__pr_converge_path_setup.py` | Tests for `_pr_converge_path_setup.py` |
+| `test_cursor_agents_continue.py` | Tests for the cursor-agents-continue toolset |
+| `test_reflow_skill_md.py` | Tests for `reflow_skill_md.py` |
+| `caller-window-pid.ps1` | Gets the PID of the calling terminal window |
+| `cursor-agents-continue.ahk` | AutoHotkey script to advance Cursor agent prompts |
+| `cursor-agents-continue.cmd` | CMD wrapper for the AHK script |
+| `cursor-agents-continue-stop-others.ps1` | Stops other Cursor agents before advancing one |
+| `cursor-agents-continue-caller.cmd` | Caller-side CMD wrapper |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `pr_converge_scripts_constants/` | Script-specific constants (re-exports skill constants plus adds reflow/CLI constants) |
+
+## Conventions
+
+- Scripts import constants from `pr_converge_scripts_constants.pr_converge_constants`, which re-exports everything from `pr_converge_skill_constants.constants`.
+- Run scripts as `python ~/.claude/skills/pr-converge/scripts/<script>.py --owner <O> --repo <R> --pr-number <N>`.
+- The `reflow_skill_md.py` script targets `SKILL.md` in the parent skill directory (resolved via `TARGET_SKILL_PATH` in `pr_converge_scripts_constants/reflow_skill_md_constants.py`).

package/skills/pr-converge/scripts/CLAUDE.md

@@ -1,46 +1 @@
-# pr-converge/scripts
-
-Python helper scripts for the `pr-converge` skill, plus their tests and a PowerShell/AutoHotkey toolset for advancing Cursor agents.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `check_bugbot_ci.py` | Checks bugbot CI check-run status on a given SHA |
-| `check_convergence.py` | Evaluates whether all convergence gates pass on the current HEAD |
-| `check_convergence_availability.py` | Resolves reviewer waivers from flag, disk-authoritative settings (env fallback), and the availability/quota probe, with waived / enforced / probe_error_reason states |
-| `check_convergence_gates.py` | GitHub REST leaf checks (review and Bugbot) the convergence gates call |
-| `check_convergence_thread_gates.py` | GitHub GraphQL and REST leaf checks (review threads and pending reviewers) the convergence gates call |
-| `check_pending_reviews.py` | Fetches pending review requests and reviewer states |
-| `fetch_copilot_reviews.py` | Fetches Copilot reviewer reviews filtered to the current HEAD |
-| `post_fix_reply.py` | Posts an inline reply to a review comment thread |
-| `reflow_skill_md.py` | Reformats `SKILL.md` to enforce a line width limit |
-| `README.md` | MCP tool reference for PR operations used by the scripts |
-| `_pr_converge_path_setup.py` | Adds the scripts directory to `sys.path` for direct script imports |
-| `conftest.py` | Puts the scripts directory on `sys.path` so pytest collects the suite |
-| `test_check_bugbot_ci.py` | Tests for `check_bugbot_ci.py` |
-| `test_check_convergence.py` | Tests for `check_convergence.py` |
-| `test_check_convergence_availability.py` | Tests for `check_convergence_availability.py` |
-| `test_check_convergence_contract.py` | Contract pins for `check_convergence.py` gate wiring |
-| `test_check_convergence_gates.py` | Tests for `check_convergence_gates.py` |
-| `test_check_convergence_thread_gates.py` | Tests for `check_convergence_thread_gates.py` |
-| `test__pr_converge_path_setup.py` | Tests for `_pr_converge_path_setup.py` |
-| `test_cursor_agents_continue.py` | Tests for the cursor-agents-continue toolset |
-| `test_reflow_skill_md.py` | Tests for `reflow_skill_md.py` |
-| `caller-window-pid.ps1` | Gets the PID of the calling terminal window |
-| `cursor-agents-continue.ahk` | AutoHotkey script to advance Cursor agent prompts |
-| `cursor-agents-continue.cmd` | CMD wrapper for the AHK script |
-| `cursor-agents-continue-stop-others.ps1` | Stops other Cursor agents before advancing one |
-| `cursor-agents-continue-caller.cmd` | Caller-side CMD wrapper |
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `pr_converge_scripts_constants/` | Script-specific constants (re-exports skill constants plus adds reflow/CLI constants) |
-
-## Conventions
-
-- Scripts import constants from `pr_converge_scripts_constants.pr_converge_constants`, which re-exports everything from `pr_converge_skill_constants.constants`.
-- Run scripts as `python ~/.claude/skills/pr-converge/scripts/<script>.py --owner <O> --repo <R> --pr-number <N>`.
-- The `reflow_skill_md.py` script targets `SKILL.md` in the parent skill directory (resolved via `TARGET_SKILL_PATH` in `pr_converge_scripts_constants/reflow_skill_md_constants.py`).
+@AGENTS.md

package/skills/pr-converge/scripts/pr_converge_scripts_constants/AGENTS.md

@@ -0,0 +1,18 @@
+# pr_converge_scripts_constants
+
+Constants module for the `pr-converge` skill's Python scripts. Re-exports all runtime/API constants from the skill-level module and adds script-specific constants for CLI arguments, markdown patterns, and reflow settings.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `__init__.py` | Package marker |
+| `pr_converge_constants.py` | Re-exports all constants from `pr_converge_skill_constants.constants` plus adds script-specific values |
+| `reflow_skill_md_constants.py` | Constants for `reflow_skill_md.py`: line width limit, list item patterns, `TARGET_SKILL_PATH` |
+| `convergence_gate_constants.py` | Constants for `check_convergence_gates.py`: short-SHA length, join separators, and the review-threads GraphQL query |
+
+## Conventions
+
+- `pr_converge_constants.py` uses `from pr_converge_skill_constants.constants import ...` (with `# noqa: F401`) to re-export everything so script files can import from one location.
+- `reflow_skill_md_constants.py` resolves `TARGET_SKILL_PATH` from its own `__file__` path, pointing to `SKILL.md` three directories up.
+- Script-specific regex patterns (ordered list items, bullet list items, unfinished markdown link targets, markdown reference definitions) live in `reflow_skill_md_constants.py`.

package/skills/pr-converge/scripts/pr_converge_scripts_constants/CLAUDE.md

@@ -1,18 +1 @@
-# pr_converge_scripts_constants
-
-Constants module for the `pr-converge` skill's Python scripts. Re-exports all runtime/API constants from the skill-level module and adds script-specific constants for CLI arguments, markdown patterns, and reflow settings.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `__init__.py` | Package marker |
-| `pr_converge_constants.py` | Re-exports all constants from `pr_converge_skill_constants.constants` plus adds script-specific values |
-| `reflow_skill_md_constants.py` | Constants for `reflow_skill_md.py`: line width limit, list item patterns, `TARGET_SKILL_PATH` |
-| `convergence_gate_constants.py` | Constants for `check_convergence_gates.py`: short-SHA length, join separators, and the review-threads GraphQL query |
-
-## Conventions
-
-- `pr_converge_constants.py` uses `from pr_converge_skill_constants.constants import ...` (with `# noqa: F401`) to re-export everything so script files can import from one location.
-- `reflow_skill_md_constants.py` resolves `TARGET_SKILL_PATH` from its own `__file__` path, pointing to `SKILL.md` three directories up.
-- Script-specific regex patterns (ordered list items, bullet list items, unfinished markdown link targets, markdown reference definitions) live in `reflow_skill_md_constants.py`.
+@AGENTS.md

package/skills/pr-converge/workflows/AGENTS.md

@@ -0,0 +1,16 @@
+# pr-converge/workflows
+
+Pacing workflow specification for the `pr-converge` loop.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `schedule-wakeup-loop.md` | Specifies `ScheduleWakeup` call parameters, delays, and stop/convergence conditions for each tick |
+
+## Conventions
+
+- `per-tick.md` (in `../reference/`) references this file for Step 4 (schedule next wakeup). Read it before running Step 4.
+- Default delay: `delaySeconds: 360`. Exception: BUGBOT inline-lag branch uses `delaySeconds: 90`.
+- On convergence or a hard stop condition, omit the `ScheduleWakeup` call entirely.
+- The `reason` field in each `ScheduleWakeup` call names what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set.

package/skills/pr-converge/workflows/CLAUDE.md

@@ -1,16 +1 @@
-# pr-converge/workflows
-
-Pacing workflow specification for the `pr-converge` loop.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `schedule-wakeup-loop.md` | Specifies `ScheduleWakeup` call parameters, delays, and stop/convergence conditions for each tick |
-
-## Conventions
-
-- `per-tick.md` (in `../reference/`) references this file for Step 4 (schedule next wakeup). Read it before running Step 4.
-- Default delay: `delaySeconds: 360`. Exception: BUGBOT inline-lag branch uses `delaySeconds: 90`.
-- On convergence or a hard stop condition, omit the `ScheduleWakeup` call entirely.
-- The `reason` field in each `ScheduleWakeup` call names what is being awaited, including the current `phase` and `bugbot_clean_at` SHA when set.
+@AGENTS.md

package/skills/prototype/SKILL.md

@@ -45,7 +45,7 @@ Follow `workflows/sandbox.md`. In short:
 
 ### Phase 2 — Promotion
 
-Run only in the normal, fully-hooked session — never inside the sandbox. Follow `workflows/promotion.md`, which drives the clean-room task seeds in `reference/promotion-tasks.md`: fresh branch off live `origin/main`, POC content as an uncommitted diff, cleanup and privacy sweep, review and verification under the [review guide](../reviews/SKILL.md#review-workflow), then `/commit` and a draft PR handed to a PR-loop skill. State the two honest limitations from `reference/honest-limitations.md`.
+Run only in the normal, fully-hooked session — never inside the sandbox. Follow `workflows/promotion.md`, which drives the clean-room task seeds in `reference/promotion-tasks.md`: fresh branch off live `origin/main`, POC content as an uncommitted diff, cleanup and privacy sweep, review and verification under the [review guide](../reviews/SKILL.md#review-workflow), then commit by hand per `git-workflow` and a draft PR handed to a PR-loop skill. State the two honest limitations from `reference/honest-limitations.md`.
 
 ## Task seeding
 
@@ -58,7 +58,6 @@ At the start of Phase 2, register every item in `reference/promotion-tasks.md` a
 | `fresh-branch` | Sandbox step 1; Promotion step 2 | isolated worktree JSON (`worktree_path`, `base_commit`, `repo_root`) | Refuse — see refusal cases |
 | `privacy-hygiene` | Promotion step 5 | personal-data and secret sweep of the diff | Warn; do a manual review before continuing |
 | [Review guide](../reviews/SKILL.md#review-workflow) | Promotion step 6 | review and verification of the real diff | Stop and report the incomplete promotion |
-| `/commit` (command) | Promotion step 7 | conventional commit + push | Commit and push by hand per `git-workflow` |
 | `autoconverge` (default; `pr-converge` or `bugteam` as alternatives) | Promotion step 9 | the PR converged to ready | Stop after the draft PR; tell the user to converge manually |
 
 ## Degree of freedom

package/skills/prototype/reference/honest-limitations.md

@@ -10,7 +10,7 @@ Promotion records the controls applied to the real diff:
 
 - review and verification under the [review guide](../../reviews/SKILL.md#review-workflow);
 - the `privacy-hygiene` sweep for personal data and secrets;
-- the pull-request review (AGENTS.md criteria and any PR-loop reviewers).
+- the pull-request review criteria and any PR-loop reviewers.
 
 Say plainly: the write-time rule engine did not see this code; the verifier and review are what cover it.
 

package/skills/prototype/reference/promotion-tasks.md

@@ -16,7 +16,7 @@ Promotion runs in the **normal, fully-hooked session** — never inside the `--b
 
 6. **Review and verify the real diff.** Apply the [review guide](../../reviews/SKILL.md#review-workflow). Evidence: the checks run and each required finding repaired. Do not rely on sandbox testing as promotion evidence.
 
-7. **Commit and open a draft PR.** After the review and verification record is complete, run `/commit`, then open a draft PR per the `git-workflow` rule. Evidence: the commit hash and the PR URL.
+7. **Commit and open a draft PR.** After the review and verification record is complete, commit by hand per the `git-workflow` rule, then open a draft PR. Evidence: the commit hash and the PR URL.
 
 8. **State the honest limitations.** Post the two statements from `reference/honest-limitations.md` — write-time rules never ran; TDD ordering waived — in the PR body or to the user. Evidence: the text was included.
 

package/skills/prototype/workflows/promotion.md

@@ -16,7 +16,7 @@ The task seeds carry the full ordered detail. The shape:
 4. **Cleanup.** Remove scratch files, debug dumps, and temp helpers the POC created (`cleanup-temp-files` rule).
 5. **Privacy sweep** via `privacy-hygiene` over the diff.
 6. **Review and verify** the real diff against the [review guide](../../reviews/SKILL.md#review-workflow). Record the checks run and repair every required finding.
-7. **Commit and PR.** After the review and verification record is complete, run `/commit`, then open a draft PR per the `git-workflow` rule.
+7. **Commit and PR.** After the review and verification record is complete, commit by hand per the `git-workflow` rule, then open a draft PR.
 8. **State the honest limitations** from `reference/honest-limitations.md` in the PR body or to the user.
 9. **Converge** by handing the PR to `autoconverge` by default; use `pr-converge` for paced ticks or `bugteam` for an open-loop audit.
 

package/skills/rebase/AGENTS.md

@@ -0,0 +1,32 @@
+# 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/skills/rebase/CLAUDE.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.
+@AGENTS.md

package/skills/recall/AGENTS.md

@@ -0,0 +1,30 @@
+# recall
+
+Retrieves prior session context and decisions from the Obsidian vault for the current project.
+
+**Trigger:** `/recall [search query or project name]`.
+
+## Purpose
+
+Surfaces relevant session reports, decision notes, and research from the Obsidian vault before starting work. Prevents repeating decisions already made or missing known gotchas.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — six steps (resolve query, frontmatter search, content search, read top matches, present with attribution, handle no results). No companion files. |
+
+## How the skill runs
+
+1. Uses `$ARGUMENTS` as the search query, or infers the project name from conversation context.
+2. Searches by frontmatter first (`mcp__obsidian__search_notes` with `searchFrontmatter: true`) to catch session reports and decision notes tagged with the project.
+3. Falls back to content keyword search when frontmatter search returns few results.
+4. Reads the top 3 most relevant notes via `mcp__obsidian__read_note`, preferring recent notes and decision summaries over raw research.
+5. Reports each note with its path, date, relevant excerpts, and whether any decisions are marked `status: Superseded`.
+6. States clearly when no vault history exists — never infers or invents history.
+
+## Conventions
+
+- `disable-model-invocation: true` is not set; this skill does invoke the model to synthesize results.
+- The skill is read-only: it never writes to the vault.
+- Companion to `/remember` (which writes decisions) and `/session-log` (which writes session reports).

package/skills/recall/CLAUDE.md

@@ -1,30 +1 @@
-# recall
-
-Retrieves prior session context and decisions from the Obsidian vault for the current project.
-
-**Trigger:** `/recall [search query or project name]`.
-
-## Purpose
-
-Surfaces relevant session reports, decision notes, and research from the Obsidian vault before starting work. Prevents repeating decisions already made or missing known gotchas.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — six steps (resolve query, frontmatter search, content search, read top matches, present with attribution, handle no results). No companion files. |
-
-## How the skill runs
-
-1. Uses `$ARGUMENTS` as the search query, or infers the project name from conversation context.
-2. Searches by frontmatter first (`mcp__obsidian__search_notes` with `searchFrontmatter: true`) to catch session reports and decision notes tagged with the project.
-3. Falls back to content keyword search when frontmatter search returns few results.
-4. Reads the top 3 most relevant notes via `mcp__obsidian__read_note`, preferring recent notes and decision summaries over raw research.
-5. Reports each note with its path, date, relevant excerpts, and whether any decisions are marked `status: Superseded`.
-6. States clearly when no vault history exists — never infers or invents history.
-
-## Conventions
-
-- `disable-model-invocation: true` is not set; this skill does invoke the model to synthesize results.
-- The skill is read-only: it never writes to the vault.
-- Companion to `/remember` (which writes decisions) and `/session-log` (which writes session reports).
+@AGENTS.md

package/skills/remember/AGENTS.md

@@ -0,0 +1,31 @@
+# remember
+
+Saves a decision, gotcha, or architectural choice to the Obsidian vault as a structured note.
+
+**Trigger:** User-initiated only. `/remember [what to remember]`.
+
+## Purpose
+
+Writes a decision, fact, procedure, or gotcha to `decisions/[Project] - [Short Title].md` in the Obsidian vault. Each note carries structured frontmatter and a body shaped by its type, making it searchable and readable via `/recall`.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — six steps (parse input, classify type, infer project, generate title, write to vault, confirm). No companion files. |
+
+## Four note types
+
+| Type | Body format |
+|---|---|
+| `decision` | Decision + Reasoning + Alternatives + Consequences |
+| `gotcha` | Gotcha + Symptom + Fix |
+| `procedural` | 1–3 clear sentences describing the how-to |
+| `fact` | 1–3 clear sentences stating the fact |
+
+## Conventions
+
+- `disable-model-invocation: true` is set — runs without a secondary LLM call.
+- Writes via `mcp__obsidian__write_note` only; never edits existing notes.
+- Path pattern: `decisions/[Project] - [Short Title].md`.
+- Companion to `/recall` (reads vault) and `/session-log` (triggers decision extraction at session end).

package/skills/remember/CLAUDE.md

@@ -1,31 +1 @@
-# remember
-
-Saves a decision, gotcha, or architectural choice to the Obsidian vault as a structured note.
-
-**Trigger:** User-initiated only. `/remember [what to remember]`.
-
-## Purpose
-
-Writes a decision, fact, procedure, or gotcha to `decisions/[Project] - [Short Title].md` in the Obsidian vault. Each note carries structured frontmatter and a body shaped by its type, making it searchable and readable via `/recall`.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — six steps (parse input, classify type, infer project, generate title, write to vault, confirm). No companion files. |
-
-## Four note types
-
-| Type | Body format |
-|---|---|
-| `decision` | Decision + Reasoning + Alternatives + Consequences |
-| `gotcha` | Gotcha + Symptom + Fix |
-| `procedural` | 1–3 clear sentences describing the how-to |
-| `fact` | 1–3 clear sentences stating the fact |
-
-## Conventions
-
-- `disable-model-invocation: true` is set — runs without a secondary LLM call.
-- Writes via `mcp__obsidian__write_note` only; never edits existing notes.
-- Path pattern: `decisions/[Project] - [Short Title].md`.
-- Companion to `/recall` (reads vault) and `/session-log` (triggers decision extraction at session end).
+@AGENTS.md

package/skills/reviews/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 # Code Review Guide
 
 Use this guide to evaluate a pull request or code change. Apply the repository's
-`AGENTS.md` and `CODE_RULES.md` as its project-specific quality rubric.
+the repository's checked-in review contract and `CODE_RULES.md` as its project-specific quality rubric.
 
 ## Review Judgment
 

package/skills/session-log/AGENTS.md

@@ -0,0 +1,32 @@
+# 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/skills/session-log/CLAUDE.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`.
+@AGENTS.md

package/skills/session-tidy/AGENTS.md

@@ -0,0 +1,36 @@
+# 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/skills/session-tidy/CLAUDE.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.
+@AGENTS.md

package/skills/skill-builder/AGENTS.md

@@ -0,0 +1,49 @@
+# 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.