Skip to main content

Enterprise Architecture Specification

Use when designing production enterprise applications.

Purpose​

Use this workflow for production architecture or major application revisions spanning several independently testable capabilities, public interfaces, security boundaries, cloud topology, or regulated data. The deliverable is an owner-approved architecture baseline and executable contract pack—not code, a roadmap alone, or unreviewed prose.

1. Establish intent before architecture​

Interview one decision at a time with a stated hypothesis and confidence. Resolve at least:

  • product and tenancy model;
  • identity admission and authorization ownership;
  • users, launch load, growth envelope, and noisy-neighbor policy;
  • availability, disaster scope, RPO/RTO, and cost tolerance;
  • data residency, compliance readiness, retention, and deletion;
  • external credentials, commercial entitlements, and billing responsibility;
  • automation authority, human-only gates, and separation of duties;
  • API/protocol/connector surface and explicit non-goals.

Restate outcome, users, success, constraints, and out-of-scope items. Require explicit owner confirmation. Do not convert “production-ready,” “highly available,” or “secure” into architecture without measurable targets.

2. Approve a capability map first​

For multi-capability work, create a small map with stable kebab-case module IDs, responsibility, tier, dependencies, and specification/build order. Gate it with the owner before detailed specs.

Validate the graph as an executable DAG, not a conceptual diagram:

  1. Trace every synchronous decision call.
  2. Trace who persists each module's state and owns migrations.
  3. Trace which module must exist first to build or test the consumer.
  4. Move lower-level substrates earlier or invert dependencies when a provider needs a consumer-owned context.
  5. Assign one owner for each business decision—especially authorization, quota admission, state transitions, and publication.

A hidden reverse edge is still a cycle. For example, identity cannot precede the data substrate it uses while that substrate depends on identity behavior; a broker cannot own quota reservation while the quota module depends on broker output.

If the owner adds an independently testable requirement after approving the map, update the map first: give it a stable capability ID, owner, dependencies, and specification order, then reconcile downstream specifications and acceptance mappings. Do not bury late scope inside an unrelated module merely to avoid reopening the map.

For recurring remediation, prefer one fixed, bounded lifecycle edge that preserves immutable prior attempts/evidence and requires fresh downstream gates. Do not generalize one known loop into a caller-defined DAG engine.

3. Research current constraints before selecting technology​

Run parallel official-source research for independent workstreams such as cloud topology/pricing, identity, data/recovery, external provider terms, protocol standards, and product workflow. Require full URLs and separate:

  • supported versus preview/unsupported behavior;
  • engineering objective versus provider SLA/guarantee;
  • consumer subscription versus commercial API/workload entitlement;
  • public retail estimate versus procurement quote;
  • technical feasibility versus commercial/legal approval.

When research invalidates a requested path, stop at that boundary. Present supported alternatives and obtain an explicit owner decision; never preserve an impossible requirement as an implementation TODO.

4. Produce the architecture set​

Create and version together:

  1. Master design — objectives/non-goals, three-tier or chosen logical view, deployment view, trust boundaries, quality attributes, threat model, lifecycle, migration, phased delivery, integrated gates, assumptions, and risks.
  2. ADRs — selected options, rejected alternatives, consequences, costs, and review triggers.
  3. One spec per approved module — objective, consumers/boundaries, owned interfaces/data/events, security/privacy, reliability/scaling, observability, migration, tests, acceptance IDs, ask-first/never rules, and sources.
  4. Versioned bill of materials — per-region components, replica minima/maxima, resource profiles, included costs, and mandatory but separately budgeted items.

Keep provider/model bindings in configuration. Domain modules request roles/capabilities; they do not own provider transports, credentials, model allowlists, or fallback policy.

Create and version the architecture chain in a dedicated product repository when the system is independently deployable or recoverable. Derive the detailed specification only from the approved intent and capability map; derive the implementation plan only from the approved specification. Never write the plan in parallel with an unapproved specification.

When the system owns recoverable local state, prefer the platform's native portable export/import contract over a custom dump. Define scope/exclusions; export outside the repository; validate structure, format, counts, hashes, secrets, and forbidden machine-local state; prove recovery through an isolated non-destructive import/readback; then publish only verified changed content with a manifest and remote commit readback. Measure RPO from completed restore verification, not schedule or export start. Surface Git-history growth and deletion-retention risk rather than silently pruning or rewriting history.

5. Check in a normative contract pack​

Prose-only enterprise specifications are incomplete. Add machine-readable artifacts where applicable:

  • OpenAPI or equivalent public API contract;
  • API-to-protocol coverage mapping, with every operation mapped exactly once or marked as a human-completion handoff;
  • policy, messaging, and idempotency schemas;
  • aggregate state machines with one owner each;
  • identity registration/token-flow matrix;
  • migration disposition for every existing route and persisted record kind;
  • compatibility/deprecation windows;
  • acceptance-to-test/evidence matrix.

Declare source-of-truth direction and generation rules. Select one canonical organization/isolation identifier and one internal actor identity; reject aliases in routes, persistence, messages, caches, metrics, receipts, and audit. External identity claims remain provenance unless explicitly authoritative.

Classify acceptance evidence honestly before mapping it:

  • Current specification validation proves only a repository-byte property at the specification commit. Bind it to one exact test method or named production-validator procedure that declares the acceptance ID, runs from repository root, and emits the exact assertion/output named by the mapping. Broad module commands and unrelated fixtures are not one-to-one evidence.
  • Future product test specification covers behavior requiring unbuilt code, a real process/workspace, database cluster, external service, backup/restore, deployment, cutover, rollback, soak, or other side effect. Specify the future harness, inputs/faults, ordered procedure, exact assertions, receipts, retained outputs, cleanup, and stop conditions. Do not attach a current command, execution timestamp, receipt, evidence path, or green status.

Execute every declared current selector from repository root in the deterministic gate. A selector that only parses or whose import depends on an accidental shell/PYTHONPATH setup is not executable evidence. Validate future cases for completeness and absence of execution claims, but never run or report them as passing during specification work.

For external side effects and independently replicated stores, model uncertainty explicitly:

  • persist OUTCOME_UNKNOWN/reconciliation states;
  • prohibit replacement attempts until the first effect is reconciled;
  • provide lookup-by-execution/idempotency interfaces;
  • define one recovery watermark valid across all authoritative stores;
  • quarantine dangling manifests, orphaned objects, and post-cut state before reopening.

6. Add one deterministic contract validator​

The repository must have one command that fails on:

  • invalid JSON/YAML/OpenAPI/JSON Schema;
  • duplicate/missing operation IDs or protocol mappings;
  • broken contract references;
  • duplicate aggregate ownership or invalid transitions;
  • noncanonical identifiers;
  • unmapped existing routes/record kinds;
  • acceptance IDs without exactly one test/evidence mapping;
  • whitespace or placeholder residue.

Run it before review, after every remediation, and immediately before completion. Scan the exact staged documentation/contracts for secret signatures before committing. Put dependency-DAG, delivery-eligibility, trigger/runbook, BOM/prose, schema/prose, cryptographic-vector, and acceptance-binding checks inside this production validator—not only in unittest helpers—because downstream users rely on the advertised single command.

7. Run fresh-context reader gates​

Before asking the owner to approve:

  1. Commit the exact draft.
  2. Dispatch independent fresh-context reviewers for enterprise architecture, security/privacy, and implementability/interfaces.
  3. Require severity, exact location, mechanism, concrete correction, and APPROVE or REQUEST_CHANGES.
  4. Consolidate accepted findings into one bounded remediation contract.
  5. Separate finding corrections from new owner decisions before editing. A reviewer recommendation that adds a database topology, authorization mechanism, retention/deletion policy, paid service, custody provider, or repository owner is not automatically approved architecture; present the concrete alternatives and record the owner's choice in the remediation contract.
  6. Decompose a large remediation contract into sequential packages by owning artifact set. Require each package to leave a green committed checkpoint and receipt before the next package edits shared schemas, validators, or evidence matrices.
  7. Fix the owning sentence or normative artifact in place; do not append contradictory updates.
  8. Re-run contract validation and commit the correction.
  9. Re-review that exact immutable head. A self-authored checklist does not replace independent re-review.

For large acceptance/evidence matrices or other regular structured artifacts, generate the transformation deterministically from authoritative IDs, owning sources, executable tests, real fixture paths, phases, and registered receipt schemas. Validate every generated reference and add mutation tests. Do not ask an agent to hand-write thousands of repetitive JSON entries: write-tool/context limits produce partial trees that look substantial but are not complete.

Do not present the specification as approved while module specs still say draft or any blocking reviewer returns REQUEST_CHANGES.

8. Owner gate and handoff​

Present a short report:

  • artifact paths and exact commit;
  • selected architecture and cost basis;
  • validation results and independent verdicts;
  • remaining legal, commercial, operational, and qualification assumptions;
  • explicit decision requested from the owner.

On a messaging surface that supports file delivery, attach every generated or revised architecture document to the same message that presents it. A filesystem path alone is not delivery; attach intent statements and capability maps at their approval gates, then attach the specification, ADRs, contract pack, and plan when each becomes available.

For any role profile whose work may use an external library/framework/SDK/package/API, verify both policy and tool reachability: install/auto-load the documentation skill, connect and smoke-test the documentation tools, and require a library ID/version/topic receipt (or a recorded coverage gap plus official current source). A policy sentence without reachable tools is not enforcement.

Only after explicit owner approval move to implementation planning. Specification approval does not authorize cloud provisioning, production credentials, paid provider calls, publication, or deployment unless the owner separately grants that authority.

Pitfalls​

  • Do not let two modules own the same control decision — duplicate authorization, quota, or state logic diverges across interfaces.
  • Do not call RLS independent isolation when a shared runtime can freely select any organization context — the same compromised process can satisfy its own predicate; use an independently validated context boundary or qualify the claim.
  • Do not restore privacy tombstones from the same backup they must suppress — a pre-erasure recovery point cannot contain later erasure state; use an independently replicated suppression ledger.
  • Do not call a transport success publication — verify destination identity/version/hash by readback before terminal success.
  • Do not hide mandatory unpriced services inside a platform subtotal — list identity add-ons, backup/recovery custody, security telemetry, model usage, support, and personnel separately.
  • Do not equate full protocol coverage with authority bypass — human-only actions can use a first-party authenticated completion surface and resume the same server-side operation.
  • Do not let a receipt prove itself with caller-supplied booleans — bind safety claims to immutable identities, verified signatures, evidence references, fail-closed state transitions, and timeline arithmetic.
  • Do not pin plausible bytes for an unbuilt artifact — mark the final digest unresolved until a reproducible build and registry readback produce a signed receipt.
  • Do not conflate runtime dependencies with delivery eligibility — keep the import DAG acyclic while separately gating later phases on immutable earlier-phase acceptance receipts.

Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/enterprise-architecture-specification/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

Published by Muse · 2026-10-04.