THE AI ARCHITECT By Patrick Savalle

Need advice or a review of any part of your DevOps project?

‘DO SOME ALCHEMY’

Open-source, platform-agnostic, drop-in for any project and any compatible
agent that you activate with /alchemy (Claude) or $alchemy (Codex).

Or just 'do some alchemy' in any context

The Alchemy router selects the right skill at the right intensity, automatically.
Super-efficient, no context bloating.

Most agent skills teach an AI how to do specific tasks — write tests, scaffold boilerplate, format code. L-GEVITY skills do something different. They teach an agent how to think about software at a structural level: the voice that asks whether a feature earns its complexity, whether a pipeline is truly idempotent, whether a structure can be simpler before it’s optimized.

Alchemy is the backbone for structural and architectural quality: is this worth building, is it well-designed, is it in the right place, is it as simple as it can be, are the rules enforced as code, are defects caught early, is the flow optimized. It is, in effect, the architect companion — not a security, accessibility, UX, API, or release reviewer. Those reviews live in their own companion skills, triggered independently alongside it.

1. Start here

Install

Prompt your coding agent:

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

The agent can inspect the repository, choose its installer, and verify the result. Use the same prompt later to update.

Use

Start with natural language:

do some alchemy on this refactor

Or direct the router:

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

Alchemy runs a lightweight preflight, skips routine work, and loads only the skills the task needs.

Every decision leads with four short plain-language blocks, what I found, why it matters, do this first, and what I did not check, and then the full record. The blocks name the record’s verdict once, so its vocabulary is picked up on the way.

Every other skill is invoked the same way, by name.

---

2. Where can this skill set help?

Use L-GEVITY when a coding agent needs to decide not only how to implement a change, but whether it should exist, where it belongs, and what evidence proves it works.

---

3. Visual model

A.L.C.H.E.M.Y. pipeline

You don’t need to know the ALCHEMY internals, and you don’t have to use every stage or step, but here they are.

This is truly more an architectural brain than just a skill set.

The adaptive preflight keeps the execution cheap, automatically. A focused request runs one gate; adaptive work runs the smallest ordered subset; only explicit full language walks the complete route.

flowchart TD
    Input(["External request or evidence(not a persisted artifact)"])

    Req0["Requirement register — grounded requirement"]
    Req1["Requirement register — approved requirement"]
    Graph["Requirement register — dependency graph"]
    Increment["Issue — admitted delivery increment"]

    Design["Issue or PR — design decision"]
    Topology["Issue or PR — topology and complexity decision"]
    Rules["Configuration — architecture boundary rules"]

    Test["Code — acceptance test"]
    Source["Code — production source"]
    TestRun["Evidence — focused test result"]
    CIRun["Evidence — CI run report"]
    Trace["Issue closeout — traceability record"]
    Outcome["Evidence — outcome measurement"]

    Input -->|"requirements-grounding"| Req0
    Req0 -->|"functionality-complexity-tradeoff"| Req1
    Req1 -->|"requirements-topology (when needed)"| Graph
    Graph -->|"implementation-readiness"| Increment
    Req1 -.->|"implementation-readiness (independent requirement)"| Increment

    Increment -->|"architecture-guidelines"| Design
    Design -->|"morphogenetic-architecture + structural-simplification"| Topology
    Topology -->|"architecture-as-code"| Rules

    Rules -->|"test-strategy (portfolio pass)"| Test
    Test -->|"implement test-first (stack skills)"| Source
    Source -->|"run focused check"| TestRun

    TestRun -->|"defect-shift-left and CI/CD"| CIRun
    CIRun -->|"requirements-traceability"| Trace
    Trace -->|"collect outcome evidence"| Outcome

    Outcome -.->|"retrospective Minimum"| Req1

Three quality spaces

Alchemy evaluates a change from three complementary directions instead of collapsing every dimension into one score.

flowchart LR
    Change["Software change"]
    Topology["TopologyDomain · tier · layerlegality, then pressure"]
    Structure["StructureD kinds · K edgesP depth · n subsystems"]
    Flow["Flowleft · out · down"]
    Evolution["Smallest evidence-backed evolution"]

    Change --> Topology --> Evolution
    Change --> Structure --> Evolution
    Change --> Flow --> Evolution

Four change primitives

Every stage describes change with the same four words. A subsystem is a part produced by decomposition — where change lands. An aspect is a property that holds across a declared set of subsystems, with one obligation and one mechanism — which dimension is touched. An increment is the bounded unit of change admitted to implementation — what changes. An iteration is one cycle that admits an increment, realizes it, and measures the resulting baseline; the next iteration on the same subject starts from that measured baseline. alchemy defines them; each skill’s local term specializes exactly one.

Living topology

Functionally, “living” means the architecture is a standing hypothesis, not a diagram drawn once and trusted forever. Placement is cheap and mechanical, so it runs on every change; restructuring is expensive and evidence-gated, so it runs only when something is actually challenged. Every accepted restructuring ships with a predicted effect and a recheck date, so drift between the declared architecture and the running system surfaces as a defect instead of accumulating silently — the topology stays continuously accountable to the code, rather than describing what the code used to be.

Every subsystem declares three coordinates: domain, abstraction tier, and layer (say UI, service, data). Those coordinates alone are enough to rule on whether a proposed dependency between two subsystems is legal — the same way a linter blocks an illegal import without running the program. Tier and layer have a direction (a UI subsystem may depend on a service, not the reverse); domain is just a label, with no ranking between domains. Seven illegal dependency shapes are caught this way, mechanically — no runtime data, no history, and no need for the rest of the repo to exist yet, so it works on day one of a greenfield project. The verdict ships as a permanent architecture-as-code rule that keeps enforcing that one dependency afterward.

Changing the existing structure — merging or splitting subsystems — is different: it isn’t decided by rule, it needs evidence that the current shape is actually causing problems (coupling, duplicated change, failure propagation). A competing design has to beat the current one on measured deltas, and the required proof scales with how hard the change is to undo — renaming a subsystem needs less justification than collapsing two services. If every measurement checks out except one that genuinely can’t be taken yet, and the change is cheap to reverse, it can proceed on probation: a recorded expiry, a task to add the missing measurement, and a rollback path. A later measurement that contradicts the decision overrides the probation regardless. Every accepted restructuring also records what result it expects, checked again once that window closes.

flowchart LR
    Scaffold["Genetic scaffolddeclared position + invariants"]
    Legality["Position legalitymechanical, day-oneseven findings"]
    Fields["Morphogen fieldsstatic · runtime · change · data · failure"]
    Baseline["Lens-free candidate"]
    Lens["Second candidategraph cut · natural lens · manual"]
    Proof["Reversibility-scaled proofstructural deltas · probationwhen a field is unobtainable"]
    Decision["PLACE · KEEP · MOVE · SPLITMERGE · INTRODUCE-BOUNDARYDECLARE-RUNTIME-CYCLE · DEFER"]
    Homeostasis["Homeostasisnamed-edge rules · probation registerprediction recheck"]

    Scaffold --> Legality --> Fields --> Baseline --> Proof --> Decision --> Homeostasis
    Legality -. "ships as architecture-as-code rules" .-> Homeostasis
    Baseline -. "generator, reversibility-scaled" .-> Lens
    Lens -. "alternative or newly exposed risk" .-> Proof
    Homeostasis -- "window close re-enters audit" --> Fields

---

4. Reference

The gates

The mnemonic is A.L.C.H.E.M.Y.; the execution order is M → A → L → C → E → H → Y so value is tested before design is enforced or optimized.

The DevOps improvement moves complement the gates:

Contributing

See CONTRIBUTING.md for the genericity and promotion contract. Licensed under MIT.