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"
+}

.github/workflows/quality.yml

@@ -0,0 +1,99 @@
+name: Quality Gate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Setup Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Setup Ruff
+        uses: astral-sh/ruff-action@4919ec5cf1f49eff0871dbcea0da843445b837e6 # v3.6.1 (v3)
+
+      - name: Install Python deps
+        run: python -m pip install jsonschema
+
+      - name: Python compile check
+        run: python -m py_compile scripts/audit-pipeline/*.py
+
+      - name: Ruff lint
+        run: ruff check scripts/audit-pipeline scripts/audit-extraction
+
+      - name: Shellcheck
+        run: shellcheck scripts/audit-extraction/*.sh
+
+      - name: Validate findings JSONL
+        run: |
+          python scripts/audit-pipeline/validate_jsonl.py \
+            --schema datasets/normalized/finding.schema.json \
+            --jsonl datasets/normalized/findings/csc_vesu_update_2025_03.findings.jsonl
+          python scripts/audit-pipeline/validate_jsonl.py \
+            --schema datasets/normalized/finding.schema.json \
+            --jsonl datasets/normalized/findings/erim_nostra_pools_2024_01.findings.jsonl
+
+      - name: Validate manifest JSONL
+        run: |
+          python scripts/audit-pipeline/validate_jsonl.py \
+            --schema datasets/manifests/audit-manifest.schema.json \
+            --jsonl datasets/manifests/audits.jsonl
+
+      - name: Segment smoke tests
+        run: |
+          cat > /tmp/segment_audit_a.txt <<'EOF'
+          L-01 Example finding
+          File(s): contract.cairo
+          Description: Example issue.
+          Recommendation: Example fix.
+          EOF
+          cat > /tmp/segment_audit_b.txt <<'EOF'
+          1.2.3 Example section
+          Body line
+          EOF
+          python scripts/audit-pipeline/segment_text.py \
+            --audit-id smoke_audit_a \
+            --input /tmp/segment_audit_a.txt \
+            --output /tmp/csc.segmented.jsonl
+          python scripts/audit-pipeline/segment_text.py \
+            --audit-id smoke_audit_b \
+            --input /tmp/segment_audit_b.txt \
+            --output /tmp/erim.segmented.jsonl
+          test -s /tmp/csc.segmented.jsonl
+          test -s /tmp/erim.segmented.jsonl
+
+      - name: Generate manifest smoke test
+        run: |
+          mkdir -p datasets/audits/raw datasets/audits/extracted /tmp
+          printf 'dummy-raw' > datasets/audits/raw/smoke_ci.pdf
+          printf 'dummy-extracted' > datasets/audits/extracted/smoke_ci.txt
+          cat > /tmp/manifest.seed.json <<'EOF'
+          [
+            {
+              "audit_id": "smoke_ci_2026_03",
+              "project": "Smoke",
+              "auditor": "CI",
+              "date": "2026-03-08",
+              "source_url": "https://example.com/smoke.pdf",
+              "source_type": "direct_pdf",
+              "raw_path": "datasets/audits/raw/smoke_ci.pdf",
+              "extracted_path": "datasets/audits/extracted/smoke_ci.txt"
+            }
+          ]
+          EOF
+          python scripts/audit-pipeline/generate_manifest.py \
+            --seed /tmp/manifest.seed.json \
+            --output /tmp/audits.generated.jsonl
+          test -s /tmp/audits.generated.jsonl
+
+      - name: Held-out leakage check
+        run: python scripts/audit-pipeline/check_no_heldout_leak.py

.gitignore

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

AGENTS.md

@@ -0,0 +1,3 @@
+# starknet-skills
+
+Canonical router: [SKILL.md](./SKILL.md)

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/`.

CODE_OF_CONDUCT.md

@@ -0,0 +1,19 @@
+# Code of Conduct
+
+## Our Standards
+
+We are committed to a respectful, inclusive, and constructive community.
+Examples of expected behavior:
+
+- giving actionable and respectful feedback
+- assuming good intent while maintaining technical rigor
+- focusing discussions on code, safety, and outcomes
+
+Unacceptable behavior includes harassment, abusive language, discrimination,
+and repeated bad-faith disruption.
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing this code of
+conduct. They may remove, edit, or reject comments, commits, or contributions
+that violate these standards.

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 or updated case in `evals/cases/`
+- updated scorecard in `evals/scorecards/`
+
+No merge without green quality gates:
+
+- formatting/build/tests
+- static analysis where applicable
+- evaluator threshold: documented expected result in a scorecard and no regression versus the latest baseline
+
+## 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

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keep-starknet-strange
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,39 @@
 # 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/` stores the full audit-to-skills pipeline (`ingest -> segment -> normalize -> distill`).
+- `evals/` stores held-out evaluation cases and scorecards.
+
+Do not merge skill changes without updating or passing the corresponding evaluation set.
+
+## Governance
+
+- Contribution guide: `CONTRIBUTING.md`
+- Security policy: `SECURITY.md`
+- Code of conduct: `CODE_OF_CONDUCT.md`
+
+## License
+
+MIT (see `LICENSE`).

SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please do not open public issues for undisclosed vulnerabilities.
+
+Report security findings to maintainers through a private channel and include:
+
+- affected module/file
+- impact and exploitability
+- reproduction steps or proof of concept
+- suggested remediation
+
+## Disclosure Expectations
+
+- We acknowledge reports as quickly as possible.
+- We validate impact before public disclosure.
+- We coordinate remediation and release notes with reporters when appropriate.

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,28 @@
+---
+name: account-abstraction
+description: Starknet account abstraction correctness and security guidance for validate/execute paths, nonces, signatures, and session policies.
+license: Apache-2.0
+metadata: {"author":"starknet-skills","version":"0.1.1","org":"keep-starknet-strange"}
+keywords: [starknet, account-abstraction, signatures, nonces, session-keys, policy]
+allowed-tools: [Bash, Read, Write, Glob, Grep, Task]
+user-invocable: true
+---
+
+# 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,11 @@
+# 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.
+- `datasets/normalized/findings/` is the canonical store for normalized findings.
+- `references/audit-findings/` is legacy/imported reference material.
+- `workflows/` contains runbooks for default/deep/targeted operation.
+- `agents/` contains agent-specific instructions for parallel scans.
+- `scripts/` contains extraction and normalization utilities.