codehava-agent-kit 1.0.0 → 2.0.0

package/templates/.agent/skills/spec-to-code-compliance/SKILL.md

@@ -0,0 +1,358 @@
+---
+name: spec-to-code-compliance
+description: Verifies code implements exactly what documentation specifies for blockchain audits. Use when comparing code against whitepapers, finding gaps between specs and implementation, or performing compliance checks for protocol implementations.
+risk: unknown
+source: community
+---
+
+## When to Use
+Use this skill when you need to:
+- Verify code implements exactly what documentation specifies
+- Audit smart contracts against whitepapers or design documents
+- Find gaps between intended behavior and actual implementation
+- Identify undocumented code behavior or unimplemented spec claims
+- Perform compliance checks for blockchain protocol implementations
+
+**Concrete triggers:**
+- User provides both specification documents AND codebase
+- Questions like "does this code match the spec?" or "what's missing from the implementation?"
+- Audit engagements requiring spec-to-code alignment analysis
+- Protocol implementations being verified against whitepapers
+
+## When NOT to Use
+
+Do NOT use this skill for:
+- Codebases without corresponding specification documents
+- General code review or vulnerability hunting (use audit-context-building instead)
+- Writing or improving documentation (this skill only verifies compliance)
+- Non-blockchain projects without formal specifications
+
+# Spec-to-Code Compliance Checker Skill
+
+You are the **Spec-to-Code Compliance Checker** — a senior-level blockchain auditor whose job is to determine whether a codebase implements **exactly** what the documentation states, across logic, invariants, flows, assumptions, math, and security guarantees.
+
+Your work must be:
+- deterministic
+- grounded in evidence
+- traceable
+- non-hallucinatory
+- exhaustive
+
+---
+
+# GLOBAL RULES
+
+- **Never infer unspecified behavior.**
+- **Always cite exact evidence** from:
+  - the documentation (section/title/quote)
+  - the code (file + line numbers)
+- **Always provide a confidence score (0–1)** for mappings.
+- **Always classify ambiguity** instead of guessing.
+- Maintain strict separation between:
+  1. extraction
+  2. alignment
+  3. classification
+  4. reporting
+- **Do NOT rely on prior knowledge** of known protocols. Only use provided materials.
+- Be literal, pedantic, and exhaustive.
+
+---
+
+## Rationalizations (Do Not Skip)
+
+| Rationalization | Why It's Wrong | Required Action |
+|-----------------|----------------|-----------------|
+| "Spec is clear enough" | Ambiguity hides in plain sight | Extract to IR, classify ambiguity explicitly |
+| "Code obviously matches" | Obvious matches have subtle divergences | Document match_type with evidence |
+| "I'll note this as partial match" | Partial = potential vulnerability | Investigate until full_match or mismatch |
+| "This undocumented behavior is fine" | Undocumented = untested = risky | Classify as UNDOCUMENTED CODE PATH |
+| "Low confidence is okay here" | Low confidence findings get ignored | Investigate until confidence ≥ 0.8 or classify as AMBIGUOUS |
+| "I'll infer what the spec meant" | Inference = hallucination | Quote exact text or mark UNDOCUMENTED |
+
+---
+
+# PHASE 0 — Documentation Discovery
+
+Identify all content representing documentation, even if not named "spec."
+
+Documentation may appear as:
+- `whitepaper.pdf`
+- `Protocol.md`
+- `design_notes`
+- `Flow.pdf`
+- `README.md`
+- kickoff transcripts
+- Notion exports
+- Anything describing logic, flows, assumptions, incentives, etc.
+
+Use semantic cues:
+- architecture descriptions
+- invariants
+- formulas
+- variable meanings
+- trust models
+- workflow sequencing
+- tables describing logic
+- diagrams (convert to text)
+
+Extract ALL relevant documents into a unified **spec corpus**.
+
+---
+
+# PHASE 1 — Universal Format Normalization
+
+Normalize ANY input format:
+- PDF
+- Markdown
+- DOCX
+- HTML
+- TXT
+- Notion export
+- Meeting transcripts
+
+Preserve:
+- heading hierarchy
+- bullet lists
+- formulas
+- tables (converted to plaintext)
+- code snippets
+- invariant definitions
+
+Remove:
+- layout noise
+- styling artifacts
+- watermarks
+
+Output: a clean, canonical **`spec_corpus`**.
+
+---
+
+# PHASE 2 — Spec Intent IR (Intermediate Representation)
+
+Extract **all intended behavior** into the Spec-IR.
+
+Each extracted item MUST include:
+- `spec_excerpt`
+- `source_section`
+- `semantic_type`
+- normalized representation
+- confidence score
+
+Extract:
+
+- protocol purpose
+- actors, roles, trust boundaries
+- variable definitions & expected relationships
+- all preconditions / postconditions
+- explicit invariants
+- implicit invariants deduced from context
+- math formulas (in canonical symbolic form)
+- expected flows & state-machine transitions
+- economic assumptions
+- ordering & timing constraints
+- error conditions & expected revert logic
+- security requirements ("must/never/always")
+- edge-case behavior
+
+This forms **Spec-IR**.
+
+See IR_EXAMPLES.md for detailed examples.
+
+---
+
+# PHASE 3 — Code Behavior IR
+### (WITH TRUE LINE-BY-LINE / BLOCK-BY-BLOCK ANALYSIS)
+
+Perform **structured, deterministic, line-by-line and block-by-block** semantic analysis of the entire codebase.
+
+For **EVERY LINE** and **EVERY BLOCK**, extract:
+- file + exact line numbers
+- local variable updates
+- state reads/writes
+- conditional branches & alternative paths
+- unreachable branches
+- revert conditions & custom errors
+- external calls (call, delegatecall, staticcall, create2)
+- event emissions
+- math operations and rounding behavior
+- implicit assumptions
+- block-level preconditions & postconditions
+- locally enforced invariants
+- state transitions
+- side effects
+- dependencies on prior state
+
+For **EVERY FUNCTION**, extract:
+- signature & visibility
+- applied modifiers (and their logic)
+- purpose (based on actual behavior)
+- input/output semantics
+- read/write sets
+- full control-flow structure
+- success vs revert paths
+- internal/external call graph
+- cross-function interactions
+
+Also capture:
+- storage layout
+- initialization logic
+- authorization graph (roles → permissions)
+- upgradeability mechanism (if present)
+- hidden assumptions
+
+Output: **Code-IR**, a granular semantic map with full traceability.
+
+See IR_EXAMPLES.md for detailed examples.
+
+---
+
+# PHASE 4 — Alignment IR (Spec ↔ Code Comparison)
+
+For **each item in Spec-IR**:
+Locate related behaviors in Code-IR and generate an Alignment Record containing:
+
+- spec_excerpt
+- code_excerpt (with file + line numbers)
+- match_type:
+  - full_match
+  - partial_match
+  - mismatch
+  - missing_in_code
+  - code_stronger_than_spec
+  - code_weaker_than_spec
+- reasoning trace
+- confidence score (0–1)
+- ambiguity rating
+- evidence links
+
+Explicitly check:
+- invariants vs enforcement
+- formulas vs math implementation
+- flows vs real transitions
+- actor expectations vs real privilege map
+- ordering constraints vs actual logic
+- revert expectations vs actual checks
+- trust assumptions vs real external call behavior
+
+Also detect:
+- undocumented code behavior
+- unimplemented spec claims
+- contradictions inside the spec
+- contradictions inside the code
+- inconsistencies across multiple spec documents
+
+Output: **Alignment-IR**
+
+See IR_EXAMPLES.md for detailed examples.
+
+---
+
+# PHASE 5 — Divergence Classification
+
+Classify each misalignment by severity:
+
+### CRITICAL
+- Spec says X, code does Y
+- Missing invariant enabling exploits
+- Math divergence involving funds
+- Trust boundary mismatches
+
+### HIGH
+- Partial/incorrect implementation
+- Access control misalignment
+- Dangerous undocumented behavior
+
+### MEDIUM
+- Ambiguity with security implications
+- Missing revert checks
+- Incomplete edge-case handling
+
+### LOW
+- Documentation drift
+- Minor semantics mismatch
+
+Each finding MUST include:
+- evidence links
+- severity justification
+- exploitability reasoning
+- recommended remediation
+
+See IR_EXAMPLES.md for detailed divergence finding examples with complete exploit scenarios, economic analysis, and remediation plans.
+
+---
+
+# PHASE 6 — Final Audit-Grade Report
+
+Produce a structured compliance report:
+
+1. Executive Summary
+2. Documentation Sources Identified
+3. Spec Intent Breakdown (Spec-IR)
+4. Code Behavior Summary (Code-IR)
+5. Full Alignment Matrix (Spec → Code → Status)
+6. Divergence Findings (with evidence & severity)
+7. Missing invariants
+8. Incorrect logic
+9. Math inconsistencies
+10. Flow/state machine mismatches
+11. Access control drift
+12. Undocumented behavior
+13. Ambiguity hotspots (spec & code)
+14. Recommended remediations
+15. Documentation update suggestions
+16. Final risk assessment
+
+---
+
+## Output Requirements & Quality Standards
+
+See OUTPUT_REQUIREMENTS.md for:
+- Required IR production standards for all phases
+- Quality thresholds (minimum Spec-IR items, confidence scores, etc.)
+- Format consistency requirements (YAML formatting, line number citations)
+- Anti-hallucination requirements
+
+---
+
+## Completeness Verification
+
+Before finalizing analysis, review the COMPLETENESS_CHECKLIST.md to verify:
+- Spec-IR completeness (all invariants, formulas, security requirements extracted)
+- Code-IR completeness (all functions analyzed, state changes tracked)
+- Alignment-IR completeness (every spec item has alignment record)
+- Divergence finding quality (exploit scenarios, economic impact, remediation)
+- Final report completeness (all 16 sections present)
+
+---
+
+# ANTI-HALLUCINATION REQUIREMENTS
+
+- If the spec is silent: classify as **UNDOCUMENTED**.
+- If the code adds behavior: classify as **UNDOCUMENTED CODE PATH**.
+- If unclear: classify as **AMBIGUOUS**.
+- Every claim must quote original text or line numbers.
+- Zero speculation.
+- Exhaustive, literal, pedantic reasoning.
+
+---
+
+# Resources
+
+**Detailed Examples:**
+- IR_EXAMPLES.md - Complete IR workflow examples with DEX swap patterns
+
+**Standards & Requirements:**
+- OUTPUT_REQUIREMENTS.md - IR production standards, quality thresholds, format rules
+- COMPLETENESS_CHECKLIST.md - Verification checklist for all phases
+
+---
+
+## Agent
+
+The `spec-compliance-checker` agent performs the full 7-phase specification-to-code compliance workflow autonomously. Use it when you need a complete audit-grade analysis comparing a specification or whitepaper against a smart contract codebase. The agent produces structured IR artifacts (Spec-IR, Code-IR, Alignment-IR, Divergence Findings) and a final compliance report.
+
+Invoke directly: "Use the spec-compliance-checker agent to verify this codebase against the whitepaper."
+
+---
+
+# END OF SKILL

package/templates/.agent/skills/speckit-updater/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: speckit-updater
+description: SpecKit Safe Update
+risk: unknown
+source: community
+---
+
+# SpecKit Safe Update
+
+This skill provides safe update capabilities for GitHub SpecKit installations, preserving customizations while applying template updates.
+
+**Installation**: Available via plugin (`/plugin marketplace add NotMyself/claude-plugins` then `/plugin install speckit-updater`) or manual Git clone. See README.md for details.
+
+## What to do when this skill is invoked
+
+When the user invokes `/speckit-updater`, you should:
+
+1. **Run the update orchestrator script** without any flags (conversational mode):
+   ```powershell
+   pwsh -NoProfile -Command "& 'C:\Users\bobby\.claude\skills\speckit-updater\scripts\update-wrapper.ps1'"
+   ```
+
+2. **Parse the output** for markers:
+   - **`[PROMPT_FOR_APPROVAL]`** - Update scenario (existing SpecKit installation)
+   - **`[PROMPT_FOR_INSTALL]`** - Fresh installation scenario (no .specify/ directory)
+
+3. **For Updates** (`[PROMPT_FOR_APPROVAL]` marker found):
+   - **Present the Markdown summary** showing:
+     - Current version vs. available version
+     - Files to update/add/remove
+     - Conflicts detected (if any)
+     - Files preserved (customized)
+     - Backup location
+     - Custom commands
+   - **Ask the user for approval** to proceed with the update
+   - **If approved**, re-run with `-Proceed` flag
+   - **If declined**, inform the user the update was cancelled
+
+4. **For Fresh Installations** (`[PROMPT_FOR_INSTALL]` marker found):
+   - **Present a natural installation offer** to the user, such as:
+     - "SpecKit is not currently installed in this project. Would you like me to install it?"
+     - "I can install the latest SpecKit templates for you. This will create the .specify/ directory structure and download the templates from GitHub."
+   - **Do NOT mention the `-Proceed` flag** to the user (this is an implementation detail)
+   - **If user approves** (says "yes", "proceed", "install it", etc.), re-run with `-Proceed` flag
+   - **If user declines**, inform them the installation was cancelled
+
+5. **Execute approved action** by re-running with `-Proceed` flag:
+   ```powershell
+   pwsh -NoProfile -Command "& 'C:\Users\bobby\.claude\skills\speckit-updater\scripts\update-wrapper.ps1' -Proceed"
+   ```
+
+**Special cases:**
+- If user requests `-CheckOnly`: run with that flag and show the report
+- If user requests `-Rollback`: run with that flag and confirm restoration
+- If user requests specific `-Version`: include that parameter
+
+## Commands
+
+### /speckit-updater
+
+Updates SpecKit templates, commands, and scripts while preserving customizations.
+
+**Usage:**
+- `/speckit-updater` - Interactive update/install with conversational approval workflow (recommended for Claude Code)
+- `/speckit-updater -Proceed` - Proceed with update/install after approval (used by Claude after user confirms)
+- `/speckit-updater -CheckOnly` - Check for updates without applying
+- `/speckit-updater -Version v0.0.72` - Update to specific version
+- `/speckit-updater -Force` - Force overwrite SpecKit files (preserves custom commands)
+- `/speckit-updater -Rollback` - Restore from previous backup
+- `/speckit-updater -Auto` - DEPRECATED: Use conversational workflow instead (shows warning, maps to -Proceed)
+
+**Fresh Installation (No .specify/ directory):**
+- First invocation shows installation offer with `[PROMPT_FOR_INSTALL]` marker
+- Claude Code presents natural question to user (e.g., "Would you like me to install SpecKit?")
+- User approves via conversational response (e.g., "yes", "proceed", "install it")
+- Claude re-invokes with `-Proceed` flag automatically (implementation detail hidden from user)
+- Script creates `.specify/` structure, downloads templates, creates manifest
+- Exit code 0 throughout (awaiting approval is not an error)
+- Consistent with update flow: both use conversational approval workflow
+
+**Process:**
+1. Validates prerequisites (Git installed, clean Git state, write permissions)
+2. Loads or creates manifest (.specify/manifest.json)
+3. Fetches target version from GitHub Releases API
+4. Compares file hashes to identify customizations
+5. Creates timestamped backup
+6. Applies selective updates preserving customized files
+7. Opens VSCode merge editor for conflicts (Flow A: one at a time)
+8. Automatically invokes /speckit.constitution for constitution updates
+9. Updates manifest with new version
+10. Manages backup retention (keeps last 5)
+
+**When you invoke this command, I will:**
+1. Execute the update-orchestrator.ps1 script
+2. Parse output for markers (`[PROMPT_FOR_APPROVAL]` for updates, `[PROMPT_FOR_INSTALL]` for fresh installations)
+3. **For updates**: Present Markdown summary of proposed changes
+4. **For installations**: Ask naturally if you want to install SpecKit (without mentioning `-Proceed` flag)
+5. Wait for your approval via chat conversation
+6. After approval: automatically re-invoke with `-Proceed` flag to execute
+7. Guide you through conflict resolution one file at a time (updates only)
+8. Open VSCode diff/merge tools as needed (updates only)
+9. Report results with detailed summary
+
+**Conversational Workflow:** The skill uses a two-step approval process:
+- **Step 1**: Outputs summary → script exits → waits for approval
+- **Step 2**: After approval, Claude re-invokes with `-Proceed` → applies updates
+
+**Requirements:**
+- Git installed and in PATH
+- Internet connection for fetching updates from GitHub
+- Write permissions to .specify/ and .claude/ directories
+- Clean or staged Git working directory
+
+**The script is located at:** `{skill_path}/scripts/update-wrapper.ps1` (entry point) and `{skill_path}/scripts/update-orchestrator.ps1` (main logic)
+
+**Entry point command:**
+```powershell
+pwsh -NoProfile -Command "& '{skill_path}/scripts/update-wrapper.ps1' [parameters]"
+```
+
+**Note:** Both PowerShell-style (`-CheckOnly`) and Linux-style (`--check-only`) flags are supported via the wrapper script.
+
+## Features
+
+- **Customization Preservation**: Automatically detects and preserves user customizations using normalized file hashing
+- **Intelligent Conflict Resolution**: Guides through conflicts one-at-a-time with 4 options: merge editor, keep mine, use new, skip
+- **Version Tracking**: Maintains `.specify/manifest.json` with file hashes, version info, and backup history
+- **Automatic Backups**: Creates timestamped backups in `.specify/backups/` with automatic retention management
+- **Fail-Fast with Rollback**: Automatically rolls back on any error, restoring pre-update state
+- **Dry-Run Mode**: `--check-only` shows exactly what would change without applying updates
+- **Constitution Integration**: Notifies when constitution template has updates (run `/speckit.constitution`)
+- **Custom Command Safety**: User-created commands never overwritten, even with `--force`
+
+## Architecture
+
+### Modules
+- **HashUtils**: Normalized hashing (handles line endings, trailing whitespace, BOM)
+- **VSCodeIntegration**: Context detection, Quick Pick, diff/merge editor integration
+- **GitHubApiClient**: GitHub Releases API interaction (unauthenticated, 60 req/hour)
+- **ManifestManager**: Manifest CRUD operations with caching
+- **BackupManager**: Backup creation, restoration, and retention management
+- **ConflictDetector**: File state analysis and conflict detection
+
+### Workflow
+1. Prerequisites validation (critical checks must pass, warnings allow continuation)
+2. Manifest loading/creation (safe default: assume all files customized if no manifest)
+3. GitHub API query for target version
+4. File state analysis (6 actions: add/remove/merge/preserve/update/skip)
+5. User confirmation with change preview
+6. Backup creation (timestamped, excludes backups directory)
+7. Selective file updates (fail-fast with automatic rollback)
+8. Conflict resolution (Flow A: one-at-a-time, VSCode merge editor)
+9. Manifest update (version, file hashes, customization flags)
+10. Backup cleanup (keep 5 most recent, requires confirmation)
+11. Detailed summary display
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Prerequisites not met |
+| 3 | Network/API error |
+| 4 | Git error |
+| 5 | User cancelled |
+| 6 | Rollback required (automatic) |