claude-dev-env 2.0.2 → 2.2.0

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.