claude-dev-env 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.10.0",
+    "version": "1.11.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/prompt-generator/REFERENCE.md

@@ -11,6 +11,8 @@ When authoring or refining prompts, ground decisions in these sources. If guidan
 - https://transformer-circuits.pub/2026/emotions/index.html -- emotion concepts research (April 2026): 171 internal activation patterns that causally influence behavior. Key prompt-engineering takeaways: clear criteria and escape routes improve output quality, collaborative framing activates engagement, positive task framing correlates with better results, inviting transparency produces more reliable output. Cross-model caveat: studied on Sonnet 4.5; patterns align with best practices independently.
 - 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)
 
@@ -37,6 +39,56 @@ When authoring or refining prompts, ground decisions in these sources. If guidan
 
 If sources disagree on a technique, apply in order: Anthropic documentation first (it describes the actual model behavior), then OpenAI/Google/Microsoft (large-scale research with cross-model relevance), then community sources (patterns and intuition, not authoritative on model internals). When Tier 3 contradicts Tier 1, Tier 1 wins without exception.
 
+## 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](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) is stateless—re-supply prior actions, tool definitions, and instructions each turn. Maximize [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits: **stable prefix first, dynamic tail last**; **append** new content via **messages** instead of rewriting the cached prompt; **avoid mid-session model switches** (caches are model-specific—use a **subagent** for a cheaper model); **treat the tool list as part of the cached prefix** and avoid churn; use **tool search** so dynamic discovery **appends** without invalidating the prefix; for multi-turn agents, **advance breakpoints** toward the latest message (**auto-caching**). Cached input tokens are priced at **10% of base input** per [pricing](https://platform.claude.com/docs/en/about-claude/pricing).
+
+### 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.

package/skills/prompt-generator/SKILL.md

@@ -19,6 +19,8 @@ description: >-
 
 **Canonical source:** https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices — the single reference for Claude's latest models. When sources conflict, defer to the authority tiers (Anthropic > major labs > community).
 
+**Harness hygiene:** Re-test harness assumptions about what Claude cannot do alone on each model generation or major product release—stale compensations bottleneck performance as capabilities improve (Hook 1; [Harnessing Claude's intelligence](https://claude.com/blog/harnessing-claudes-intelligence), inventory `docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md`).
+
 **Eval contract:** The user-visible behavior this skill must satisfy is defined in `packages/claude-dev-env/skills/prompt-generator/TARGET_OUTPUT.md`. Automated evals live in `packages/claude-dev-env/skills/prompt-generator/evals/prompt-generator.json`.
 
 **Terminology:** **Prompt artifact** — the full XML inside the single user-facing `xml` fence (the paste-ready handoff). **Scope block** — the five-key contract in §3A that grounds instructions. **Default refinement pipeline** — §10: base draft → section refine → merge → 14-row compliance audit → capped fixes (subagent-internal unless draft-only). **Light self-check** — §8: fast pre-return sanity pass (shape, tools, scope, patterns); *not* the compliance audit. **Compliance audit (14-row)** — §11: hook-keyed rows that set the `Audit: pass|fail` numerator. **Execution handoff** — `/agent-prompt` after explicit user intent to run work.
@@ -59,16 +61,17 @@ Match `TARGET_OUTPUT.md`. Summary:
 |----------|---------|-------------|-----------------|
 | **1 — Fresh brief goal** | `/prompt-generator` with short goal; little session context | **3–5** parallel Glob/Grep (or equivalent) **before** any question | **One** form, **2–4** questions |
 | **2 — Session handoff** | User wants a prompt so a **new** session can continue this thread | **Conversation only** — skip redundant repo tools for facts already stated | **One** form, **1–2** questions |
-| **3 — Long unstructured input** | Many requirements / paths in one message | Verify repo references (packages, shared utils, configs) with targeted tools **before** questions | First question **confirms extracted intent**; ambiguities as **specific** options |
+| **3 — Long unstructured input** | Many requirements / paths in one message | Verify repo references (packages, shared utils, configs) with targeted tools **before** questions | First question **confirms extracted intent**; ambiguities as **specific** options; **every** user-stated requirement captured in the generated XML by name — track all requirements from the unstructured input and confirm coverage before shipping |
 | **4 — Noisy context** | Long unrelated thread before `/prompt-generator` | Build the subagent brief from: the user’s literal `/prompt-generator` text, a **≤120-word** summary of on-topic facts, and discovery notes—**exclude** raw stack traces and unrelated tangents | As needed (often Scenario 1-shaped) |
 
-**Handoff (Scenario 2):** `<context>` must be **self-contained** — state, **decisions**, files touched, next steps, constraints — so a new session needs no prior chat.
+**Handoff (Scenario 2):** `<context>` must be **self-contained** — state, **decisions**, files touched, next steps, constraints — so a new session needs no prior chat. Preserve prior decisions verbatim in the handoff; quote the exact decision text where precision matters rather than paraphrasing it away.
 
 ## Phase ordering (structural invariant A)
 
 For the **final** user-visible turn that ships the artifact:
 
 - Compose the message as **audit line → opening fence → XML → closing fence → end**; keep the byte stream free of `tool_use` blocks **between** the opening and closing fences.
+- **Completeness:** End every numbered step inside `<instructions>` with a complete sentence and a fully written list item. Balance every XML tag explicitly (open and close each `<role>`, `<context>`, `<instructions>`, `<constraints>`, `<output_format>`). The artifact must be copy-pasteable into a new file with zero manual repair.
 - Global pipeline: **discovery tools** (when applicable) → **AskUserQuestion** → **subagent** (draft + refinement + internal audit) → **one** orchestrator reply containing only audit line + fence.
 
 ## Interactive discovery mode (default)
@@ -109,7 +112,7 @@ Match specificity to task fragility:
 
 - **High:** Multiple valid approaches; numbered goals and acceptance criteria.
 - **Medium:** Preferred pattern exists; pseudocode or parameterised template.
-- **Low:** Fragile or safety-critical; numbered steps with explicit file paths, command names, and **allowed / disallowed action lists** (e.g. “Allowed: `pytest packages/foo/tests`; Disallowed: `git push --force` without user approval”).
+- **Low:** Fragile or safety-critical; numbered steps with explicit file paths, command names, and **permitted-action-only lists** (e.g. “Permitted: `pytest packages/foo/tests`; requires explicit user approval before: `git push --force`”).
 
 ### 3. Collect required missing facts
 
@@ -131,13 +134,13 @@ Use this scope block as the grounding contract for all generated instructions. E
 
 Apply principles from Anthropic’s prompting guide (see REFERENCE.md): XML sections, role, motivation in `<context>`, positive framing, emotion-informed collaborative tone where appropriate, **commit-and-execute** for multi-step agent prompts.
 
-**Structural invariant D:** Write `<instructions>` / `<constraints>` as direct imperatives (“Open `path/to/file.ts` and …”). Park unresolved items in `<open_question>` tags—one distinct question per tag with the exact decision you need.
+**Structural invariant D:** Write `<instructions>` / `<constraints>` as direct imperatives (“Open `path/to/file.ts` and …”). Park unresolved items in `<open_question>` tags—one distinct question per tag with the exact decision you need. Inside the fenced XML artifact, use only confident, definitive language: replace hedging phrases (“let me also check”, “actually”, “one more consideration”) and tentative qualifiers (“might be”, “possibly”, “I think”, “could be”) with direct assertions or move genuine uncertainty into `<open_question>` tags.
 
 **Set a role** in the system prompt. Anthropic: "Setting a role in the system prompt focuses Claude's behavior and tone for your use case. Even a single sentence makes a difference."
 
 **Add motivation behind constraints** in `<context>`. Anthropic: "Providing context or motivation behind your instructions... can help Claude better understand your goals and deliver more targeted responses." Claude generalizes from the explanation.
 
-**Frame positively.** Anthropic: state the desired outcome directly. "Your response should be composed of smoothly flowing prose paragraphs" provides clearer guidance than a prohibition-only instruction.
+**Frame positively (zero-negative-keyword rule).** Anthropic: state the desired outcome directly. "Your response should be composed of smoothly flowing prose paragraphs" provides clearer guidance than a prohibition-only instruction. Apply this rule absolutely inside the fenced XML artifact across all sections (`<role>`, `<context>`, `<instructions>`, `<constraints>`, `<output_format>`): every instruction states what to do, what to produce, what to enforce. Use affirmative directives exclusively: "only X", "always X", "ensure X", "require X." Banned keywords inside generated XML: "no", "not", "don't", "do not", "never", "avoid", "without", "refrain", "stop", "prevent", "exclude", "prohibit", "forbid", "reject." Also banned: indirect negative patterns such as "instead of X", "rather than X", "as opposed to." Example pass: "Ensure all functions have explicit return types." Example fail: "Do not leave return types implicit." When a boundary is needed, phrase it as what is permitted: "only run commands within the scoped paths" rather than a prohibition.
 
 **Emotion-informed framing.** Anthropic's emotion concepts research (2026) shows that internal activation patterns causally influence output quality. Apply: explicit success criteria with "say so if you're unsure" as an accepted answer; collaborative language ("help figure out", "work on this together"); framing tasks as interesting problems rather than chores; constructive, forward-looking tone. Cross-model caveat: studied on Sonnet 4.5; the patterns align with Anthropic's prompting best practices independently. Full pattern catalog and citations: `packages/claude-dev-env/docs/emotion-informed-prompt-design.md`.
 
@@ -145,6 +148,12 @@ Apply principles from Anthropic’s prompting guide (see REFERENCE.md): XML sect
 
 **Commit-and-execute pattern.** Anthropic: "When you're 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." For prompts that guide agents through multi-step work, include this pattern so the agent doesn't spin revisiting decisions.
 
+**Tool-return policy (agent-harness / tool-use prompts):** Require explicit justification before the harness tokenizes full tool outputs; when the next hop needs only a slice or a tool-to-tool handoff, steer authors toward code execution (bash/REPL) so only execution output reaches model-visible context—not every intermediate payload (Hook 2; [Harnessing Claude's intelligence](https://claude.com/blog/harnessing-claudes-intelligence)).
+
+**Bash + text-editor foundation:** Prefer bash and the text editor for file work; treat Agent Skills, programmatic tool calling, and the memory tool as compositions of those primitives—state which primitive stack the harness assumes (Hook 3; same post).
+
+**Progressive disclosure:** Avoid monolithic system prompts packed with rarely used task branches; keep short always-on summaries and load full bodies via a read path when relevant (skills YAML frontmatter pattern per [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)) (Hook 4; same post).
+
 **For long context** (20k+ tokens): put documents first, query/instructions last. Anthropic: "Queries at the end can improve response quality by up to 30% in tests." Ground responses in quotes from source material before analysis.
 
 ### 5. Control output format
@@ -172,6 +181,7 @@ Expand the light self-check with this internal checklist when useful:
 - [ ] **Code prompts** include read-before-claim grounding ("read files first; say 'I don't know' when uncertain") and anti-test-fixation (general solutions, flag bad tests)
 - [ ] **Research prompts** include the structured-investigation pattern with competing hypotheses, confidence tracking, and self-critique
 - [ ] **Agentic prompts** that span multiple context windows address state management (context awareness, multi-window workflow, structured state files)
+- [ ] **Agent-harness prompts** for long browse/search or multi-window work cite the context stack levers in **REFERENCE.md → Harness design patterns** (context editing, subagents, compaction, memory folder) (Hook 5)
 - [ ] Emotion-informed framing is present: collaborative language, explicit success criteria, and explicit permission to express uncertainty ("say so if unsure")
 - [ ] Constraints are surfaced upfront (proactive constraint awareness) so the model can incorporate them into its plan, and each non-obvious constraint carries its motivation
 - [ ] Self-correction chaining is considered when the prompt must hold up over time (generate → review → refine)
@@ -239,6 +249,7 @@ When the user explicitly asks for debug / full audit, emit the markdown table, `
 ### 14. Source anchors for pipeline requirements
 
 - Anthropic Prompting Best Practices: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
+- Harness economics (context stack, caching, typed tools, benchmarks): **REFERENCE.md → Harness design patterns**
 - Autonomy / reversibility / no safety-bypass: same + “Autonomy and safety pattern” below
 - Evidence-grounding / read-before-claim policy: `packages/claude-dev-env/skills/prompt-generator/REFINEMENT_PIPELINE_RUNBOOK.md`
 
@@ -280,14 +291,16 @@ For `agent-harness` and `tool-use` prompt types, embed this **reversibility ladd
 ```text
 Default: take local, reversible actions first—read files, run targeted tests, apply patches under paths the user scoped.
 
-Before running any command that deletes data, rewrites shared history, or notifies other people, stop and ask the user for explicit approval. Concrete categories:
+For commands that delete data, rewrite shared history, or notify other people, obtain explicit user approval first. Concrete categories requiring approval:
 - File or branch deletion, database drops, `rm -rf`
 - `git push --force`, `git reset --hard`, rewriting published commits
 - Pushes, PR comments, chat messages, or emails visible outside this workspace
 
-When tests fail or tooling blocks progress, prefer iterative fixes inside the allowed scope. Keep safety hooks (`--verify`, linters) enabled; surface unfamiliar files as questions instead of deleting them.
+When tests fail or tooling blocks progress, prefer iterative fixes inside the allowed scope. Keep safety hooks (`--verify`, linters) enabled; surface unfamiliar files as questions.
 ```
 
+**Positive rewrite guidance:** When embedding this pattern into a generated XML artifact, rephrase each line using affirmative directives only (per the zero-negative-keyword rule in §4). Example rewrite for generated output: "Prioritize local, reversible actions: read files, run targeted tests, apply patches within scoped paths. Obtain explicit user approval before running commands that delete data, rewrite shared history, or send external notifications. Keep safety hooks enabled (`--verify`, linters). Surface unfamiliar files as questions for the user."
+
 ## Research prompt pattern
 
 For `research` prompt types:
@@ -302,4 +315,6 @@ Search for this information in a structured way. As you gather data, develop sev
 2. **Tier 2:** OpenAI, Google DeepMind, Microsoft Research
 3. **Tier 3:** Community / blogs
 
+**Out-of-scope guard (Hook 12):** [Harnessing Claude's intelligence](https://claude.com/blog/harnessing-claudes-intelligence) and `docs/references/anthropic-harnessing-claudes-intelligence-technique-inventory.md` cover harness evolution, context economics, caching, and declarative boundaries—not a substitute for a full security threat model or product-specific compliance catalog unless paired with other Tier 1 or governance sources.
+
 Full links: `REFERENCE.md`.

package/skills/prompt-generator/evals/prompt-generator.json

@@ -118,6 +118,21 @@
         "All uncertainty expressed as <open_question> tags, not inline hedges",
         "Prompt reads as confident complete instructions, not a draft-in-progress"
       ]
+    },
+    {
+      "id": 9,
+      "name": "zero_negative_phrasing_in_output",
+      "scenario": "Content quality gate A (anti-pattern elimination)",
+      "prompt": "/prompt-generator Write a system prompt for an agent that reviews TypeScript code for type safety, enforces strict null checks, and ensures all function signatures have complete type annotations",
+      "files": [],
+      "expected_behavior": [
+        "Fenced prompt artifact contains zero hard anti-pattern keywords: 'no', 'not', 'don't', 'do not', 'never', 'avoid', 'without', 'refrain', 'stop', 'prevent', 'exclude', 'prohibit', 'forbid', 'reject'",
+        "Zero indirect anti-patterns: 'instead of X' (implies X is bad), 'rather than X', 'as opposed to'",
+        "Every instruction phrased as a positive directive: what TO do, what TO produce, what TO enforce",
+        "Constraints section uses affirmative boundaries: 'only X', 'always X', 'ensure X', 'require X' — positive framing throughout",
+        "Example: 'Ensure all functions have explicit return types' passes; 'Do not leave return types implicit' fails; 'Avoid missing return types' fails",
+        "Applies to all sections inside the fenced block: <role>, <context>, <instructions>, <constraints>, <output_format>"
+      ]
     }
   ]
 }