Aircury AI Framework

The Aircury AI Framework is a meta-routing framework for AI-assisted software engineering. Its main job is to decide which workflow an AI agent should use for each request.

You normally do not choose a mode. Ask for the work you need, and the framework tells the agent whether to use plan-build, Spec Kit, or a direct implementation flow. Only specify a mode when you explicitly want to force that workflow.

It also installs project rules, agent entrypoints, living specification folders, mandatory engineering non-negotiables, optional standards, greenfield bootstrap guidance, and curated skills while separating a shared workflow constitution from installable capabilities.

Why Aircury

Aircury gives agents enough structure to work consistently without forcing every change through a heavy process. The default behavior is automatic routing:

• Use plan-build for clear day-to-day changes.
• Use Spec Kit when requirements need formal clarification and planning before code.
• Keep durable behavior knowledge in specs/features/.

Quick Install

Run the installer from any project directory (or your home directory for a global setup):

bunx @aircury/ai-framework
# or
npx @aircury/ai-framework

The TUI asks for:

1. Scope — Local to configure the current project, Global to configure your machine.
2. AI tools — select the tool-specific integrations you want.
3. Language preference — for local installs, optionally enforce British English and include the language capability.
4. Capabilities — choose the workflows and standards this installation should include.

Rerunning the installer updates a project without asking: files carrying the framework-maintained notice are replaced by the current version, AGENTS.md and CLAUDE.md keep their content and gain the framework section, the project's own files (FRAMEWORK.local.md, the specs/ guides) are never overwritten, and framework capability documents the profile no longer installs are removed. The installed version is recorded as frameworkVersion in .aircury/framework.config.json. Skills are installed through the skills ecosystem with npx or bunx, so they can be updated later. When a project keeps .agents/skills as a git submodule (a shared skills repository), the installer installs no skills there: that repository owns them, and the installer lists the selected skills it already provides and the ones to add to it.

Every local installation includes non-negotiable engineering rules in FRAMEWORK.md: TDD where automated testing is feasible, SOLID design constraints, Clean Code, explicit architecture boundaries, and justified tradeoffs for any exception.

Update A Project

To bring an installed project to the latest framework without prompts (for example from an automated agent), run from the project root:

npx @aircury/ai-framework@latest --update
# or preview the plan without writing anything
npx @aircury/ai-framework@latest --update --dry-run

It reads the saved .aircury/framework.config.json and applies the same plan as the interactive installer: framework-maintained files refreshed, the project's own files kept, AGENTS.md/CLAUDE.md merged, dropped capability documents removed, skills installed (none into a .agents/skills submodule).

Install From A Local Branch

To test an unpublished branch, build the CLI from your local checkout:

bun install
bun run build

Then run the built installer from the project you want to configure:

node /absolute/path/to/ai-framework/dist/cli.js

Use a throwaway project first if you want to verify the generated files before installing into a real repository.

What It Installs

Walking Skeleton

For greenfield projects, Aircury can install the external aircury/walking-skeleton skill as an optional capability.

It is recommended when a team wants to start from reviewed ADRs, define a tiny end-to-end slice, and build a runnable baseline before normal feature delivery begins.

The skill stays in its own repository. This framework only references and installs it through skills add; it does not vendor the ADR catalogue or generated example code.

Use the workflow in order:

/walking-skeleton plan
/walking-skeleton spec
/walking-skeleton build

Documentation