claude-dev-env 2.0.2 → 2.2.0

package/skills/privacy-hygiene/SKILL.md

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

package/skills/privacy-hygiene/reference/sweep-procedure.md

@@ -0,0 +1,62 @@
+# Full-tree PII sweep procedure
+
+The on-demand full-repository sweep for the `privacy-hygiene` skill — the
+complement to the write-time `pii_prevention_blocker`, which scans one payload at
+a time. The canonical per-payload patterns live in the hooks' `pii_scanner` and
+`pii_prevention_constants` modules; the ripgrep command below is the only
+full-tree pass. The hub ([`../SKILL.md`](../SKILL.md)) points here.
+
+## 1. Scope the tree
+
+```
+git status -sb
+git diff --stat
+git diff --cached --stat
+```
+
+Prefer the branch diff vs `origin/main` for PR prep:
+
+```
+git fetch origin main
+git diff --name-only origin/main...HEAD
+```
+
+## 2. Search for high-confidence patterns
+
+Run from the repo root (PowerShell-friendly example):
+
+```
+rg -n --hidden -g '!node_modules' -g '!.git' -e '@[A-Za-z0-9.-]+\.[A-Za-z]{2,}' -e 'Users[/\\][^/\\]+' -e '[/]home/[^/]+' -e '\b(10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[0-1])\.\d+\.\d+)\b' -e '\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b' -e '\bgithub_pat_[A-Za-z0-9_]{20,}\b' -e '\bAKIA[0-9A-Z]{16}\b' -e '-----BEGIN [A-Z ]*PRIVATE KEY-----'
+```
+
+Review each hit. Ignore:
+
+- Test fixtures under `test_*.py` / `*_test.py` / `/tests/` (synthetic only)
+- `LICENSE` / copyright notice identity that is intentional and public
+- This package's own `pii_scanner` / `pii_prevention_constants` modules
+- Documented placeholders (`user@example.com`, `C:/Users/<you>/`)
+
+## 3. Remediate
+
+| Hit | Fix |
+|---|---|
+| Real email | Replace with `user@example.com` or remove |
+| Home path | Use `Path.home()`, `~`, or `C:/Users/<you>/` |
+| LAN address | Remove, use a hostname, or — for your own NAS — set the host in `CLAUDE_NAS_HOST` or `~/.claude/local-identity.json`, both of which stay out of git |
+| Credential material | Remove from the tree; rotate the credential; load from env/secret store |
+| Already committed | Rewrite is not enough if already pushed — rotate secrets; scrub history only with explicit user approval |
+
+## 4. Re-check before commit / post
+
+- Stage only clean files
+- Prefer `--body-file` for `gh` posts (also required by the gh-body-file rule)
+- Let `pii_prevention_blocker` re-run on the next Write / commit / post
+
+## Accepted residual (do not over-scrub)
+
+- LICENSE copyright lines naming a legal person or org that owns the work
+- Intentional public maintainer identity published on purpose
+- Example domains reserved for documentation (`example.com` and siblings)
+- Placeholder home users (`example`, `user`, `alice`, `<you>`, `YOUR_USER`)
+- The NAS host you configure locally (allowlisted at scan time, never committed)
+- Public addresses and docs that name private ranges without a live host (still prefer hostnames)

package/skills/session-log/CLAUDE.md

@@ -12,7 +12,8 @@ Produces a self-contained HTML session report shaped to the session's character
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Hub — six steps, gotchas, backend detection, frontmatter contract, run-and-report checklist. Single-file skill; no companion files. |
+| `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
 

package/skills/session-log/SKILL.md

@@ -60,21 +60,7 @@ Resolve the metadata used by the frontmatter and the vault path:
 - **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>`):
-
-```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]]
--->
-```
+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.
 
@@ -113,16 +99,7 @@ Review the conversation history for any use of these vault MCP tools (look only
 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 at the end of the content:
-
-```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>
-```
+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.
 
@@ -189,4 +166,5 @@ The primary outcome comes from the session title resolved in step 1.
 
 ## Folder map
 
-- `SKILL.md` — this hub. Single-file skill; no companions.
+- `SKILL.md` — this hub.
+- `templates/frontmatter.md` — the report frontmatter contract and the Step 3 notes block.

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

@@ -0,0 +1,40 @@
+# 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/skills/skill-builder/CLAUDE.md

@@ -1,12 +1,12 @@
 # skill-builder
 
-Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via `skill-writer`, enforce modularity (sub-skills / composition), write description as a trigger catalog, self-audit, and refine from real usage.
+Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via `skill-writer`, 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.
+**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, use `/skill-writer` directly. This skill classifies, scaffolds, gathers context (including composition plan and description triggers), delegates writing, and self-audits.
+Enforces craft standards for new and existing skills. For quick one-off SKILL.md edits, use `/skill-writer` directly. This skill classifies, scaffolds, gathers context (composition plan, description triggers, deterministic inventory), delegates writing, and self-audits.
 
 ## Key files
 
@@ -17,13 +17,14 @@ Enforces craft standards for new and existing skills. For quick one-off SKILL.md
 | `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/self-audit-checklist.md` | Mandatory post-build audit |
+| `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 |
+| `templates/gap-analysis.md` | Gaps, composition plan, description triggers, deterministic inventory |
 
 ## Subdirectories
 
@@ -43,6 +44,6 @@ Enforces craft standards for new and existing skills. For quick one-off SKILL.md
 ## Conventions
 
 - Every build ends with the self-audit at `references/self-audit-checklist.md`; fix failures before delivery.
-- Modularity items and description trigger-catalog items are mandatory on every delivery.
-- `skill-builder` orchestrates; `skill-writer` authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, degree-of-freedom assessment, and constraints.
+- Modularity items, description trigger-catalog items, and deterministic-element classification are mandatory on every delivery.
+- `skill-builder` orchestrates; `skill-writer` 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.

package/skills/skill-builder/SKILL.md

@@ -2,9 +2,10 @@
 name: skill-builder
 description: >-
   Skill lifecycle: classify, scaffold, write via skill-writer, self-audit, compose
-  sub-skills, polish description triggers. Triggers: build a skill, new skill
-  workflow, improve this skill, optimize skill description, skill development
-  lifecycle, skill modularity, skill composition, description trigger catalog.
+  sub-skills, polish description triggers, enforce deterministic scripts. Triggers:
+  build a skill, new skill workflow, improve this skill, optimize skill description,
+  skill development lifecycle, skill modularity, skill composition, description
+  trigger catalog, deterministic skill scripts.
 ---
 
 # Skill Builder
@@ -22,6 +23,8 @@ Highest-signal content. Append a bullet each time a skill build fails in a new w
 - Story-form `description` burns always-on context and weakens selection — rewrite to capability stem + `Triggers:` list (`description-field.md`).
 - Multi-capability packages fail modularity audit — split or thin orchestrator + named sub-skills (`skill-modularity.md`).
 - Skipping the composition plan before Write reintroduces silent reimplementation of peer skills.
+- Deterministic steps written only as prose (fenced source, giant `rg` lines, multi-step mechanical sequences) fail audit — extract to `scripts/` / `workflow/` / `templates/` / `reference/` (`deterministic-elements.md`).
+- Markdown `- [ ]` checklists as the agent's progress board fail audit when a task tool exists — seed tasks via `TaskCreate` / `TodoWrite` (`deterministic-elements.md`).
 
 ## When this skill applies
 
@@ -116,11 +119,13 @@ Mandatory highest-signal section (see Gotchas above). Capture real failure modes
 
 Use the template pattern for structured outputs. Use the examples pattern (input/output pairs) for style-dependent work.
 
-### Workflows and checklists
+### Workflows and task seeds
 
-> "For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses."
+Multi-step required work is a **task seed list** (plain bullets in a reference file) plus an instruction to register each item on the host task tool (`TaskCreate`, `TodoWrite`, or equivalent). Agents work the task list and mark complete with evidence.
 
-Multi-step processes get `[ ]` checklists. Quality-critical operations get feedback loops (run validator → fix → repeat).
+Do **not** ship markdown `- [ ]` boards as the completion protocol when a task tool is available. Do **not** say "copy this checklist into your response and check it off."
+
+Quality-critical operations still use feedback loops (run validator → fix → repeat). Spec: [`references/deterministic-elements.md`](references/deterministic-elements.md) (Task-tool tracking).
 
 ### Scripts
 
@@ -128,6 +133,14 @@ Multi-step processes get `[ ]` checklists. Quality-critical operations get feedb
 
 > "One of the most powerful tools you can give Claude is code — letting Claude spend its turns on composition rather than reconstructing boilerplate."
 
+### Deterministic elements (mandatory classification)
+
+Any skill element that is **deterministic** (same inputs → same outputs; machine-checkable success) ships as code, a fixed artifact, or a **session task seed** — not prose-only steps or markdown checkbox boards. Judgment, routing, and refusals stay in markdown.
+
+Full rules, inventory table, task-tool tracking, CODE_RULES bar for skill scripts, and anti-patterns: [`references/deterministic-elements.md`](references/deterministic-elements.md).
+
+New-skill Gather records a deterministic-elements inventory before write. Self-audit items register as session tasks and are mandatory on every delivery (pure-judgment skills mark script rows N/A with evidence).
+
 ### Setup and memory
 
 > "Think through the Setup — some skills may need to be set up with context from the user. A good pattern is to store this in a config.json file."
@@ -142,22 +155,23 @@ Multi-step processes get `[ ]` checklists. Quality-critical operations get feedb
 
 > No Windows paths. Don’t offer too many options — provide a default with escape hatch. Avoid time-sensitive claims. Use consistent terminology. No deeply nested references.
 
-Also: story-form descriptions; monolith multi-capability skills; silent reimplementation of peer skills; nested folders used as fake sub-skills.
+Also: story-form descriptions; monolith multi-capability skills; silent reimplementation of peer skills; nested folders used as fake sub-skills; deterministic logic only in prose or fenced source; markdown `- [ ]` as the agent's work tracker.
 
 ## Self-audit
 
-After every build, improvement, or polish pass, run the mandatory checklist at `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`. Every item must pass before delivery. Fix failures, then re-audit.
+After every build, improvement, or polish pass, load `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`, **register every bullet as a session task**, and complete each with evidence. Every item must pass before delivery. Fix failures, then re-audit.
 
 ## Delegation to skill-writer
 
 skill-builder orchestrates; skill-writer authors. The handoff packet from Step 4 must include:
 
 - Skill type and folder structure
-- Gap analysis or observation findings (composition plan + description triggers)
+- Gap analysis or observation findings (composition plan + description triggers + deterministic inventory)
 - Degree of freedom assessment
 - Initial gotchas
 - Composition plan: related skills, sub-skills to invoke, split decisions
 - Description trigger catalog: capability stem + trigger phrases (not prose)
+- Deterministic elements inventory: each process step classified; code paths + paired tests
 - Any constraints
 
 See `${CLAUDE_SKILL_DIR}/references/delegation-map.md` for exact patterns.
@@ -171,12 +185,13 @@ See `${CLAUDE_SKILL_DIR}/references/delegation-map.md` for exact patterns.
 | `references/progressive-disclosure.md` | Folder conventions, hub pattern, 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/self-audit-checklist.md` | Mandatory post-build audit (core, modularity, description) |
+| `references/deterministic-elements.md` | Deterministic steps as code/task seeds; CODE_RULES; no markdown checkbox boards |
+| `references/self-audit-checklist.md` | Post-build audit task seeds (register via TaskCreate / TodoWrite) |
 | `references/delegation-map.md` | Subagent handoff patterns and transcript guidance |
 | `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 |
+| `templates/gap-analysis.md` | Gaps, composition plan, description triggers, deterministic inventory |
 
 ## Folder map
 

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

@@ -6,11 +6,12 @@ Best-practice specifications and the mandatory self-audit checklist for the `/sk
 
 | File | Purpose |
 |---|---|
-| `self-audit-checklist.md` | Checklist after every build, improvement, or polish pass. Every item must pass before delivery. |
+| `self-audit-checklist.md` | Audit task seeds after every build, improve, or polish. Register via TaskCreate / TodoWrite. |
 | `skill-types.md` | 9-type skill taxonomy with folder structures per type. |
 | `progressive-disclosure.md` | Hub pattern, folder conventions, hard rules: SKILL.md under 500 lines, one-level references. |
 | `skill-modularity.md` | Cross-skill modularity: one capability, sub-skills by name, composition plan, anti-monolith. |
 | `description-field.md` | Frontmatter description as trigger catalog (capability stem + Triggers). No story prose. |
+| `deterministic-elements.md` | Classify process steps; deterministic ones ship as code, task seeds, or fixed artifacts under CODE_RULES. |
 | `delegation-map.md` | Subagent handoff patterns and transcript guidance for skill-builder → skill-writer. |
 | `thariq-x-post-skills.json` | Source reference data from Anthropic lessons on building Claude Code skills. |
 
@@ -20,4 +21,5 @@ Best-practice specifications and the mandatory self-audit checklist for the `/sk
 - `self-audit-checklist.md` always loads at the end of a build cycle.
 - Load `skill-modularity.md` during Gather and when scope/overlap is diagnosed.
 - Load `description-field.md` during Gather, polish Step 1, and any activation diagnosis.
+- Load `deterministic-elements.md` during Gather, when prose-as-code is diagnosed, and on polish structure audit.
 - `thariq-x-post-skills.json` is source reference data, not executable content.

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

@@ -21,15 +21,19 @@ Create a skill with these parameters:
 **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)
-5. Every file under 500 lines; TOC on files over 100 lines
-6. File index listing every file and its purpose
-7. No reimplementation of steps owned by named sub-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
@@ -44,9 +48,11 @@ Refine this existing skill:
 **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
@@ -78,27 +84,30 @@ Scan the transcript for:
 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. **Tool call errors** — Any "tool not found" or path errors? Fix references.
+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 checklist independently:
+After building, spawn a subagent to run the audit independently (task-tool first):
 
 ```
 Agent(
   subagent_type="general-purpose",
-  description="Self-audit skill against checklist",
+  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 checklist at [skill-builder-path]/references/self-audit-checklist.md.
+Then read the self-audit task seeds at [skill-builder-path]/references/self-audit-checklist.md.
 
-Check every item. For each: PASS, FAIL with specific file:line evidence and what to fix, or N/A with reason.
+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
-[ ] Item 1: PASS
-[ ] Item 2: FAIL — [file:line] — [what's wrong and how to fix]
-..."
+- PASS: N
+- N/A: M
+- FAIL fixed: K
+- Remaining FAIL (must be empty): …
+"
 )
 ```
 

package/skills/skill-builder/references/description-field.md

@@ -85,19 +85,17 @@ description: You can use this to process Excel files
 3. List **near-misses** that must *not* select it (sibling skills). Fold only the shortest distinguishing tokens into Triggers if needed.
 4. Assemble stem + `Triggers:` list. Strip adjectives, benefits, and process narrative.
 5. Count characters (≤1024). Prefer under ~400 when possible — every skill’s description is always loaded.
-6. Run the checklist below.
+6. Register the task seeds below on the session task list (`TaskCreate` / `TodoWrite`); complete each with evidence. Do not use markdown checkboxes as the tracker.
 
-## Description checklist
+## Description task seeds
 
-```
-- [ ] Third person; no I/you
-- [ ] Capability stem present (what), ≤20 words of tokens
-- [ ] Triggers: segment (or equivalent dense when-list) with concrete phrases
-- [ ] No story prose, benefits language, or implementation steps
-- [ ] No XML; length ≤1024
-- [ ] Distinguishable from sibling skills in the same domain
-- [ ] Body holds process detail — not the description
-```
+- Third person; no I/you
+- Capability stem present (what), ≤20 words of tokens
+- Triggers: segment (or equivalent dense when-list) with concrete phrases
+- No story prose, benefits language, or implementation steps
+- No XML; length ≤1024
+- Distinguishable from sibling skills in the same domain
+- Body holds process detail — not the description
 
 ## Where process lives