claude-dev-env 2.0.1 → 2.1.0

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
 

package/skills/skill-builder/references/deterministic-elements.md

@@ -0,0 +1,218 @@
+# Deterministic skill elements
+
+Source: [Anthropic — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (scripts, progressive disclosure), [Lessons from Building Claude Code](thariq-x-post-skills.json), repo skill conventions (`skills/CLAUDE.md`), `docs/CODE_RULES.md`, host task tools (`TaskCreate`, `TodoWrite`, and equivalents).
+
+## Contents
+
+- [Rule](#rule)
+- [What counts as deterministic](#what-counts-as-deterministic)
+- [Placement](#placement)
+- [Task-tool tracking (not markdown checklists)](#task-tool-tracking-not-markdown-checklists)
+- [CODE_RULES bar (every code file in the skill)](#code_rules-bar-every-code-file-in-the-skill)
+- [Inventory (required before Write)](#inventory-required-before-write)
+- [Required task seeds (Gather / gates)](#required-task-seeds-gather--gates)
+- [Anti-patterns (fail self-audit)](#anti-patterns-fail-self-audit)
+- [How the body should look](#how-the-body-should-look)
+- [Relation to other skill-builder specs](#relation-to-other-skill-builder-specs)
+
+## Rule
+
+Any skill element that is **deterministic** ships as **code**, a **fixed artifact**, or a **session task** — never as prose-only work tracking.
+
+| Deterministic shape | Required home |
+|---|---|
+| Validators, transforms, detection, mechanical sequences | `scripts/` or `workflow/*.mjs` (+ tests, `*_constants/`) |
+| Verbatim templates | `templates/` |
+| Long fixed tables / catalogs Claude must not paraphrase | `reference/` |
+| Ordered work the agent must complete without skipping | Host **task tool** (`TaskCreate`, `TodoWrite`, or equivalent) |
+
+> "One of the most powerful tools you can give Claude is code — letting Claude spend its turns on composition rather than reconstructing boilerplate."
+
+> "These can include deterministic scripts or tools for maximum robustness."
+
+Judgment, routing, and refusal stay in markdown. Fixed procedures and transforms stay in scripts. Required step lists stay on the task list — not as markdown `[ ]` boxes.
+
+## What counts as deterministic
+
+A process step is deterministic when **all** of these hold:
+
+1. Same inputs → same outputs (no open-ended taste or design judgment).
+2. Success or failure is machine-checkable (exit code, schema, path exists, token present, task marked complete with evidence).
+3. A human could write the step as a pure function, a fixed command sequence, or a fixed task list.
+
+### Deterministic (must leave prose-only tracking)
+
+| Shape | Home |
+|---|---|
+| Validators, linters, schema/packet checks | `scripts/` (or `workflow/*.mjs`) |
+| Multi-step mechanical sequences (compile, collect, gate, scan) | `scripts/` |
+| Detection logic (regex sets, path rules, pattern catalogs) | `scripts/` + `*_constants/` |
+| Sorting, ranking, ID assignment, path resolution | `scripts/` |
+| Verbatim prompt or output templates | `templates/` (skill body points to the path) |
+| Long fixed tables / catalogs | `reference/` or a script that prints the list |
+| Inline Python / JS fences meant to run | Extract to `scripts/` or `workflow/` |
+| Ordered gates, audits, author checks the agent must finish | **Task tool** — seed each item; mark complete with evidence |
+
+### Judgment (markdown is correct)
+
+| Shape | Home |
+|---|---|
+| When to invoke the skill; refusal lines | `SKILL.md` |
+| How to weigh trade-offs or pick among valid approaches | `SKILL.md` / `reference/` |
+| Gotchas and failure modes | `SKILL.md` |
+| Sub-skill routing and composition | `SKILL.md` |
+| Degree-of-freedom guidance | `SKILL.md` |
+
+### Borderline
+
+- A one-liner that only launches a tool with no branching → may stay in body; the moment it grows patterns, branches, or magic strings → `scripts/`.
+- A short narrative process outline (Step 1 / Step 2 headings) may stay in body **if** every required work item is also registered on the task list. Headings are orientation; the task list is the completion surface.
+- Markdown `[ ]` as the only place an agent is expected to track progress → **always fail** when a task tool is available.
+
+## Placement
+
+| Artifact | Directory / surface | Role |
+|---|---|---|
+| Python helpers | `scripts/` | Run, do not load into context as source |
+| Workflow scripts | `workflow/` (`*.mjs`) | Host `Workflow` tool entrypoints |
+| Named constants | `*_constants/` next to the scripts that import them | CODE_RULES config surface for skill code |
+| Fixed templates | `templates/` | Copy/fill or pass to a script |
+| Domain tables, long fixed lists | `reference/` | Load on demand |
+| Required work items | Host task tool | Create at skill start; complete with evidence |
+| Process skeleton + pointers | `SKILL.md` | "Run `scripts/foo.py` …" / "Register tasks from …" |
+
+`SKILL.md` names the script, when to run it, what it prints, and how to treat non-zero exit. It does not restate the algorithm. It names which task-seed lists to load and when to register them.
+
+## Task-tool tracking (not markdown checklists)
+
+Harnesses expose task tools so agents cannot silently skip steps. A skill that expects the agent to finish an ordered set of work **must**:
+
+1. Publish the items as a **task seed list** (plain bullets or numbered lines in a reference file — **no** `- [ ]` syntax).
+2. Instruct the agent, at the start of that phase, to **create one session task per item** via the host tool:
+   - Prefer `TaskCreate` (or host `Task` / tasks MCP) when present.
+   - Else `TodoWrite` / equivalent.
+   - Fail closed: if no task tool exists, say so and stop — do not fall back to markdown checkboxes as the tracking plan.
+3. Require each task to be marked complete only with evidence (PASS / FAIL+file:line / N/A+reason / exit code / path).
+4. Ban "copy this checklist into your response and check it off" as the primary tracking method.
+
+Reference files may still **catalog** the required items so authors and agents know what to seed. Catalogs are data for `TaskCreate`; they are not the live work board.
+
+### Skills that ship multi-step process
+
+Any skill whose process has two or more required steps must include a short **Task seeding** instruction in `SKILL.md` or the active workflow:
+
+```markdown
+## Task seeding
+
+Before Step N, register every item under [reference/…-tasks.md] as a session task
+(TaskCreate / TodoWrite). Work only from the task list. Mark complete with evidence.
+```
+
+The seed list file lives under `reference/` (or is a named section of an existing reference). Do not use `- [ ]` in that file.
+
+## CODE_RULES bar (every code file in the skill)
+
+Skill scripts are production code. They obey the same rules as the rest of the repo (`docs/CODE_RULES.md` / root `AGENTS.md`), including:
+
+- **Named constants** — no bare magic numbers/strings in function bodies; skill-local values live in a `*_constants/` package the script imports.
+- **Types** — parameters and returns annotated; no bare `Any` / untyped escape hatches.
+- **Naming** — full words; `is_`/`has_` booleans; `all_` collections; `each_` multi-letter loops; banned prefixes (`handle_`, `process_`, `manage_`, `do_`).
+- **Errors** — catch specific exceptions; exit with a clear code and message; do not punt raw traces to Claude as the recovery plan.
+- **Tests** — every new production path ships a paired test in the same change (`test_*.py` beside the script, or `*.test.mjs` for workflow helpers).
+- **Execute intent** — body says `Run scripts/…` (execute), not "see the script for the algorithm," unless the script is deliberately reference-only.
+
+JS/TS skill helpers follow the same spirit: named constants, no silent stubs, paired tests.
+
+## Inventory (required before Write)
+
+Every new skill and every improve pass that touches process steps records a **deterministic elements inventory** in the gap analysis:
+
+| Column | Content |
+|---|---|
+| Step | Short name |
+| Class | `deterministic` \| `judgment` \| `borderline` |
+| Home | Path (`scripts/…`, `workflow/…`, `templates/…`, `reference/…`, `task-seed:…`, or `SKILL.md`) |
+| Evidence | Why this class (one line) |
+| Paired test | Path if code; `task-tool` if work list; N/A + reason if pure judgment |
+
+Rules:
+
+- Every `deterministic` row has a real path under `scripts/`, `workflow/`, `templates/`, `reference/`, or a `task-seed:` pointer — not prose-only.
+- Every code path under `scripts/` or `workflow/` has a paired test path (or a one-line pure-data reason).
+- Every required multi-step work list has a `task-seed:` home and a body instruction to register those tasks.
+- A `borderline` row kept in prose has a one-line why it is not worth extracting.
+
+## Required task seeds (Gather / gates)
+
+At the **deterministic-elements gate** (and again at self-audit), register **each** line below as its own session task, then complete it with evidence. Do not track these as markdown checkboxes.
+
+1. Every process step is classified (deterministic / judgment / borderline).
+2. Every deterministic step has a script, workflow, template, reference, or task-seed path — not prose-only.
+3. No fenced executable source lives only inside `SKILL.md` when it is meant to run.
+4. No multi-branch detection/validation logic lives only as an `rg`/`grep` one-liner in the body.
+5. Each script states execute vs read intent from the body.
+6. Each script uses a `*_constants/` (or equivalent) package for non-obvious literals.
+7. Each new script path has a paired test in the same delivery.
+8. `SKILL.md` process steps point at paths; they do not re-implement the script in markdown.
+9. Every required multi-step work list in the skill is a task-seed catalog plus a seed instruction — not a markdown `- [ ]` board.
+
+## Anti-patterns (fail self-audit)
+
+- Full Python/JS program in a markdown code fence as the skill's real implementation.
+- Giant shell one-liner with many alternations as the only form of a detector.
+- 10+ step mechanical verification sequence written only as numbered markdown with no script.
+- "Deterministic" claim in prose with no executable path Claude can run.
+- Script that dumps unhandled exceptions for Claude to interpret.
+- Magic literals and unnamed thresholds inside skill scripts.
+- New script with no paired test.
+- Markdown `- [ ]` checklist as the agent's progress tracker when a task tool is available.
+- "Copy this checklist into your response and check off items" as the skill's completion protocol.
+- Task-seed list written with checkbox syntax (`- [ ]`) so agents tick markdown instead of creating tasks.
+
+## How the body should look
+
+**Good (script):**
+
+```markdown
+## Step 3: Validate packet
+
+Run `scripts/validate_packet.py --packet <path>`.
+- Exit 0 → continue.
+- Exit 2 → fix listed paths, re-run (do not invent missing sections).
+```
+
+**Good (required work list):**
+
+```markdown
+## Task seeding
+
+Before self-audit, register every item in `reference/self-audit-tasks.md`
+as a session task (TaskCreate). Complete each with PASS / FAIL+evidence / N/A+reason.
+```
+
+**Bad:**
+
+```markdown
+## Step 3: Validate packet
+
+Check that README.md, packet.json, context/source-map.md, …
+Also run compileall, then pytest --collect-only, then scan for …
+(and three more mechanical steps only in prose)
+
+## Self-audit
+
+Copy this checklist into your response and check every box:
+- [ ] Item one
+- [ ] Item two
+```
+
+## Relation to other skill-builder specs
+
+| Spec | Concern |
+|---|---|
+| `progressive-disclosure.md` | Where files live and how the hub points to them |
+| `skill-modularity.md` | One capability; compose peer skills by name |
+| `description-field.md` | Frontmatter trigger catalog |
+| **This file** | Which elements must be code, task-tool lists, or fixed artifacts |
+
+Progressive disclosure alone does not satisfy this file: moving a mechanical sequence into `reference/` as prose still fails when the sequence is deterministic — it belongs in `scripts/` or on the task list.

package/skills/skill-builder/references/self-audit-checklist.md

@@ -1,109 +1,126 @@
-# Self-Audit Checklist
+# Self-Audit Task Seeds
 
 Mandatory post-build verification. Every item must pass before a skill is delivered. Run after writing a new skill, improving an existing one, or polishing.
 
-Source synthesis: [Anthropic best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Lessons from Building Claude Code](thariq-x-post-skills.json), model skills (bugteam, pr-converge).
+**How to run:** Register **each** bullet below as a session task (`TaskCreate`, `TodoWrite`, or host equivalent). Complete tasks only with evidence (PASS / FAIL+file:line / N/A+reason). Do not track progress as markdown `- [ ]` boxes in chat.
+
+Source synthesis: [Anthropic best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Lessons from Building Claude Code](thariq-x-post-skills.json), model skills (bugteam, pr-converge), host task tools.
 
 ## Core quality
 
-- [ ] **Conciseness** — Only context Claude doesn't already have. Every line justifies its token cost.
+- **Conciseness** — Only context Claude doesn't already have. Every line justifies its token cost.
   > "Default assumption: Claude is already very smart."
-- [ ] **Degree of freedom** — Matches task fragility. Low for narrow bridges, high for open fields.
+- **Degree of freedom** — Matches task fragility. Low for narrow bridges, high for open fields.
   > "Match the level of specificity to the task's fragility and variability."
-- [ ] **Naming convention** — Name uses gerund form (verb-ing) unless it's a well-known acronym or proper name. Lowercase, numbers, hyphens only. Max 64 chars. No reserved words.
+- **Naming convention** — Name uses gerund form (verb-ing) unless it's a well-known acronym or proper name. Lowercase, numbers, hyphens only. Max 64 chars. No reserved words.
   > "Use consistent naming patterns to make Skills easier to reference."
-- [ ] **Description is a trigger catalog** — Capability stem (what tokens) + concrete Triggers list (when). Third person. Max 1024 chars. No XML. Spec: `description-field.md`.
+- **Description is a trigger catalog** — Capability stem (what tokens) + concrete Triggers list (when). Third person. Max 1024 chars. No XML. Spec: `description-field.md`.
   > "The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
-- [ ] **Description is not a story** — No narrative prose, benefits language ("helps you"), first/second person, or process/implementation dump in frontmatter.
+- **Description is not a story** — No narrative prose, benefits language ("helps you"), first/second person, or process/implementation dump in frontmatter.
   > "The description field is not a summary — it's a description of when to trigger."
-- [ ] **Description match surface** — Includes specific phrases, slash forms, and file types a user would say; distinguishable from sibling skills.
+- **Description match surface** — Includes specific phrases, slash forms, and file types a user would say; distinguishable from sibling skills.
   > "Be specific and include key terms."
-- [ ] **SKILL.md body under 500 lines**
+- **SKILL.md body under 500 lines**
   > "Keep SKILL.md body under 500 lines for optimal performance."
-- [ ] **One level deep** — All reference files link directly from SKILL.md. No nested references.
+- **One level deep** — All reference files link directly from SKILL.md. No nested references.
   > "Claude may partially read files when they're referenced from other referenced files."
-- [ ] **TOC on files over 100 lines** — Every reference file >100 lines has a table of contents.
+- **TOC on files over 100 lines** — Every reference file >100 lines has a table of contents.
   > "This ensures Claude can see the full scope of available information even when previewing with partial reads."
-- [ ] **No time-sensitive claims** — Or isolated in "old patterns" section.
+- **No time-sensitive claims** — Or isolated in "old patterns" section.
   > "Don't include information that will become outdated."
-- [ ] **Consistent terminology** — One term per concept throughout.
+- **Consistent terminology** — One term per concept throughout.
   > "Consistency helps Claude understand and follow instructions."
-- [ ] **Forward slashes only** — File paths use `/`, not `\`.
+- **Forward slashes only** — File paths use `/`, not `\`.
   > "Unix-style paths work across all platforms."
-- [ ] **Default provided, not options menu** — One recommended approach, escape hatch for special cases.
+- **Default provided, not options menu** — One recommended approach, escape hatch for special cases.
   > "Don't present multiple approaches unless necessary. Provide a default with escape hatch."
-- [ ] **Gotchas section present** — Highest-signal content. Built from real failure observations.
+- **Gotchas section present** — Highest-signal content. Built from real failure observations.
   > "The highest-signal content in any skill is the Gotchas section."
-- [ ] **Doesn't state the obvious** — Pushes Claude out of defaults, doesn't re-teach what Claude knows.
+- **Doesn't state the obvious** — Pushes Claude out of defaults, doesn't re-teach what Claude knows.
   > "Focus on information that pushes Claude out of its normal way of thinking."
-- [ ] **Not railroading** — Gives information and flexibility, not rigid scripts.
+- **Not railroading** — Gives information and flexibility, not rigid scripts.
   > "Give Claude the information it needs, but give it the flexibility to adapt to the situation."
-- [ ] **When-this-applies section** — Trigger conditions clear. Refusal cases with exact response text.
+- **When-this-applies section** — Trigger conditions clear. Refusal cases with exact response text.
   > bugteam pattern — "Refusals — first match wins; respond with the quoted line exactly and stop."
-- [ ] **File index present** — Every file in the package listed with its purpose.
+- **File index present** — Every file in the package listed with its purpose.
   > "Tell Claude what files are in your skill, and it will read them at appropriate times."
-- [ ] **Concrete examples** — Input/output pairs or exit scenarios, not abstract descriptions.
+- **Concrete examples** — Input/output pairs or exit scenarios, not abstract descriptions.
   > "Examples help Claude understand the desired style and level of detail more clearly than descriptions alone."
-- [ ] **Workflows have checklists** — Multi-step processes include copyable `[ ]` checklists.
-  > "For particularly complex workflows, provide a checklist that Claude can copy into its response and check off as it progresses."
-- [ ] **Feedback loops where quality-critical** — Run validator → fix → repeat pattern.
+- **Workflows seed tasks** — Multi-step processes ship a task-seed list and instruct the agent to register each item on the host task tool (`TaskCreate` / `TodoWrite`). No markdown `- [ ]` as the progress board when a task tool is available.
+  > Spec: `deterministic-elements.md` — Task-tool tracking.
+- **Feedback loops where quality-critical** — Run validator → fix → repeat pattern.
   > "This pattern greatly improves output quality."
-- [ ] **Constraints separated** — Non-negotiables in CONSTRAINTS.md or equivalent section.
+- **Constraints separated** — Non-negotiables in CONSTRAINTS.md or equivalent section.
   > bugteam pattern — constraints file with design rationale.
-- [ ] **Folder map at bottom** — Lists directories and their purposes.
+- **Folder map at bottom** — Lists directories and their purposes.
   > pr-converge pattern — "Folder map" section.
 
 ## Skill-type-specific
 
-- [ ] **Skill type classified** — Fits one of 9 types. Folder structure matches type recommendation.
+- **Skill type classified** — Fits one of 9 types. Folder structure matches type recommendation.
   > "The best skills fit cleanly into one; the more confusing ones straddle several."
-- [ ] **Domain layout appropriate** — If multiple domains, organized by domain (reference/finance.md, reference/sales.md).
+- **Domain layout appropriate** — If multiple domains, organized by domain (reference/finance.md, reference/sales.md).
   > Pattern 2 — domain-specific organization.
 
-## Code and scripts (if applicable)
+## Deterministic elements
+
+Mandatory for every skill. Spec: `deterministic-elements.md`. Progressive disclosure alone does not satisfy these items.
 
-- [ ] **Scripts solve, don't punt** — Error handling explicit, no raw exceptions for Claude to figure out.
+- **Process steps classified** — Every process step is marked deterministic, judgment, or borderline (inventory in gap analysis or equivalent).
+  > "One of the most powerful tools you can give Claude is code."
+- **Deterministic steps are not prose-only** — Each deterministic step has a real path under `scripts/`, `workflow/`, `templates/`, `reference/`, or a task-seed list — not only markdown steps, fenced source, markdown checkboxes, or a giant shell one-liner in the body.
+  > "These can include deterministic scripts or tools for maximum robustness."
+- **Body points at code** — SKILL.md names when to run each script, what it prints, and how to treat non-zero exit; it does not restate the algorithm.
+  > "Make clear in your instructions whether Claude should execute the script or read it as reference."
+- **No executable-only fences** — Full programs meant to run do not live only inside `SKILL.md` code fences.
+- **CODE_RULES on skill scripts** — Any `scripts/` or `workflow/` code uses named constants (`*_constants/` or equivalent), type annotations where the language supports them, specific error handling, and no banned identifier/prefix patterns from CODE_RULES.
+- **Paired tests for new scripts** — Each new production script path ships a paired test in the same delivery (N/A only when the package has zero code files).
+- **Task seeds for required work lists** — Every ordered gate/audit/process list the agent must finish is a plain task-seed catalog plus a seed instruction; no markdown checkbox board.
+- **Scripts solve, don't punt** — Error handling explicit, no raw exceptions for Claude to figure out.
   > "Handle error conditions rather than punting to Claude."
-- [ ] **No voodoo constants** — Every magic number has a documented justification.
-  > "Configuration parameters should be justified and documented."
-- [ ] **Execute vs read intent clear** — "Run script.py" (execute) vs "See script.py for algorithm" (read).
+- **Execute vs read intent clear** — "Run script.py" (execute) vs "See script.py for algorithm" (read).
   > "Make clear in your instructions whether Claude should execute the script or read it as reference."
-- [ ] **Dependencies listed** — Required packages stated, verified as available.
+- **Dependencies listed** — Required packages stated, verified as available (N/A when no scripts).
   > "List required packages in your SKILL.md and verify they're available."
-- [ ] **MCP tools fully qualified** — `ServerName:tool_name` format.
+- **MCP tools fully qualified** — `ServerName:tool_name` format when MCP tools appear.
   > "Always use fully qualified tool names to avoid 'tool not found' errors."
-- [ ] **Plan-validate-execute for high-stakes ops** — Verifiable intermediate outputs before destructive actions.
+- **Plan-validate-execute for high-stakes ops** — Verifiable intermediate outputs before destructive actions (N/A when no high-stakes ops).
   > "Catches errors early: validation finds problems before changes are applied."
 
 ## Setup and memory (if applicable)
 
-- [ ] **Setup instructions clear** — config.json pattern or AskUserQuestion for initial context.
+- **Setup instructions clear** — config.json pattern or AskUserQuestion for initial context.
   > "If the config is not set up, the agent can then ask the user for information."
-- [ ] **Persistent data uses `${CLAUDE_PLUGIN_DATA}`** — Not stored in skill directory itself.
+- **Persistent data uses `${CLAUDE_PLUGIN_DATA}`** — Not stored in skill directory itself.
   > "Data stored in the skill directory may be deleted when you upgrade the skill."
 
 ## Modularity and composition
 
 Mandatory for every skill. Spec: `skill-modularity.md`. Progressive disclosure (file split) does not satisfy these items.
 
-- [ ] **Single capability boundary** — One clear job in one sentence. Unrelated jobs are separate skills or an orchestrator that only routes to named sub-skills.
+- **Single capability boundary** — One clear job in one sentence. Unrelated jobs are separate skills or an orchestrator that only routes to named sub-skills.
   > "The best skills fit cleanly into one; the more confusing ones straddle several."
-- [ ] **Compose before reimplement** — Steps an existing skill already owns are invoked by name, not pasted into this package. Local reimplementation has a one-line why in the gap analysis or gotchas.
+- **Compose before reimplement** — Steps an existing skill already owns are invoked by name, not pasted into this package. Local reimplementation has a one-line why in the gap analysis or gotchas.
   > "You can just reference other skills by name, and the model will invoke them if they are installed."
-- [ ] **Sub-skills table (when composing)** — Each invoked skill lists when to call it, what it produces, and missing-install behavior. N/A only when the skill is a pure leaf (invokes no peers).
+- **Sub-skills table (when composing)** — Each invoked skill lists when to call it, what it produces, and missing-install behavior. N/A only when the skill is a pure leaf (invokes no peers).
   > "You may want to have skills that depend on each other."
-- [ ] **Sibling boundary clear** — Description and when-this-applies distinguish this skill from related skills in the same domain. No silent overlap.
+- **Sibling boundary clear** — Description and when-this-applies distinguish this skill from related skills in the same domain. No silent overlap.
   > "The description field is not a summary — it's a description of when to trigger."
-- [ ] **No monolith packing** — Multi-capability content is not stuffed under one description. Either split packages or thin orchestrator + peer sub-skills (not nested fake skills under `workflows/`).
+- **No monolith packing** — Multi-capability content is not stuffed under one description. Either split packages or thin orchestrator + peer sub-skills (not nested fake skills under `workflows/`).
   > skill-modularity.md — anti-patterns: monolith, silent reimplementation, folder nesting as composition.
 
 ## Hooks (if applicable)
 
-- [ ] **Hooks declared** — If skill registers hooks, their purpose and scope is stated.
+- **Hooks declared** — If skill registers hooks, their purpose and scope is stated.
   > "Skills can include hooks that are only activated when the skill is called."
 
 ---
 
 ## Usage
 
-Copy this checklist into your response after building. Check off each item. Any item that fails → fix before delivering. Any item marked "if applicable" that doesn't apply → mark N/A with a one-line reason. Sub-skills table may be N/A for pure leaf skills; single capability boundary and no-monolith never are.
+1. Register every bullet in this file as a session task (batch create is fine).
+2. Work only from the task list. Mark complete with PASS, FAIL+file:line+fix, or N/A+one-line reason.
+3. Any FAIL must be fixed before delivery; re-open a task if the fix needs re-check.
+4. Sub-skills table may be N/A for pure leaf skills; single capability boundary and no-monolith never are. Process-step classification and "deterministic steps are not prose-only" never are N/A — pure-judgment skills still inventory steps and mark each as judgment.
+5. Deliver a short audit summary (counts of PASS / N/A / FAIL fixed) — not a markdown checkbox dump.
+