claude-dev-env 2.0.2 → 2.1.0

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

@@ -100,14 +100,13 @@ Self-audit requires this table (or equivalent) whenever the skill composes other
 - **Vague dependency** — "use other skills as needed" with no names, when, or outputs.
 - **Redundant twin** — a new skill whose description overlaps an existing one without a refusal boundary.
 
-## Checklist for authors
+## Task seeds for authors
 
-Copy into the response during new-skill Gather and improve Diagnose:
+Register each item as a session task during new-skill Gather and improve Diagnose (`TaskCreate` / `TodoWrite`). Complete with evidence. Do not track as markdown checkboxes.
+
+- Capability fits one sentence without an unrelated "and"
+- Related skills scanned; inventory written
+- Reusable steps map to named skills (or justify local procedure)
+- Multi-capability work is split or is an orchestrator with sub-skills
+- SKILL.md will name each sub-skill with when + produces + missing behavior
 
-```
-- [ ] Capability fits one sentence without an unrelated "and"
-- [ ] Related skills scanned; inventory written
-- [ ] Reusable steps map to named skills (or justify local procedure)
-- [ ] Multi-capability work is split or is an orchestrator with sub-skills
-- [ ] SKILL.md will name each sub-skill with when + produces + missing behavior
-```

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

@@ -6,9 +6,9 @@ Reusable templates for skill-building artifacts.
 
 | File | Purpose |
 |---|---|
-| `gap-analysis.md` | Template for gaps, composition plan, and description triggers. Used in new-skill Gather and improve diagnosis. |
+| `gap-analysis.md` | Template for gaps, composition plan, description triggers, and deterministic-elements inventory. Used in new-skill Gather and improve diagnosis. |
 
 ## Conventions
 
 - Fill the template inline during the workflow; do not commit completed gap analyses to this directory.
-- Composition plan and Description triggers sections are required before Write on a new skill.
+- Composition plan, Description triggers, and Deterministic Elements Inventory sections are required before Write on a new skill.

package/skills/skill-builder/templates/gap-analysis.md

@@ -36,6 +36,21 @@ description: >-
   <stem>. Triggers: <phrases>.
 ```
 
+## Deterministic Elements Inventory
+
+See `references/deterministic-elements.md`. Required before Write.
+
+| Step | Class (`deterministic` / `judgment` / `borderline`) | Home path | Evidence (one line) | Paired test (if code) |
+|---|---|---|---|---|
+| [step name] | [class] | [`scripts/…` / `workflow/…` / `templates/…` / `reference/…` / `SKILL.md`] | [why this class] | [`test_…` / N/A + reason] |
+
+Rules:
+
+- Every `deterministic` row has a real path under `scripts/`, `workflow/`, `templates/`, `reference/`, or `task-seed:…` — not prose-only.
+- Every code path has a paired test path (or a one-line pure-data reason).
+- Every required multi-step work list uses `task-seed:…` plus a body seed instruction (no markdown `- [ ]` board).
+- A `borderline` row kept in prose has a one-line why it stays in the body.
+
 ## Gaps Identified
 
 ### Gap 1: [Descriptive Name]

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

@@ -6,14 +6,14 @@ Step-by-step workflow files for each skill lifecycle phase, loaded on demand by
 
 | File | Purpose |
 |---|---|
-| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers), write via skill-writer, self-audit, deliver. |
-| `improve-skill.md` | Observation-first improve: diagnose activation/modularity/quality, targeted fix, re-audit. |
-| `polish-skill.md` | Description trigger-catalog audit, progressive disclosure + modularity audit, checklist sign-off. |
+| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers + deterministic inventory), write via skill-writer, self-audit, deliver. |
+| `improve-skill.md` | Observation-first improve: diagnose activation/modularity/quality/deterministic prose, targeted fix, re-audit. |
+| `polish-skill.md` | Description trigger-catalog audit; progressive disclosure + modularity + deterministic audit; task-seeded self-audit. |
 
 ## Conventions
 
 - `SKILL.md` routes to exactly one workflow file per invocation based on the user's intent (new / improve / polish).
 - Each workflow references `../references/self-audit-checklist.md` at its final verification step.
-- New and improve load `skill-modularity.md` and `description-field.md` when gathering or diagnosing.
-- Polish Step 1 is the dedicated description rewrite pass.
+- New and improve load `skill-modularity.md`, `description-field.md`, and `deterministic-elements.md` when gathering or diagnosing.
+- Polish Step 1 is the dedicated description rewrite pass; Step 2 covers structure, modularity, and deterministic placement.
 - Load only the workflow that matches the active task; the other two stay out of context.

package/skills/skill-builder/workflows/improve-skill.md

@@ -52,10 +52,16 @@ Failure classification:
 | Claude over-explains basics | Skill states what Claude already knows | Principles: Concision |
 | Claude follows instructions too rigidly | Skill railroads instead of guiding | Principles: Degree of freedom |
 | Claude makes same mistake repeatedly | Missing gotcha | Principles: Gotchas |
-| Claude errors on script execution | Script doesn’t handle errors, missing deps | Principles: Scripts |
+| Claude errors on script execution | Script doesn’t handle errors, missing deps | Principles: Scripts + `deterministic-elements.md` CODE_RULES bar |
 | Output format is wrong | Missing template or examples | Principles: Templates and examples |
+| Mechanical sequence only in markdown | Deterministic work left as prose | `deterministic-elements.md` — extract to scripts/workflow |
+| Detection/validation is a giant one-liner in body | Executable logic not in `scripts/` | `deterministic-elements.md` |
+| Fenced Python/JS in SKILL.md is the real implementation | Code not shipped as a file | Extract to `scripts/` or `workflow/` + paired test |
+| Script has magic literals / no tests | CODE_RULES bar missed | `deterministic-elements.md` + CODE_RULES |
+| Skill uses `- [ ]` for agent progress | Work list not on task tool | Task-seed catalog + seed instruction (`deterministic-elements.md`) |
+| "Copy checklist into response" protocol | Markdown as tracker | Switch to TaskCreate / TodoWrite seeding |
 
-When scope or activation is in play, re-read `${CLAUDE_SKILL_DIR}/references/skill-modularity.md` and `${CLAUDE_SKILL_DIR}/references/description-field.md`.
+When scope, activation, or deterministic placement is in play, re-read `${CLAUDE_SKILL_DIR}/references/skill-modularity.md`, `${CLAUDE_SKILL_DIR}/references/description-field.md`, and `${CLAUDE_SKILL_DIR}/references/deterministic-elements.md`.
 
 **Output:** Diagnosis per failure — which best practice was violated.
 
@@ -69,11 +75,13 @@ When scope or activation is in play, re-read `${CLAUDE_SKILL_DIR}/references/ski
 
 For each diagnosis from Step 2:
 
-1. Read the matching reference (`description-field.md`, `skill-modularity.md`, `progressive-disclosure.md`, or SKILL.md principles).
+1. Read the matching reference (`description-field.md`, `skill-modularity.md`, `deterministic-elements.md`, `progressive-disclosure.md`, or SKILL.md principles).
 2. Make the minimum change that addresses the failure.
 3. For description failures: rewrite frontmatter into a trigger catalog (capability stem + Triggers list); strip story prose.
 4. For modularity failures: add sub-skills table, split packages, or thin the orchestrator; do not paste peer skill procedures.
-5. Verify the fix doesn’t break anything that was working.
+5. For deterministic failures: extract mechanical work to `scripts/` / `workflow/` / `templates/` / `reference/`; body only points and handles exit codes; apply CODE_RULES + paired tests to new code.
+6. For checkbox/tracker failures: replace markdown `- [ ]` boards with a plain task-seed list and a seed instruction (`TaskCreate` / `TodoWrite`).
+7. Verify the fix doesn’t break anything that was working.
 
 Delegate larger rewrites to `/skill-writer` using the refine-skill handoff from delegation-map.md.
 
@@ -104,10 +112,10 @@ For each failure observed in Step 1:
 Same process as new-skill Step 5:
 
 1. Read `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
-2. Check every item. Fix failures. Re-check.
+2. Register every bullet as a session task; complete with evidence. Fix failures. Re-complete those tasks.
 3. Pay special attention to items that overlap with the diagnosis from Step 2 — those were the failures; confirm they’re now fixed.
 
-**Output:** Completed checklist, all PASS or N/A.
+**Output:** Audit summary; all PASS or N/A.
 
 ---
 
@@ -122,6 +130,7 @@ Present to the user:
 3. **What changed** — delta summary (files modified, lines added/removed).
 4. **Description** — final frontmatter if rewritten (paste the trigger catalog).
 5. **Composition** — sub-skills or splits if modularity changed.
-6. **New gotchas added** — list of gotchas captured.
-7. **Audit summary** — post-fix audit results.
-8. **Suggested re-test** — a concrete task to verify the fix with Claude B.
+6. **Deterministic extracts** — scripts/workflows/templates added or moved out of prose.
+7. **New gotchas added** — list of gotchas captured.
+8. **Audit summary** — post-fix audit results.
+9. **Suggested re-test** — a concrete task to verify the fix with Claude B.

package/skills/skill-builder/workflows/new-skill.md

@@ -56,7 +56,7 @@ Best-practice-driven lifecycle for building a skill from scratch.
 
 > "Build a Gotchas Section — these sections should be built up from common failure points that Claude runs into when using your skill."
 
-Read `${CLAUDE_SKILL_DIR}/references/skill-modularity.md` and `${CLAUDE_SKILL_DIR}/references/description-field.md` before the interview. Modularity and description triggers are gates: do not proceed to Write until the composition plan and trigger catalog drafts are filled.
+Read `${CLAUDE_SKILL_DIR}/references/skill-modularity.md`, `${CLAUDE_SKILL_DIR}/references/description-field.md`, and `${CLAUDE_SKILL_DIR}/references/deterministic-elements.md` before the interview. Modularity, description triggers, and deterministic inventory are gates: do not proceed to Write until the composition plan, trigger catalog draft, and deterministic-elements inventory are filled.
 
 ### Interview questions
 
@@ -74,6 +74,7 @@ Ask the user:
 10. "Which existing skills already cover a step of this work? Which steps should this skill invoke by name?"
 11. "Is this one skill, several skills, or a thin orchestrator that calls sub-skills?"
 12. "What exact phrases, slash commands, or file types should select this skill?"
+13. "Which steps of this work are fixed procedures (same inputs → same outputs, machine-checkable) versus open judgment?"
 
 ### Related-skills inventory
 
@@ -90,6 +91,7 @@ Use the template at `${CLAUDE_SKILL_DIR}/templates/gap-analysis.md`. Fill in:
 - Initial gotcha candidates
 - **Composition plan** — capability sentence, related skills, sub-skills to invoke, split or orchestrator decision, missing sub-skills to create
 - **Description triggers** — capability stem tokens + trigger phrase list (not story prose)
+- **Deterministic elements inventory** — each process step classified; home path; paired test for code
 
 ### Assess degree of freedom
 
@@ -105,13 +107,17 @@ Record the assessment with reasoning.
 
 ### Modularity gate
 
-Copy the author checklist from `skill-modularity.md` and check every box. If the capability sentence needs an unrelated "and", stop and split scope with the user before Step 4.
+Register each task seed from `skill-modularity.md` on the session task list (`TaskCreate` / `TodoWrite`). Complete with evidence. If the capability sentence needs an unrelated "and", stop and split scope with the user before Step 4.
 
 ### Description gate
 
-Draft the frontmatter description using the template in `description-field.md`. Copy the description checklist and check every box. Story prose fails the gate.
+Draft the frontmatter description using the template in `description-field.md`. Register each description task seed and complete with evidence. Story prose fails the gate.
 
-**Output:** Completed gap analysis (composition plan + description triggers), initial gotchas, degree-of-freedom assessment, modularity checklist, draft description.
+### Deterministic-elements gate
+
+Register each task seed under **Required task seeds** in `deterministic-elements.md`. Complete with evidence. Every deterministic step must have a planned `scripts/`, `workflow/`, `templates/`, `reference/`, or task-seed path. Prose-only mechanical sequences and markdown checkbox boards fail the gate.
+
+**Output:** Completed gap analysis (composition plan + description triggers + deterministic inventory), initial gotchas, degree-of-freedom assessment, modularity gate done, draft description.
 
 ---
 
@@ -121,7 +127,7 @@ Draft the frontmatter description using the template in `description-field.md`.
 
 Delegate to `/skill-writer` using the structured handoff from `${CLAUDE_SKILL_DIR}/references/delegation-map.md`.
 
-The handoff must include: skill type, folder structure, gap analysis (composition plan + description triggers), initial gotchas, degree of freedom, constraints, sub-skills to name in SKILL.md, exact description string to put in frontmatter.
+The handoff must include: skill type, folder structure, gap analysis (composition plan + description triggers + deterministic inventory), initial gotchas, degree of freedom, constraints, sub-skills to name in SKILL.md, exact description string to put in frontmatter, script/test paths for every deterministic step.
 
 After skill-writer produces the draft:
 
@@ -131,8 +137,9 @@ After skill-writer produces the draft:
 4. Verify files over 100 lines have a TOC.
 5. Verify modularity: single capability, sub-skills table when composing, no silent reimplementation of inventoried skills.
 6. Verify description is a trigger catalog per `description-field.md` (not story prose).
+7. Verify deterministic inventory: every deterministic step has a real code/artifact/task-seed path; no prose-only mechanical sequences; no markdown checkbox boards for required work; scripts follow CODE_RULES and have paired tests.
 
-Fix structural, modularity, and description issues before proceeding.
+Fix structural, modularity, description, and deterministic-element issues before proceeding.
 
 **Output:** Complete skill package at the target directory.
 
@@ -143,14 +150,14 @@ Fix structural, modularity, and description issues before proceeding.
 **Goal:** Verify every best practice is satisfied before delivery.
 
 1. Read `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
-2. Copy the checklist into your response.
-3. Check every item against the built skill. For each: PASS, FAIL with file:line evidence, or N/A with reason.
-4. Every FAIL must be fixed before proceeding. Apply fixes, then re-check that item.
-5. When all items are PASS or N/A, proceed to Step 6.
+2. Register **every** bullet as a session task (`TaskCreate` / `TodoWrite`).
+3. Complete each task against the built skill: PASS, FAIL with file:line evidence, or N/A with reason.
+4. Every FAIL must be fixed before proceeding. Apply fixes, then re-open/complete that task.
+5. When all tasks are PASS or N/A, proceed to Step 6.
 
 For an independent check, spawn a subagent to run the audit (see delegation-map.md).
 
-**Output:** Completed checklist with all items PASS or N/A.
+**Output:** Audit summary (PASS / N/A / FAIL-fixed counts). All items PASS or N/A.
 
 ---
 
@@ -165,7 +172,8 @@ Present to the user:
 3. **Degree of freedom** — assessment and reasoning.
 4. **Composition plan** — capability sentence, sub-skills invoked, any skills split out.
 5. **Description** — final frontmatter trigger catalog (paste the string).
-6. **Gotchas seeded** — initial gotchas captured.
-7. **Audit summary** — "All checklist items: N passed, M N/A."
-8. **Maintenance notes** — what to watch for in future usage that might warrant iteration.
-9. **Suggested first test** — a concrete task to try with Claude B.
+6. **Deterministic inventory** — steps classified; script/template/reference paths; tests for code.
+7. **Gotchas seeded** — initial gotchas captured.
+8. **Audit summary** — "All checklist items: N passed, M N/A."
+9. **Maintenance notes** — what to watch for in future usage that might warrant iteration.
+10. **Suggested first test** — a concrete task to try with Claude B.

package/skills/skill-builder/workflows/polish-skill.md

@@ -35,15 +35,17 @@ description: >-
   <capability tokens>. Triggers: <phrase>, <phrase>, <slash>, <filetype>.
 ```
 
-### Checklist
+### Description task seeds
 
-- [ ] **Third person** — no I/you
-- [ ] **Capability stem** — what tokens, ≤20 words, no story
-- [ ] **Triggers list** — concrete phrases / slash forms / file types
-- [ ] **Under 1024 characters** (prefer much shorter; always-on context)
-- [ ] **No XML tags**
-- [ ] **Not a story** — no narrative, benefits, or process dump
-- [ ] **Sibling boundary** — distinguishable from related skills
+Register each as a session task; complete with evidence (no markdown checkboxes):
+
+- **Third person** — no I/you
+- **Capability stem** — what tokens, ≤20 words, no story
+- **Triggers list** — concrete phrases / slash forms / file types
+- **Under 1024 characters** (prefer much shorter; always-on context)
+- **No XML tags**
+- **Not a story** — no narrative, benefits, or process dump
+- **Sibling boundary** — distinguishable from related skills
 
 ### Trigger phrase review
 
@@ -66,13 +68,14 @@ If any check fails, rewrite. Show before/after. The after form must match `descr
 
 ---
 
-## Step 2: Progressive disclosure and modularity audit
+## Step 2: Progressive disclosure, modularity, and deterministic audit
 
-**Goal:** Verify within-skill structure and cross-skill modularity.
+**Goal:** Verify within-skill structure, cross-skill modularity, and deterministic placement.
 
 1. Apply hard rules in `${CLAUDE_SKILL_DIR}/references/progressive-disclosure.md`.
 2. Apply modularity rules in `${CLAUDE_SKILL_DIR}/references/skill-modularity.md`.
-3. Cross-check matching items on `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
+3. Apply deterministic-elements rules in `${CLAUDE_SKILL_DIR}/references/deterministic-elements.md`.
+4. Cross-check matching items on `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
 
 ### Common fixes
 
@@ -81,8 +84,11 @@ If any check fails, rewrite. Show before/after. The after form must match `descr
 - Missing TOC → add to files over 100 lines
 - Multi-capability package → split or orchestrator + named sub-skills
 - Silent reimplementation → invoke peer skill by name; add Sub-skills table
+- Mechanical sequence / fenced program / giant detector only in body → extract to `scripts/` or `workflow/`; point from process steps; add paired tests and `*_constants/` as needed
+- Verbatim templates inline → `templates/`; long fixed tables → `reference/`
+- Markdown `- [ ]` progress boards → plain task-seed list + seed instruction (`TaskCreate` / `TodoWrite`)
 
-**Output:** Verified structure and composition (and edits if needed).
+**Output:** Verified structure, composition, and deterministic placement (and edits if needed).
 
 ---
 
@@ -104,16 +110,16 @@ If any check fails, rewrite. Show before/after. The after form must match `descr
 
 ## Step 4: Full self-audit
 
-**Goal:** Complete checklist pass including description and modularity items.
+**Goal:** Complete checklist pass including description, modularity, and deterministic items.
 
 Same as new-skill Step 5 and improve-skill Step 5:
 
 1. Read `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
-2. Check every item. Fix failures. Re-check.
+2. Register every bullet as a session task; complete with evidence. Fix failures. Re-complete.
 3. All items must be PASS or N/A.
-4. Description items and modularity items are never N/A for a delivered skill (sub-skills table alone may be N/A for pure leaf skills).
+4. Description items, modularity items, and process-step classification are never N/A for a delivered skill (sub-skills table alone may be N/A for pure leaf skills; script/test rows are N/A only when the package has zero code files and every step is judgment).
 
-**Output:** Completed checklist.
+**Output:** Audit summary; all PASS or N/A.
 
 ---
 
@@ -125,8 +131,9 @@ Present to the user:
 
 1. **Description** — final trigger-catalog string (paste it).
 2. **Composition** — sub-skills or leaf status.
-3. **File structure** — folder map with line counts.
-4. **Gotchas** — current gotcha count and most recent additions.
-5. **Audit summary** — "All checklist items: N passed, M N/A."
-6. **Before/after** — description rewrite and structural changes if any.
-7. **Maintenance notes** — what to watch for, when to re-audit.
+3. **Deterministic inventory** — any extracts to scripts/templates/reference.
+4. **File structure** — folder map with line counts.
+5. **Gotchas** — current gotcha count and most recent additions.
+6. **Audit summary** — "All checklist items: N passed, M N/A."
+7. **Before/after** — description rewrite and structural changes if any.
+8. **Maintenance notes** — what to watch for, when to re-audit.