# Implementing Architecture

> Use when: about to write code and docs/architecture/ exists with STATUS: APPROVED in architecture.yaml. Not when: no approved architecture yet (use compiling-architecture first), or architecture.yaml lacks STATUS: APPROVED header.

- **Type:** Skill
- **Install:** `agentstack add skill-inetgas-arch-compiler-implementing-architecture`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [inetgas](https://agentstack.voostack.com/s/inetgas)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [inetgas](https://github.com/inetgas)
- **Source:** https://github.com/inetgas/arch-compiler/tree/main/skills/implementing-architecture

## Install

```sh
agentstack add skill-inetgas-arch-compiler-implementing-architecture
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Architecture Pattern Implementer

## Overview

Translates approved architecture artifacts into working code. The architecture folder is the authoritative source for HOW to build — which services, which config, which constraints. It does NOT replace functional requirements, which tell you WHAT to build (business logic, features, API contracts). You need both.

---

## Repo Structure — Read This First

Treat the compiler repo as having this contract:

```text
arch-compiler/
├── README.md
├── AGENTS.md
├── README-AGENTS.md
├── tools/         A prototype stores files on local disk and uses ad hoc session auth, but the approved architecture selects object storage and managed OAuth/OIDC. Refactoring the prototype to use the approved storage and auth stack is implementation work, so this skill applies.

---

## What the Artifacts Contain

| File | What to use it for |
|------|--------------------|
| `architecture.yaml` | All decisions explicit at top-level — constraints, NFR targets, pattern configs at `patterns..*`. No `assumptions` section; every field is intentional. |
| `selected-patterns.yaml` | The approved pattern list — every pattern here must be reflected in the implementation |
| `patterns/.json` | Full pattern detail — read this before implementing each pattern |

Inside each `patterns/.json`:
- `description` — what the pattern is
- `defaultConfig` — the specific services/values chosen; use these directly
- `configSchema` — descriptions and trade-off explanations for each config option; read this to understand why a value was chosen and what the alternatives mean
- `provides` — capabilities the implementation must exhibit
- `requires` — what must be in place before this pattern can work
- `tags` — useful for finding official documentation

> **`docs/architecture/` is read-only.** You may not edit any file in this folder — not `architecture.yaml`, not `selected-patterns.yaml`, not pattern JSONs. These files are compiler output. Their `STATUS: APPROVED` header reflects a human decision made against a specific compiler run. A hand-edited `architecture.yaml` is not an approved architecture — it is drift with an approval header on it.
>
> If you spot a discrepancy between files in `docs/architecture/` (e.g. `architecture.yaml` lists a pattern not in `selected-patterns.yaml`, or has wrong config for a variant): **stop. Do not fix it yourself.** Tell the human what is mismatched. Then: if you have the `compiling-architecture` skill, propose the input spec changes, get human confirmation, apply them, re-run the compiler, and present the output for re-approval. If you do not have that skill, ask the human to update the input spec and re-run the compiler themselves. Either way, human re-approval of the compiler output is required before you continue.
>
> The temptation to "just update the date and fix the field" is the exact failure mode this constraint prevents.

---

## Implementation Workflow

### Step 1 — Read the artifacts

Before writing any code:

1. Read `architecture.yaml` — every field is explicit; note `constraints` (cloud, language, platform), `nfr` targets, and `patterns..*` for pattern-specific config
2. Read `selected-patterns.yaml` — get the full list of pattern IDs
3. For each pattern ID, read `patterns/.json` — `defaultConfig` gives approved values; `configSchema` explains the trade-offs

### Step 1.5 — Pre-flight check before writing any code

**You MUST perform this check yourself. Do not delegate it to a subagent.** Subagents optimise for "no blocking errors" and resolve flags creatively rather than raising them — which defeats the purpose. A subagent returning "Overall Status: GREEN" is not a substitute for your own verification.

Before the detailed pattern-by-pattern checks below, run the shared workflow preflight helper:

```bash
python3 ~/.codex/arch-compiler/tools/archcompiler_preflight.py --app-repo  --mode implement
```

If it fails, stop and fix the reported issue before continuing.

After reading all pattern JSONs in Step 1, and **before writing a single line of code**, go through every pattern and verify:

1. **`requires` is satisfiable** — every capability listed in `requires` is either provided by another selected pattern or already exists in the environment. If a required capability (e.g. `metrics-collection`, `distributed-tracing`, `time-series-database`) has no provider anywhere in the architecture, flag it.

   **Before flagging a gap**, check `schemas/capability-vocabulary.yaml` if it exists in the project. Capabilities with `category: environment` are always satisfied by the deployment environment — skip them entirely, do not raise them as gaps. Examples: `internet-connectivity`, `git-repository`, `compute`, `persistent-storage`, `network-connectivity`, `cloud-infrastructure`, `storage`, `infrastructure`, `data-storage`, `system-architecture`.
2. **`provides` is deliverable** — you can concretely implement every capability listed in `provides` given the current constraints (cloud, language, platform). If delivering a capability would need infrastructure or tooling not present in the architecture, flag it.
3. **Pattern integrity** — if a pattern's `requires` lists a capability that the same pattern's own `supports_nfr`, `provides`, or description explicitly states it cannot deliver, that is a registry bug. Flag it as: "Pattern X requires capability Y but its own NFR section declares it cannot support Y — this looks like a pattern authoring bug."
4. **Runtime semantics are compatible with the selected patterns** — check whether the chosen runtime is stateless, ephemeral, edge-restricted, or otherwise hostile to process-local assumptions. If a pattern implementation would rely on durable in-process state, sticky sessions, local filesystem persistence, or long-lived memory, either bind it to a persistent store or flag it before planning proceeds.

Collect **all** flags across all patterns, then raise them together with the human before proceeding. Do not start implementing and discover blockers mid-way — a partial codebase with unresolved blockers is harder to reason about than a clean pre-implementation conversation.

**A flag means: raise to the human — not find a creative interpretation that allows you to proceed.** The following are NOT resolutions:
- "The platform has logs" is not `monitoring`
- "Deployment logs exist" is not `audit-logging`
- "We can do it manually" is not a provided capability
- "It's close enough" is not satisfiable

**Architecture-binding flags are a stop signal, not plan TODOs.** If pre-flight exposes unresolved choices such as:
- which provider actually satisfies a selected pattern
- where auth is enforced
- which transport implements async delivery semantics
- how retention/deletion is operationalised
- whether an external AI provider changes accepted risk posture

then stop and route back to the compiling skill. Do not keep planning around the ambiguity.

If you catch yourself reasoning that a thin platform feature satisfies a `requires: optional: false` entry, stop. That is a flag.

Example raise:
> "`ops-low-cost-observability` requires `metrics-collection`, `distributed-tracing`, and `time-series-database` — none of these are provided by any other selected pattern. `ops-slo-error-budgets` similarly requires SLO tracking infrastructure. Neither can be fully implemented as the architecture stands. Should I add them to `disallowed-patterns` and recompile, or do you want to add an observability stack first?"

Example integrity flag:
> "`pattern-x` requires `audit-logging` (optional: false) but its own `supports_nfr` declares `audit_logging` must equal `false` because the pattern has no built-in access tracking. This is a contradiction in the pattern registry — should I raise a fix, and how do you want to handle the missing audit trail?"

Example runtime-semantics flag:
> "`resilience-circuit-breaker` is selected, but the target runtime is stateless Lambda-style execution. A module-global circuit breaker will reset across invocations and does not provide durable breaker state. Should I back it with a persistent store, or should we re-evaluate whether this pattern belongs in the approved architecture?"

**Human gate — required even when no flags found.** After completing Steps 1.5, 1.6, and 1.7, present a summary to the human regardless of whether flags were raised:

> "Pre-flight complete. No blocking gaps found. Summary:
> - Requires/provides: all satisfied
> - NFR targets: [list each and whether the selected service meets it]
> - Functional requirements: [list each and the task that covers it]
> - Known limitations accepted: [list any thin implementations]
>
> Ready to proceed to the plan?"

Wait for explicit human confirmation before writing the plan. A clean pre-flight is not implicit approval to proceed.

### Step 1.6 — NFR feasibility check

After Step 1.5, verify that the **selected services** can actually satisfy each NFR target in `architecture.yaml`. The `requires`/`provides` check only confirms pattern compatibility — it does not confirm that real-world services meet real-world targets.

**Do not treat the table below as exhaustive.** After verifying the listed fields, iterate through every field under `nfr.*` in `architecture.yaml` and confirm there is a plan task that delivers it. Any `nfr.*` field with no corresponding task is a gap — flag it. Common examples not in the table: `data.retention_days` requires a cleanup mechanism (scheduled job, TTL policy, or soft-expiry at read time) — a schema comment is not an implementation.

For each NFR field, look up the selected service's actual capability:

| NFR field | What to verify against the actual service |
|-----------|------------------------------------------|
| `nfr.rpo_minutes` | What is the backup frequency of the selected `db-*` provider on the chosen plan? If it exceeds `rpo_minutes`, **flag it** — do not assume it will be fine. |
| `nfr.availability.target` | Does the selected hosting provider's SLA meet or exceed the target on the chosen plan tier? |
| `nfr.latency.p95Milliseconds` | Are function timeout budgets set within this value? Does the selected region minimise latency? |
| `nfr.data.compliance.*` | Does the selected provider offer the required compliance certifications on the chosen plan? |
| `nfr.data.retention_days` | Is there a scheduled cleanup job, TTL policy, or equivalent? A note in a comment is not a plan task. |

**A service limitation is a flag — not a creative interpretation.** Example:
> "`nfr.rpo_minutes: 60` but Neon free tier performs daily backups (1440 min). This NFR cannot be met on the current plan. Should we upgrade the plan, relax the RPO, or accept the gap explicitly?"

### Step 1.7 — Functional requirements cross-check

**Before consulting any heuristic list, locate and read the primary source of functional requirements** — this may be a design doc, user stories, feature specs, a requirements list, or any combination. Extract requirements verbatim from whatever source exists. Also extract anything the source explicitly marks as **out of scope** and record that list alongside requirements.

Only if no source of any kind exists should you fall back to the "common silent misses" heuristics below. A heuristic-based gap that the source material explicitly marks out of scope is not a gap — do not flag it.

For each requirement, confirm a specific plan task will deliver it. Any requirement with no assigned task is a gap — flag it before proceeding.

**Common silent misses** (fallback only — apply when no requirements source exists):
- Navigation/header UI linking between pages
- Sign-in / sign-out flow and unauthenticated landing state
- Error states and retry flows (e.g. retry button on failed jobs)
- Empty states (e.g. "no pets detected", "no history yet")
- Per-user data scoping (history visible only to owner)

**Functional coverage matrix** — every plan document must include this table:

| Functional requirement | Task that delivers it |
|------------------------|----------------------|
| [requirement from design doc] | Task N: [name] |

If any row has no task, stop and either add the task or flag the gap to the human.

**When the human says "accept the gap":** implement the pattern but add an explicit named comment at the point of implementation — not a silent acceptance. Example:
```
// NOTE: monitoring (requires: optional: false) is not provided by this architecture.
// Kill switches must be triggered manually — no automated alerting will signal when to use them.
```

**When the human says "add a note to the architecture":** you cannot — `docs/architecture/` is read-only for implementing agents. Ask the human to update `architecture.yaml` themselves, then confirm before proceeding.

### When generating a plan with an upfront planning tool (e.g. writing-plans)

**MUST-DO before finalising any plan:**

Every plan document must include a **Pattern Coverage Matrix** in addition to the functional coverage matrix:

| Selected pattern | Task that delivers it | Concrete artifact(s) |
|------------------|-----------------------|----------------------|
| `pattern-id` | Task N: [name] | `path/to/file`, infrastructure resource type/name, config file, migration, named test function, or other concrete artifact |

The artifact column must name something concrete: a source file, infrastructure resource type/name, configuration file, migration, named test function, runbook, or other durable implementation artifact. A pattern mapped only to an area such as "backend", "infra", or "observability" is not coverage. An environment variable reference, a client call that assumes an externally-created resource, or a comment that mentions a resource without defining it is also not coverage.

For EVERY selected pattern, immediately before writing that pattern's task in the plan:

1. Read `patterns/.json` — specifically the `provides` array
2. List every `provides` capability explicitly inside that task's steps
3. Verify each capability has a named, testable step and at least one concrete artifact target — not just a table entry
4. Add or update the Pattern Coverage Matrix row for that pattern
5. Do NOT add a pattern to any "done" or summary table unless its task delivers ALL capabilities in `provides`

**This resolves the planning/coding tension:** "read pattern JSON immediately before writing its code" means immediately before writing that pattern's *task in the plan* — not deferred to implementation time. The plan is the first form of code.

**Red flags during plan writing:**
- Writing a "done" summary table before writing the tasks
- Mapping a pattern to an "area of code" without listing its `provides` capabilities
- Mapping a pattern to a task without naming any concrete artifact it will produce
- Any pattern whose only plan entry is a one-liner in a summary table
- Leaving the Pattern Coverage Matrix incomplete or with vague artifact targets
- Finishing the plan before checking every pattern's `provides` array

**A pattern in a summary table without a task that delivers ALL its `provides` capabilities is a silent skip.**

### After drafting the plan — Adversarial review

Once the plan is drafted and before presenting it to the human, dispatch a subagent with an adversarial mandate. This is the one exception to the "do not delegate verification to a subagent" rule in Step 1.5. The difference: the subagent here is forbidden from producing a pass/fail verdict and must assume the plan is incomplete. Its only output is a gap list.

**Why "forbidden from pass/fail" is the key mechanism:** A reviewer asked "does the plan cover X?" will find creative ways to confirm coverage. A reviewer told "find what's missing" and forbidden from positive statements cannot return green without lying — which forces genuine fault-finding instead of validation theatre.

**Subagent prompt — copy and fill in the bracketed paths:**

> You are an adversarial plan reviewer. Your job i

…

## Source & license

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

- **Author:** [inetgas](https://github.com/inetgas)
- **Source:** [inetgas/arch-compiler](https://github.com/inetgas/arch-compiler)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-inetgas-arch-compiler-implementing-architecture
- Seller: https://agentstack.voostack.com/s/inetgas
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.