@sentry/warden 0.22.0 → 0.24.0

package/src/internal-skills/skill-writer/references/artifact-layouts/reference-backed-skill-layout.md

@@ -0,0 +1,35 @@
+# Reference-Backed Skill Layout
+
+Use this layout when the skill needs deep knowledge, but most runs only need one branch or subset of that knowledge.
+
+## Choose this layout when
+
+- `SKILL.md` can act as a router
+- bundled references can stay focused by lookup need
+- the complexity is optional knowledge, not heavy automation
+
+## File layout
+
+```text
+my-skill/
+├── SKILL.md
+└── references/
+    ├── focused-topic-a.md
+    ├── focused-topic-b.md
+    └── troubleshooting.md
+```
+
+Subfolders are acceptable when they make the lookup path clearer, for example `references/api/` or `references/examples/`.
+
+## Required contract
+
+1. `SKILL.md` tells the agent exactly when to open each reference.
+2. Reference filenames predict their contents.
+3. No reference mixes routing, troubleshooting, examples, and source notes without a clear reason.
+4. Large references include navigation or are split further.
+
+## Avoid this layout when
+
+- the skill is small enough to stay inline
+- scripts or validators are central to execution
+- the references would only exist as vague topic buckets

package/src/internal-skills/skill-writer/references/artifact-layouts/script-backed-skill-layout.md

@@ -0,0 +1,31 @@
+# Script-Backed Skill Layout
+
+Use this layout when parsing, validation, APIs, or repeatable transformations are fragile in plain shell or prose alone.
+
+## Choose this layout when
+
+- the skill benefits from deterministic automation
+- repeated shell snippets would be brittle
+- validation or data extraction should be reusable
+
+## File layout
+
+```text
+my-skill/
+├── SKILL.md
+└── scripts/
+    ├── fetch.py
+    └── validate.py
+```
+
+## Required contract
+
+1. Every script is named in `SKILL.md` with arguments, outputs, and fallback behavior.
+2. Scripts are non-interactive.
+3. Standard output is structured when practical.
+4. The skill explains what to do if a script fails or is unavailable.
+
+## Avoid this layout when
+
+- one simple shell command is enough
+- the "script" would only wrap trivial shell for no reliability gain

package/src/internal-skills/skill-writer/references/authoring-path.md

@@ -0,0 +1,91 @@
+# Authoring Path
+
+Use this path to create or update skill files.
+
+## Runtime Writing Rules
+
+1. Frontmatter must be first line.
+2. `name` must match the directory.
+3. `description` must contain realistic trigger language.
+4. Keep runtime guidance imperative and compact.
+5. Prefer tables, checklists, templates, and examples over prose.
+6. Use `SKILL.md` as the runtime decision layer for complex skills.
+
+## Path Rules
+
+1. Treat the skill directory as the root for bundled files.
+2. Use `references/...`, `scripts/...`, and `assets/...` paths by default.
+3. Reserve repo-root paths for registration instructions only.
+4. Follow repo prior art if the workspace already standardizes on a provider-specific path variable.
+5. Avoid host-specific absolute filesystem paths.
+
+## Supporting Files
+
+Create only what the skill needs:
+
+| File or dir | Use |
+|-------------|-----|
+| `SPEC.md` | maintenance contract |
+| `references/` | optional depth loaded by route |
+| `references/evidence/` | persistent iteration examples |
+| `scripts/` | repeatable automation or validation |
+| `assets/` | reusable templates or static artifacts |
+
+Subfolders inside `references/` are acceptable only when they make the lookup path clearer.
+
+## File Creation Rules
+
+1. Read `references/reference-architecture.md` before adding bundled files.
+2. Create a new reference only when it has a clear "open when..." reason.
+3. If you add a bundled reference, add a direct routing entry for it in `SKILL.md`.
+4. Do not create catch-all docs that mix workflow, source notes, examples, and eval results.
+5. Keep provenance in `SOURCES.md`, not in runtime files.
+6. Update `SPEC.md` when the skill contract changes materially.
+
+## Class-Specific Requirements
+
+### `integration-documentation`
+
+Require focused coverage for:
+
+1. API surface and behavior contracts
+2. config/runtime options
+3. common downstream use cases
+4. known issues and workarounds
+5. version or migration variance
+
+Default minimum depth:
+
+1. at least 6 concrete downstream use cases
+2. at least 8 issue/fix or failure/workaround entries
+
+## Shape-Specific Requirements
+
+| Shape | Require |
+|-------|---------|
+| `router` | route criteria, fallback, per-route contract, misroute recovery |
+| `script-backed-workflow` | documented scripts, non-interactive execution, structured output, fallback |
+| `parallelization` / `orchestrator-workers` | unit of work, worker output schema, merge rule, stop condition |
+| `evaluator-optimizer` | rubric, stop rule, acceptance condition, evidence handling |
+| `subagent-fork` | actionable task, return contract, isolation reason, portability note |
+| `hook-backed` | event scope, side-effect boundary, fallback, safety note |
+| `asset-template` | asset routing, placeholder guidance, validation checklist when needed |
+| `argument-driven` | expected arguments, empty-input behavior, manual-only use when risky |
+
+## Example Requirements
+
+Authoring or generator skills should include:
+
+1. happy-path example
+2. secure or robust variant
+3. anti-pattern plus correction
+
+Do not accept abstract-only guidance when a concrete example is needed.
+
+## Required Output
+
+- updated `SKILL.md`
+- updated `SPEC.md` when required
+- updated or added supporting files
+- explanation of major authoring decisions
+- description-optimization handoff

package/src/internal-skills/skill-writer/references/claude-code/argument-substitutions.md

@@ -0,0 +1,20 @@
+# Claude Argument Substitutions
+
+Load this when the skill uses Claude Code argument fields or substitution variables.
+
+## Supported substitutions
+
+- `$ARGUMENTS`
+- `$ARGUMENTS[N]`
+- `$N`
+- named arguments such as `$issue` when `arguments` is declared
+- `${CLAUDE_SESSION_ID}`
+- `${CLAUDE_EFFORT}`
+- `${CLAUDE_SKILL_DIR}`
+
+## Required contract
+
+1. Document expected arguments and empty-input behavior.
+2. Add quoting-aware examples for multi-word input when ambiguity is likely.
+3. Use manual-only invocation for side-effect-heavy argument-driven skills.
+4. Add portability notes because this syntax is Claude Code-specific.

package/src/internal-skills/skill-writer/references/claude-code/dynamic-context.md

@@ -0,0 +1,16 @@
+# Claude Dynamic Context Injection
+
+Load this when the skill uses Claude Code shell preprocessing with ``!`command` `` or fenced ````!` blocks.
+
+## Use this file for
+
+- stable, high-signal preprocessing
+- small dynamic snippets that are cheaper than adding a full script
+
+## Use sparingly
+
+1. Only inject output that is stable, high-signal, and cheap.
+2. Never inject large or noisy output.
+3. Prefer a normal script or tool call when that is easier to reason about.
+
+Treat this as preprocessing, not model behavior, and add portability notes because it is Claude Code-specific.

package/src/internal-skills/skill-writer/references/claude-code/frontmatter-and-invocation.md

@@ -0,0 +1,33 @@
+# Claude Frontmatter And Invocation
+
+Load this when the skill needs Claude Code-specific frontmatter or invocation control.
+
+## Use this file for
+
+- extra trigger metadata
+- invocation visibility rules
+- skill-scoped model or effort overrides
+- path or shell activation controls
+
+## Relevant fields
+
+| Field | Purpose | Notes |
+|-------|---------|-------|
+| `when_to_use` | extra trigger context for Claude | additive only; keep trigger-rich language in `description` |
+| `disable-model-invocation` | only the user can invoke | good for side-effect-heavy workflows |
+| `user-invocable` | hide from `/` menu and let Claude invoke | good for passive background knowledge |
+| `allowed-tools` | pre-approve tools while skill is active | provider-specific |
+| `model` | skill-scoped model override | provider-specific |
+| `effort` | skill-scoped effort override | provider-specific |
+| `paths` | glob-based activation limits | provider-specific |
+| `shell` | shell for `!` preprocessing | provider-specific |
+
+## Invocation rules
+
+1. If Claude should not decide when to run the skill, set `disable-model-invocation: true`.
+2. If the skill is not a meaningful command for humans, consider `user-invocable: false`.
+3. Keep trigger-rich language in `description` even if `when_to_use` is present.
+
+## Portability rule
+
+When using any Claude-specific field, say why it is necessary and note that it is not portable Agent Skills behavior.

package/src/internal-skills/skill-writer/references/claude-code/hook-backed-skills.md

@@ -0,0 +1,28 @@
+# Claude Hook-Backed Skills
+
+Load this when the skill uses Claude Code hooks for deterministic enforcement around tool or lifecycle events.
+
+## Use this file for
+
+- pre-tool validation for risky commands
+- post-edit formatting or linting
+- scoped guardrails around specific tool events
+
+## Required contract
+
+1. Narrow event and matcher scope.
+2. Explicit side-effect boundaries.
+3. Fallback behavior when hooks are unavailable.
+4. Security note for shell execution, path handling, and sensitive files.
+
+## Security rules
+
+1. Command hooks run with full user permissions.
+2. Validate and sanitize inputs.
+3. Use absolute paths for scripts inside the hook definition.
+4. Avoid sensitive files such as `.env`, `.git/`, and keys.
+5. Test hooks before treating them as trusted enforcement.
+
+## Async note
+
+Async hooks cannot block the action that triggered them; they are not a substitute for synchronous validation.

package/src/internal-skills/skill-writer/references/claude-code/subagent-fork-skills.md

@@ -0,0 +1,22 @@
+# Claude Subagent-Fork Skills
+
+Load this when the skill should run in isolated context with `context: fork`.
+
+## Use this file for
+
+- self-contained delegated investigations
+- isolated context for focus or permission boundaries
+- model or tool specialization where the main thread only needs a summary
+
+## Required contract
+
+1. An actionable task in the skill body.
+2. Expected return or summary contract.
+3. Explicit reason isolation is useful.
+4. Portability note because this is Claude Code-specific.
+
+## Avoid when
+
+1. The skill is passive conventions or reference material.
+2. The task depends heavily on the current conversation history.
+3. The main value comes from inline collaboration rather than delegation.

package/src/internal-skills/skill-writer/references/description-optimization.md

@@ -0,0 +1,28 @@
+# Description Optimization
+
+Use this path to improve skill triggering quality and reduce false matches.
+
+## Trigger quality loop
+
+1. Draft a description with realistic user language and concrete trigger phrases.
+2. Build two query sets:
+- should-trigger queries
+- should-not-trigger queries
+3. Evaluate the current description against both sets.
+4. Edit description wording to improve precision/recall.
+5. Repeat until false positives and false negatives are reduced to acceptable levels.
+
+## Authoring rules
+
+1. Keep the description in third person.
+2. Include what the skill does and when to use it.
+3. Avoid implementation details that do not help triggering.
+4. Avoid provider-specific phrasing unless the skill is intentionally provider-specific.
+5. For provider-agnostic skills, avoid naming Claude, Codex, or any provider in ways that would narrow portability expectations.
+
+## Required output
+
+- Final description text
+- should-trigger query set
+- should-not-trigger query set
+- Summary of edits made to improve trigger behavior

package/src/internal-skills/skill-writer/references/design-principles.md

@@ -0,0 +1,74 @@
+# Skill Design Principles
+
+Use this guide to keep skill instructions dense, scannable, and worth their token cost.
+
+## Core Rule
+
+- Every line should help the agent decide, do, or verify something.
+- Prefer tables, checklists, templates, and input/output examples over explanatory prose.
+- Keep rationale to one short sentence unless the agent is likely to make the wrong choice without it.
+
+## Add Vs Cut
+
+| Keep | Cut |
+|------|-----|
+| project-specific conventions | generic background the agent already knows |
+| non-obvious gotchas | motivational filler |
+| exact commands, schemas, and templates | repeated restatements of the same rule |
+| branch logic and defaults | long essays where a table would work |
+| one strong example | multiple weak examples saying the same thing |
+
+## Match Structure To Fragility
+
+| Fragility | Preferred structure | Avoid |
+|-----------|---------------------|-------|
+| high | exact steps, strict templates, validation gates | open-ended guidance |
+| medium | short checklist plus examples | long rationale-heavy prose |
+| low | brief goals and constraints | overspecified playbooks |
+
+## Preferred Instruction Shapes
+
+| Need | Preferred shape |
+|------|-----------------|
+| choose a path | decision table |
+| do a repeatable task | numbered checklist |
+| enforce output structure | template or schema |
+| show style or tone | input/output examples |
+| diagnose failures | symptom/cause/fix matrix |
+| communicate exact facts | compact reference table |
+
+## Description Rules
+
+- Keep `description` in third person.
+- Put trigger language in `description`, not the body.
+- Front-load what the skill does and when to use it.
+- Do not spend description space on internals unless they improve triggering.
+
+## Runtime Writing Rules
+
+- Use imperative voice.
+- State one default path before mentioning alternatives.
+- Use one term per concept; do not rotate synonyms.
+- Put universal rules in `SKILL.md`; put optional depth in routed refs.
+- If a section is mostly explanation, cut it or replace it with a denser structure.
+
+## Reference Rules
+
+- Reference filenames should predict their contents.
+- Each reference should answer one lookup question.
+- Subfolders are acceptable only when they make the lookup path clearer.
+- Every bundled reference should have a direct "open when..." entry in `SKILL.md`.
+- Do not create catch-all files for notes, context, or mixed patterns.
+
+## Independence And Portability
+
+- Do not require another skill by name at runtime.
+- Use skill-root-relative paths by default.
+- Reuse established repo-specific path variables only when the repo already standardizes on them.
+- Label provider-specific mechanics explicitly and add portability notes when they matter.
+
+## Long Files
+
+- Keep `SKILL.md` short enough to scan as a router.
+- For references over 100 lines, add `## Contents`.
+- If a reference grows because it mixes multiple lookup needs, split it.

package/src/internal-skills/skill-writer/references/evaluation-path.md

@@ -0,0 +1,73 @@
+# Evaluation Path
+
+Load this only when the user asks for evaluation, the change is high-risk, or you need to verify a non-obvious architectural choice.
+
+## Default approach (lightweight, guidance-only)
+
+If you do run evaluation, start here:
+
+1. Define representative prompts for the target skill task.
+2. Compare observed behavior before/after edits in concise notes.
+3. For material skill changes, judge the architectural choice as well as the prose:
+   - class selection: pass/fail
+   - execution shape selection: pass/fail
+   - reference routing clarity: pass/fail
+   - advanced mechanics justification: pass/fail
+   - portability/fallback notes: pass/fail
+4. Mark outcomes as improved, unchanged, or regressed.
+5. Record unresolved weaknesses and next steps.
+
+For `integration-documentation` and `skill-authoring` skills, include a concise depth rubric:
+
+1. API surface coverage: pass/fail.
+2. Known issues/workarounds coverage: pass/fail.
+3. Common use-case coverage: pass/fail.
+4. Gap handling quality (explicit next retrieval actions for partials): pass/fail.
+
+## Deeper eval playbook (optional)
+
+Use this only when:
+
+1. The user requests rigorous evals.
+2. The skill is high-risk or high-cost if wrong.
+3. You need regression-tracking over time.
+
+Suggested workflow:
+
+1. Build a prompt set with positives, implicit triggers, negatives, and wrong-shape temptations.
+2. Capture deterministic run traces (for example `codex exec --json`).
+3. Apply machine-checkable rubric/schema checks (for example `--output-schema` where applicable).
+4. Compare baseline vs updated behavior and report deltas.
+
+For advanced shapes, add targeted checks:
+
+1. routers: should-route and should-not-route prompts
+2. evaluator loops: stop-condition and acceptance checks
+3. subagent-fork skills: task-oriented prompt vs passive-guidance negative
+4. hook-backed skills: fallback behavior and security-note presence
+
+## Optional quantitative benchmark
+
+Run only when explicitly requested or when objective scoring is practical.
+
+1. Define baseline (without skill guidance).
+2. Define with-skill run.
+3. Use the same prompt set and scoring rubric for both.
+4. Report deltas and confidence in the result.
+
+Do not block completion on deeper evals unless the user asks for them.
+
+## Canonical eval prompts
+
+Keep reusable, copy/paste eval prompts in `../EVAL.md`.
+Use those prompts when you need a repeatable depth check against `skill-writer`.
+
+## Agent-agnostic requirement
+
+Keep evaluation instructions tool-agnostic so they work in both Codex and Claude environments.
+
+## Required Output
+
+- Qualitative evaluation summary
+- Deeper eval or quantitative summary (optional, if run)
+- Final acceptance decision and residual risks

package/src/internal-skills/skill-writer/references/examples/documentation-skill.md

@@ -0,0 +1,70 @@
+# Case Study: Documentation Skill Synthesis
+
+## Scenario
+
+Goal: create a skill that helps an agent answer and author code for a library without repeatedly re-reading upstream docs.
+
+## Input collection approach
+
+This case used breadth-first source collection and only stopped when new retrieval yielded mostly duplicates:
+
+1. Official docs landing pages and navigation trees.
+2. All API/class/module reference pages.
+3. Configuration and environment reference pages.
+4. Official examples/tutorials.
+5. Troubleshooting/error catalog pages.
+6. Migration/deprecation/changelog pages.
+7. Upstream repo README plus canonical examples.
+8. In-repo usage of the library (`rg` on imports and key APIs).
+
+## Coverage matrix used
+
+Required dimensions tracked during synthesis:
+
+1. Setup and installation.
+2. Core primitives and API surface.
+3. Configuration and runtime options.
+4. Normal usage patterns.
+5. Edge cases and failure handling.
+6. Version-specific differences.
+7. Migration and deprecation guidance.
+8. Instructional templates/examples for direct reuse.
+
+## Synthesized artifacts produced
+
+The resulting skill references included:
+
+1. Happy-path implementation template.
+2. Production-safe variant with defensive defaults.
+3. Anti-pattern and corrected implementation.
+4. Intent-to-reference routing guide (which section to load for which user request).
+5. Gap log with explicit next retrieval steps.
+
+## Source-to-decision trace (sample)
+
+1. Source class: migration/changelog docs.
+   Decision: add a version-compatibility checklist section to the skill.
+   Why: multiple API signatures existed across versions; without this, answers were inconsistent.
+2. Source class: troubleshooting/error catalog.
+   Decision: add an error-to-fix lookup table in references.
+   Why: user prompts often start from failures, not idealized setup.
+3. Source class: in-repo usage scan (`rg`).
+   Decision: prioritize examples matching local project patterns.
+   Why: produced outputs became directly usable with fewer edits.
+
+## Concrete artifacts (sample)
+
+1. Prompt and output skeleton:
+   Prompt: "Configure <library> client for retries and auth in production."
+   Output: a production-safe template with retry/backoff, timeout defaults, and auth placeholders.
+2. Anti-pattern transformation:
+   Before: single inline config with no timeout/error handling.
+   After: structured config with explicit timeout, retry policy, and failure handling notes.
+3. Reference routing snippet:
+   If request mentions "migration" -> load migration/changelog reference first, then API reference.
+
+## What made this high quality
+
+1. Input retrieval was exhaustive across all doc classes, not just top pages.
+2. The skill shipped transformed examples, not citation-only notes.
+3. Coverage and gaps were explicit, so iteration could continue safely.

package/src/internal-skills/skill-writer/references/examples/evaluator-loop-skill.md

@@ -0,0 +1,38 @@
+# Case Study: Evaluator-Loop Skill Synthesis
+
+## Scenario
+
+Goal: create a skill where one pass is not enough and quality improves through critique and revision.
+
+## Input collection approach
+
+This case collected:
+
+1. examples of first-draft failures
+2. existing review rubrics or acceptance criteria
+3. evidence that critique materially improves output
+4. stopping rules to avoid endless loops
+
+## Coverage matrix used
+
+Required dimensions tracked during synthesis:
+
+1. rubric quality
+2. feedback-to-edit mapping
+3. loop stop conditions
+4. evidence retention between rounds
+
+## Synthesized artifacts produced
+
+The resulting skill references included:
+
+1. first-draft to critique to revision example
+2. rubric reference
+3. max-loop or plateau rule
+4. acceptance checklist
+
+## What made this high quality
+
+1. the rubric was explicit
+2. the loop had a clear stopping rule
+3. the revision process produced measurable improvement rather than vague repetition

package/src/internal-skills/skill-writer/references/examples/hook-backed-skill.md

@@ -0,0 +1,39 @@
+# Case Study: Hook-Backed Skill Synthesis
+
+## Scenario
+
+Goal: create a skill that enforces a deterministic check at a specific lifecycle or tool boundary.
+
+## Input collection approach
+
+This case collected:
+
+1. official hook lifecycle and schema docs
+2. security guidance for shell-executed hooks
+3. examples of narrow matchers vs over-broad hooks
+4. fallback behavior for environments without hooks
+
+## Coverage matrix used
+
+Required dimensions tracked during synthesis:
+
+1. event and matcher scope
+2. decision behavior
+3. security boundaries
+4. fallback behavior
+5. portability constraints
+
+## Synthesized artifacts produced
+
+The resulting skill references included:
+
+1. hook configuration example
+2. safety checklist
+3. fallback path without hooks
+4. anti-pattern showing over-broad or unsafe hook scope
+
+## What made this high quality
+
+1. the hook scope was narrow and auditable
+2. security assumptions were explicit
+3. the skill still described what to do when hooks were unavailable

package/src/internal-skills/skill-writer/references/examples/router-skill.md

@@ -0,0 +1,41 @@
+# Case Study: Router Skill Synthesis
+
+## Scenario
+
+Goal: create a skill that classifies requests into distinct downstream paths without overloading one prompt.
+
+## Input collection approach
+
+This case collected:
+
+1. examples of request categories
+2. known ambiguous cases
+3. downstream resources for each route
+4. historical misroutes and their fixes
+
+Collection stopped only after route criteria and fallback behavior were explicit.
+
+## Coverage matrix used
+
+Required dimensions tracked during synthesis:
+
+1. route categories and triggers
+2. ambiguous or overlapping cases
+3. downstream ownership per route
+4. default/fallback path
+5. misroute recovery behavior
+
+## Synthesized artifacts produced
+
+The resulting skill references included:
+
+1. route-selection table
+2. one reference or script per route
+3. ambiguous-case examples
+4. fallback rule for unclear input
+
+## What made this high quality
+
+1. the route table was explicit
+2. every route had one clear downstream owner
+3. the skill knew what to do when classification was uncertain