@sentry/warden 0.0.0

package/.claude/skills/agent-prompt/references/agentic-patterns.md

@@ -0,0 +1,94 @@
+# Agentic Patterns
+
+Patterns for building effective tool-using agents.
+
+## Tool Boundaries
+
+Define clear tool access for safety:
+
+```typescript
+allowedTools: ['Read', 'Grep'],
+disallowedTools: ['Write', 'Edit', 'Bash', 'WebFetch', 'WebSearch'],
+```
+
+Document available tools in the system prompt so the agent knows its capabilities.
+
+## Investigation Before Reporting
+
+From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
+
+> ALWAYS read and understand relevant files before proposing code edits.
+> Do not speculate about code you have not inspected.
+
+Encourage thorough analysis:
+
+```markdown
+## Analysis Approach
+
+1. **Understand intent**: What is the code trying to do?
+2. **Trace data flow**: Follow variables from input to usage
+3. **Consider edge cases**: Empty, null, zero, negative values?
+4. **Check error paths**: Are failures handled correctly?
+5. **Verify assumptions**: What might not be true?
+```
+
+## Confidence Levels
+
+Require explicit confidence:
+
+```markdown
+"confidence" reflects certainty this is a real issue:
+- **high**: Clear violation, no ambiguity
+- **medium**: Likely issue, context might justify it
+- **low**: Possible concern, needs human review
+```
+
+## Handling Uncertainty
+
+From [OpenAI's agent guidelines](https://cookbook.openai.com/examples/gpt4-1_prompting_guide):
+
+> Different tools should have different uncertainty thresholds.
+
+For analysis:
+
+```markdown
+Only report bugs you are confident are real. Do not speculate or
+report "potential" issues. If you're unsure, don't report it.
+```
+
+## Persistence for Agentic Tasks
+
+From [OpenAI's GPT-5 guide](https://cookbook.openai.com/examples/gpt-5/gpt-5_prompting_guide):
+
+> Keep going until the task is resolved before yielding back to the user.
+
+For multi-step analysis, encourage completion:
+
+```markdown
+Continue investigating until you have checked all relevant code paths.
+Use Read and Grep to trace data flow through the codebase.
+```
+
+## Subagent Isolation
+
+From [agentic best practices](https://www.ranthebuilder.cloud/post/agentic-ai-prompting-best-practices-for-smarter-vibe-coding):
+
+> Each subagent should run in complete isolation. Every call should be
+> like a pure function - same input, same output, no shared state.
+
+Warden achieves this by analyzing each hunk independently.
+
+## Context Management
+
+For long-running tasks, from [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
+
+```markdown
+Your context window will be automatically compacted. Do not stop tasks
+early due to token budget concerns. Save progress before context refreshes.
+```
+
+## Sources
+
+- [Anthropic: Claude 4.x Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
+- [OpenAI: GPT-5 Prompting Guide](https://cookbook.openai.com/examples/gpt-5/gpt-5_prompting_guide)
+- [Agentic AI Prompting Best Practices](https://www.ranthebuilder.cloud/post/agentic-ai-prompting-best-practices-for-smarter-vibe-coding)

package/.claude/skills/agent-prompt/references/anti-patterns.md

@@ -0,0 +1,140 @@
+# Anti-Patterns
+
+Common mistakes to avoid when writing prompts.
+
+## Over-Emphasis and Anchoring
+
+From [Anthropic's Opus 4.5 guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
+
+> Claude Opus 4.5 is more responsive to the system prompt than previous
+> models. Where you might have said "CRITICAL: You MUST...", you can
+> use more normal prompting.
+
+From [Vercel's AGENTS.md research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals):
+
+> Instructions stating "You MUST invoke the skill" caused agents to anchor
+> excessively on documentation patterns while missing project context.
+
+**Avoid:**
+```markdown
+CRITICAL: You MUST ALWAYS check for SQL injection. NEVER skip this.
+IT IS ABSOLUTELY ESSENTIAL that you...
+```
+
+**Prefer:**
+```markdown
+Understand the code's intent first, then check for SQL injection:
+Is user input concatenated into queries instead of parameterized?
+```
+
+The key insight: "MUST" language causes anchoring on the instruction at the expense of contextual understanding.
+
+## Scope Creep
+
+Each skill should do one thing well.
+
+**Avoid:**
+```markdown
+Find security issues, performance problems, and bugs too.
+```
+
+**Prefer:** Create separate skills for each concern.
+
+## Vague Severity
+
+**Avoid:**
+```markdown
+Use high severity for important issues and medium for less important ones.
+```
+
+**Prefer:**
+```markdown
+- **critical**: Crash, data loss, or silent data corruption
+- **high**: Incorrect behavior in common scenarios
+- **medium**: Incorrect behavior in edge cases
+```
+
+## Negative-Only Instructions
+
+**Avoid:**
+```markdown
+Do not output markdown.
+Do not include explanations.
+Do not wrap in code fences.
+```
+
+**Prefer:**
+```markdown
+Return ONLY valid JSON starting with {"findings":
+```
+
+## Missing Exclusions
+
+Without explicit exclusions, skills report everything tangentially related.
+
+**Avoid:** Omitting "What NOT to Report" section.
+
+**Prefer:**
+```markdown
+## What NOT to Report
+
+- Security vulnerabilities (use security-review skill)
+- Style or formatting issues
+- Performance concerns (unless causing incorrect behavior)
+```
+
+## Hallucination-Prone Patterns
+
+From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
+
+> Never speculate about code you have not opened.
+
+**Avoid:** Asking for analysis without providing code context.
+
+**Prefer:** Always include actual code in the prompt (Warden does this automatically).
+
+## Over-Engineering Output
+
+From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
+
+> Claude Opus 4.5 has a tendency to overengineer by creating extra files
+> or adding unnecessary abstractions.
+
+For prompts, keep output requirements minimal:
+
+**Avoid:**
+```markdown
+Include a detailed analysis section, then a summary, then recommendations,
+then a risk assessment matrix, then...
+```
+
+**Prefer:**
+```markdown
+Return JSON with findings array. Keep descriptions to 1-2 sentences.
+```
+
+## Conflicting Instructions
+
+**Avoid:**
+```markdown
+Be thorough and check everything.
+...
+Only report high-confidence issues.
+```
+
+**Prefer:** Consistent stance throughout the prompt.
+
+## Missing Examples
+
+For complex output formats, include an example:
+
+**Avoid:** Schema only without example.
+
+**Prefer:**
+```markdown
+Example response format:
+{"findings": [{"id": "sql-injection-1", "severity": "high", ...}]}
+
+Full schema:
+...
+```

package/.claude/skills/agent-prompt/references/context-design.md

@@ -0,0 +1,124 @@
+# Context Design
+
+Research on how context delivery affects agent performance. Based on [Vercel's AGENTS.md evaluation](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals).
+
+## Key Finding: Passive Context Wins
+
+Vercel's evaluation showed dramatic performance differences:
+
+| Approach | Pass Rate |
+|----------|-----------|
+| No docs | 53% |
+| Skills (default) | 53% |
+| Skills with explicit instructions | 79% |
+| AGENTS.md (passive context) | 100% |
+
+## Why Passive Context Outperforms
+
+Three structural advantages:
+
+### 1. Eliminated Decision Burden
+
+Information exists automatically rather than requiring agent judgment about when retrieval is necessary.
+
+**Implication for skills:** Warden injects skill prompts directly into the system prompt. This is passive context - the agent doesn't need to decide to load the skill.
+
+### 2. Persistent Availability
+
+Documentation remains accessible throughout every conversation turn via system prompt.
+
+**Implication for skills:** Keep skill prompts self-contained. Don't require the agent to fetch additional context to understand the task.
+
+### 3. Avoided Sequencing Problems
+
+No competing instructions about whether to explore first vs consult docs first.
+
+**Implication for skills:** Be explicit about the analysis approach. Don't leave ordering ambiguous.
+
+## Instruction Wording Matters
+
+Subtle wording differences produced dramatically divergent outcomes:
+
+| Wording | Effect |
+|---------|--------|
+| "You MUST invoke the skill" | Agent anchored on docs, missed project context |
+| "Explore project first, then invoke skill" | Agent built context first, better results |
+
+### Recommendations
+
+**Avoid:**
+```markdown
+You MUST check for SQL injection on every code change.
+```
+
+**Prefer:**
+```markdown
+Understand the code's intent first, then check for SQL injection:
+Is user input concatenated into queries?
+```
+
+## Retrieval-Led Reasoning
+
+From Vercel's research:
+
+> "Prefer retrieval-led reasoning over pre-training-led reasoning"
+
+This means: look at the actual code before applying general knowledge.
+
+**For Warden skills:**
+```markdown
+## Analysis Approach
+
+1. Read the code context provided
+2. Use Read/Grep to investigate related files if needed
+3. Apply skill criteria to what you've observed
+4. Only report issues you've verified in the code
+```
+
+## Compression Works
+
+Vercel reduced docs from 40KB to 8KB (80% reduction) with no loss in effectiveness.
+
+**Implication for skills:**
+- Concise prompts work as well as verbose ones
+- Use structured formats (tables, lists) over prose
+- Index references rather than including full content
+
+**Example - compressed reference:**
+```markdown
+### Injection Types
+SQL|Command|Template|Header|XSS|Path traversal
+```
+
+vs verbose:
+```markdown
+There are several types of injection vulnerabilities you should check for.
+First, SQL injection occurs when... Second, command injection...
+```
+
+## When Skills Add Value
+
+Skills remain valuable for:
+- User-triggered workflows (version upgrades, migrations)
+- Explicit "apply this standard" requests
+- Tasks requiring specific tool sequences
+
+For general knowledge that should always apply, passive context wins.
+
+## Application to Warden
+
+Warden's architecture aligns with these findings:
+
+1. **Passive injection** - Skill prompts are injected into system prompt
+2. **Hunk context provided** - Code is in the user prompt, not requiring retrieval
+3. **Read-only tools available** - Agent can investigate but starts with context
+
+To maximize effectiveness:
+- Write self-contained skill prompts
+- Include analysis approach (explore → apply criteria)
+- Avoid "MUST" language that causes anchoring
+- Keep prompts concise with structured references
+
+## Sources
+
+- [Vercel: AGENTS.md Outperforms Skills](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)

package/.claude/skills/agent-prompt/references/core-principles.md

@@ -0,0 +1,75 @@
+# Core Principles
+
+Foundational rules for writing effective prompts. Derived from [Anthropic's official documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices).
+
+## 1. Be Explicit
+
+Claude 4.x models respond well to clear, explicit instructions.
+
+**Less effective:**
+```
+Review this code for issues.
+```
+
+**More effective:**
+```
+Analyze the code changes for security issues. Only report genuine
+security concerns, not style issues.
+```
+
+## 2. Provide Context and Motivation
+
+Explain *why* a behavior matters.
+
+**Less effective:**
+```
+Never report style issues.
+```
+
+**More effective:**
+```
+Do not report style issues. This skill focuses on security vulnerabilities.
+Style issues are handled by code-simplifier and would create noise here.
+```
+
+## 3. Be Vigilant with Examples
+
+Claude pays close attention to examples. Ensure they demonstrate desired behaviors only.
+
+## 4. Prefer Positive Instructions
+
+Tell Claude what to do, not what to avoid.
+
+**Less effective:**
+```
+Do not use markdown in your response.
+```
+
+**More effective:**
+```
+Return ONLY valid JSON starting with {"findings":
+```
+
+## 5. Scope Narrowly
+
+Broad prompts decrease accuracy. Each skill should have one clear focus.
+
+**Less effective:**
+```
+Find bugs, security issues, performance problems, and style violations.
+```
+
+**More effective:**
+```
+Identify functional bugs that cause incorrect behavior. Focus on null
+handling, off-by-one errors, and async issues.
+```
+
+## 6. Match Prompt Style to Output
+
+The formatting in your prompt influences Claude's response style. Remove markdown from prompts if you want less markdown in output.
+
+## Sources
+
+- [Anthropic: Claude 4.x Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
+- [OpenAI: Prompt Engineering Guide](https://platform.openai.com/docs/guides/prompt-engineering)

package/.claude/skills/agent-prompt/references/model-guidance.md

@@ -0,0 +1,118 @@
+# Model-Specific Guidance
+
+Optimizations for Claude 4.x models (Sonnet 4.5, Opus 4.5).
+
+## Claude 4.x Strengths
+
+| Capability | Implication |
+|------------|-------------|
+| Precise instruction following | Can use simpler, more natural prompts |
+| Structured output (JSON) | Reliable parsing without complex extraction |
+| Parallel tool calling | Can investigate multiple files simultaneously |
+| Long-horizon state tracking | Maintains context across extended sessions |
+
+## Prompting Adjustments
+
+### Simpler Language
+
+Claude 4.x doesn't need aggressive emphasis:
+
+**Before (older models):**
+```markdown
+CRITICAL: You MUST use this tool when...
+```
+
+**After (Claude 4.x):**
+```markdown
+Use this tool when...
+```
+
+### More Direct Communication
+
+From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
+
+> Claude 4.5 models have a more concise and natural communication style.
+> More direct and grounded, provides fact-based progress rather than
+> self-celebratory updates.
+
+### Explicit Thoroughness
+
+Claude 4.x may be conservative. If you want thorough analysis:
+
+```markdown
+Go beyond the basics to create a fully-featured analysis. Include
+as many relevant findings as possible.
+```
+
+## Thinking and Reflection
+
+Claude 4.x supports thinking between tool calls:
+
+```markdown
+After receiving tool results, carefully reflect on their quality and
+determine optimal next steps before proceeding.
+```
+
+### Interleaved Thinking
+
+For complex multi-step analysis:
+
+```markdown
+Use your thinking to plan and iterate based on new information,
+then take the best next action.
+```
+
+### Thinking Sensitivity
+
+From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
+
+> When extended thinking is disabled, Claude Opus 4.5 is particularly
+> sensitive to the word "think" and its variants.
+
+If not using extended thinking, prefer alternatives:
+- "consider" instead of "think about"
+- "evaluate" instead of "think through"
+- "reflect on" instead of "think over"
+
+## Tool Usage
+
+Claude 4.x excels at parallel tool execution:
+
+```markdown
+If you intend to call multiple tools and there are no dependencies,
+make all independent calls in parallel.
+```
+
+### Proactive vs Conservative
+
+To make Claude more proactive:
+
+```markdown
+By default, implement changes rather than only suggesting them.
+Infer the most useful action and proceed.
+```
+
+To make Claude more conservative:
+
+```markdown
+Do not take action unless clearly instructed. Default to providing
+information and recommendations rather than making changes.
+```
+
+## Code Exploration
+
+From [Anthropic's guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices):
+
+> Claude Opus 4.5 can be overly conservative when exploring code.
+
+If needed, add explicit instructions:
+
+```markdown
+ALWAYS read and understand relevant files before reporting issues.
+Do not speculate about code you have not inspected.
+```
+
+## Sources
+
+- [Anthropic: Claude 4.x Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices)
+- [Anthropic: What's New in Claude 4.5](https://docs.claude.com/en/about-claude/models/whats-new-claude-4-5)

package/.claude/skills/agent-prompt/references/output-formats.md

@@ -0,0 +1,98 @@
+# Output Formats
+
+How to specify structured output for reliable parsing.
+
+## Enforce JSON-Only Output
+
+Be explicit about format requirements:
+
+```markdown
+IMPORTANT: Your response must be ONLY a valid JSON object.
+No markdown, no explanation, no code fences.
+
+Example response format:
+{"findings": [{"id": "example-1", "severity": "medium", ...}]}
+```
+
+## Provide Complete Schema
+
+Include all available fields so Claude knows the full structure:
+
+```json
+{
+  "findings": [
+    {
+      "id": "unique-identifier",
+      "severity": "critical|high|medium|low|info",
+      "confidence": "high|medium|low",
+      "title": "Short descriptive title",
+      "description": "Detailed explanation",
+      "location": {
+        "path": "path/to/file.ts",
+        "startLine": 10,
+        "endLine": 15
+      },
+      "suggestedFix": {
+        "description": "How to fix",
+        "diff": "unified diff format"
+      }
+    }
+  ]
+}
+```
+
+## Field Requirements
+
+Document which fields are required vs optional:
+
+```markdown
+Requirements:
+- Return ONLY valid JSON starting with {"findings":
+- "findings" array can be empty if no issues found
+- "location.path" is auto-filled - just provide startLine (and optionally endLine). Omit location for general findings.
+- "confidence" reflects certainty given codebase context
+- "suggestedFix" is optional - only include when the fix is complete, correct, and applies to the same file being analyzed. If the fix requires changes to a different file, describe it in the description instead.
+```
+
+## Set Length Expectations
+
+Prevent verbose output:
+
+```markdown
+Keep descriptions SHORT (1-2 sentences max)
+Be concise - focus only on the changes shown
+```
+
+## Empty Results
+
+Explicitly allow empty arrays:
+
+```markdown
+Return an empty findings array if no issues match the skill's criteria:
+{"findings": []}
+```
+
+## Warden's JSON Extraction
+
+The runner handles common output issues (`src/sdk/runner.ts`):
+
+- Strips markdown code fences if present
+- Finds `{"findings"` pattern in prose
+- Extracts balanced JSON with nested objects
+- Validates against FindingSchema with Zod
+
+This provides resilience, but clean JSON output is still preferred.
+
+## Severity Level Definitions
+
+Severity reflects **urgency and required action**, not the type of issue. Each skill defines what "significant impact" means in its domain.
+
+| Level    | Definition                                               |
+|----------|----------------------------------------------------------|
+| critical | Must fix before merge: significant impact if ignored     |
+| high     | Should fix before merge: notable issue affecting quality |
+| medium   | Worth reviewing: potential issue, may need action        |
+| low      | Minor: address when convenient                           |
+| info     | Informational: no action required                        |
+
+Avoid vague definitions like "important" or "less important."