Compiling Architecture

Architecture Compiler

Overview

A deterministic compiler that selects architecture design patterns from a canonical YAML spec. No LLM, no hidden defaults — same input always produces the same output. All architectural logic lives in pattern files; the compiler is intentionally simple.

---

Repo Structure — Read This First

Treat the compiler repo as having this contract:

arch-compiler/
├── README.md
├── AGENTS.md
├── README-AGENTS.md
├── tools/         --mode compile
   ```

   If the helper reports a failure, stop and follow the exact next action it prints before writing any files.

4. **Verify git is initialised in the application repo**

   The helper above already checks this. The command below is the manual fallback if the helper cannot be run:

   ```bash
   git -C  rev-parse --git-dir
   ```

   If this exits non-zero, initialise git and create an initial commit before writing any files:

   ```bash
   git -C  init
   git -C  commit --allow-empty -m "chore: initial commit"
   ```

5. **Do not write any files until all checks pass**

## Provider-Binding Gate

Pattern-level approval is not the same as provider-level approval.

Treat the architecture as still provisional if any of these remain unresolved:
- concrete cloud/runtime target
- OIDC/auth provider or enforcement boundary
- database/storage/queue provider choice
- AI provider or model class
- retention/deletion mechanism for `nfr.data.retention_days`
- message transport and delivery semantics behind `async_messaging`

If those choices are deferred, say so explicitly to the human before finalising. Once they become concrete later, return to this skill, update the spec, recompile, diff the pattern set, and obtain fresh approval before implementation continues.

For brownfield systems, an existing prototype may reveal provider/runtime/boundary choices that are missing from the approved or in-progress spec. Treat those as inputs that must be made explicit in the spec review loop — not as automatically approved architecture. If the prototype exposes architecture drift, return here, update the spec, recompile, diff the result, and obtain approval before implementation continues.

---

## Artifacts Generated

| File | When written | Description |
|------|-------------|-------------|
| `compiled-spec.yaml` | always (with `-o`) | Full merged spec with defaults applied and `assumptions` section; valid re-input |
| `selected-patterns.yaml` | always (with `-o`) | Patterns that passed all filters, with match scores and honored rules |
| `rejected-patterns.yaml` | `-v` flag only | Patterns that were filtered out, with reason and filter phase |
| `compiled-spec-.yaml` | `-t` flag | Same files with UTC timestamp suffix (e.g. `compiled-spec-2026-03-17T19:36:31Z.yaml`) |
| stdout | always | Compiled spec printed to stdout; inline pattern comments in `-v` mode |

Exit code `0` on success, `1` on validation error or unsatisfiable NFR constraints. Advisory warnings (`warn_nfr`, `[high]` cost) do not change the exit code — they are informational only.

When the spec is rejected (exit 1), the compiler prints a `💡 Suggestions` block listing exactly which fields to change and what values are valid — read it before retrying.

---

## Before Writing Any Spec — App Repo Setup

**MUST-DO before writing a single line of spec or running the compiler:**

1. **Ask the user where the application repo lives.** The spec file, compiled artifacts, and all architecture outputs belong in the application repo — not in the pattern compiler repo. If no app repo exists yet, ask the user to create one (or create a new directory) and confirm the path before proceeding.

2. **Ensure git is initialised in the app repo.** All architecture artifacts must be version-controlled. If the app repo has no git history, run `git init` and make an initial commit before writing any files.

3. **Write the spec file into the app repo**, not into the compiler working directory. Use a name like `-spec.yaml` at the root of the app repo.

4. **All compiled output goes into the app repo** — not into a `compiled_output/` folder inside the compiler repo.

**Why this matters:** Architecture artifacts are the permanent record for the application. Placing them in the compiler repo creates confusion about which repo is authoritative, and git-ignored `docs/architecture/` folders in the compiler repo are silently untracked.

---

## Authoring an Input Spec

**When writing a spec on behalf of a user, you MUST:**

1. **Read `schemas/canonical-schema.yaml` first** — this is the authoritative contract for every field, allowed value, and constraint. Do not guess field names or structure.
2. **Read `config/defaults.yaml`** — fields omitted from the spec are filled from here; knowing defaults prevents spec over-specification.
3. **Consult `test-specs/`** — comprehensive examples covering edge cases, compliance requirements, and platform combinations. Use these as reference, not templates to copy blindly.

For brownfield systems, inspect the existing codebase to extract actual providers, runtime assumptions, storage/auth boundaries, and feature signals. Use that information to inform the spec, but do not treat the prototype stack as approved architecture until it is explicit in the spec and reviewed by the human.

**If the user hasn't specified `constraints.cloud`, `constraints.language`, or `constraints.platform`, ask before proceeding.** These three fields drive the majority of pattern selection — defaulting them silently produces a spec that doesn't reflect the user's system. Same applies to any NFR target the user cares about (availability, latency, compliance).

**After writing `functional.summary`, cross-check implied feature flags and confirm with the user before compiling.** Users rarely know the flag names — infer from the description:

| If the summary mentions… | Ask about… |
|--------------------------|------------|
| Calling an AI/ML model (GPT, Claude, embeddings, vision, etc.) | `ai_inference: true` |
| Message queues, events, pub/sub, Kafka, SQS | `async_messaging: true` |
| Real-time updates, WebSockets, live feeds | `real_time_streaming: true` |
| Semantic search, similarity search, embeddings | `vector_search: true` |
| Storing documents or blobs with flexible schema | `document_store: true` |
| Session cache, Redis, low-latency key lookups | `key_value_store: true` |
| Multiple tenants, tenant isolation, per-customer data | `multi_tenancy: true` |
| Scheduled jobs, bulk processing, nightly runs | `batch_processing: true` |

Ask about each implied flag explicitly — do not silently leave implied flags at their `false` default.

**Spec authoring checklist:**
- [ ] Every field used exists in `schemas/canonical-schema.yaml`
- [ ] `constraints.cloud`, `constraints.language`, `constraints.platform` confirmed with user (not assumed)
- [ ] NFR targets reflect actual user requirements, not defaults
- [ ] Feature flags cross-checked against `functional.summary` — implied flags confirmed with user, not silently defaulted to `false`
- [ ] Save spec to a user-specified file (e.g. `-spec.yaml`) before compiling

**Example spec:**

```yaml
project:
  name: My Service
  domain: ecommerce
functional:
  summary: REST API for product catalogue
constraints:
  cloud: azure          # aws | azure | gcp | agnostic
  language: python
  platform: api         # api | web | mobile | data | cli
nfr:
  availability:
    target: 0.999
  latency:
    p95Milliseconds: 100
    p99Milliseconds: 200
  security:
    auth: jwt

All missing fields are filled from config/defaults.yaml and recorded in assumptions.

---

After Compilation

Once the compiler succeeds (exit 0), present results to the user by:

1. Summarising selected patterns — read selected-patterns.yaml and list pattern names grouped by category, with a one-line description of what each provides. Ask explicitly: "Are there any patterns here you don't want, or patterns you expected that are missing?" Do not move forward until the human has reviewed the full pattern list — patterns are not surfaced again in the pre-approval gate, so this is the human's primary chance to challenge the selection.
2. Diffing against previous compile (on recompile only) — if this is not the first compilation, compare the new selected-patterns.yaml against the previous one and present the diff before anything else: which patterns were added, which were removed, and the compiler's reason for each change. Do this before presenting cost results. Silent pattern churn between compilations is a common source of surprises.

If you find yourself presenting cost or pattern summaries before running a diff, stop — you skipped this step. Run: ``bash diff **Cost ceiling exceeded — confirmation required before finalising** > > | | Ceiling | Actual | Overage | > |--|---------|--------|---------| > | Monthly OpEx | $X | $Y | +$Z/mo | > | One-time CapEx | $X | $Y | +$Z | > > **Pattern infrastructure costs** *(for reference only — costs come from each pattern's cost.provenance field and were estimated by LLM at authoring time, not sourced from live pricing. Check cost.provenance.source in each pattern JSON for the estimate date. Validate against current provider pricing before treating as accurate)*: > - pattern-a — $X/mo > - pattern-b — $Y/mo > > **Operating model costs** *(requires your close attention — these often dominate real TCO)*: > > The compiler calculated ops team cost using: > ` > ops_team_size × single_resource_monthly_ops_usd × on_call_multiplier × deploy_freq_multiplier > = × $ × × = $/mo > ` > Please confirm each input is accurate for your team: > - **opsteamsize: ** — number of engineers dedicated to operating this system. Default is 0, which produces $0 ops cost and understates real TCO if your team has dedicated ops engineers. > - **singleresourcemonthlyopsusd: ** — fully-loaded monthly cost per ops engineer (salary + benefits + overhead). Default is $10,000. > - **oncall: ** — whether the team is on-call. true applies a 1.5× multiplier reflecting SRE on-call overhead. > - **deployfreq: ** — deployment frequency. Affects operational burden (daily = 1.0×, weekly = 0.8×, on-demand = 1.2×). > > If any of these don't match your team's reality, update operatingmodel in the spec and recompile before finalising. > > **How would you like to proceed?** > 1. **Update operatingmodel** — correct the ops team inputs and recompile for an accurate cost picture > 2. **Raise the ceiling** — update cost.ceilings` in the spec to reflect the actual cost and recompile > 3. Remove specific patterns — tell me which patterns are not required; I'll remove them and recompile > 4. Proceed anyway — acknowledge the breach and approve as-is; the ceiling remains in the spec as a documented aspiration ---

Wait for the human's explicit choice. Do not guess which option they want and do not proceed to finalisation on your own.

Promoting assumptions to formal spec fields

When a user wants to adjust a defaulted value, or before finalising (see below):

1. Find the field under assumptions — e.g. assumptions.nfr.latency.p95Milliseconds: 500
2. Add it at the corresponding top-level path with the confirmed value — e.g. nfr.latency.p95Milliseconds: 100
3. Remove the entry from assumptions
4. Recompile — the compiler will respect the explicit value and not re-default it

The path mapping is direct: assumptions.. → ..

MUST-DO when promoting assumptions.patterns..*: Before copying any pattern config value into the top-level patterns: section, cross-check each value against the spec's explicit choices:

• Does the defaultConfig name a specific provider (e.g. model_provider: openai, provider: supabase)? Cross-check against constraints.saas-providers and constraints.cloud. If there is a conflict — e.g. model_provider: openai but saas-providers: [anthropic] — flag it and ask the human for the correct value before promoting.
• Does the defaultConfig name a language-specific framework or tool? Cross-check against constraints.language.

Do not silently promote a defaultConfig value that contradicts a spec-level constraint. The defaultConfig is a registry default, not a user decision — it must be validated against what the user actually specified before it becomes part of the authoritative architecture.

MUST-DO before final approval when provider-specific variants are selected: inspect the promoted pattern config as a system, not field-by-field. Look for contradictions such as:

• cloud-specific architecture pattern defaults that imply a different auth or database provider than the human approved
• generic pattern config and provider-specific variant config disagreeing on timeout, persistence, or transport semantics
• a provider default changing the architecture from "agnostic" to provider-bound without that being reflected in constraints.cloud or constraints.saas-providers

If you find a contradiction, stop and resolve it in the spec before finalising. Do not bury the conflict in the approval header.

---

Pre-Approval Validation Gate

Before finalising, you MUST present the compiled spec's core sections to the human for explicit sign-off. Do not skip this step even if the human said "looks good" to the pattern list — the pattern list is not the architecture contract. The sections below are.

Present the following sections from compiled-spec.yaml in readable form and ask the human to confirm each:

constraints:
  cloud:           # is this the right target environment?
  language: 
  platform: 
  saas-providers: [...]   # are these all the external services you intend to use?
  features:               # are these the right feature flags — anything missing or incorrectly enabled?
    ai_inference: 
    caching: 
    ...

nfr:
  availability:
    target:        # does this reflect your actual uptime requirement?
  latency:
    p95Milliseconds: 
    p99Milliseconds: 
  data:
    pii:           # does this app store or process personally identifiable information?
    retention_days: 
    compliance:           # are these compliance requirements accurate for your jurisdiction?
      gdpr: 
      ccpa: 
      hipaa: 
      sox: 

operating_model:
  ops_team_size:         # how many engineers will operate this?
  on_call:               # will someone be paged if this goes down?
  deploy_freq:           # how often will you deploy?

cost:
  ceilings:
    monthly_operational_usd:    # is this a real constraint or a placeholder?
    one_time_setup_usd: 
  preferences:
    prefer_saas_first: 

Then ask: "Do all of these reflect your actual system requirements? Any corrections before I finalise?"

Wait for explicit confirmation. Do not proceed to finalisation until the human confirms (or makes corrections and confirms the updated values). If corrections are made, update the spec and recompile before finalising.

Why this gate exists: The compiler promotes defaults into these sections — values the human never explicitly typed. A pattern list review does not surface these defaults. This gate ensures the human is signing off on the actual architecture contract, not just the pattern names.

MUST-DO before asking for approval: call out any architecture-binding decisions that are still open. If the user is treating them as "implementation details" but they would change providers, runtimes, message semantics, auth boundaries, retention handling, or accepted data-processing risk, tell them these are still architecture decisions and must be resolved before final approval.

Priority groupings review

The compiler groups assumptions.patterns into buckets:

• meta — compile-time validators (not implementation work; skip in sequencing)
• P0 — backbone fulfilling constraints (arch, platform, hosting, data, inference, IaC, agentic topology+session)
• P1 — built o

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: inetgas
• Source: inetgas/arch-compiler
• License: MIT

Install and usage instructions live in the source repository linked above.