claude-dev-env 4.3.0 → 7.1.0

package/.agents/skills/run-claude-dev-env/SKILL.md

@@ -1,84 +0,0 @@
----
-name: run-claude-dev-env
-description: Build, install, run, and test the claude-dev-env installer. Use when asked to run claude-dev-env, install the Claude Code config into ~/.claude, drive the installer, smoke-test it against a sandbox, or run its test suite.
----
-
-`claude-dev-env` is the npm-distributed installer that copies this repo's rules, hooks, commands, and docs into `~/.claude/`, copies skills and agents into `~/.agents/`, publishes directory pointers at `~/.claude/skills` and `~/.claude/agents`, and merges its hook entries into `~/.claude/settings.json`. Its entry point is `bin/install.mjs`. Drive it with the smoke driver at `.claude/skills/run-claude-dev-env/driver.mjs`, which runs the installer against a throwaway sandbox home directory so a run never touches the real `~/.claude/` or `~/.agents/`.
-
-All paths below are written from the `packages/claude-dev-env/` directory.
-
-## Prerequisites
-
-The installer needs three tools on `PATH`:
-
-- **Node.js 18+** — the installer is an ES module (verified on Node 22.17).
-- **Python 3.8+** — the installer bakes a Python interpreter into every hook command and aborts if it finds none. On Windows it skips the Microsoft Store stub (verified `py -3` → Python 3.13.5).
-- **git** — the installer reads `git status` to guard against installing from a conflicted source, and sets a global git hooks path.
-
-```bash
-node --version
-git --version
-py -3 --version    # POSIX: python3 --version
-```
-
-On a fresh Ubuntu container the three come from `sudo apt-get install -y nodejs python3 git`.
-
-## Run (agent path) — the smoke driver
-
-The driver is the handle to reach for first. It spawns the installer against a fresh temp home directory with `HOME`, `USERPROFILE`, and `GIT_CONFIG_GLOBAL` all redirected, runs the `--help` → install → `--uninstall` lifecycle, asserts the result of each step against the sandbox tree, then deletes the sandbox. It works the same on Windows and POSIX.
-
-```bash
-node .claude/skills/run-claude-dev-env/driver.mjs
-```
-
-Expected tail:
-
-```
-21/21 checks passed.
-ALL CHECKS PASSED
-```
-
-The driver proves a full install lands skills under `<sandbox>/.agents/skills` with a directory pointer at `<sandbox>/.claude/skills`, lands agents the same way, lands hook scripts, rules, the `CLAUDE.md` hub, a populated `settings.json`, and a tracking manifest, and that `--uninstall` removes every manifest-tracked file. The real `~/.claude/`, `~/.agents/`, and the real global git config stay untouched. Exit code is 0 only when all checks hold.
-
-## Run (human path) — install for real
-
-These write into your real `~/.claude/` and set a global git hooks path. Run them only when you mean to install on this machine.
-
-```bash
-node bin/install.mjs --help         # usage only, no side effects
-node bin/install.mjs                # install every group
-node bin/install.mjs --only core    # install one or more named groups
-node bin/install.mjs --update       # remove manifest-tracked files, then reinstall
-node bin/install.mjs --uninstall    # remove every installed file
-```
-
-Groups: `core`, `journal`, and the discovered `prompt-generator` dependency group. Run `node bin/install.mjs --help` for the live list. The published package runs the same entry point as `npx claude-dev-env`.
-
-## Test
-
-```bash
-npm test
-```
-
-Runs `node --test` over `bin/*.test.mjs` and `.agents/skills/**/*.test.mjs` with Node's built-in test runner — no extra dependency, no network. Expected: `# fail 0`, with the pass count growing as tests are added.
-
-## Gotchas
-
-- **The install target is `os.homedir()/.claude` with no override flag** (the `CLAUDE_HOME` constant in `bin/install.mjs`). To drive the installer without overwriting your real config, redirect the home directory: set `USERPROFILE` (Windows) and `HOME` (POSIX) to a temp dir. The driver does this for you.
-- **The installer reaches outside `~/.claude/`.** It writes skills and agents under `~/.agents/`, runs `git config --global core.hooksPath ...`, which applies to every git repo on the machine, and it writes `~/.mypy.ini`. The driver isolates those writes by pointing `GIT_CONFIG_GLOBAL` at a sandbox file and redirecting the home directory.
-- **git "dubious ownership" aborts the install.** The source-conflict guard runs `git status`; when the checkout sits on a path git distrusts (a UNC network share owned by another account), git exits 128 with a dubious-ownership message that the installer rethrows. The driver seeds its sandbox git config with `safe.directory = *` so the guard runs. For a real install on such a checkout, add the exception: `git config --global --add safe.directory '<repo-path>'`.
-- **`npm install` at the repo root fails on a Windows network-share checkout.** npm symlinks the workspace package into root `node_modules` and the share rejects the symlink (`UNKNOWN ... symlink`, errno -4094). The package's own `node_modules` already carries its single dependency, so the driver and tests run without it. The installer also keeps working when `@jl-cmd/prompt-generator` cannot resolve — it skips that group with a warning (`discoverDependencyGroups` in `bin/install.mjs`).
-- **Microsoft Store Python is rejected on Windows.** The installer skips any interpreter under a `WindowsApps` directory because that stub cannot run as a hook subprocess (`isWindowsStorePythonStub` in `bin/install.mjs`). Install Python from python.org if detection fails.
-
-## Troubleshooting
-
-- **`ERROR: No usable Python 3 found`**: no `py -3` / `python3` / `python` resolves to a non-Store Python 3. Install Python 3.8+ from python.org and reopen the shell.
-- **`fatal: detected dubious ownership in repository`**: add the `safe.directory` exception shown above, then rerun.
-- **`ERROR: settings.json is malformed JSON`**: `~/.claude/settings.json` has a syntax error; fix the JSON and rerun.
-
-## Files
-
-- `SKILL.md` — this page: the agent path (the driver), the human install path, the test command, gotchas, and troubleshooting.
-- `driver.mjs` — the smoke harness that drives `bin/install.mjs` against a sandbox home directory. Run it; you do not need to read it. It sits beside this file at `.claude/skills/run-claude-dev-env/driver.mjs`.
-
-The `/run` skill auto-discovers this skill when asked to run, install, or test `claude-dev-env`.

package/.agents/skills/session-log/.claude/CLAUDE.md

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

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

@@ -1 +0,0 @@
-

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

@@ -1,170 +0,0 @@
----
-name: session-log
-description: >-
-  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
-
-## Overview
-
-Session-log composes the HTML report and publishes it directly with the `Artifact` tool. The skill owns the whole flow: where the file lives in the vault, what number it gets, the frontmatter metadata contract, HTML composition and publishing, post-write vault tracking, decision extraction, project-folder hygiene, and the closing `/rename` hand-off.
-
-**Announce at start:** "I'm logging this session."
-
-## Why this report is designed fresh per session
-
-Sessions come in many shapes — convergence loops, feature builds, research dives, incidents, refactors, decisions. A single h2-emoji-list template forces every session into the same form regardless of fit, and the artifact reads as a process log rather than a substance log. Load the `artifact-design` skill before composing any page content — it calibrates the design investment and shape to the session's character: a feature build reads naturally as a PR writeup, an incident or convergence loop as a timeline, a status update as a progress summary, a plan or decision as a decision record, an exploration as a multi-approach walkthrough.
-
-## Gotchas
-
-- **Load the `artifact-design` skill before writing page content.** The `Artifact` tool needs this step first — it is not optional polish.
-- **The `Artifact` tool wraps the file in a document skeleton at publish time.** It adds `<!doctype html>…<head>…</head><body>` around whatever the file holds — write page content only (a `<title>`, a `<style>` block, and the body markup). Do not include `<!DOCTYPE>`, `<html>`, `<head>`, or `<body>` tags in the file itself.
-- **The `Artifact` tool redeploys to the same URL only within the current run.** Editing the session's HTML file in a later step of this same skill run and calling `Artifact` again does not mint a new URL — it updates the same published page in place. A fresh session has no memory of an artifact's URL from an earlier run, so republishing a session report written in a prior session always mints a new URL (there is no other way to target the old one without the user supplying it).
-- **Vault paths sit outside `.claude/`.** Headless vault paths (e.g., `$OBSIDIAN_VAULT_PATH`) resolve outside the project tree. Session reports use HTML regardless of vault location — the Artifact tool needs a written file to publish.
-- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html. Apply `~/.claude/rules/asd-ste100-language.md` for user-facing word choice and sentence style, and keep the session report current and self-contained.
-- **`write_existing_file_blocker` rejects Write on existing paths.** Use Write only when creating a fresh session report; use Edit for the vault-context append in step 3.
-- **Obsidian frontmatter index is HTML-blind.** Obsidian's native YAML-frontmatter parser reads only `.md` files. HTML files do not appear in Obsidian's frontmatter index. Search by content still works; search by `type: session-report` does not.
-
-## Backend Detection (run before Step 1)
-
-Determine which storage backend is available for the write path. First success wins.
-
-1. **Headless vault** — Bash `ob --version` to verify the obsidian-headless CLI is installed. Check `OBSIDIAN_VAULT_PATH` env var or `~/.claude/vault/` for a vault directory. When the CLI check succeeds AND at least one of those paths resolves to a vault directory, set `backend = "headless"`.
-2. **Local vault** — fall back to `~/.claude/vault/`. Create `~/.claude/vault/sessions` via `mkdir -p` if missing. Set `backend = "local"`.
-
-session-log writes with Write/Edit and publishes with Artifact, so it uses headless or local filesystem paths only. `/session-tidy` Phase 0 reuses this headless → local order and adds an Obsidian MCP branch for vault maintenance.
-
-**Session-number detection:** Bash `ls` the project's session folder, parse filenames matching `[N]. *.html` or `[N]. *.md`. Highest N + 1. New project → start at 1.
-
-**Output paths:**
-- headless: `$OBSIDIAN_VAULT_PATH/sessions/[Project]/[N]. [Title].html` (falls back to `~/.claude/vault/` when the env var is unset)
-- local: `~/.claude/vault/sessions/[Project]/[N]. [Title].html`
-
-Announce the backend: "Using headless vault at [path]." or "Using local vault at ~/.claude/vault/. Install obsidian-headless and set the `OBSIDIAN_VAULT_PATH` environment variable (PowerShell: `$env:OBSIDIAN_VAULT_PATH = '<path>'`; POSIX shells: `export OBSIDIAN_VAULT_PATH=<path>`) to enable sync."
-
----
-
-## Step 1: Compose Session Metadata
-
-Review the conversation to identify the session's primary outcome and the small set of facts a cold reader needs.
-
-Resolve the metadata used by the frontmatter and the vault path:
-
-- **Project name:** infer from conversation context
-- **Session number:** from backend detection above
-- **Session ID:** the session ID of the agent authoring this log, read from the `CLAUDE_CODE_SESSION_ID` environment variable (PowerShell: `$env:CLAUDE_CODE_SESSION_ID`). This UUID names the authoring agent's own transcript file (`<session-id>.jsonl`), so the saved report points back to the exact session that produced it. When the variable is unset, use the literal `unknown`.
-- **Date:** today's date
-- **Title:** a 2–5 word summary of the session's primary outcome. Examples: "Amazon Auth Migration", "Source Loading Fix", "PR 475 Convergence". Avoid generic titles like "Bug Fixes".
-
-The frontmatter contract every session report carries (inside an HTML comment, as the first child of `<body>`) is the metadata block in [`templates/frontmatter.md`](templates/frontmatter.md).
-
-Every session report carries this metadata block verbatim so vault search and the tidy step in step 5 work. **Initial values for Step 2's Write:** substitute concrete values for every placeholder — for `session_id`, write the value read from `CLAUDE_CODE_SESSION_ID` in step 1 (or `unknown` when the variable is unset); for `vault_context_retrieved`, write the literal value `false` (the safe default before Step 3's vault-MCP-tool scan completes). Step 3 then Edits `vault_context_retrieved` to `true` if any of the three vault MCP tools fired this session.
-
-## Step 2: Compose and Publish the HTML via the Artifact Tool
-
-Load the `artifact-design` skill before writing any content. Design the artifact for **this session's character** — a feature build reads naturally as a PR writeup, an incident or convergence loop as a timeline, a status update as a progress summary, a plan or decision as a decision record, an exploration as a multi-approach walkthrough. The report must answer for a cold reader, from the section headers alone, three questions: *what shipped*, *why it matters*, *what impact it had*. Process narration (commit-by-commit walks, agent gotchas, retry counts) belongs at the end, not in the opening sections.
-
-**Required as the first content line:** the frontmatter HTML comment from step 1.
-
-**Required somewhere in the content:** a `<title>` element naming the session — it names the browser tab and the artifact gallery entry.
-
-**Required as the first content section (after the frontmatter comment):** an opening "What this session shipped" paragraph + bullets — written so a reader with zero prior context understands the outcome. For continuation sessions (where the substantive work landed in a prior session), recap the parent session's outcome briefly so the report stands alone.
-
-**Required: self-contained, responsive, theme-aware HTML.** Inline all CSS in a `<style>` block and all JS inline; embed any images as data URIs — the `Artifact` tool's content security policy blocks external CDN scripts, stylesheets, fonts, and network requests. Use relative units so the layout holds at any width, and support both light and dark via `prefers-color-scheme` (or `:root[data-theme]` overrides).
-
-**No document wrapper tags.** The `Artifact` tool wraps the file content in a `<!doctype html>…<head>…</head><body>` skeleton at publish time — write the `<title>`, `<style>`, and body markup directly, with no `<!DOCTYPE>`, `<html>`, `<head>`, or `<body>` tags of your own.
-
-Beyond those requirements, design the shape that fits the session — the `artifact-design` skill's guidance covers typography, palette, and layout choices.
-
-**Write the file** via the Write tool to the vault path. Create the project directory via `mkdir -p` if it does not exist.
-
-**Publish the file** by calling the `Artifact` tool with `file_path` set to the vault path just written, `favicon` set to the fixed session-log favicon `📓` — this favicon stays the same across every session-log report so the series reads as one consistent collection; never swap it per session — and `description` set to a one-sentence subtitle summarizing the session. Capture the returned URL: it is the canonical URL for this session report, and it stays the same across every later `Artifact` call on this same `file_path` within the current run (steps 3 and 5 redeploy to it rather than minting a new one).
-
-**If the Write fails**, output the HTML content in the conversation so the user can copy it manually. Before emitting the HTML to chat, resolve the `vault_context_retrieved` placeholder to `true` or `false` based on the same vault-MCP-tool scan that Step 3 would have run, and include the matching vault-context `<li>` line (Retrieved or Not retrieved) so the emitted HTML is a valid copy-paste artifact with complete frontmatter. Skip Step 3 and continue at step 4.
-
-## Step 3: Vault Context Tracking
-
-This step runs automatically after step 2.
-
-Review the conversation history for any use of these vault MCP tools (look only at tool calls the session made before /session-log itself ran):
-
-- `mcp__obsidian__search_notes`
-- `mcp__obsidian__read_note`
-- `mcp__obsidian__read_multiple_notes`
-
-Edit the vault HTML via two Edit calls:
-
-1. Set the frontmatter `vault_context_retrieved` field to `true` when any of the three tools fired this session, `false` otherwise.
-2. Append one fact — vault-context status — into whatever section the report designer placed for notes / metadata / references. If the report has no such section, append a fresh `<h2>Notes</h2>` block (in [`templates/frontmatter.md`](templates/frontmatter.md)) at the end of the content.
-
-If the report already has a notes / references section, use Edit to insert one matching child element at the end of that section. The element shape mirrors whatever the section already uses: an extra `<li>` before the closing `</ul>` for a list, an extra `<dt>Vault context</dt><dd>…</dd>` pair before the closing `</dl>` for a description list, an extra `<p><strong>Vault context:</strong> …</p>` before the section's closing tag for a paragraph-based section. Pick the form that matches the surrounding markup.
-
-After both Edits land, call the `Artifact` tool again with the same `file_path` and the same `favicon` used in step 2 to redeploy the updated content. This updates the URL captured in step 2 in place; no new URL is minted.
-
-## Step 4: Decision Extraction
-
-Scan the conversation for decisions, gotchas, or architectural choices that were not already saved via `/remember`. For each one found, ask the user via `AskUserQuestion`:
-
-> "I noticed this decision: [summary]. Save it to the vault via `/remember`?"
-
-Only invoke `/remember` for decisions the user confirms; `/remember` writes the decision as a vault note. If no unrecorded decisions are found, skip silently.
-
-## Step 5: Session Tidy (Project Scope)
-
-Scope: the current project's session folder only.
-
-1. **List files** in the project's vault session folder via Bash `ls`.
-2. **Audit** each `.html` and `.md` session file using the audit rules in `session-tidy` Phase 1 (naming, frontmatter completeness, type, status coherence, orphaned next-steps, categorization). session-tidy SKILL.md is the single home for those rules.
-3. **Auto-fix minor HTML metadata issues** via Edit (this step's write path is HTML-oriented):
-   - Missing frontmatter fields that can be inferred (e.g., `blocked: false` when status is `completed`; `vault_context_retrieved: false` when the field is absent)
-   - `type` field set to a wrong value (correct to `session-report`)
-
-   When the Edit touches the session report created in this run, call `Artifact` again with the same `file_path` and `favicon` from step 2 to redeploy — the URL captured in step 2 stays unchanged. When the Edit touches an older HTML session report published in a prior run, call `Artifact` on that `file_path` with no `url` argument, since this skill keeps no record of that file's earlier URL — this publishes that report at a new URL. Surface a `Session [N] republished at a new URL: <url>` line so the user can update any prior shares.
-4. **Report issues that need user input:**
-   - Files with wrong naming convention (propose new name)
-   - Stale statuses (propose update to `completed` or ask)
-   - Contradictory status/blocked combos
-
-   If no issues are found, skip silently. Do not report "all clean."
-5. **Rollup check:** if the project has 5+ sessions and no `Summary.html` or `Summary.md`, mention it:
-   > "This project has [N] sessions and no summary. Run `/session-tidy` for a project rollup."
-
-## Step 6: Finalize
-
-Copy a `/rename` command to the user's clipboard via PowerShell:
-
-```
-pwsh -NoProfile -Command "Set-Clipboard '/rename [Project] - [Primary Outcome]'"
-```
-
-Then tell the user:
-
-> "Copied `/rename [Project] - [Primary Outcome]` to your clipboard. Paste it to rename this session."
-
-The primary outcome comes from the session title resolved in step 1.
-
----
-
-## Run-and-report checklist
-
-- [ ] Backend detected and announced
-- [ ] Session number resolved from `[N]. *.html` and `[N]. *.md` files (highest N + 1)
-- [ ] `artifact-design` skill loaded before composing page content
-- [ ] HTML composed for this session's character (no document wrapper tags; self-contained, responsive, theme-aware)
-- [ ] Frontmatter HTML comment present as the first content line
-- [ ] `session_id` frontmatter field set from `CLAUDE_CODE_SESSION_ID` (the authoring agent's own session), or `unknown` when the variable is unset
-- [ ] Opening section answers "what shipped / why / impact" for a cold reader
-- [ ] Published via the `Artifact` tool with the fixed favicon `📓`; URL captured (or HTML emitted to chat when step 2 Write failed)
-- [ ] Vault-context line appended via Edit (step 3); `Artifact` redeployed on the same URL
-- [ ] Decision extraction surfaced any unrecorded items
-- [ ] Session tidy ran session-tidy Phase 1 audit rules on the project folder (or stayed silent when clean)
-- [ ] `/rename` command copied to clipboard via `pwsh Set-Clipboard`
-
-## Folder map
-
-- `SKILL.md` — this hub.
-- `templates/frontmatter.md` — the report frontmatter contract and the Step 3 notes block.

package/.agents/skills/session-log/templates/frontmatter.md

@@ -1,40 +0,0 @@
-# Session-log template blocks
-
-The two verbatim HTML blocks the `session-log` skill drops into every session
-page. The hub ([`../SKILL.md`](../SKILL.md)) points here from Step 1 / Step 2
-(frontmatter) and Step 3 (notes).
-
-## Frontmatter contract
-
-The first child of `<body>`, inside an HTML comment. Substitute a concrete value
-for every placeholder; `vault_context_retrieved` starts `false` and Step 3 sets
-it.
-
-```html
-<!--
-type: session-report
-project: [name]
-session: [N]
-session_id: [uuid]
-date: [YYYY-MM-DD]
-status: completed|in-progress|blocked
-blocked: true|false
-vault_context_retrieved: true|false
-tags: [session, [project-tag], [topic-tags]]
--->
-```
-
-## Notes block (Step 3)
-
-Append one vault-context line. When the page already carries a notes /
-references section, add a matching child element to that section; use the block
-below only when the page has no such section.
-
-```html
-<h2>Notes</h2>
-<ul>
-  <!-- Pick exactly one of the two forms based on whether vault MCP tools fired this session: -->
-  <li><strong>Vault context:</strong> Retrieved ([list of note paths])</li>
-  <li><strong>Vault context:</strong> Not retrieved</li>
-</ul>
-```

package/.agents/skills/session-tidy/.claude/CLAUDE.md

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

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

@@ -1 +0,0 @@
-

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

@@ -1,191 +0,0 @@
----
-name: session-tidy
-description: Audit, clean, and consolidate session logs in the Obsidian vault. Fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries. Use when session logs feel cluttered or before starting a new project milestone. Triggers on '/session-tidy', 'tidy sessions', 'clean up session logs', 'session audit'.
-disable-model-invocation: true
----
-
-# Session Tidy: Session Log Consolidation
-
-## Overview
-
-Audit and consolidate session logs in the Obsidian vault (`sessions/[Project]/`) by enforcing the tidy audit rules, categorizing uncategorized files into project subfolders, resolving orphaned next-steps, updating stale statuses, and generating project rollup summaries.
-
-**Announce at start:** "Running session log consolidation."
-
-**Context:** Standalone maintenance utility. Run periodically, after completing a project milestone, or when starting fresh on a project. Companion to `/dream` (memory consolidation) and `/session-log` (session creation).
-
-## The Format Contract
-
-**Write-side HTML contract:** `/session-log` owns how new session reports are written — vault path, HTML frontmatter comment block, Artifact publish, and body design. Read `journal:session-log` SKILL.md for that contract. The markdown field shapes below describe files tidy may read; they are not the write path for new session reports.
-
-**What tidy audits:** Project folders under `sessions/` may hold `.html` session reports and `.md` session files. Audit every session file present. The rules in this skill are the single home for tidy audit criteria.
-
-**Directory structure:** `sessions/[Project]/`
-- Session files match `[N]. [Title].html` or `[N]. [Title].md`, where Title is a 2-5 word summary of the primary outcome (e.g., `3. Amazon Auth Migration.html`)
-- Summary files are `Summary.html` or `Summary.md` in the same project folder
-- No parenthetical suffixes like `(Wrap-Up)`
-- Files missing a title (e.g., `Session 1.md` or `1.html`) should be flagged for renaming — read the content to derive a title
-
-**Shared metadata fields (required on every session file):**
-`type`, `project`, `session`, `date`, `status`, `blocked`, `tags`
-
-**HTML session reports** — when tidy reads a `.html` session file, metadata sits in an HTML comment block at the start of the file content. The write-side comment shape lives in session-log SKILL.md. HTML reports also carry `session_id` and `vault_context_retrieved`.
-
-**Markdown session files** — when tidy reads a `.md` session file, metadata sits in YAML frontmatter:
-
-```yaml
----
-type: session-report
-project: "[name]"
-session: [N]
-date: "[YYYY-MM-DD]"
-status: "completed" | "in-progress" | "blocked"
-blocked: true | false
-tags: ["session", "[project-tag]"]
----
-```
-
-**Content structure for markdown session files:**
-- Section headers (`###`) use one emoji + outcome-oriented title
-- Valid emojis: ✅ (done), 🚫 (blocked), ⚠️ (note), 🔧 (in-progress), 📋 (queued)
-- Explanatory paragraphs under each header, not just bullets
-- Tables for 3+ rows of structured data
-- No play-by-play or process narration
-
-**Content structure for HTML session reports:** Body shape is session-specific (session-log designs per session). Tidy does not enforce a fixed HTML section template. Audit naming, metadata completeness, type, status coherence, orphaned next-steps text in the body, and categorization.
-
-## The Process
-
-### Phase 0: Preflight
-
-Determine which storage backend is available. First success wins:
-
-1. **Headless vault** — same check as Backend Detection in `journal:session-log` SKILL.md: Bash `ob --version`, then `OBSIDIAN_VAULT_PATH` or `~/.claude/vault/`. When the CLI check succeeds and a vault directory resolves, set `backend = "headless"`.
-
-2. **Obsidian MCP** — call `mcp__obsidian__list_directory` with `path="sessions"`. If it succeeds, set `backend = "obsidian"`.
-
-3. **Local vault** — same fallback as session-log Backend Detection: `~/.claude/vault/`. Create `~/.claude/vault/sessions` via `mkdir -p` if missing. Set `backend = "local"`.
-
-**Capability notes by backend:**
-- **obsidian:** list, read, move, frontmatter update, and write via MCP tools (`list_directory`, `read_note`, `move_note`, `update_frontmatter`, `write_note`). For `.html` files, metadata edits use Read + Edit of the HTML comment block when MCP frontmatter tools do not apply.
-- **headless / local:** Move/rename via `mv` (Bash). Metadata update via Read + Edit/Write. Search via Bash `ls` + Grep.
-
-### Phase 1: Audit
-
-List project subdirectories in `sessions/` (MCP `list_directory` when backend is obsidian; Bash `ls` when headless or local). For each project folder, read its files. Also check for any files sitting directly in `sessions/` (uncategorized). Audit both `.html` and `.md` session files. For each file, check:
-
-1. **Naming convention?** Must match `[N]. [Title].html` or `[N]. [Title].md` where N is the session number and Title is a 2-5 word outcome summary. Flag bracket prefixes, date-only names, parenthetical suffixes, or patterns missing a title such as `Session 1.md` or `1.html`.
-2. **Frontmatter complete?** All shared required fields present: `type`, `project`, `session`, `date`, `status`, `blocked`, `tags`. For `.html` session reports, also require `session_id` and `vault_context_retrieved`.
-3. **Type correct?** Must be `session-report`. Flag other types.
-4. **Status coherent?** `status: completed` with `blocked: true` is contradictory. `status: in-progress` or `status: blocked` on sessions older than 7 days is likely stale.
-5. **Orphaned next-steps?** Scan content for sections containing "Next", "Queued", "Session N+1", "TODO", or clipboard emoji sections. Cross-reference against subsequent sessions for the same project to determine if the items were addressed.
-6. **Categorized?** Files sitting directly in `sessions/` (not in a project subfolder) are uncategorized. Infer the project name from the filename pattern (e.g., `BudgetBridge Session 3.md` belongs in `sessions/BudgetBridge/`) or from the frontmatter `project` field. Flag for a move into the correct subfolder.
-
-### Phase 2: Propose Changes
-
-Present a structured report:
-
-**Format violations** -- files with wrong naming, missing/wrong frontmatter fields, wrong type
-**Stale statuses** -- in-progress or blocked sessions older than 7 days, contradictory status+blocked combos
-**Orphaned next-steps** -- queued items from session N with no evidence of resolution in session N+1 or later. For each item, state whether it was:
-  - **Resolved:** found evidence in a later session
-  - **Orphaned:** no later session addresses it
-  - **Unknown:** later sessions exist but don't clearly address or skip the item
-**Uncategorized files** -- files in `sessions/` root that should live in a project subfolder
-**Rollup candidates** -- projects with 3+ sessions that have no `Summary.html` or `Summary.md`
-**Proposed actions** -- numbered list of specific changes
-
-Do NOT execute any changes yet. Wait for user approval.
-
-### Phase 3: Execute
-
-After user approves (all or selected items):
-
-1. **Rename** non-conforming files via `mcp__obsidian__move_note` (obsidian) or `mv` (headless/local). Keep the file's extension (`.html` or `.md`).
-2. **Fix frontmatter:**
-   - `.md` files: `mcp__obsidian__update_frontmatter` when backend is obsidian; Read + Edit/Write of YAML frontmatter when headless or local. Set correct type; add missing shared fields.
-   - `.html` files: Read + Edit of the HTML comment block fields (shape in session-log SKILL.md). Set correct type; add missing shared fields plus `session_id` and `vault_context_retrieved` when absent.
-3. **Update stale statuses** -- change old in-progress/blocked to completed (or ask user for correct status).
-4. **Clean orphaned next-steps** -- for confirmed orphaned items, either:
-   - Remove the section if all items are orphaned and the session is old
-   - Add a strikethrough or "(not pursued)" annotation if some items remain relevant
-   - Leave unchanged if user declines
-5. **Generate project rollups** -- for each qualifying project, write a summary note via `mcp__obsidian__write_note` (obsidian) or Write (headless/local):
-   - **Path:** `sessions/[Project]/Summary.md`
-   - **Frontmatter:** `{"type": "project-summary", "project": "[name]", "sessions": [count], "date_range": "[first] to [last]", "tags": ["summary", "[project-tag]"]}`
-   - **Content:** Use this template:
-
-```markdown
-## [Project] -- Project Summary
-
-### Timeline
-
-| # | Title | Date | Status |
-|---|-------|------|--------|
-| 1 | [title from filename] | [date] | ✅/🔧/🚫 |
-
-### Key Outcomes
-- **Session [N]:** [one-line summary of primary outcome]
-
-### Current Status
-[One paragraph: where the project stands now, what's active, what's done]
-
-### Carried Forward
-- [ ] [unresolved item from latest session]
-```
-6. **Categorize uncategorized files** -- move files from `sessions/` root into the correct project subfolder via `mcp__obsidian__move_note` or `mv`. When moving, rename to match the `[N]. [Title].html` or `[N]. [Title].md` convention for that file's extension (e.g., `sessions/BudgetBridge Session 3.md` becomes `sessions/BudgetBridge/3. [Title derived from content].md`).
-
-### Phase 4: Verify
-
-After execution, re-read the vault and confirm:
-- Every session file lives in a project subfolder under `sessions/[Project]/`
-- Every file has valid frontmatter with all required fields for its shape
-- Every filename matches the naming convention (`[N]. [Title].html`, `[N]. [Title].md`, `Summary.html`, or `Summary.md`)
-- No contradictory status/blocked combos
-- All orphaned next-steps resolved or annotated
-- Rollup summaries exist for qualifying projects
-
-Report the results: files renamed, frontmatter fixed, statuses updated, next-steps resolved, rollups generated.
-
-If Phase 1 finds zero issues across all checks, skip Phases 2-4 and report: "All session logs are tidy. Nothing to do."
-
-## Output Format
-
-Phase 2 report structure:
-
-```
-## Session Tidy Report
-
-### Format Violations (X found)
-- [file] -- [issue]
-
-### Stale Statuses (X found)
-- [file] -- [status] since [date] ([age] days ago)
-
-### Uncategorized Files (X found)
-- [file] -- move to sessions/[Project]/[new filename]
-
-### Orphaned Next-Steps (X found)
-- [file] -- "[item text]" -- [resolved/orphaned/unknown]
-
-### Rollup Candidates (X projects)
-- [project] -- [N] sessions, [date range], no summary exists
-
-### Proposed Actions
-1. [action] -- [file] -- [reason]
-2. ...
-
-Approve all, select by number, or cancel?
-```
-
-## After Completion
-
-Report summary: files renamed, frontmatter fixes, status updates, next-steps cleaned, rollups generated.
-
-## Best Practices
-
-- Run after finishing a multi-session project
-- Run before starting a new milestone on an existing project (clears stale context)
-- Cross-reference next-steps manually when the skill flags "unknown" -- it cannot determine intent from content alone
-- The 7-day staleness threshold is a heuristic -- adjust based on how frequently you session-log
-- Rollup summaries are not a replacement for individual session logs -- they are a navigational aid

package/.agents/skills/skill-builder/references/.claude/CLAUDE.md

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

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

@@ -1 +0,0 @@
-

package/.agents/skills/skill-builder/references/delegation-map.md

@@ -1,130 +0,0 @@
-# Delegation Map
-
-How skill-builder delegates authoring to the `skill-writer-agent` agent.
-
-## Delegating to skill-writer-agent (Step 4)
-
-skill-builder orchestrates; the `skill-writer-agent` agent authors the SKILL.md and companion files. The caller spawns it with `Agent(subagent_type="skill-writer-agent", ...)`. The handoff must be structured so the agent has everything it needs.
-
-### New skill handoff
-
-```
-Create a skill with these parameters:
-
-**Skill type:** [one of 9 types from skill-types.md]
-**Folder structure:** [directories to create: reference/, scripts/, etc.]
-**What it does:** [one-sentence capability — single job]
-**Domain context:** [what Claude needs to know that it doesn't already]
-**Initial gotchas:** [failure patterns to document from the start]
-**Degree of freedom:** [high | medium | low — with reasoning]
-**Constraints:** [non-negotiables]
-**Composition plan:** [related skills; sub-skills with when/produces/missing; leaf vs orchestrator]
-**Description (exact frontmatter string):** [capability stem. Triggers: phrase, phrase, ...]
-  — Trigger catalog only per description-field.md. No story prose.
-**Deterministic inventory:** [each process step → class → home path → paired test]
-  — Per deterministic-elements.md. Deterministic steps must be code/artifacts, not prose-only.
-
-Produce:
-1. SKILL.md with hub layout (principle, gotchas, when-applies, process, file index, folder map)
-2. Frontmatter description set to the exact trigger-catalog string above
-3. Sub-skills table in body when composition plan lists peer skills
-4. Companion files as needed (reference docs, workflow steps, templates, scripts)
-5. Scripts/workflows for every deterministic inventory row; body only points and handles exit codes
-6. Skill scripts follow CODE_RULES (`*_constants/`, types, specific errors, paired tests)
-7. Every file under 500 lines; TOC on files over 100 lines
-8. File index listing every file and its purpose
-9. No reimplementation of steps owned by named sub-skills
-```
-
-### Refine skill handoff
-
-```
-Refine this existing skill:
-
-**Current SKILL.md:** [reference or paste]
-**What was observed:** [specific failures from Claude B usage]
-**What to change:** [specific instructions to add/remove/modify]
-**New gotchas to add:** [failure patterns discovered]
-**What to preserve:** [working content — do not touch]
-**Description rewrite (if activation issue):** [exact new trigger-catalog string]
-**Composition change (if modularity issue):** [sub-skills to add/invoke or split plan]
-**Deterministic fix (if prose-only mechanical work):** [steps to extract → script/workflow/template paths + tests]
-
-Constraint: Only change what the observations demand. Do not reorganize working content.
-Description must remain a trigger catalog (description-field.md), never story prose.
-Deterministic steps must not remain prose-only (deterministic-elements.md).
-```
-
-## Spawning a test subagent
-
-To observe how Claude B uses a skill on a real task:
-
-```
-Agent(
-  subagent_type="general-purpose",
-  description="Test skill on real task",
-  prompt="Read the skill at [skill-path]/SKILL.md and follow its instructions.
-
-Task: [realistic user prompt]
-
-Save a complete transcript of your work to: [workspace]/transcript.md"
-)
-```
-
-Spawn with `run_in_background=true` for longer tasks. Read the transcript when the agent completes.
-
-## Reading a transcript for observations
-
-> "Watch for unexpected exploration paths, missed connections, overreliance on certain sections, and ignored content."
-
-Scan the transcript for:
-
-1. **File access order** — Did Claude read files in the expected order? Unexpected ordering means the structure is not intuitive.
-2. **Missed files** — Were any reference files never accessed? They might be unnecessary or poorly signaled.
-3. **Re-read files** — Did Claude re-read the same file multiple times? That content should be in SKILL.md.
-4. **Gotcha moments** — Where did Claude make a wrong choice? That's a gotcha candidate.
-5. **Script usage** — Did Claude execute scripts as expected, or did it try to read them instead?
-6. **Prose-as-code** — Did Claude reconstruct a multi-step mechanical sequence from markdown when a script should have run? Flag as deterministic-elements failure.
-7. **Tool call errors** — Any "tool not found" or path errors? Fix references.
-
-## Delegating self-audit
-
-After building, spawn a subagent to run the audit independently (task-tool first):
-
-```
-Agent(
-  subagent_type="general-purpose",
-  description="Self-audit skill via task seeds",
-  prompt="Read the skill at [skill-path]/SKILL.md and all companion files.
-
-Then read the self-audit task seeds at [skill-builder-path]/references/self-audit-checklist.md.
-
-Register every bullet as a session task (TaskCreate / TodoWrite). Complete each with PASS, FAIL+file:line+fix, or N/A+reason. Do not use markdown checkboxes as the tracker.
-
-Report as:
-## Audit Results
-- PASS: N
-- N/A: M
-- FAIL fixed: K
-- Remaining FAIL (must be empty): …
-"
-)
-```
-
-This gives an independent verification. Fix failures, then re-deliver to user.
-
-## Testing across models
-
-> "Test your Skill with all the models you plan to use it with."
-
-If the skill will be used with Haiku, spawn a haiku test subagent:
-
-```
-Agent(
-  subagent_type="general-purpose",
-  model="haiku",
-  ...
-)
-```
-
-Haiku needs more explicit guidance than Opus. Observe whether the skill provides enough.