Spec To TDD Starknet

Overview

This skill turns a detailed protocol spec into a TDD-ready Cairo repo: interface/abstract scaffolding, comprehensive testing infrastructure, BTT trees, and placeholder tests that compile and validate coverage before any implementation begins.

Key Patterns (Ekubo + Starknet-Staking Inspired):

• •Co-located tests under src/tests/ with #[cfg(test)]
• •snforge deploy helpers using declare().unwrap().contract_class().deploy()
• •Action/Result enums for complex test flows (Ekubo)
• •Flow-based testing with SystemState abstraction (Starknet-Staking)
• •Event test utilities module with per-event assertion helpers
• •Structured errors with Describable trait
• •Type aliases for domain concepts (Amount, Epoch, Commission)
• •Test constants module with addresses as 'NAME'.try_into().unwrap()

Progressive Disclosure Map

Load only what is needed:

• •Workflow gates: references/workflow-gates.md
• •BTT format: references/btt-format.md (manual BTT application for Cairo)
• •Test infra blueprint: references/test-infra-blueprint.md (Ekubo patterns)
• •Fixtures/scenarios: references/fixtures-and-scenarios.md
• •Mock patterns: references/mocks-patterns.md (MockERC20, Locker, Extension)
• •Assertions/events: references/assertions-and-events.md
• •Repo conventions: references/repo-conventions.md (Ekubo-style layout)
• •Naming rules: references/naming-rules.md
• •Config guidance: references/snforge-config.md
• •Spec -> tests mapping: references/mapping-spec-to-tests.md
• •Commands: references/lint-and-test-commands.md
• •Path configuration: references/path-configuration.md

Inputs (Configurable Per Repo)

Confirm these before doing any work; stop and ask if missing or ambiguous. Do not assume fixed paths.

• •PROJECT_ROOT: repo root for the current project
• •SPEC_PATH: spec file path (relative to PROJECT_ROOT)
• •TEMPLATE_DEST: where to copy the template asset (relative to PROJECT_ROOT)
• •TESTS_DIR: test files root (relative to PROJECT_ROOT)
• •BTT_DIR: BTT tree files root (relative to PROJECT_ROOT)
• •SPEC_DOCS_DIR: test-spec docs root (manifest/invariants/risk matrix)
• •Allowed edit scope: exact folders/files the implementation agent may touch
• •Test/lint commands: scarb fmt, scarb build, snforge test (or repo-specific equivalents)

Use references/path-configuration.md to set defaults and allow overrides.

Non-Negotiables

• •No business logic before tests and scaffolding are approved.
• •No bypassing failing validation, lint, or type checks.
• •No edits outside allowed scope.
• •Do not invent requirements; ask when spec is unclear.

Assets And Scripts

• •Template asset: assets/cairo-repo-template/ (comprehensive repo skeleton, includes SNForge config in Scarb.toml; copy and adapt to the repo layout).
• •Coverage validator: scripts/validate_coverage.py (enforces naming and mapping rules; pass repo-specific paths).

Workflow (Progressive Disclosure With Gates)

Follow this sequence strictly. Stop after each gate and ask for confirmation.

Gate 0 - Intake & Constraints

Use: references/workflow-gates.md

Actions:

• •Confirm PROJECT_ROOT, SPEC_PATH, TEMPLATE_DEST, TESTS_DIR, BTT_DIR, SPEC_DOCS_DIR, and allowed edit scope.
• •Confirm where to copy the template asset inside the repo and what to rename/adjust.
• •Confirm toolchain versions if relevant.

Stop: ask for confirmation.

Gate 1 - Spec Decomposition Map

Use: references/mapping-spec-to-tests.md

Actions:

• •Read the spec in slices (avoid loading the full file at once).
• •Extract: contracts/interfaces/events/storage, logic flows, invariants, risks, test requirements.
• •Present a concise coverage map (no files) and ask for approval.

Stop: ask for confirmation.

Gate 2 - Apply Template (No New Spec Package)

Use: references/repo-conventions.md, references/snforge-config.md

Actions:

• •Copy assets/cairo-repo-template/ into TEMPLATE_DEST.
• •Update Scarb.toml values as needed (name, versions, fork URL) and align to existing repo layout.
• •Do not add business logic.

Stop: ask for confirmation.

Gate 3 - Interface + Abstract Skeletons

Use: references/repo-conventions.md, references/naming-rules.md

Actions:

• •Create Cairo interface/trait files and abstract shells per the spec.
• •Include storage layouts, events, and access control surfaces.
• •No real logic.

Stop: ask for confirmation.

Gate 4 - Testing Infrastructure + Placeholders

Use: references/test-infra-blueprint.md, references/btt-format.md, references/fixtures-and-scenarios.md, references/mocks-patterns.md, references/assertions-and-events.md

Actions:

• •Populate SPEC_DOCS_DIR with test manifest, invariants, risk matrix, pre/post conditions, property tests, and infrastructure notes.
• •Create BTT trees in BTT_DIR with TEST-IDs in leaf nodes.
• •Create placeholder tests in TESTS_DIR (unit/integration/property structure as configured).
• •Every test must include a // TEST-ID: TEST-... marker.

Stop: ask for confirmation.

Gate 5 - Coverage Validation

Use: scripts/validate_coverage.py

Actions:

• •Run the validator with explicit paths and fix gaps until it passes.
• •Validator enforces TEST-ID naming, BTT presence, stub presence, invariant/risk mapping.

Stop: ask for confirmation.

Gate 6 - Handoff

Actions:

• •Summarize what is ready for the implementation agent.
• •Confirm that all constraints were met.

Output Quality Bar

• •Clear traceability from spec -> skeletons -> tests.
• •All tests mapped to BTT + stubs + invariants + risks.
• •Template compiles and tooling config is present.
• •No business logic implemented.