claude-dev-env 1.17.2 → 1.19.0

package/skills/agent-prompt/SKILL.md

@@ -1,199 +0,0 @@
----
-name: agent-prompt
-description: >-
-  Craft a structured prompt using prompt-generator's workflow, then spawn a
-  background agent to execute it after user approval. Use instead of
-  /prompt-generator when the user wants execution, not just the prompt.
-  Triggers on /agent-prompt, "launch an agent for this", "spawn agent to do X",
-  "delegate this", "run this in background", or any task that benefits from
-  agent delegation with prompt quality.
----
-
-@packages/claude-dev-env/skills/prompt-generator/SKILL.md
-@packages/claude-dev-env/skills/prompt-generator/REFERENCE.md
-
-# Agent Prompt
-
-Craft a structured agent prompt, get approval, spawn a background agent.
-
-The prompt-generator skill above defines the prompt-crafting workflow. This skill extends it: instead of delivering the prompt as a fenced block, it presents the prompt for approval and spawns a background agent.
-
-## When this skill applies
-
-Trigger only when the user explicitly wants to delegate or execute a task with an agent.
-
-`/prompt-generator` is the default owner for prompt authoring and refinement. This skill starts after explicit execution intent.
-
-When invoked with arguments (e.g. `/agent-prompt fix the auth bug via TDD`), treat the arguments as the task to build a prompt for and execute.
-
-## Workflow
-
-### Steps 1-8: Craft the prompt
-
-Follow the prompt-generator workflow steps 1 through 8 exactly as written. Classify the prompt type, set degree of freedom, collect missing facts, build the prompt with XML tags and role, control format and style, add examples if needed, and self-check against the rubric.
-
-After steps 1-8, continue directly to step 9 for context gathering; deliverables are handled through the orchestration flow below.
-
-### Step 9: Gather context before crafting
-
-The agent starts with zero conversation history. Before building the prompt, use Read, Glob, Grep, and other research tools to gather the concrete values the agent will need -- file paths, function signatures, existing patterns, branch names. Embed these directly in the prompt instead of telling the agent to "find" them.
-
-The agent-spawn-protocol rule requires this: if any context question has the answer "I don't know", investigate first, then delegate with complete context.
-
-Proactive context gathering enables agents to plan effectively from the start. Anthropic's emotion concepts research (2026) found that agents produce higher-quality output when they understand constraints, available tools, and system boundaries upfront — they incorporate these into their approach naturally, leading to better first attempts and more accurate results.
-
-### Step 10: Determine agent configuration
-
-Map the task to agent parameters:
-
-| Task type | subagent_type | mode |
-|---|---|---|
-| Codebase exploration, search, research | Explore | default |
-| Code implementation, bug fix, refactoring | general-purpose | auto |
-| Read-only audit, analysis, review | general-purpose | default |
-| Architecture, multi-step planning | Plan | plan |
-
-Always set `run_in_background: true`.
-
-Generate a descriptive `name` (3-5 words, kebab-case) so the user can track progress and send follow-up messages via `SendMessage({to: name})`.
-
-### Step 10A: Section-refinement orchestration mode (default for execution tasks)
-
-Execution behavior: run this deterministic orchestration for delegated prompt work after explicit launch intent.
-Prompt authoring and prompt refinement ownership remain in `/prompt-generator`.
-
-Use simplified mode when either condition is true:
-- The user explicitly requests single-agent execution
-- The task is genuinely too small for orchestration (for example, one quick read/search)
-
-This mode is triggered when execution input includes `pipeline_mode: internal_section_refinement_with_final_audit` or equivalent execution-ready orchestration metadata.
-If present, carry forward the scope block (`target_local_roots`, `target_canonical_roots`, `target_file_globs`, `comparison_basis`, `completion_boundary`) so execution remains artifact-bound.
-
-1. Spawn exactly 6 refinement agents, one per section in fixed order:
-   - `role`
-   - `context`
-   - `instructions`
-   - `constraints`
-   - `output_format`
-   - `examples`
-2. Enforce section-only scope in each sub-prompt:
-   - "Edit `<SECTION_NAME>` and preserve all other sections unchanged."
-3. Require section output contract from each agent:
-   - `improved_block`
-   - `rationale`
-   - `concise_diff`
-4. Merge outputs into one canonical prompt after all 6 refiners finish.
-5. Run one final audit agent against the merged prompt and checklist.
-6. If audit fails, apply targeted fixes and re-run audit with capped retries (`max_retries: 2` unless user overrides).
-
-Run all stages in this exact order.
-
-### Step 11: Present for approval (must reflect default orchestration)
-
-Use AskUserQuestion with one question. The question text must summarize:
-- agent config (type, mode, name)
-- orchestration mode (`section_refinement_with_final_audit` by default)
-- retry cap for audit loop
-
-Each option should use the `preview` field to show the full crafted prompt.
-
-Options:
-1. "Launch it" (recommended) -- preview shows the crafted prompt
-2. "Edit first" -- preview shows the prompt with a note that user can provide changes
-3. "Cancel" -- no preview
-
-### Step 12: Spawn
-
-On **"Launch it"**: spawn the Agent tool with the crafted prompt and configuration. Report the agent name so the user knows what's running.
-
-On **"Edit first"**: present the prompt in conversation text. After the user provides changes, return to step 11 with the updated prompt.
-
-On **"Cancel"**: acknowledge and stop.
-
-## Prompt adjustments for agent execution
-
-When building the prompt in step 4, these adjustments ensure the agent can work independently:
-
-**Context completeness** -- include file paths, line numbers, function names, branch state, and anything you learned during step 9. The agent cannot see this conversation.
-Bind execution steps to the scope block artifacts passed from refinement output whenever available.
-Keep runtime context compact: include only actionable facts required for execution.
-
-**Acceptance criteria** -- state what "done" looks like. For code: include the test command. For research: specify the output format and save location.
-
-**Scope boundary** -- include "Make requested changes and keep surrounding code stable" or equivalent. Agents with explicit scope constraints stay aligned to task intent.
-
-**Constraints from this project** -- if the project has CODE_RULES.md, TDD requirements, or naming conventions, include the relevant subset in the prompt so the agent follows them.
-
-**Emotion-informed briefing** -- Anthropic's emotion concepts research (2026) found that briefing style causally affects output quality. Frame tasks collaboratively ("work on this together", "help figure out"). Include permission to express uncertainty ("flag anything you're unsure about", "use [PLACEHOLDER] for unverified specifics"). Provide motivation behind constraints ("this ordering ensures tests define behavior before implementation exists"). Share system context proactively (what hooks enforce, what tools are available, what the fallback is) so the agent can incorporate constraints into its plan from the start.
-
-**Anti-test-fixation** -- For code tasks, include guidance against test-specific solutions. Anthropic: "Implement a solution that works correctly for all valid inputs, not just the test cases. Tests are there to verify correctness, not to define the solution. If the task is unreasonable or infeasible, or if any of the tests are incorrect, please inform me rather than working around them."
-
-**Commit-and-execute** -- For multi-step agent work, include decision commitment guidance. Anthropic: "When deciding how to approach a problem, choose an approach and commit to it. Avoid revisiting decisions unless you encounter new information that directly contradicts your reasoning."
-
-**Temp file cleanup** -- If the agent may create scratch files during iteration, include cleanup instructions. Anthropic: "If you create any temporary new files, scripts, or helper files for iteration, clean up these files by removing them at the end of the task."
-
-## Final audit-agent stage requirements (for default section-refinement mode)
-
-After merge, run one dedicated audit agent that validates the full prompt against:
-
-- Prompt-generator rubric requirements (`packages/claude-dev-env/skills/prompt-generator/SKILL.md`)
-- The deterministic checklist from the handoff artifact
-- Embedded research-mode evidence constraints below
-
-Required audit output shape:
-
-```json
-{
-  "overall_status": "pass|fail",
-  "checklist_results": [
-    {
-      "check_id": "structured_scoped_instructions",
-      "status": "pass|fail",
-      "evidence_quote": "word-for-word quote",
-      "source_ref": "path-or-url",
-      "fix_if_fail": "targeted correction"
-    }
-  ],
-  "corrective_edits": ["..."],
-  "retry_count": 0
-}
-```
-
-### Embedded research-mode policy text (audit behavior)
-
-The audit agent must enforce these constraints as policy text in the audit prompt (do not rely on a global mode switch):
-
-- "Every recommendation, claim, or piece of advice must cite a specific source."
-- "Ground your response in word-for-word quotes, not paraphrased summaries."
-- "If you don't have a credible source for a claim, say 'I don't know'."
-- Source priority:
-  1. Official vendor/creator docs for external tools
-  2. Local project files for local behavior
-  3. Academic or named expert sources
-  4. Reputable external sources with URLs
-  5. Blogs/community posts (lowest)
-
-Policy source: `packages/claude-dev-env/skills/prompt-generator/REFINEMENT_PIPELINE_RUNBOOK.md`
-
-## Section-refinement acceptance criteria
-
-Section-refinement orchestration is done only when all are true:
-
-- All 6 section agents ran, each scoped to exactly one section
-- Merge produced one canonical prompt containing all six sections
-- Final audit returned `overall_status: pass`
-- Any non-pass audit was resolved through targeted revisions within retry cap
-- AskUserQuestion approval gate was honored before launch
-- Final user artifact includes one complete pasteable prompt block
-
-## Constraints
-
-- Present every launch for approval via AskUserQuestion before spawning
-- Always run agents in background
-- Gather context before crafting -- do not send an agent in blind
-- Start only after explicit user execution intent; keep prompt authoring/refinement in `/prompt-generator`
-- Default to `section_refinement_with_final_audit` orchestration for execution tasks unless user requests simplified mode
-- Carry scope-block context into execution prompts; native Agent/Task tools have no custom intent metadata
-- If the task is too small for an agent (single file read, quick grep), say so and just do it directly
-- Include obstacle handling: "When encountering obstacles, do not use destructive actions as a shortcut (e.g. --no-verify, discarding unfamiliar files)" -- agents without this guidance may take irreversible shortcuts
-- Frame agent tasks with collaborative language and include permission to express uncertainty — agents produce higher-quality output with collaborative briefing (Anthropic emotion concepts research, 2026)

package/skills/prompt-generator/ARCHITECTURE.md

@@ -1,18 +0,0 @@
-# prompt-generator — file map
-
-Baseline inventory of files in the prompt-generator skill package.
-
-## Baseline inventory
-
-| Path | Role |
-| --- | --- |
-| `SKILL.md` | Orchestrator rules, subagent contract, compliance audit |
-| `TARGET_OUTPUT.md` | User-visible output contract for evals and hooks |
-| `REFERENCE.md` | Tiered sources, harness patterns, debug schema |
-| `REFINEMENT_PIPELINE_RUNBOOK.md` | Evidence-grounding runbook |
-| `evals/prompt-generator.json` | Scenario eval rows |
-| `templates/skill-from-ground-up.md` | Net-new skill checkpoint template |
-| `templates/skill-refinement-package.md` | Existing-skill refinement template |
-| `hooks/blocking/prompt_workflow_validate.py` | Validator CLI (file-based loop) |
-| `hooks/blocking/prompt_workflow_gate_core.py` | Fence extraction, markers |
-| `hooks/blocking/prompt_workflow_clipboard.py` | Clipboard copy for artifacts |

package/skills/prompt-generator/REFERENCE.md

@@ -1,254 +0,0 @@
-# Prompt generator -- reference
-
-## Canonical resources
-
-When authoring or refining prompts, ground decisions in these sources. If guidance conflicts, defer to the higher tier.
-
-### Tier 1: Anthropic (primary authority for Claude)
-
-- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview -- overview, links to all sub-guides
-- https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices -- the single living reference for Claude's latest models.
-- https://transformer-circuits.pub/2026/emotions/index.html -- emotion concepts research (April 2026). Key takeaways: clear criteria and escape routes, collaborative framing, positive task framing, inviting transparency. Full catalog: `packages/claude-dev-env/docs/emotion-informed-prompt-design.md`.
-- https://www.anthropic.com/research/emotion-concepts-function -- blog summary of the above paper.
-- https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking -- adaptive thinking reference; replaces manual budget_tokens with effort-based control.
-- https://claude.com/blog/harnessing-claudes-intelligence -- harness evolution: primitives Claude already knows, what to stop doing in the harness, deliberate boundaries (context economics, caching, typed tools). Local inventory: `docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md`.
-- https://github.com/anthropics/skills/tree/main/skills/claude-api -- Anthropic `claude-api` Agent Skill for hands-on API/tool patterns from that post (Hook 10). Platform entry: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill
-
-### Tier 2: Major labs (strong secondary, often transfers across models)
-
-- https://platform.openai.com/docs/guides/prompt-engineering -- six strategies: write clear instructions, provide reference text, split complex tasks, give models time to think, use external tools, test systematically.
-- https://deepmind.google/research/ -- learning resources and chain-of-thought research.
-- https://www.microsoft.com/en-us/research/blog/ -- publications and applied research.
-
-### Tier 3: Courses, communities, individuals (supplementary)
-
-**Courses:**
-
-- https://www.deeplearning.ai/short-courses/ -- Andrew Ng's courses. "ChatGPT Prompt Engineering for Developers" (with OpenAI) is the foundational one.
-- https://course.fast.ai/ -- Jeremy Howard's top-down teaching style.
-- https://www.elementsofai.com/ -- University of Helsinki introductory course.
-- https://ocw.mit.edu/search/?t=Artificial%20Intelligence -- MIT OpenCourseWare AI curriculum.
-
-**Communities and individuals:**
-
-- https://discuss.huggingface.co/ -- open-source model community.
-- https://www.latent.space/ -- AI engineering perspective (Latent Space Podcast & Newsletter).
-- https://simonwillison.net/ -- practical LLM experiments. His "LLM" tag is especially valuable.
-
-### Conflict resolution rule
-
-If sources disagree, apply tier order: Anthropic first, then OpenAI/Google/Microsoft, then community. Tier 1 wins when conflicting with lower tiers.
-
-### Outcome preview gate and digest (`prompt-generator`)
-
-See SKILL.md §§107-115 (Phases 4-5) and `TARGET_OUTPUT.md` for the full contract. **Clipboard safety:** `extract_fenced_xml_content` concatenates every ` ```xml ` block—follow §7 sample formatting so clipboard copy stays the lone artifact body.
-
-### Outcome preview gate and digest (`prompt-generator`)
-
-Human checkpoint before the paste-ready artifact ships: the orchestrator runs an **Outcome preview** turn (`### Outcome preview` bullets built from the **preview summary**, defined in SKILL.md Terminology) plus **AskUserQuestion** (**Ship** recommended first, two contextual alternates, **Refine with free text**), then emits `Audit`, a single ` ```xml ` fence, and **`## Outcome digest`** after the fence. Rationale matches collaborative checkpoints in `templates/skill-from-ground-up.md` and the refinement pattern in `templates/skill-refinement-package.md`. `ARCHITECTURE.md` lists all files in this skill package.
-
-**Clipboard safety:** `prompt_workflow_gate_core.extract_fenced_xml_content` concatenates every ` ```xml ` block in the message—follow the sample formatting rules in SKILL.md section 7 so clipboard copy stays the lone artifact body. Full contract: `TARGET_OUTPUT.md`.
-
-## Harness design patterns (Anthropic blog, April 2026)
-
-Primary URL: https://claude.com/blog/harnessing-claudes-intelligence. Structured inventory: `docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md`.
-
-### Mechanism doc map (Hook 11)
-
-Jump from concept to the platform specs the post names:
-
-- [Bash tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool) / [Text editor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool)
-- [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) / [Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)
-- [Memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)
-- [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
-- [Context windows](https://platform.claude.com/docs/en/build-with-claude/context-windows) / [Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) / [Compaction](https://platform.claude.com/docs/en/build-with-claude/compaction)
-- [Subagents](https://code.claude.com/docs/en/sub-agents)
-- [System prompts](https://platform.claude.com/docs/en/release-notes/system-prompts) / [Working with the Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) / [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
-- [Model migration guide — hard-coded filters](https://platform.claude.com/docs/en/about-claude/models/migration-guide#additional-recommended-changes)
-- [Harness design for long-running applications](https://www.anthropic.com/engineering/harness-design-long-running-apps)
-- [Claude Code auto-mode](https://www.anthropic.com/engineering/claude-code-auto-mode)
-- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
-
-### Context stack (Hook 5)
-
-- **Context editing:** Remove stale tool results and thinking blocks selectively ([Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing)).
-- **Subagents:** Fork fresh windows for isolated subtasks; post cites **+2.8%** BrowseComp vs best single-agent for Opus 4.6 ([Subagents](https://code.claude.com/docs/en/sub-agents)).
-- **Compaction:** Summarize prior context for long horizons ([Compaction](https://platform.claude.com/docs/en/build-with-claude/compaction)); effectiveness varies by model generation (see Hook 9 table).
-- **Memory folder:** Persist agent-chosen state via the memory tool / files ([Memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)).
-
-### Prompt caching (Hook 6)
-
-The Messages API is stateless. Maximize [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): **stable prefix first, dynamic tail last**; **append** via messages; **avoid mid-session model switches** (use a subagent for cheaper models); **treat tool list as cached prefix**; use **tool search** to append without invalidation; **advance breakpoints** toward the latest message. Cached tokens cost **10% of base input**.
-
-### Typed tools vs bash strings (Hook 7)
-
-Promote actions to **dedicated tools** with typed arguments when the harness must intercept, gate, render (e.g., **modals**), or audit—**hard-to-reverse** steps (e.g., external API calls) for user confirmation; **write/edit** paths with **staleness checks** so concurrent edits are not blindly overwritten ([Harnessing Claude's intelligence](https://claude.com/blog/harnessing-claudes-intelligence)).
-
-### Standing review: dedicated tools vs general bash + policy (Hook 8)
-
-Re-evaluate promotions as models improve—e.g., Claude Code **auto-mode** (secondary reviewer over bash strings) can **reduce** bespoke tools **only** where users accept that trust profile; **high-stakes** actions still warrant dedicated tools ([Claude Code auto-mode](https://www.anthropic.com/engineering/claude-code-auto-mode)).
-
-### Benchmark vignettes — motivation only, not guarantees (Hook 9)
-
-| Vignette | Outcome stated in the post |
-|----------|----------------------------|
-| SWE-bench Verified | Claude 3.5 Sonnet **49%** with bash + editor only (then SOTA framing) |
-| BrowseComp + output filtering | Opus 4.6 **45.3% → 61.6%** |
-| BrowseComp + subagents | Opus 4.6 **+2.8%** vs best single-agent |
-| BrowseComp + compaction | Sonnet 4.5 **43%** flat; Opus 4.5 **68%**; Opus 4.6 **84%** (same setup) |
-| BrowseComp-Plus + memory folder | Sonnet 4.5 **60.4% → 67.2%** |
-| Prompt caching | Cached tokens **10%** the cost of base input tokens |
-
-## NotebookLM Audio Overview customization (example)
-
-Adapt `[FOCUS AREA]` per notebook. Pair with Deep Dive + Longer in the product UI when that matches the user's plan.
-
-```text
-Target audience: [Expert-level listener profile -- skip beginner padding.]
-
-Focus: [FOCUS AREA -- single notebook-specific paragraph.]
-
-Style: [Technical depth, anti-patterns, implications for builders.]
-
-Prioritize: [Technical depth and specific findings over marketing tone or generic summaries.]
-```
-
-## Agent checklist pattern
-
-For long tasks, optional checklist the model can mirror:
-
-```text
-Copy this checklist and mark items as you go:
-
-Progress:
-- [ ] ...
-- [ ] ...
-```
-
-## Agentic state management
-
-For `agent-harness` prompts that span multiple context windows, include state persistence and multi-window patterns. Based on Anthropic's guidance:
-
-### Context awareness
-
-Claude 4.6 tracks its remaining context window. Include harness capabilities so Claude can plan accordingly:
-
-```text
-<context_management>
-Your context window will be automatically compacted as it approaches its limit, allowing you to continue working indefinitely from where you left off. Do not stop tasks early due to token budget concerns. As you approach the limit, save current progress and state before the context window refreshes. Always be as persistent and autonomous as possible and complete tasks fully.
-</context_management>
-```
-
-### Multi-window workflow
-
-Anthropic recommends differentiating the first context window from subsequent ones:
-
-**First window:** Set up the framework -- write tests, create setup scripts, establish the todo-list.
-
-**Subsequent windows:** Iterate on the todo-list, using state files to resume.
-
-Key patterns from Anthropic:
-- Have the model write tests in a **structured format** (e.g. `tests.json` with `{id, name, status}`) before starting work. Remind: "It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality."
-- Encourage **setup scripts** (e.g. `init.sh`) to start servers, run test suites, and linters. This prevents repeated work across windows.
-- When starting fresh, be **prescriptive about resumption**: "Review progress.txt, tests.json, and the git logs."
-- Provide **verification tools** (Playwright, computer use) for autonomous UI testing.
-
-### State tracking
-
-```text
-<state_management>
-Track progress in structured + freeform files:
-- tests.json: structured test status {id, name, status}
-- progress.txt: freeform session notes and next steps
-- Use git commits as checkpoints for rollback
-
-When approaching context limits, save current state before the window refreshes.
-Do not stop tasks early due to token budget concerns.
-</state_management>
-```
-
-### Encouraging complete context usage
-
-```text
-This is a very long task, so it may be beneficial to plan out your work clearly. It's encouraged to spend your entire output context working on the task - just make sure you don't run out of context with significant uncommitted work. Continue working systematically until you have completed this task.
-```
-
-## Research prompt pattern
-
-For `research` prompt types, include structured investigation with hypothesis tracking:
-
-```text
-<research_approach>
-Search for this information in a structured way. As you gather data, develop several competing hypotheses. Track your confidence levels in your progress notes to improve calibration. Regularly self-critique your approach and plan. Update a hypothesis tree or research notes file to persist information and provide transparency. Break down this complex research task systematically.
-</research_approach>
-```
-
-## Evaluation loop
-
-For prompt drafts that must hold up over time:
-
-1. Run the draft on 2-3 representative user utterances.
-2. Note failure modes (skipped steps, wrong format, over-refusal).
-3. Tighten **constraints** or add **examples** for the failure class only.
-
-Anthropic's **self-correction chaining** pattern extends this: generate a draft, have Claude review it against criteria, then have Claude refine based on the review. Each step can be a separate API call for inspection and branching.
-
-## Anti-test-fixation pattern
-
-```text
-Write general-purpose solutions using the standard tools available. Implement logic that works correctly for all valid inputs, not just the test cases. Tests verify correctness -- they do not define the solution. If a test seems incorrect or the task is unreasonable, flag it rather than working around it.
-```
-
-## Commit-and-execute pattern
-
-```text
-When deciding how to approach a problem, choose an approach and commit to it. Avoid revisiting decisions unless you encounter new information that directly contradicts your reasoning. If you are weighing two approaches, pick one and see it through. You can always course-correct later if the chosen approach fails.
-```
-
-## Debug JSON schema (prompt-generator pipeline)
-
-Use **only** when the user explicitly requests debug output (for example `show debug`, `full audit table`, `raw internal object`). Default assistant turns complete the normal handoff first: one `xml` fence + **`## Outcome digest`** (see also `TARGET_OUTPUT.md`); this JSON object is an optional appendix **after** that handoff.
-
-Shape (field names stable for internal audit helpers and Stop-hook leak detection):
-
-```json
-{
-  "pipeline_mode": "internal_section_refinement_with_final_audit",
-  "scope_block": {
-    "target_local_roots": ["..."],
-    "target_canonical_roots": ["..."],
-    "target_file_globs": ["..."],
-    "comparison_basis": "...",
-    "completion_boundary": "..."
-  },
-  "required_sections": ["role", "background", "instructions", "constraints", "output_format", "illustrations"],
-  "base_prompt_xml": "<role>...</role><background>...</background><instructions>...</instructions><constraints>...</constraints><illustrations>...</illustrations><output_format>...</output_format>",
-  "section_scope_rule": "Each refiner edits exactly one section and returns sibling sections unchanged.",
-  "section_output_contract": {
-    "required_fields": ["improved_block", "rationale", "concise_diff"]
-  },
-  "merge_output_contract": {
-    "required_fields": ["canonical_prompt_xml"]
-  },
-  "audit_output_contract": {
-    "required_fields": [
-      "overall_status",
-      "checklist_results",
-      "evidence_quotes",
-      "source_refs",
-      "corrective_edits",
-      "retry_count"
-    ]
-  },
-  "checklist_results": {
-    "<row_name>": {
-      "status": "pass|fail",
-      "evidence_quote": "exact quote used for verification",
-      "source_ref": "URL or local path",
-      "fix_if_fail": "concrete edit text (empty only if pass)"
-    }
-  }
-}
-```
-
-`checklist_results` keys must include all **15** compliance row ids from `SKILL.md` §11 (for example `reversible_action_and_safety_check_guidance`, `scope_terms_explicit_and_anchored`).

package/skills/prompt-generator/REFINEMENT_PIPELINE_RUNBOOK.md

@@ -1,177 +0,0 @@
-# Prompt Refinement Pipeline Runbook
-
-## Purpose
-
-Validate deterministic behavior for:
-
-1. Base prompt generation (`/prompt-generator`)
-2. Six section refiners (owned by `/prompt-generator`)
-3. Merge + final audit with citation-grounded checks
-4. Targeted fix + capped re-audit loop
-
-## Sample Input
-
-Use this command:
-
-```text
-/prompt-generator Create a trusted final system prompt for a coding agent that edits files safely, follows user scope, and returns concise status updates.
-```
-
-## Expected Stage Artifacts
-
-1. **Base stage**
-   - Scope block is present and explicit:
-     - `target_local_roots`
-     - `target_canonical_roots` (if applicable)
-     - `target_file_globs`
-     - `comparison_basis`
-     - `completion_boundary`
-   - XML scaffold includes all sections — verified by the Stop hook at runtime; each required section tag must have both an opening and a closing tag:
-     - `<role>`
-     - `<background>`
-     - `<instructions>`
-     - `<constraints>`
-     - `<output_format>`
-     - `<illustrations>`
-   - Includes internal refinement object with:
-     - `pipeline_mode: internal_section_refinement_with_final_audit`
-     - `required_sections` list with all six sections
-     - section/merge/audit output contracts
-
-2. **Section refinement stage**
-   - Exactly 6 agent runs, one per section.
-   - Each section output includes:
-     - `improved_block`
-     - `rationale`
-     - `concise_diff`
-   - No section agent edits another section.
-
-3. **Merge stage**
-   - One canonical merged prompt with all six sections.
-
-4. **Audit stage**
-   - Output includes:
-     - `overall_status`
-     - `checklist_results`
-     - `corrective_edits`
-     - `retry_count`
-   - Every checklist item includes:
-     - `status`
-     - `evidence_quote` (direct quote)
-     - `source_ref`
-     - `fix_if_fail`
-
-5. **Final output**
-   - One complete prompt block that is copy-pasteable.
-   - Internal refinement object is not shown unless debug output was requested.
-   - Default output must not leak the raw internal refinement object fields.
-
-## Deterministic Checklist Coverage
-
-Audit report must include all check IDs:
-
-- `structured_scoped_instructions`
-- `sequential_steps_present`
-- `positive_framing`
-- `acceptance_criteria_defined`
-- `safety_reversibility_language`
-- `reversible_action_and_safety_check_guidance`
-- `concrete_output_contract`
-- `scope_boundary_present`
-- `explicit_scope_anchors_present`
-- `all_instructions_artifact_bound`
-- `scope_terms_explicit_and_anchored`
-- `completion_boundary_measurable`
-- `citation_grounding_policy_present`
-- `source_priority_rules_present`
-- `artifact_language_confidence`
-
-## Citation and Grounding Validation
-
-For each factual compliance claim in the audit:
-
-- Include a source citation
-- Include a word-for-word quote
-- If unsupported, explicitly return "I don't know"
-
-Source priority must be applied in this order:
-
-1. Official vendor docs (external behavior)
-2. Local project files (local behavior)
-3. Academic / named experts
-4. Reputable external URLs
-5. Blog/community content
-
-## Non-pass Loop Validation
-
-If `overall_status` is `fail`:
-
-1. Apply only targeted edits listed in `corrective_edits`
-2. Re-run audit
-3. Stop after retry cap (`max_retries: 2` unless explicitly overridden)
-4. Return unresolved failures with evidence if still failing at cap
-
-## Ownership and Execution-Intent Validation
-
-- Prompt refinement remains inside `/prompt-generator`.
-- `/agent-prompt` is used only after explicit execution/delegation intent.
-- Execution handoffs that go through `/agent-prompt` carry scope-block context in the execution prompt as needed.
-- Final refined prompt content is treated as artifact text during refinement and audit.
-- Execution steps (when requested) are bound to scope block artifacts.
-
-## Scope-Phrasing Validation
-
-- Reject ambiguous scope wording such as "this session", "current files", "here", "above", or "as needed" when used as scope boundaries.
-- Require artifact-bound replacements using explicit roots, globs, comparison basis, and measurable completion boundary.
-
-## Runtime Hook Gate Validation
-
-Validate fail-closed runtime gates:
-
-1. **Stop leakage/scope/checklist gate**
-   - **Section-presence gate (Stop)** — Block responses where the fenced XML artifact is missing any of the five required section tag pairs: `role`, `background`, `instructions`, `constraints`, `output_format`.
-   - Block responses that leak raw internal refinement object fields unless debug intent is explicit.
-   - Block responses missing deterministic checklist rows when audit output is present.
-   - Block responses using ambiguous scope phrasing in scope-bound sections.
-   - Block responses containing negative keywords (no, not, don't, never, avoid, etc.) inside fenced XML artifacts.
-   - Block responses containing hedging language (might be, possibly, I think, etc.) inside fenced XML artifacts.
-
-## Context-Footprint Controls
-
-- Keep baseline prompt-workflow policy minimal by default.
-- Store stable enforcement text in hooks/rules; avoid repeating full policy blocks in prompt artifacts.
-- Load heavy skills on demand based on explicit task intent.
-- Prefer canonical references and compact outputs over repeated long policy text.
-
-## Deterministic vs Semantic Boundary
-
-- **Deterministic (fail-closed):**
-  - Missing required scope anchors (when Stop guard applies)
-  - Raw internal object leakage without debug intent
-  - Missing required checklist rows in audit output
-  - Missing required XML sections (`role`, `background`, `instructions`, `constraints`, `output_format`) in the fenced artifact (opening and closing tags)
-  - Ambiguous scope terms in scope-bound text
-  - Negative keywords inside fenced XML artifacts
-  - Hedging language inside fenced XML artifacts
-- **Semantic-only (auditor layer):**
-  - Overall quality/readability of scope wording beyond banned-term checks
-  - Whether instruction binding quality is "good enough" beyond explicit anchor presence
-  - Whether context compaction is optimal for a specific task
-
-## Doc Alignment Validation
-
-Each major workflow requirement added in skills text must map to at least one principle:
-
-- Structured/scoped instructions
-- Clear sequential process
-- Positive framing
-- Explicit acceptance criteria
-- Concrete output format contract
-- Reversibility/safety constraints
-
-## Traceability Validation
-
-Each major requirement in skill text should point to:
-
-- Anthropic best-practice URL, and/or
-- Local source file path used as authority