feat: bootstrap production-grade starknet-skills foundation

.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "starknet-skills",
+  "version": "0.1.0",
+  "description": "Cairo/Starknet reasoning and audit-quality skills",
+  "author": "keep-starknet-strange"
+}

.gitignore

@@ -0,0 +1,17 @@
+.DS_Store
+*.swp
+*.swo
+
+# Local tooling
+.venv/
+.env
+
+# Python cache
+__pycache__/
+*.pyc
+
+# Local audit ingest artifacts
+datasets/audits/raw/*
+!datasets/audits/raw/.gitkeep
+datasets/audits/extracted/*
+!datasets/audits/extracted/.gitkeep

CLAUDE.md

@@ -0,0 +1,19 @@
+# Repo Context
+
+This repository is for reasoning-grade Cairo/Starknet skills.
+
+## Hard Boundary
+
+- Keep operational SDK/protocol usage content out of this repo.
+- Keep this repo focused on correctness, security patterns, and evaluation-backed guidance.
+
+## Editing Rules
+
+- Keep root skill modules concise.
+- Move large details to `references/` and `workflows/`.
+- Do not expand scope without accompanying eval updates.
+
+## Evaluation Rules
+
+- Detection quality changes must add or update evaluation cases.
+- Prefer held-out regressions from `datasets/audits/`.

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+## Quality Bar
+
+Every change must satisfy both tests:
+
+1. Would a strong stock model still get this wrong without this content?
+2. Does this change improve deterministic quality outcomes (fewer misses, fewer false positives, better remediation quality)?
+
+If both answers are not yes, do not add the content.
+
+## Required Structure in Skill Files
+
+Each `SKILL.md` must include:
+
+- `When to Use`
+- `When NOT to Use`
+
+Security/audit skills must also include:
+
+- `Rationalizations to Reject`
+
+Keep entry skills short and link one level deep to `references/` and `workflows/`.
+
+## Evaluation-Driven Changes
+
+Skill changes that affect detection or remediation quality must include one of:
+
+- New/updated case in `evals/cases/`
+- Updated benchmark scorecard in `evals/scorecards/`
+
+No merge without green quality gates:
+
+- formatting/build/tests
+- static analysis where applicable
+- evaluator pass threshold
+
+## Audit Data Handling
+
+When ingesting external audits into `datasets/audits/`:
+
+- redact confidential or client-identifying material
+- preserve technical root cause and exploitability detail
+- tag confidence and provenance for every finding

README.md

@@ -1 +1,37 @@
 # starknet-skills
+
+Production-grade skills for high-quality Cairo and Starknet security engineering.
+
+This repository is focused on reasoning quality, audit rigor, and deterministic quality gates.
+Operational SDK and protocol execution playbooks belong in `starknet-agentic` / `starkzap`.
+
+## Scope Boundary
+
+- In scope: Cairo correctness, security review patterns, Starknet architectural facts, testing and hardening workflows.
+- Out of scope: runtime tool execution guides (MCP tool usage, SDK call recipes, protocol operation runbooks).
+
+## Modules
+
+- `cairo-auditor/` — flagship workflow skill for Cairo security review.
+- `cairo-contract-authoring/` — contract structure and implementation patterns.
+- `cairo-testing/` — Starknet Foundry testing and fuzzing workflows.
+- `cairo-optimization/` — performance and low-level Cairo optimization rules.
+- `cairo-toolchain/` — build/declare/deploy/verification and release operations.
+- `account-abstraction/` — Starknet account abstraction and account-security semantics.
+- `starknet-network-facts/` — network-level constraints and chain behavior guardrails.
+- `openzeppelin-cairo/` — OpenZeppelin Cairo composition and hardening patterns.
+
+## Data + Evals
+
+- `datasets/audits/` stores normalized findings extracted from real audits.
+- `evals/` stores held-out evaluation cases and scorecards.
+
+Do not merge skill changes without updating or passing the corresponding evaluation set.
+
+## Initial Source Imports
+
+v0.1 seeds several modules from existing `starknet-agentic` skills and then constrains them to this repo boundary.
+
+## License
+
+MIT

SKILL.md

@@ -0,0 +1,25 @@
+---
+name: starknet-skills
+description: Router skill for Cairo/Starknet high-quality coding and auditing. Use this first to pick a focused module.
+---
+
+# Starknet Skills Router
+
+Use this file to choose the smallest relevant module.
+
+## Start Here
+
+- For contract security review: `cairo-auditor/SKILL.md`
+- For writing new contracts: `cairo-contract-authoring/SKILL.md`
+- For testing and fuzzing: `cairo-testing/SKILL.md`
+- For gas/perf optimization: `cairo-optimization/SKILL.md`
+- For build/declare/deploy/release operations: `cairo-toolchain/SKILL.md`
+- For account abstraction rules and risks: `account-abstraction/SKILL.md`
+- For Starknet network constraints: `starknet-network-facts/SKILL.md`
+- For OpenZeppelin Cairo usage and footguns: `openzeppelin-cairo/SKILL.md`
+
+## Routing Policy
+
+- Prefer one module first.
+- Add a second module only when blocked.
+- Keep context narrow and evidence-based.

account-abstraction/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: account-abstraction
+description: Starknet account abstraction correctness and security guidance for validate/execute paths, nonces, signatures, and session policies.
+---
+
+# Account Abstraction
+
+## When to Use
+
+- Reviewing account contract validation and execution paths.
+- Designing session-key policy boundaries.
+- Validating nonce and signature semantics.
+
+## When NOT to Use
+
+- General contract authoring not involving account semantics.
+
+## Core Focus
+
+- `__validate__` constraints and DoS resistance.
+- `__execute__` policy enforcement correctness.
+- Replay protection and domain separation.
+- Privileged selector and self-call protection.

account-abstraction/references/README.md

@@ -0,0 +1,3 @@
+# References
+
+Account abstraction threat models, selector policy examples, and replay-protection references.

cairo-auditor/README.md

@@ -0,0 +1,10 @@
+# cairo-auditor
+
+Flagship security workflow module for Cairo/Starknet auditing.
+
+- `SKILL.md` contains orchestration policy and output contract.
+- `references/vulnerability-db/` stores generalized vulnerability patterns.
+- `references/audit-findings/` stores normalized findings from historical audits.
+- `workflows/` contains runbooks for default/deep/targeted operation.
+- `agents/` contains agent-specific instructions for parallel scans.
+- `scripts/` contains extraction and normalization utilities.

cairo-auditor/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: cairo-auditor
+description: Security audit workflow for Cairo/Starknet contracts. Use for pre-merge and pre-release vulnerability discovery, triage, and remediation planning.
+allowed-tools: [Bash, Read, Glob, Grep, Task]
+---
+
+# Cairo Auditor
+
+Workflow skill for systematic Cairo contract security review.
+
+## When to Use
+
+- Reviewing contract changes before merge.
+- Performing release-gate security checks.
+- Triaging suspicious Cairo/Starknet patterns from code review or incidents.
+
+## When NOT to Use
+
+- Writing new contract features from scratch.
+- Deployment-only tasks.
+- SDK or protocol operation guides.
+
+## Rationalizations to Reject
+
+- "Tests pass so this is safe."
+- "This pattern is standard in EVM so it is safe in Cairo."
+- "The edge case is impossible in production."
+- "We can skip replay/domain checks because signatures are temporary."
+
+## Modes
+
+- `default`: whole-package review using scoped file discovery.
+- `deep`: default + adversarial reasoning pass + strict false-positive gate.
+- `targeted`: explicit file-path review for fast PR iteration.
+
+## Workflow
+
+1. Discover in-scope Cairo files.
+2. Run vectorized scans using vulnerability patterns in `references/vulnerability-db/`.
+3. Correlate with historical findings in `references/audit-findings/`.
+4. Merge and deduplicate findings by root cause.
+5. Run false-positive verification gate.
+6. Emit prioritized report with remediation guidance and test requirements.
+
+## Reporting Contract
+
+Each finding must include:
+
+- severity
+- file/function location
+- root cause
+- exploit path
+- fix recommendation
+- required regression test
+
+## Evidence Sources
+
+- canonical patterns: `references/vulnerability-db/`
+- audit-derived cases: `references/audit-findings/`
+- evaluator regressions: `../../evals/cases/`
+
+## Output Rule
+
+Only report actionable findings with confidence >= medium unless `deep` mode is requested.

cairo-auditor/VERSION

@@ -0,0 +1 @@
+0.1.0

cairo-auditor/agents/adversarial.md

@@ -0,0 +1,4 @@
+# Adversarial Agent
+
+Construct concrete exploit paths for candidate findings.
+Reject findings that cannot produce a realistic attack path under stated assumptions.

cairo-auditor/agents/vector-scan.md

@@ -0,0 +1,4 @@
+# Vector Scan Agent
+
+Scan assigned files for pattern matches against `../references/vulnerability-db/`.
+Do not report stylistic issues. Report only security-relevant findings.

cairo-auditor/references/audit-findings/README.md

@@ -0,0 +1,5 @@
+# Audit Findings Corpus
+
+This directory stores normalized findings extracted from historical audits.
+
+Do not store confidential client identifiers.