Development¶

A guide for contributors — setting up the development environment, running the autonomous CID workflow, understanding quality gates, and using the task runner.

Dev Container Setup¶

iscc-lib uses a Dev Container to provide a fully configured development environment. All tooling is pre-installed — no manual setup required.

Prerequisites¶

• Docker with Dev Containers support
• VS Code with the Dev Containers extension, or any Dev Containers-compatible IDE
• A GitHub personal access token (GH_TOKEN) for repo operations
• Claude Code credentials (~/.claude/.credentials.json) for the CID loop

Getting Started¶

Set environment variables on your host before opening the container:

export GH_TOKEN="ghp_your_token_here"

Open the repository in VS Code and select Reopen in Container (or use the Dev Containers CLI). The postCreateCommand runs automatically: trusts the mise config, installs Python dev dependencies (uv sync), and sets up pre-commit hooks.

Included Tools¶

git config user.name "Your Name"
git config user.email "your@email.com"

CID Autonomous Workflow¶

This project uses Continuous Iterative Development (CID) — an autonomous agent loop that advances the codebase in small, verified increments. Four specialized agents cycle through:

update-state → define-next → advance → review (+ push on PASS)

The CID orchestrator (tools/cid.py) streams agent progress to the terminal in real-time — you see tool calls, text output, turn counts, and cost per agent.

Running the Loop¶

mise run cid:run        # Run up to 20 iterations (stops on DONE or failure)
mise run cid:run 5      # Run up to 5 iterations

Single Iteration¶

mise run cid:step       # Run one full iteration

Individual Agents¶

mise run cid:status     # Show current project state (no agent invocation)
mise run cid:state      # Run update-state agent
mise run cid:next       # Run define-next agent
mise run cid:advance    # Run advance agent
mise run cid:review     # Run review agent (pushes on PASS)

Context Files¶

The CID agents communicate through files in .claude/context/:

Quality Gates¶

Two-stage git hook setup via prek (Rust-based drop-in replacement for pre-commit).

Pre-commit (fast, auto-fix on every commit)¶

Runs on every git commit. Fixes files in place — if changes are made, the commit is aborted so you can review and re-stage.

• File hygiene (line endings, trailing whitespace, YAML/JSON/TOML validation)
• cargo fmt — Rust formatting
• ruff check --fix + ruff format — Python linting and formatting
• taplo fmt — TOML formatting
• yamlfix — YAML formatting
• mdformat — Markdown formatting

Pre-push (thorough, run before code leaves the machine)¶

Runs on every git push. Blocks the push if any check fails.

• cargo clippy — Rust linting with -D warnings (zero warnings policy)
• cargo test — full Rust test suite
• ty check — Python type checking
• Ruff security scan (S rules)
• Ruff complexity check (C901)
• pytest with 100% coverage enforcement

Manual Commands¶

mise run check          # Run all pre-commit hooks on all files
mise run lint           # Format checks + clippy + ruff
mise run format         # Apply all formatting (pre-commit auto-fix hooks)
mise run test           # Run all tests (Rust + Python)

Installing Hooks¶

uv run prek install --hook-type pre-commit --hook-type pre-push

Project Structure¶

iscc-lib/
├── Cargo.toml                  # Virtual workspace root
├── pyproject.toml              # Python project (uv)
├── zensical.toml               # Documentation config
├── mise.toml                   # Tool versions + tasks
├── .pre-commit-config.yaml     # prek hooks
├── crates/
│   ├── iscc-lib/               # Core Rust library (pure, no FFI)
│   │   ├── src/                # Algorithm implementations
│   │   └── tests/              # Conformance test vectors (data.json)
│   ├── iscc-py/                # Python bindings (maturin + PyO3)
│   │   ├── src/lib.rs          # PyO3 wrappers
│   │   └── python/iscc_lib/    # Python package + type stubs
│   ├── iscc-napi/              # Node.js bindings (napi-rs)
│   │   ├── src/lib.rs          # napi-rs wrappers
│   │   └── __tests__/          # Node.js conformance tests
│   ├── iscc-wasm/              # WebAssembly bindings (wasm-bindgen)
│   │   ├── src/lib.rs          # wasm-bindgen exports
│   │   └── tests/              # WASM integration tests
│   ├── iscc-ffi/               # C FFI bindings
│   │   ├── src/lib.rs          # extern "C" functions
│   │   └── tests/              # C test program
│   └── iscc-jni/               # Java JNI bindings
│       ├── src/lib.rs          # JNI extern "system" functions
│       └── java/               # Java package + Maven build
│           ├── pom.xml
│           └── src/             # IsccLib.java + tests
├── packages/
│   └── go/                     # Go module (pure Go, no cgo)
│       ├── go.mod
│       ├── codec.go            # ISCC codec, constants, types
│       ├── code_meta.go        # GenMetaCodeV0
│       ├── code_content_*.go   # GenText/Image/Audio/Video/MixedCodeV0
│       ├── code_data.go        # GenDataCodeV0 + DataHasher
│       ├── code_instance.go    # GenInstanceCodeV0 + InstanceHasher
│       ├── code_iscc.go        # GenIsccCodeV0
│       ├── conformance.go      # ConformanceSelftest
│       └── *_test.go           # Conformance tests
├── docs/                       # Documentation site (lib.iscc.codes)
├── benchmarks/
│   └── python/                 # Comparative Python benchmarks
├── notes/                      # Architecture design documents
├── reference/                  # Reference implementation (gitignored)
│   └── iscc-core/              # Shallow clone of iscc/iscc-core
├── .claude/
│   ├── agents/                 # CID agent definitions
│   └── context/                # CID state files
└── .github/workflows/
    ├── ci.yml                  # Test + lint
    ├── docs.yml                # Documentation deployment
    └── release.yml             # Publish to crates.io, PyPI, npm, Maven Central

Crate Summary¶

Mise Task Runner¶

All development tasks are defined in mise.toml and run via mise run <task>.

Quality Tasks¶

CID Tasks¶

Version and Release Tasks¶

Releasing¶

All packages share a single version defined in the root Cargo.toml workspace. The version_sync.py script propagates it to all language-specific manifests and documentation. CI enforces consistency on every push.

Version Bump¶

# 1. Edit the canonical version in Cargo.toml (line 13)
#    version = "X.Y.Z"

# 2. Propagate to all manifests and docs
mise run version:sync

# 3. Update Cargo.lock
cargo update -w

# 4. Format, stage, and commit
mise run format
git add -A
git commit -m "Release X.Y.Z"

version:sync updates these files automatically:

Cargo workspace members (Cargo.lock) inherit the version automatically via version.workspace = true.

Publish¶

# 1. Merge develop into main
mise run pr:main          # Create PR
# Merge PR after CI passes

# 2. Tag the release on main
git checkout main && git pull
git tag vX.Y.Z
git push origin vX.Y.Z

The tag push triggers .github/workflows/release.yml, which publishes to all registries in parallel:

Each publish job checks if the version already exists on the registry and skips gracefully.

You can also publish to individual registries via workflow_dispatch on the Release workflow page (select the checkboxes for crates.io, PyPI, npm, or Maven).

Post-Release Verification¶

mise run test:install --version X.Y.Z

This installs each package from its registry in a clean environment and runs a smoke test.