The shield for agentic software production

ASPIS — Agentic Software Production & Intelligence System.

A file-first, deterministic system for building software with AI agents — where the cheapest sufficient model produces production-grade work, repeatably.

Quickstart · Architecture · Roadmap · Contributing

---

Why ASPIS

Frontier models are capable but inconsistent. ASPIS doesn't hope a model gets it right — it engineers the conditions under which a cheap model can't get it wrong:

Quality = model capability × task clarity × test strength × review discipline

Every piece of project state — plans, rules, traces, agent definitions — lives as plain files in Git, so any AI runtime reads and writes the same source of truth.

Install

One command — it checks prerequisites, installs uv if missing, installs the global aspis, and verifies:

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/mahmoud-emad-dev/aspis/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/mahmoud-emad-dev/aspis/main/install.ps1 | iex

Other methods (clone, contributor, troubleshooting, uninstall): docs/INSTALL.md.

Quickstart

mkdir my-project && cd my-project
aspis init --write        # scaffold the brain (.aspis/) + runtime assets (.claude/, .opencode/)
aspis bootstrap --write   # make the project live (goal, stack, promote leads)
aspis models --sync       # assign each agent a model available on this machine

Then open AGENTS.md and start your runtime (OpenCode by default; add --runtime claude for Claude Code). The factory drives a deterministic loop:

The Quickstart walks the whole first build with a worked example.

Commands

aspis init <dir>        # scaffold an ASPIS project (dry-run; --write to apply)
aspis bootstrap         # onboarding: make an initialized project live
aspis status            # report project state
aspis models            # the model each agent resolves to, per runtime
aspis commit <paths…>   # compose a conventional message and commit (single writer)
aspis commits           # audit commit-message history (--fix repairs the auto-fixable)
aspis gitignore         # write/refresh .gitignore for the detected stack
aspis doctor            # check environment + project health (-v for paths + runtimes)
aspis uninstall         # remove machine-wide state (keeps project brains)

Model intelligence

ASPIS routes each agent to the cheapest sufficient model — per runtime, because the same agent can run on a different model under Claude than OpenCode. Agents declare a tier (cheap/standard/deep), never a hard-coded model; a resolver translates that to the exact model your connected providers expose, with per-agent and per-capability overrides — all data, no code change. Detection is presence-only (no session or content access).

Documentation

• Install — every install method, troubleshooting, uninstall.
• Quickstart — clone → first build, with a worked example.
• Architecture — how the factory is built.
• Roadmap — the six parts: what's shipped, what's next, what isn't done.
• Testing — the manual acceptance pass.
• Contributing · Security · Changelog

⚠️ Status: early beta. Parts 1–2 of the six-part plan are shipped — install, onboarding, and the production system; tracing is next. The public API and CLI are not yet stable. See the Roadmap.

License

MIT © 2026 Mahmoud Emad