Skip to content

QUICKSTART-DEV.adoc

Latest commit

 

History

History
140 lines (106 loc) · 3.83 KB

QUICKSTART-DEV.adoc

File metadata and controls

140 lines (106 loc) · 3.83 KB
Raw

standards — Quick Start for Developers

Table of Contents
Note
 Working on the standards themselves. Canonical entry points: README.adoc (human), 0-AI-MANIFEST.a2ml (agent), REGISTRY.a2ml (spec index).

Tech Stack

The product is the specs (AsciiDoc + A2ML). The code is reference implementations and language bindings that prove them:

  • Rust/SPARK — a2ml/bindings/rust, k9-svc/bindings/rust

  • Deno — protocol reference impls (axel-protocol, 0-ai-gatekeeper-protocol/mcp-repo-guardian)

  • Zig — FFI/reference targets

  • AsciiDoc / A2ML — the specs, templates, and machine-readable metadata

Language + licence policy is binding: .claude/CLAUDE.md.

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/standards.git
cd standards
just setup-dev

Build

just build          # builds the Rust/Zig sub-project artefacts

Test

just test           # runs every sub-project test suite

Project Structure

standards/
├── README.adoc           # Human front door (routing table)
├── 0-AI-MANIFEST.a2ml    # Machine front door (agent entry)
├── REGISTRY.adoc         # Prose: the registry + drift automation
├── a2ml/  k9-svc/  *-a2ml/   # Foundation specs (Stream 1)
├── *-protocol/           # Protocol specs
├── *-readiness-grades/   # ARG / FRG / CRG / TRG frameworks
├── hypatia-rules/        # Dogfooding rules incl. HYP-S006 (drift)
├── scripts/build-registry.sh   # Generator for REGISTRY.a2ml + TOPOLOGY.md
├── .machine_readable/    # State (6a2/), REGISTRY.a2ml, contractiles
├── Justfile              # Task runner recipes
├── guix.scm / flake.nix  # Guix (primary) / Nix (fallback) env
└── .github/workflows/    # Enforcement + registry-verify CI

Registry workflow (important)

.machine_readable/REGISTRY.a2ml and TOPOLOGY.md are generated. To add or move a spec, edit the SPECS table in scripts/build-registry.sh, then:

just registry        # regenerate REGISTRY.a2ml + TOPOLOGY.md
just registry-check  # what CI enforces — fails on drift

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:

  • A2ML state files live in .machine_readable/6a2/ only — never the repo root.

  • REGISTRY.a2ml + TOPOLOGY.md are generated — regenerate, never hand-edit.

  • No Makefiles (use Justfile); SPDX header on every source file.

  • Licence/SPDX is Manual-Only for agents — flag drift, never edit it.

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