QUICKSTART-DEV.adoc

modshells — Quick Start for Developers

Table of Contents

• Tech Stack
• Set Up Development Environment
  • Option A: Guix (preferred)
  • Option B: Nix (fallback)
  • Option C: Manual
• Build
• Test
• Project Structure
• Key Recipes
• Before Submitting a PR
• Contractile Invariants
• LLM/AI Agent Development
• Get Help

Tech Stack

{{LANG_STACK}}

Set Up Development Environment

Option A: Guix (preferred)

guix shell

Option B: Nix (fallback)

nix develop

Option C: Manual

git clone https://github.com/hyperpolymath/modshells.git
cd modshells
just setup-dev

Build

{{BUILD_CMD}}

Test

{{TEST_CMD}}

Project Structure

modshells/
├── src/                  # Source code
├── src/abi/              # Idris2 ABI definitions (if applicable)
├── ffi/zig/              # Zig FFI bridge (if applicable)
├── tests/                # Test suite
├── docs/                 # Documentation
├── .machine_readable/    # Checkpoint files (STATE, META, ECOSYSTEM)
├── Justfile              # Task runner recipes
├── guix.scm              # Guix environment
├── flake.nix             # Nix environment (fallback)
└── 0-AI-MANIFEST.a2ml    # AI agent entry point

Key Recipes

just build          # Build the project
just test           # Run tests
just doctor         # Self-diagnostic
just lint           # Lint and format
just panic-scan     # Security scan via panic-attacker
just tour           # Guided tour of the codebase

Before Submitting a PR

just lint           # Format and lint
just test           # All tests pass
just panic-scan     # No new security issues

Contractile Invariants

Read .machine_readable/MUST.contractile before making changes. Key invariants that must never be violated:

{{MUST_INVARIANTS}}

LLM/AI Agent Development

If using an AI assistant, load the warmup context first:

just llm-context    # Outputs role-appropriate context

Or read 0-AI-MANIFEST.a2ml and .claude/CLAUDE.md directly.

Get Help

• Architecture: EXPLAINME.adoc

• Wiki: https://github.com/hyperpolymath/modshells/wiki

• Report issue: just help-me