@jhm1909/ag-kit 0.1.0

package/.agent/skills/code-review/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: code-review
+description: >
+  Code review practices emphasizing technical rigor, verification gates, evidence-based claims,
+  and security-focused differential review. Use when receiving feedback, completing tasks,
+  reviewing PRs for security regressions, or before making completion/success claims.
+metadata:
+  version: "2.0.0"
+  sources:
+    - trailofbits/skills (differential-review, spec-to-code-compliance)
+---
+
+# Code Review
+
+Guide proper code review practices: technical rigor, evidence-based claims, security-focused review.
+
+## Three Practices
+
+1. **Receiving feedback** — Technical evaluation over performative agreement
+2. **Requesting reviews** — Systematic review process
+3. **Verification gates** — Evidence before any completion claims
+
+## Core Principle
+
+**Technical correctness over social comfort.** Verify before implementing. Ask before assuming. Evidence before claims.
+
+## Quick Decision Tree
+
+```
+SITUATION?
+│
+├─ Received feedback
+│  ├─ Unclear items? → STOP, ask for clarification first
+│  ├─ From human partner? → Understand, then implement
+│  └─ From external reviewer? → Verify technically before implementing
+│
+├─ Security-focused PR review?
+│  └─ Read: differential_review.md (blast radius, risk classification)
+│
+├─ Spec-to-code compliance check?
+│  └─ Read: spec_compliance.md (6-phase audit methodology)
+│
+├─ Completed work
+│  └─ Major feature/task? → Run verification, present evidence
+│
+└─ About to claim status
+   ├─ Have fresh verification? → State claim WITH evidence
+   └─ No fresh verification? → RUN verification command first
+```
+
+## Receiving Feedback Protocol
+
+**Pattern**: READ → UNDERSTAND → VERIFY → EVALUATE → RESPOND → IMPLEMENT
+
+**Key Rules**:
+- ❌ No performative agreement: "You're absolutely right!", "Great point!"
+- ❌ No implementation before verification
+- ✅ Restate requirement, ask questions, push back with technical reasoning
+- ✅ If unclear: STOP and ask for clarification on ALL unclear items first
+- ✅ YAGNI check: grep for usage before implementing suggested features
+
+**Full protocol**: [code-review-reception.md](./references/code-review-reception.md)
+
+## Verification Gates Protocol
+
+**The Iron Law**: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test output: 0 failures | Previous run, "should pass" |
+| Build succeeds | Build command: exit 0 | "Linter passed" |
+| Bug fixed | Original symptom passes | "Code changed" |
+| Requirements met | Line-by-line checklist | "Tests passing" |
+
+**Red Flags — STOP**:
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification
+- Committing without verification
+
+**Full protocol**: [verification-before-completion.md](./references/verification-before-completion.md)
+
+## Security Review — Risk Classification
+
+| Risk Level | Triggers |
+|------------|----------|
+| **HIGH** | Auth, crypto, external calls, value transfer, validation removal |
+| **MEDIUM** | Business logic, state changes, new public APIs |
+| **LOW** | Comments, tests, UI, logging |
+
+**Red Flags (immediate investigation)**:
+- Removed code from "security", "CVE", or "fix" commits
+- Access control modifiers removed
+- Validation removed without replacement
+- High blast radius (50+ callers) + HIGH risk change
+
+**Full methodology**: [differential_review.md](./references/differential_review.md)
+
+## References
+
+| Reference | Purpose |
+|:----------|:--------|
+| `code-review-reception.md` | Receiving feedback protocol |
+| `verification-before-completion.md` | Iron Law verification gates |
+| `requesting-code-review.md` | How to request reviews |
+| `differential_review.md` | Security PR review (Trail of Bits) |
+| `spec_compliance.md` | Spec-to-code audit (Trail of Bits) |
+
+## Bottom Line
+
+1. Technical rigor over social performance — No performative agreement
+2. Evidence before claims — Verification gates always
+3. Security before speed — Risk-classify every PR change
+4. Verify. Question. Then implement. Evidence. Then claim.

package/.agent/skills/code-review/references/code-review-reception.md

@@ -0,0 +1,209 @@
+---
+name: receiving-code-review
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+```
+your human partner: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From your human partner
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with your human partner's prior decisions:
+  Stop and discuss with your human partner first
+```
+
+**your human partner's rule:** "External feedback - be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with your human partner's architectural decisions
+
+**How to push back:**
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve your human partner if architectural
+
+**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch - [specific issue]. Fixed in [location]."
+✅ [Just fix it and show in the code]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+❌ "Thanks for [anything]"
+❌ ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+```
+✅ "You were right - I checked [X] and it does [Y]. Implementing now."
+✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending why you pushed back
+❌ Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Performative agreement | State requirement or just act |
+| Blind implementation | Verify against codebase first |
+| Batch without testing | One at a time, test each |
+| Assuming reviewer is right | Check if breaks things |
+| Avoiding pushback | Technical correctness > comfort |
+| Partial implementation | Clarify all items first |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## Real Examples
+
+**Performative Agreement (Bad):**
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**Technical Verification (Good):**
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
+**YAGNI (Good):**
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
+```
+
+**Unclear Item (Good):**
+```
+your human partner: "Fix items 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
+```
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.

package/.agent/skills/code-review/references/differential_review.md

@@ -0,0 +1,59 @@
+# Differential Security Review
+
+> Source: Trail of Bits — differential-review skill
+
+Security-focused code review for PRs, commits, and diffs.
+
+## Core Principles
+
+1. **Risk-First**: Focus on auth, crypto, value transfer, external calls
+2. **Evidence-Based**: Every finding backed by git history, line numbers, attack scenarios
+3. **Adaptive**: Scale to codebase size (SMALL/MEDIUM/LARGE)
+4. **Honest**: Explicitly state coverage limits and confidence level
+
+## Codebase Size Strategy
+
+| Size | Strategy | Approach |
+|------|----------|----------|
+| SMALL (<20 files) | DEEP | Read all deps, full git blame |
+| MEDIUM (20-200) | FOCUSED | 1-hop deps, priority files |
+| LARGE (200+) | SURGICAL | Critical paths only |
+
+## Workflow
+
+### Pre-Analysis → Triage → Code Analysis → Test Coverage → Blast Radius → Deep Context → Adversarial → Report
+
+### Phase 0: Triage
+Classify risk per file: HIGH / MEDIUM / LOW
+
+### Phase 1: Code Analysis
+For HIGH risk files: git blame removed code, check for regression patterns
+
+### Phase 2: Test Coverage
+Missing tests on security code = elevated severity
+
+### Phase 3: Blast Radius
+Count transitive callers. High blast radius + HIGH risk = critical priority.
+
+### Phase 4: Adversarial Modeling (HIGH risk only)
+- Attacker model: What can they exploit?
+- Exploit scenario: Concrete steps
+- Exploitability rating: trivial / moderate / complex
+
+### Phase 5: Report
+Generate markdown report with all findings, evidence, and recommendations.
+
+## Red Flags (Stop and Investigate)
+
+- Removed code from "security", "CVE", or "fix" commits
+- Access control modifiers removed
+- Validation removed without replacement
+- External calls added without checks
+- High blast radius (50+ callers) + HIGH risk change
+
+## Rationalizations to Reject
+
+- "Small PR, quick review" → Heartbleed was 2 lines
+- "I know this codebase" → Familiarity breeds blind spots
+- "Just a refactor" → Refactors break invariants; analyze as HIGH until proven LOW
+- "No tests = not my problem" → Missing tests = elevated risk rating

package/.agent/skills/code-review/references/requesting-code-review.md

@@ -0,0 +1,105 @@
+---
+name: requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements - dispatches code-reviewer subagent to review implementation against plan or requirements before proceeding
+---
+
+# Requesting Code Review
+
+Dispatch code-reviewer subagent to catch issues before they cascade.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Dispatch code-reviewer subagent:**
+
+Use Task tool with `code-reviewer` type, fill template at `code-reviewer.md`
+
+**Placeholders:**
+- `{WHAT_WAS_IMPLEMENTED}` - What you just built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
+- `{DESCRIPTION}` - Brief summary
+
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Example
+
+```
+[Just completed Task 2: Add verification function]
+
+You: Let me request code review before proceeding.
+
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
+
+[Dispatch code-reviewer subagent]
+  WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
+
+You: [Fix progress indicators]
+[Continue to Task 3]
+```
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each batch (3 tasks)
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
+
+See template at: requesting-code-review/code-reviewer.md

package/.agent/skills/code-review/references/spec_compliance.md

@@ -0,0 +1,43 @@
+# Spec-to-Code Compliance Check
+
+> Source: Trail of Bits — spec-to-code-compliance skill
+
+Verifies code implements exactly what documentation specifies.
+
+## 6-Phase Methodology
+
+### Phase 0: Documentation Discovery
+Find ALL docs: whitepaper, README, design notes, Notion, transcripts.
+
+### Phase 1: Normalize
+Convert all docs to clean canonical text corpus.
+
+### Phase 2: Spec → Intent IR
+Extract all intended behavior with evidence:
+- Invariants, preconditions, postconditions
+- Math formulas, state transitions
+- Security requirements ("must/never/always")
+
+### Phase 3: Code → Behavior IR
+Line-by-line semantic analysis:
+- State reads/writes, conditional branches
+- Revert conditions, external calls
+- Authorization graph, hidden assumptions
+
+### Phase 4: Alignment (Spec ↔ Code)
+Match types: full_match | partial_match | mismatch | missing_in_code | code_stronger | code_weaker
+
+### Phase 5: Classification
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | Spec says X, code does Y |
+| HIGH | Partial/incorrect implementation |
+| MEDIUM | Ambiguity with security implications |
+| LOW | Documentation drift |
+
+## Anti-Hallucination Rules
+
+- If spec is silent → classify as **UNDOCUMENTED**
+- If code adds behavior → classify as **UNDOCUMENTED CODE PATH**
+- Every claim must quote original text or line numbers
+- Zero speculation

package/.agent/skills/code-review/references/verification-before-completion.md

@@ -0,0 +1,139 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.