ALCHEMY — your self-orchestrating software engineering team

The AI Architect by Patrick Savalle

Give your coding agent an objective. ALCHEMY selects the engineering skills, decides whether one agent or a team should do the work, and checks the result against evidence before preparing a pull request for your approval.

Open-source and platform-agnostic. Start with /alchemy in Claude Code, $alchemy in Codex, or “do some alchemy.”

The main concepts

ALCHEMY combines an engineering method with a team that scales to the task:

• Skills provide the method. Each skill defines how to answer an engineering question: whether a feature is worth building, where code belongs, how to verify it, or what limits delivery. Use skills individually or let ALCHEMY select them.
• Self-orchestration chooses the process. The alchemy router selects the questions a change needs to answer. alchemy-orchestrate assigns work, orders dependencies, checks hand-offs, and verifies completion.
• The agent team scales on demand. One agent is the default. Independent work can run in parallel; high-risk work can get a separate reviewer. Each agent loads only the skills it needs, within explicit concurrency and rework limits. There is no standing team to configure.
• Evidence determines correctness. Executed checks and independent review support completion claims. Disagreements are resolved through evidence or human decisions. You retain consequential approvals and accepted risk.

The method and orchestration are runtime-neutral. Adapters launch and isolate agents in Claude Code, Codex, or Unstoppable; support and enforcement differ by runtime. See runtime support and evidence.

Get started · Engineering workflow · Agent teams · Skills · Architecture concepts · Configuration

Get started

Ask your coding agent:

Install l-gevity/l-gevity-skills into this project.

The agent inspects the repository, chooses an installer, and verifies the result. Use the same prompt to update.

do some alchemy on this refactor

/alchemy this auth refactor       # Claude Code
$alchemy this auth refactor       # Codex
/alchemy M should we build this?  # one focused gate
/alchemy audit this PR            # structural audit
/alchemy ?                        # help

Other skills are invoked by name in the same way. To enable agent teams, install the runtime adapters after installing the library:

python .agents/skills/alchemy-orchestrate/scripts/init_workspace.py --runtime claude-code

Choose codex, unstoppable, or all for other runtimes. See workspace configuration for limits and permissions.

Installers are provided for Claude Code, Codex, Gemini CLI, and Grok CLI on Windows, Linux, and macOS. Each installs the shared skills into its agent's skills tree, adds the agent's root instruction file, and records provenance in l-gevity-skills.lock.json. When the project already keeps the other skills tree, that tree is updated as well.

Agent	Skills tree	Root instruction file
Claude Code	.claude/skills/	CLAUDE.md
Codex	.agents/skills/	AGENTS.md
Gemini CLI	.agents/skills/	GEMINI.md
Grok CLI	.agents/skills/	GROK.md

An existing root instruction file is preserved; the L-GEVITY version is written beside it with a .l-gevity suffix for manual merging. Locally added skills are not removed during updates. Set L_GEVITY_SKILLS_REF to pin a branch, tag, or commit.

Inspect the installer scripts.

The engineering workflow

The router first chooses how much analysis the task needs:

Dispatch	When it applies
SKIP	Routine local work; no structural analysis.
DIRECT	One focused question or gate.
ADAPTIVE	Structural work; the smallest ordered set of relevant gates.
FULL	Explicit full or all request; every justified stage, with skips recorded.

Focused commands stay focused. An audit starts from a read-only structural baseline; it does not automatically require a full traversal. Matching companion skills can run alongside any route.

The seven gates

The name is A.L.C.H.E.M.Y.; execution follows M → A → L → C → E → H → Y. Value is checked before design, enforcement, or optimization.

Gate	Question
M — Minimum	Is the functionality worth its complexity?
A — Architecture	Is the design minimal, modular, and purposeful?
L — Locality	Is each subsystem in the right boundary?
C — Complexity	Does the change measurably simplify the system?
E — Enforcement	Can architectural rules be encoded as checks?
H — Hermetic	Is each defect caught at the earliest capable stage?
Y — Yield	What constraint actually limits flow?

Requirements grounding, dependency analysis, and implementation readiness qualify work before design when needed. Yield uses the stable, measured baseline in the iteration after an increment ships, or examines an existing bottleneck. The DevOps improvement commands are available when requested:

Command	Move
/alchemy left	Detect defects earlier.
/alchemy out	Move recurring toil into durable systems.
/alchemy down	Replace bespoke code with reusable capability.

This is the beginning of the README. Read the rest at the original. Read the full README ↗