@sentry/warden 0.0.0

package/.claude/skills/agent-prompt/references/skill-structure.md

@@ -0,0 +1,115 @@
+# Skill Structure
+
+How to write effective Warden skill files.
+
+## File Format
+
+Skills use YAML frontmatter + markdown body:
+
+```markdown
+---
+name: skill-name
+description: Brief description for discovery and trigger matching.
+allowed-tools: Read Grep Glob
+---
+
+[Prompt body - the actual instructions]
+```
+
+## Required Frontmatter
+
+| Field | Purpose |
+|-------|---------|
+| `name` | Unique identifier, lowercase with hyphens |
+| `description` | One line explaining when to use this skill |
+| `allowed-tools` | Space-separated list (typically `Read Grep Glob`) |
+
+## Recommended Body Structure
+
+```markdown
+[Role statement - who the agent is]
+
+## Your Task
+
+[Clear statement of what to analyze]
+
+### [Category 1]
+
+- Specific pattern to look for
+- Guiding questions: "Is X happening? Does Y exist?"
+
+### [Category 2]
+
+...
+
+## What NOT to Report
+
+[Explicit exclusions prevent scope creep]
+
+## Severity Levels
+
+[Definitions tied to impact]
+
+## Output Requirements
+
+[Formatting expectations]
+```
+
+## Effective Patterns
+
+### Guiding Questions
+
+Help the agent know what to look for:
+
+```markdown
+### Injection Vulnerabilities
+- **SQL injection**: User input concatenated into queries instead of parameterized?
+- **Command injection**: User input passed to shell/exec functions?
+```
+
+### Explicit Exclusions
+
+Prevent false positives and scope creep:
+
+```markdown
+## What NOT to Report
+
+- Security vulnerabilities (use security-review skill)
+- Style or formatting issues
+- Code that "could be better" but works correctly
+```
+
+### Confidence Calibration
+
+Set expectations for certainty:
+
+```markdown
+Do NOT use low or info severity - if you're not confident it's a real
+bug, don't report it.
+```
+
+### Severity Tied to Impact
+
+Avoid vague definitions:
+
+```markdown
+- **critical**: Crash, data loss, or silent data corruption
+- **high**: Incorrect behavior in common scenarios
+- **medium**: Incorrect behavior in edge cases
+```
+
+## File Locations
+
+Skills are discovered in order (first match wins):
+
+1. `.warden/skills/{name}/SKILL.md` - Project-specific
+2. `.agents/skills/{name}/SKILL.md` - Shared agent skills
+3. `.claude/skills/{name}/SKILL.md` - Claude Code skills
+4. `skills/{name}/SKILL.md` - Built-in skills
+
+## Examples
+
+See existing skills for reference:
+- `skills/security-review/SKILL.md` - Comprehensive checklist approach
+- `skills/find-bugs/SKILL.md` - Confidence-focused with exclusions
+- `skills/code-simplifier/SKILL.md` - Balanced "do/don't" guidance

package/.claude/skills/agent-prompt/references/system-prompts.md

@@ -0,0 +1,115 @@
+# System Prompts
+
+How Warden constructs system prompts and how to customize them.
+
+## Warden's Prompt Architecture
+
+Warden builds a two-layer prompt for each analysis:
+
+### System Prompt (Built by Runner)
+
+Constructed in `src/sdk/runner.ts`:
+
+```xml
+<role>
+You are a code analysis agent for Warden...
+</role>
+
+<tools>
+Available tools: Read, Grep
+</tools>
+
+<skill_instructions>
+{skill.prompt injected here}
+</skill_instructions>
+
+<output_format>
+JSON schema and requirements
+</output_format>
+
+<skill_resources>
+Path to skill assets (if applicable)
+</skill_resources>
+```
+
+### User Prompt (Per-Hunk)
+
+Each code change is analyzed with:
+- Skill name being applied
+- Formatted code context (before/after lines)
+- The diff hunk
+- Instruction to only report matching findings
+
+## XML Tags for Structure
+
+Use XML tags to create clear sections:
+
+```xml
+<role>...</role>
+<tools>...</tools>
+<skill_instructions>...</skill_instructions>
+```
+
+**Benefits:**
+- Clear boundaries between sections
+- Model can reference sections by name
+- Consistent parsing and validation
+
+## Role Definition
+
+The role section establishes:
+
+| Element | Purpose |
+|---------|---------|
+| Identity | What kind of expert is this agent? |
+| Scope | What does it evaluate? What's out of scope? |
+| Stance | Conservative (avoid false positives) or thorough? |
+
+**Example:**
+```xml
+<role>
+You are a code analysis agent for Warden. You evaluate code changes
+against specific skill criteria and report findings ONLY when the code
+violates or conflicts with those criteria.
+</role>
+```
+
+## Tool Documentation
+
+Document available tools clearly:
+
+```xml
+<tools>
+You have access to these tools to gather context:
+- **Read**: Check related files to understand context
+- **Grep**: Search for patterns to trace data flow
+</tools>
+```
+
+## Claude Agent SDK Options
+
+From [Anthropic's SDK documentation](https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts):
+
+| Option | Effect |
+|--------|--------|
+| `systemPrompt: string` | Replace default entirely |
+| `systemPrompt: { preset: "claude_code" }` | Use full Claude Code prompt |
+| `systemPrompt: { preset: "claude_code", append: "..." }` | Add to Claude Code prompt |
+
+**Note:** The SDK's minimal default omits coding guidelines. Use `preset: "claude_code"` for full capabilities.
+
+## CLAUDE.md Integration
+
+Project-level context via CLAUDE.md requires explicit configuration:
+
+```typescript
+options: {
+  systemPrompt: { preset: "claude_code" },
+  settingSources: ["project"], // Required to load CLAUDE.md
+}
+```
+
+## Sources
+
+- [Anthropic: Modifying System Prompts](https://platform.claude.com/docs/en/agent-sdk/modifying-system-prompts)
+- `src/sdk/runner.ts` - Warden's implementation

package/.claude/skills/notseer/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: notseer
+description: High-precision bug detection. Every report is a proof, not a suspicion. Finds logic errors, null handling bugs, async issues, and edge cases with certainty.
+allowed-tools: Read Grep Glob
+---
+
+You are an expert bug hunter analyzing code changes. Your reports are proofs, not suspicions.
+
+## Core Principle
+
+**Certainty-based reporting**: Every bug report must be provable from the code. If you cannot construct a concrete proof that code will fail, do not report it.
+
+## The 5-Point Proof
+
+Before reporting ANY bug, you MUST be able to answer ALL five:
+
+1. **Location**: What exact file and line is wrong?
+2. **Behavior**: What incorrect output, state, or crash will occur?
+3. **Trigger**: What specific input or condition causes it?
+4. **Root Cause**: Why doesn't the code handle this case?
+5. **Confidence**: Would another engineer agree this is a bug without debate?
+
+If you cannot complete all 5, it is speculation—do NOT report.
+
+## Bug Categories
+
+### Null & Undefined Access
+- Property access without null check
+- Missing guard after nullable operation
+- Optional chaining hiding real errors
+- Array access without bounds checking
+
+### Off-by-One and Boundary Errors
+- Loop misses first or last element
+- Array index calculation off by one
+- Inclusive/exclusive range confusion
+- Boundary value handling (min/max)
+
+### Logic Errors
+- Condition negated incorrectly
+- `&&` / `||` swapped
+- Wrong comparison operator (`<` vs `<=`, `==` vs `===`)
+- Missing else branches or switch cases
+- Short-circuit evaluation hiding bugs
+- Assignment in conditional (`=` vs `==`)
+
+### Async & Promise Bugs
+- Missing `await` on async operations
+- Unhandled promise rejections
+- Race conditions in parallel mutation
+- Stale closures capturing outdated values
+
+### Type Coercion
+- String concat instead of number add (`"1" + 1 = "11"`)
+- Truthiness check where `0` or `""` is valid
+- Implicit coercion causing unexpected behavior
+
+### State & Data Bugs
+- Unintended mutation of shared objects/arrays
+- State updates based on stale values
+- Incorrect shallow vs deep copy
+- Missing React hook dependencies
+- Return statement inside finally block
+
+### Copy-Paste Errors
+- Wrong variable from copy-paste
+- Incomplete find-replace
+- Partial refactor leaving inconsistency
+
+### Edge Cases
+- Empty array/string not handled
+- Division by zero possible
+- Integer overflow/underflow
+
+## What NOT to Report
+
+Do NOT report:
+- Style or formatting preferences
+- "Could be cleaner" suggestions
+- Speculative "might be a problem" issues
+- Performance concerns (unless causing incorrect behavior)
+- Security vulnerabilities (use security-review skill)
+- Missing error handling that "might" matter
+- Incomplete implementations (unless they'll crash)
+- Unused variables or dead code
+- Missing tests or documentation
+
+If linters or type checkers would catch it, don't report it.
+
+## Analysis Method
+
+1. **Read enough context.** Understand what the code is trying to do before judging correctness. If unsure, read more files.
+
+2. **Trace data flow.** Follow values from source to use. Where could they be null, empty, wrong type?
+
+3. **Check boundaries.** Empty input? Null? Zero? Negative? First/last element? Max values?
+
+4. **Verify async.** Every promise awaited? Can operations race? Are closures stale?
+
+5. **Spot copy-paste.** Similar blocks with inconsistent variable names are a top source of bugs.
+
+6. **Never guess.** If uncertain whether something is a bug, read more code. Do not speculate.
+
+## Pre-Report Checklist
+
+Before reporting each bug, verify:
+- [ ] I am certain this code is wrong
+- [ ] I can explain exactly what breaks and when
+- [ ] I have read enough context to understand intent
+- [ ] Another engineer would agree this is a bug, not a style preference
+- [ ] I can construct a specific input or condition that triggers failure
+
+If ANY answer is no, do not report.
+
+## Severity Levels
+
+- **critical**: Crash, data loss, or silent data corruption in normal usage paths
+- **high**: Incorrect behavior users will encounter in common scenarios
+- **medium**: Incorrect behavior requiring specific edge conditions to trigger
+
+Do NOT use low or info. If confidence is that low, don't report it.
+
+## Output Format
+
+For each bug:
+- File path and line number
+- One sentence: what's wrong
+- Trigger: the specific condition that causes failure
+- Suggested fix (only if the fix is clear and obvious)
+
+Be concise. Focus on the proof, not general advice.

package/.claude/skills/skill-writer/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: Skill Writer
+description: Generate valid Warden skill definitions from natural language descriptions
+---
+
+## Usage
+
+Describe what the skill should do, and this will generate a complete skill YAML file.
+
+## Instructions
+
+When the user describes a skill they want to create:
+
+1. **Understand the Purpose**: Clarify what the skill should analyze or check
+2. **Design the Prompt**: Write a clear, specific system prompt for the Claude agent
+3. **Configure Tools**: Select appropriate tool restrictions based on the skill's needs
+4. **Define Output Expectations**: Ensure the skill will produce valid SkillReport output
+
+## Skill Definition Schema
+
+```yaml
+name: skill-name  # kebab-case, unique identifier
+description: Short description of what the skill does
+
+prompt: |
+  Detailed instructions for the Claude agent.
+  - What to analyze
+  - What to look for
+  - How to categorize findings
+  - Severity guidelines
+
+tools:
+  allowed:  # Tools the skill CAN use
+    - Read
+    - Grep
+    - Glob
+    - WebFetch
+    - WebSearch
+  denied:   # Tools the skill CANNOT use
+    - Write
+    - Edit
+    - Bash
+```
+
+## Available Tools
+
+| Tool | Purpose | When to Allow |
+|------|---------|---------------|
+| Read | Read file contents | Analysis skills (always) |
+| Grep | Search file contents | Finding patterns/issues |
+| Glob | Find files by pattern | Discovering relevant files |
+| WebFetch | Fetch URL content | CVE lookups, doc references |
+| WebSearch | Web search | External information |
+| Write | Create files | NEVER for review skills |
+| Edit | Modify files | Auto-fix skills only |
+| Bash | Run commands | Test runners, builds |
+
+## Severity Guidelines
+
+Instruct skills to use these severity levels:
+
+- **critical**: Actively exploitable, high impact, immediate action required
+- **high**: Exploitable with moderate effort, should fix before merge
+- **medium**: Potential issue, needs review and consideration
+- **low**: Minor concern, fix when convenient
+- **info**: Observation, no action required
+
+## Output Schema
+
+All skills must output a SkillReport:
+
+```typescript
+{
+  skill: string;      // Skill name
+  summary: string;    // Brief overview of findings
+  findings: [{
+    id: string;       // Unique finding ID
+    severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
+    title: string;    // Short title
+    description: string; // Detailed explanation
+    location?: {      // Where the issue is
+      path: string;
+      startLine: number;
+      endLine?: number;
+    };
+    suggestedFix?: {  // Optional fix
+      description: string;
+      diff: string;   // Unified diff format
+    };
+  }];
+  metadata?: Record<string, unknown>;
+}
+```
+
+## Example Output
+
+When asked to create a skill, output the complete YAML:
+
+```yaml
+name: test-coverage
+description: Check if new code has adequate test coverage
+
+prompt: |
+  You are a test coverage analyst. Review the PR changes and check:
+
+  1. New functions/methods have corresponding tests
+  2. Edge cases are covered
+  3. Error paths are tested
+  4. Test names are descriptive
+
+  Focus on:
+  - New code additions (not modifications to existing tests)
+  - Public APIs and exported functions
+  - Complex logic branches
+
+  Severity levels:
+  - high: Public API with no tests
+  - medium: Complex logic without edge case tests
+  - low: Missing negative/error case tests
+  - info: Suggestions for additional coverage
+
+tools:
+  allowed:
+    - Read
+    - Grep
+    - Glob
+  denied:
+    - Write
+    - Edit
+    - Bash
+    - WebFetch
+    - WebSearch
+```
+
+## Process
+
+1. Ask clarifying questions if the skill purpose is unclear
+2. Generate the skill YAML
+3. Explain any design decisions
+4. Offer to refine based on feedback

package/.claude/skills/testing-guidelines/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: testing-guidelines
+description: Guide for writing tests. Use when adding new functionality, fixing bugs, or when tests are needed. Emphasizes integration tests, real-world fixtures, and regression coverage.
+---
+
+# Testing Guidelines
+
+Follow these principles when writing tests for this codebase.
+
+## Core Principles
+
+### 1. Mock External Services, Use Real Fixtures
+
+**ALWAYS** mock third-party network services. **ALWAYS** use fixtures based on real-world data.
+
+- Fixtures must be scrubbed of PII (use dummy data like `foo@example.com`, `user-123`)
+- Capture real API responses, then sanitize them
+- Never make actual network calls in tests
+
+### 2. Prefer Integration Tests Over Unit Tests
+
+Focus on **end-to-end style tests** that validate inputs and outputs, not implementation details.
+
+- Test the public interface, not internal methods
+- Unit tests are valuable for edge cases in pure functions, but integration tests are the priority
+- If refactoring breaks tests but behavior is unchanged, the tests were too coupled to implementation
+
+### 3. Minimize Edge Case Testing
+
+Don't test every variant of a problem.
+
+- Cover the **common path** thoroughly
+- Skip exhaustive input permutations
+- Skip unlikely edge cases that add maintenance burden without value
+- One representative test per category of input is usually sufficient
+
+### 4. Always Add Regression Tests for Bugs
+
+When a **bug** is identified, **ALWAYS** add a test that would have caught it.
+
+- The test should fail before the fix and pass after
+- Name it descriptively to document the bug
+- This prevents the same bug from recurring
+
+**Note:** Regression tests are for unintentional broken behavior (bugs), not intentional changes. Intentional feature removals, deprecations, or breaking changes do NOT need regression tests—these are design decisions, not defects.
+
+### 5. Cover Every User Entry Point
+
+**ALWAYS** have at least one basic test for each customer/user entry point.
+
+- CLI commands, API endpoints, public/exported functions
+- Test the common/happy path first
+- This proves the entry point works at all
+
+**Note:** "Entry point" means the public interface—exported functions, CLI commands, API routes. Internal/private functions are NOT entry points, even if they handle user-facing flags or options. Test entry points; internal functions get coverage through those tests.
+
+### 6. Tests Validate Before Manual QA
+
+Tests are how we validate **ANY** functionality works before manual testing.
+
+- Write tests first or alongside code, not as an afterthought
+- If you can't test it, reconsider the design
+- Passing tests should give confidence to ship
+
+## Technical Guidelines
+
+### File Organization
+
+- Test files use `*.test.ts` extension
+- Co-locate tests with source: `foo.ts` → `foo.test.ts`
+
+### Test Isolation
+
+Every test must:
+- Run independently without affecting other tests
+- Use temporary directories for file operations
+- Clean up resources in `afterEach` hooks
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+describe('my feature', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = join(tmpdir(), `warden-test-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('does something with files', () => {
+    writeFileSync(join(tempDir, 'test.ts'), 'content');
+    // ... test code
+  });
+});
+```
+
+### Pure Function Tests
+
+For pure functions without side effects, no special setup is needed:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { matchGlob } from './matcher.js';
+
+describe('matchGlob', () => {
+  it('matches exact paths', () => {
+    expect(matchGlob('src/index.ts', 'src/index.ts')).toBe(true);
+  });
+});
+```
+
+## Running Tests
+
+```bash
+pnpm test              # Run all tests in watch mode
+pnpm test:run          # Run all tests once
+```
+
+## Checklist Before Submitting
+
+- [ ] New entry points have at least one happy-path test
+- [ ] Bug fixes (not intentional changes) include a regression test
+- [ ] External services are mocked with sanitized fixtures
+- [ ] Tests validate behavior, not implementation
+- [ ] No shared state between tests