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:

arch-compiler/
├── README.md
├── AGENTS.md
├── README-AGENTS.md
├── tools/        <-- read-only for agents
├── schemas/      <-- read-only for agents
├── config/       <-- read-only for agents
├── scripts/      <-- read-only for agents
├── patterns/     <-- read-only for agents
└── skills/
    ├── using-arch-compiler/
    │   └── SKILL.md
    ├── compiling-architecture/
    │   └── SKILL.md
    └── implementing-architecture/
        └── SKILL.md

Before acting:

1. Read AGENTS.md for repo-wide agent rules and boundaries.
2. Read this SKILL.md for the task-specific workflow.
3. Treat tools/, schemas/, config/, and patterns/ as read-only unless the human explicitly asks for compiler-maintenance work in this repo.
4. Use this skill only when docs/architecture/ already exists and is approved. If architecture is missing or unapproved, switch to skills/compiling-architecture/SKILL.md instead of inventing architecture choices.

The important split is:

• AGENTS.md = global agent rules for this repo
• skills/using-arch-compiler/SKILL.md = workflow router
• skills/compiling-architecture/SKILL.md = how to compile and finalise architecture
• skills/implementing-architecture/SKILL.md = how to implement an already-approved architecture

When to Use

• You have a docs/architecture/ folder with approved artifacts
• You are about to write code and need to know which technology choices are authorised
• You have an existing prototype or codebase and need to refactor it to conform to an approved architecture

When NOT to Use

• No docs/architecture/ folder exists — a compiled and approved architecture must be produced first (see skills/compiling-architecture/SKILL.md if available)
• The architecture.yaml has no STATUS: APPROVED header — do not implement an unapproved architecture
• You have architecture artifacts but no functional requirements — ask the human for features, user stories, design doc, or API specs before writing application code. The architecture tells you which database to use; functional requirements tell you what to store in it.
• Planning or pre-flight reveals unresolved provider/runtime/auth-boundary/retention/message-path decisions that would materially change constraints., constraints.saas-providers, patterns., or accepted risk posture — that is architecture work, not implementation. Stop and return to skills/compiling-architecture/SKILL.md.
• Do not treat an existing prototype or codebase as architectural authority. Existing code that conflicts with the approved artifacts must be refactored to match, or raised as an architecture mismatch. Do not silently treat the prototype as the source of truth.
• Do not use this skill if making the existing prototype fit the system would require changing the approved architecture itself. That is architecture work and must return to skills/compiling-architecture/SKILL.md.
• If the human explicitly wants existing prototype choices to replace approved providers, boundaries, or selected patterns, treat that as architecture work immediately instead of starting implementation and discovering the stop condition later.

Brownfield rule: existing code is still implementation scope when the job is to bring it into compliance with an approved architecture. This skill applies to both greenfield implementation and brownfield refactoring. The stop condition is not "code already exists"; the stop condition is "the approved architecture itself must change."

Example:

> 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

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:

python3 ~/.codex/arch-compiler/tools/archcompiler_preflight.py --app-repo <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.

1. 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.
2. 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."
3. 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:

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:

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:

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 is to find gaps — not to validate. You are explicitly forbidden from producing a pass/fail verdict or any positive summary statement.

>

> Read:

> 1. Functional requirements source: [path or inline content — design doc, user stories, feature specs, or any combination]

> 2. docs/architecture/architecture.yaml

> 3. The drafted plan: [path/to/plan.md]

>

> For each area below, produce a numbered list of questions and concerns. If you find nothing to question in an area, look harder — do not leave an area blank.

>

> Area 1 — Functional requirements: For each requirement in the source, ask: "Where exactly in the plan is this implemented — which file, function, and test?" If the answer is not obvious from the plan text, flag it. Also extract any items the source explicitly marks out of scope — do not flag those.

>

> Area 2 — NFR completeness: For every field under nfr. in architecture.yaml, ask: "Where in the plan is this enforced with code?" A comment, a note, or a documentation file is not an implementation. Pay attention to fields outside the common set: data.retention_days, data.pii, consistency., durability., throughput..

>

> Area 3 — Pattern provides delivery: For each selected pattern, read its provides array in docs/architecture/patterns/.json. For each capability, ask: "Which specific step in which task delivers this?" If a pattern appears only in a summary table with no task that walks through its provides capabilities, flag it.

>

> Area 3.5 — Concrete artifact coverage: For each selected pattern, ask: "What concrete artifact will exist after implementation?" Acceptable answers include a code file, infrastructure resource type/name, migration, configuration file, named test function, or runbook. If the plan only names a subsystem or workstream and not an artifact, flag it. If the answer is only an environment variable reference, a client call that assumes an externally-created resource, or a comment, flag it as non-implementation.

>

> Area 4 — Runtime and API compatibility: For each pattern with runtime-specific defaultConfig values (function_runtime, edge_functions, compute_type), ask: "Do the packages and APIs chosen in the plan actually work in this runtime?" Name the specific API or package you are questioning.

>

> Area 5 — Error and edge cases: For each main user-facing flow in the requirements source, ask: "Where does the plan handle the failure scenario?" Look for: upload failures, external API timeouts, empty results, retry flows, unauthenticated access attempts. Additionally, for any state that persists across page reloads (poll results, uploaded image URLs, job status), ask: "Does the plan preserve or re-fetch this state from a durable source — or does it survive only in-memory or in a URL parameter that is unavailable after a reload?"

>

> Output ONLY this structure — no preamble, no verdict, no positive statements:

>

> ```

> ## Adversarial Review — Gaps and Questions

>

> ### Area 1: Functional requirements

> 1. [Requirement text]: [Specific question]. Not visible in plan because: [what's absent].

>

> ### Area 2: NFR completeness

> 1. nfr.[field]: [Specific question]. Not visible in plan because: [what's absent].

>

> ### Area 3: Pattern provides delivery

> 1. [pattern-id] provides [capability]: [Specific question].

>

> ### Area 3.5: Concrete artifact coverage

> 1. [pattern-id]: [Specific question about missing concrete artifact].

>

> ### Area 4: Runtime and API compatibility

> 1. [pattern-id] sets [config key]: [value]. Plan uses [package/API]. Question: [compatibility concern].

>

> ### Area 5: Error and edge cases

> 1. Flow [name], failure scenario [x]: [Specific question].

> ```

>

> If you find yourself writing a positive statement, delete it and find another gap instead.

Resolving the gap list:

For each item the reviewer raises, respond with exactly one of:

• Covered — cite it: "Covered at Task N, Step M, file path/to/file.ts." If you cannot cite a specific location, the item is a real gap.
• Gap confirmed: add the missing task or step to the plan before presenting to the human.

Do not dismiss items with vague reassurances ("handled by the framework", "implied by the pattern", "standard practice"). If it is not explicitly in the plan, it is a gap.

After resolving, note in the human-facing summary what the adversarial review found and what was added.

Final Verification must be structured as numbered tasks, not prose. After resolving adversarial-review gaps, write a Final Verification section in the plan as explicitly numbered tasks with exact commands and expected output. A prose appendix is not a task and will not be tracked by plan executors.

At minimum, Final Verification must include:

1. A smoke-test task that starts the service (or nearest equivalent), performs at least one real call, and verifies a valid response
2. A post-implementation adversarial-review task matching Step 5 below

Rewrite vs patch: If more than 3 gaps are confirmed, rewrite the full plan rather than patching individual tasks. Patching accumulates on top of the original blindspots — the same mental model that produced the gaps is now editing its own output. A full rewrite forces you to trace every task from scratch with the gap list in hand, which surfaces secondary issues invisible in a diff. (Example: fixing a retry flow reveals a polling cleanup bug that only shows up when reading the whole JobPoller spec in one pass — not when diffing the retry step in isolation.)

Re-review trigger: If the architecture is recompiled or re-approved after the plan was drafted, the plan is stale by default. Re-run the adversarial review against the new docs/architecture/ before presenting or executing the plan. If the pattern set or top-level constraints changed materially, rewrite the plan instead of carrying the old one forward.

Step 2 — Establish implementation order

Primary: derive sequencing from requires/provides. For each selected pattern, read its requires list and find which other selected patterns provides those capabilities — those providers must be implemented first. Build the full dependency order before writing any code. Do not skip this: the category table below is a manually authored approximation and can diverge from actual dependencies.

Secondary: use this table only when the dependency graph leaves order ambiguous (e.g. two patterns with no dependency on each other). It is a scaffold, not a substitute for the requires/provides check.

If the table order conflicts with a requires/provides dependency, the dependency wins.

Step 3 — Implement each pattern

Do this for each pattern individually, immediately before writing its code — not as a bulk upfront exercise. Reading compiled-spec.yaml or a prior subagent summary is not a substitute for reading the pattern JSON itself.

For each pattern:

1. Read patterns/.json now — even if you read it earlier, re-read it immediately before writing this pattern's code
2. Read defaultConfig — use these values directly; they are the approved choices
3. Read configSchema descriptions — understand the trade-offs and wire config into environment variables or config files accordingly
4. Check defaultConfig for runtime-specific values (e.g. function_runtime, edge_functions, compute_type) and verify that the packages and APIs in your implementation are compatible with that runtime. function_runtime: nodejs means Edge-only APIs are unavailable — use Node.js equivalents. edge_functions: true means Node.js built-ins are unavailable — use Web APIs. Mismatches compile and deploy silently but fail at runtime.
5. Check whether the pattern relies on process-local state, sticky sessions, local filesystem persistence, or long-lived memory. If the selected runtime is stateless or ephemeral, do not implement a thin in-process approximation and call it done — either bind it to a durable backing service or flag the mismatch.
6. Check requires as a pre-implementation checklist — confirm each required capability is already in place before starting. If a required capability (e.g. a metrics backend, CI/CD integration, SLO tracking tool) does not exist anywhere in the current architecture, stop — do not write code for this pattern. Follow the unimplementable pattern workflow below.
7. After implementing, verify your implementation delivers every capability listed in provides. If any capability is undelivered, stop — do not move to the next pattern. Follow the unimplementable pattern workflow below.

Do not deviate from defaultConfig values without human approval. If a value is unachievable or breaks NFR targets and/or compliance requirements, surface it to the human — do not substitute silently. Ask human to review and recompile architecture if needed.

Step 4 — Verify against NFR targets

After implementing each pattern, verify configuration correctness against architecture.yaml. Agents verify that config values are set appropriately for each target — live performance testing against actual workloads is a human-run step done outside this workflow.

Step 5 — Post-implementation verification

After all patterns are implemented, complete two verification tasks before declaring implementation done. Both must appear in the plan as explicit numbered tasks inside Final Verification.

5a. Smoke test (mandatory)

Start the service and verify at least one real call succeeds end-to-end.

Step 4 covers configuration correctness. Step 5a covers whether the implementation actually runs. The carve-out in Step 4 for human-run live testing applies to load/performance testing only — not to the smoke test.

If the smoke test hits a runtime environment blocker (for example SDK incompatibility, missing cloud access, expired credentials, or unavailable external infrastructure), make one reasonable workaround attempt. If it still fails, surface the blocker to the human and stop iterating around it. An environment blocker is not the same thing as an implementation bug.

5b. Post-implementation adversarial review

Run an adversarial review of the actual implementation against docs/architecture/ — not just the plan. The plan adversarial review asks "does the plan cover the architecture?" This review asks "does the implementation in the working tree or commit candidate deliver what the plan said?"

The reviewer must be forbidden from producing a pass/fail verdict or positive summary. Its only output is a gap list. Prefer a reviewer with no prior implementation context so it is less likely to rationalize gaps away.

Focus areas:

• Does each selected pattern's provides capability appear in actual code, infrastructure, config, or tests — not stubs, comments, or log lines?
• Are NFR targets wired in running code, not only in config or documentation files?
• Do any implementation details contradict the approved defaultConfig values?
• Are cross-task integration points correct?

Resolve findings the same way as the plan adversarial review: cite the exact file and line, or confirm the gap and fix it.

When a Pattern Can't Be Implemented or Human Asks to Skip It

If a pattern is unachievable, over-engineered for the scope, or the human explicitly says to skip it — do not skip it silently in code.

A partial implementation is a silent skip. Writing a log line, a comment, or a stub that references a pattern's defaultConfig values without delivering the capabilities in provides is not implementation — it is a silent skip with extra steps. It is worse than a clean skip because it creates the illusion of compliance. Treat it identically: stop and follow the workflow below.

The approved docs/architecture/ folder is the source of truth. A pattern listed there but not fully implemented creates drift between what was decided and what was built — defeating the purpose of having an approved architecture.

The correct response in all cases:

1. Confirm with the human that the pattern should be removed and that this requires a recompile:

> "ops-low-cost-observability and ops-slo-error-budgets are in the approved architecture. To keep things simple I'd suggest removing them — that means recompiling and re-approving the spec. Should I proceed?"

1. Do not recompile yourself — the human or a compiler agent adds the pattern IDs to disallowed-patterns in the spec, recompiles, and re-approves the output (see skills/compiling-architecture/SKILL.md if available)
2. Only implement once the updated architecture is re-approved — the refreshed docs/architecture/ is your new source of truth

Binding Constraints

architecture.yaml constraints are not suggestions:

• constraints.cloud — use only services from this provider
• constraints.language — implement in this language only
• constraints.platform — shapes deployment target and code structure (e.g. data-pipeline means batch jobs, not an HTTP server)
• constraints.features.* — only features set to true are in scope; do not implement features that aren't enabled

Common Mistakes