A Lyra product — free and open source (MIT).
A community extension step for Sigma Protocol: an architecture-deepening pass that slots between Step 2 (Architecture) and Step 11 (PRDs), turning shallow modules into deep, AI-navigable ones before test contracts and implementation waves are written.
Built and battle-tested at Lyra across multiple production codebases.
A tangled shallow-module codebase makes interface contracts impossible to write cleanly. If you lock contracts (Sigma 11.5-style test-first gates) against shallow interfaces, your coding agents cement the mess. Deepen first, then contract, then build:
Step 2 Architecture ─┬─> 2.5 deepening (new project: optional polish)
retrofit ─┘ (existing project: REQUIRED before contracts/waves)
│
▼
11 PRD → test contracts → implementation waves
Step 19 Maintenance ──> 2.5 deepening (recurring refactor pass)
Doctrine: deep modules (Ousterhout, A Philosophy of Software Design; Matt Pocock — "Your codebase isn't ready for AI").
| Path | What |
|---|---|
skills/lyra-step-2.5-architecture-deepening/ |
The step wrapper — places the pass in the Sigma sequence, captures output into sigma/step-2.5-*/output.md, surfaces interface-changing proposals as **Decision:** markers |
skills/improve-codebase-architecture/ |
The engine — explore → candidates → grilling loop, with a strict architecture vocabulary (module, interface, depth, seam, adapter, leverage, locality) |
skills/formats/ |
CONTEXT-FORMAT.md + ADR-FORMAT.md — the domain-glossary and ADR formats the engine reads and maintains |
git clone https://github.com/lyra-engine/lyra-step-2.5-architecture-deepening
mkdir -p ~/.claude/skills
cp -R lyra-step-2.5-architecture-deepening/skills/* ~/.claude/skills/Then in any project:
/lyra-step-2.5-architecture-deepening [workspace-path]
Works standalone too — without a Sigma workspace it runs the deepening analysis directly against the repo (you just lose the .state.json bookkeeping).
- Deletion test — imagine deleting the module. Complexity vanishes → it was a pass-through. Complexity reappears across N callers → it was earning its keep.
- The interface is the test surface.
- One adapter = hypothetical seam. Two adapters = real seam.
Proposals are explained in terms of leverage (what callers gain) and locality (what maintainers gain), using your project's own domain vocabulary from CONTEXT.md, and they respect your ADRs instead of re-litigating them.
This step is the free, open-source slice of lyra-step — Lyra's full agentic delivery pipeline on top of Sigma Protocol (steps 0–20: mission → architecture → deepening → PRDs → RED test contracts → implementation waves → cross-model review → CI → deploy → observability → maintenance → learning extraction).
The full framework, governed agent runtimes, and DSGVO-grade delivery for German-speaking companies are what we do commercially: lyra-engine.com.
MIT — see LICENSE. Use it, fork it, ship with it.