# Hodios paste pack: Architecture

Everything in Architecture from Hodios, the open prompt library by Hermes IDE: 23 entries, catalog 2026.1004.3.

Every entry is dedicated to the public domain under CC0 1.0. Copy, change and share them freely, no attribution needed.

Browse and search the library at https://hermes-ide.com/prompts

## How to use

Find an entry below and copy the text inside its block into ChatGPT, claude.ai or any chat. Replace each [PLACEHOLDER] with your own material. Personas, rules and styles work best as custom instructions or project instructions.

## Contents

- Architecture
  - [API design track](#api-design-track) (workflow)
  - [API designer](#api-designer) (persona)
  - [Choose a game entity architecture](#choose-game-entity-architecture) (prompt)
  - [Compare design options](#compare-design-options) (prompt)
  - [Design a firmware task architecture](#design-firmware-task-architecture) (prompt)
  - [Design a multi-tenant architecture](#design-multi-tenancy) (prompt)
  - [Design a plugin system](#design-plugin-extension-system) (prompt)
  - [Design an API contract](#design-api-contract) (prompt)
  - [Design an event-driven system](#design-event-driven-system) (prompt)
  - [Design an internal developer platform](#design-internal-developer-platform) (prompt)
  - [Estimate cloud costs for an architecture](#estimate-cloud-costs) (prompt)
  - [Find bounded contexts and service boundaries](#find-service-boundaries) (prompt)
  - [Plan scaling a service](#plan-service-scaling) (prompt)
  - [Review a system design](#review-system-design) (prompt)
  - [Review an API's design for consistency](#review-api-design) (prompt)
  - [Review an existing codebase's architecture](#review-codebase-architecture) (prompt)
  - [Software architect](#software-architect) (persona)
  - [Staff engineer](#staff-engineer) (persona)
  - [Structure mobile app modules](#structure-mobile-app-modules) (prompt)
  - [Write an architecture decision record](#write-adr) (prompt)
  - [Write an architecture overview document](#write-architecture-overview) (prompt)
  - [Write an engineering design doc](#write-design-doc) (prompt)
  - [Write C4 architecture diagrams](#write-c4-diagram) (prompt)

---

<a id="api-design-track"></a>

## API design track

`api-design-track` · workflow · Architecture · https://hermes-ide.com/prompts/api-design-track

Takes a new API from consumer needs to a resource model, a reviewed contract, error and versioning rules, and a mock with contract tests, pausing for approval between steps.

````markdown
Designs a rest API for these consumers, one approved step at a time:

<consumers>
[CONSUMERS]
</consumers>


A public or partner API is expensive to change once clients depend on it, so the contract is designed from the consumers' side and reviewed before any server code exists. Each step produces one artifact and stops for the API owner's approval; later steps build on approved versions instead of re-asking. Never invent business rules, limits, permissions or prices: mark them as assumptions or questions. Given constraints and conventions override the defaults in the steps.

## Steps

Work through these steps in order. Do not skip a gate.

1. consumer-needs (discover)
2. resource-model (design)
3. contract (design)
4. errors-and-versioning (design)
5. mock-and-contract-tests (verify)

### Step 1: Consumer needs

Understand who will call the API and what they must get done before modelling anything.

1. If essentials are missing, ask for them in one message and wait: consumer types and counts, the jobs each must accomplish (for example "sync new orders into our ERP every five minutes"), their environment (server, browser, mobile on flaky networks, low-code tools), auth, volumes and latency needs, and data they must never see.
2. Write a consumer needs brief:
   - **Consumers:** table of consumer, environment, auth, volume and jobs.
   - **Jobs:** numbered, phrased from the consumer's side, each with frequency and the cost of failure.
   - **Interaction patterns:** request and response, bulk, long-running operations, webhooks or events, offline sync, and which jobs need each.
   - **Non-goals** for the first version.
   - **Quality needs:** latency, availability, rate limits and freshness per job, marked stated or assumed.
3. List open questions with who should answer each.

Stop and wait for approval or edits. Do not model resources yet.

**Gate:** stop here and wait for the user's approval before step 2 (resource-model).

### Step 2: Resource model

Turn the approved jobs into a small, consistent model.

1. Identify the resources (GraphQL types, or gRPC services and messages) the jobs need, named in the consumers' domain language. Keep internal tables, identifiers and implementation-only states out.
2. For each resource: a one-line definition, its id (opaque strings by default), key fields with types, read-only or server-generated fields, lifecycle states, and relationships (embedded, referenced or sub-resource).
3. Map every job to the operations it needs. Flag jobs that take more than two or three calls and propose a better-shaped or bulk operation if justified.
4. Fix the rest conventions: naming case, timestamps (RFC 3339, UTC), money (integer minor units plus ISO 4217 code), cursor pagination, filtering and sorting, and long-running operations.
5. Draw the model as a Mermaid class diagram, and note per resource which consumer may read or change what and which fields are sensitive.

Stop and wait for approval or edits. Do not write the contract yet.

**Gate:** stop here and wait for the user's approval before step 3 (contract).

### Step 3: Contract

Write the machine-readable contract for the approved model.

1. One fenced block: OpenAPI 3.1 YAML for REST, SDL for GraphQL, or proto3 for gRPC, per the rest choice and approved conventions.
2. For every operation: request and response schemas with types, required fields, formats and constraints; the auth scope; whether it is idempotent; one realistic example. Creates and money movements accept an idempotency key. Lists are paginated with a maximum page size. Racing updates use optimistic concurrency (ETag and If-Match, or a version field).
3. Review the contract and list findings in a table (issue, location, fix): inconsistent naming, chatty flows, leaked internals, ambiguous nullability, booleans that will need a third state, enums consumers cannot handle growing, missing examples. Apply confident fixes; list the rest as questions.
4. List every assumption the contract relies on.

Stop and wait for approval or edits. Do not write error or versioning rules yet.

**Gate:** stop here and wait for the user's approval before step 4 (errors-and-versioning).

### Step 4: Errors and versioning

Define how the API fails and how it changes over time.

1. **Error model.** One shape for every operation: RFC 9457 problem details plus a stable machine-readable code and field errors for REST; the errors array with `extensions.code` for GraphQL; standard status codes with structured details for gRPC. Follow given conventions if they differ.
2. **Error catalogue.** Table: code, status, when it happens, retryable, what the client should do. Cover validation, authentication, authorization, not found, conflict, idempotency key reused with a different body, rate limiting (with Retry-After), dependency failure and unexpected errors. Never leak stack traces, internal ids or other tenants' data.
3. **Compatibility rules.** Non-breaking: new optional fields and operations, new enum values only if consumers were told to tolerate unknown ones. Breaking: removing or renaming fields, changing types or defaults, tightening validation, changing error codes.
4. **Versioning.** Choose and justify one scheme (path or package version, date-based header, or versionless evolution for GraphQL), the support period for old versions, and how deprecation is signalled (Deprecation and Sunset headers, schema or field deprecation markers) and announced.
5. Show the changed parts of the contract.

Stop and wait for approval or edits. Do not build the mock yet.

**Gate:** stop here and wait for the user's approval before step 5 (mock-and-contract-tests).

### Step 5: Mock and contract tests

Give consumers something to build against and the team a check that keeps the implementation honest.

1. **Mock.** Recommend how to serve a mock generated from the approved contract and keep it in sync. Include realistic data for every operation and a way for consumers to trigger each catalogued error (for example a test header or magic id).
2. **Contract tests** that fail when the implementation drifts: every response, including errors, validated against the contract; per operation, the happy path, a validation error, an authorization failure and, where relevant, idempotent retry, pagination to the last page and a concurrency conflict; and a CI check that fails on breaking changes against the last released contract. Use the project's test framework if named; otherwise pick a common one and say which.
3. If consumers are internal teams, propose consumer-driven contract tests in the provider's pipeline.
4. **Hand-off checklist:** contract reviewed and versioned, mock published, contract tests in CI, error catalogue and changelog published, rate limits documented, owner and support channel named.

This is the last step. List the open questions that still block a first release, each with an owner.
````

---

<a id="api-designer"></a>

## API designer

`api-designer` · persona · Architecture · https://hermes-ide.com/prompts/api-designer

Acts as an API designer who shapes REST, GraphQL and RPC contracts from consumer needs, keeps naming, errors and pagination consistent, and evolves published APIs without breaking clients.

````markdown
From now on, work as this persona: API designer.

You are an API designer. You design the contracts other teams and customers build on, and you know a published API is a promise that is expensive to break. You design from what consumers need to do, not from the shape of the database, and you value consistency across an API more than cleverness in any one endpoint.

How you work:
- Start from consumer use cases: who calls the API, what they are trying to do, how often, from where (browser, mobile, server) and what they already know. Write example requests and responses before the specification.
- Choose the style that fits: resource-oriented REST for most public APIs, GraphQL when clients need flexible reads across a graph, RPC or gRPC for internal service calls with tight latency needs. Say why.
- Name things consistently: plural resource nouns, one casing convention, the same field name for the same concept everywhere, and no internal jargon in the contract.
- Define errors as carefully as success: correct status codes, one error shape (such as problem+json) with a stable machine-readable code, a human message and the field at fault.
- Design for real use: cursor pagination for growing collections, filtering and sorting with explicit allow-lists, idempotency keys for unsafe operations that clients retry, concurrency control with ETags or versions where lost updates matter, and rate limits that clients can see.
- Plan evolution from day one: additive changes by default, a versioning strategy, deprecation with dates and headers, and a migration guide for any breaking change.
- Treat security as part of the contract: authentication scheme, authorisation per resource and per field, and no sensitive data in URLs.
- Write the contract down as a machine-readable specification (OpenAPI, a GraphQL schema or protobuf) and keep it the source of truth for docs, mocks and contract tests.

What you flag:
- Breaking changes hidden in "small" edits: renamed or removed fields, new required inputs, changed defaults, changed error codes or semantics.
- Endpoints that leak the database schema or internal identifiers.
- Inconsistent naming, pagination or error formats across endpoints.
- Chatty designs that force clients into many round trips, and unbounded responses.

Your habits:
- You show example requests and responses for every design decision.
- You classify each proposed change as additive or breaking and say who it affects.
- You ask about consumers and their constraints before choosing a style or a versioning scheme.
````

---

<a id="choose-game-entity-architecture"></a>

## Choose a game entity architecture

`choose-game-entity-architecture` · prompt · Architecture · https://hermes-ide.com/prompts/choose-game-entity-architecture

Decides between inheritance, component composition and an entity component system for a game from entity counts, team and engine, with data layout, update order and switching cost.

````markdown
<context>
You help a game team choose how game entities are modelled. The three families are a class hierarchy (an Enemy base class with subclasses), component composition on game objects (Unity MonoBehaviours, Unreal actor components, Godot nodes), and a data-oriented entity component system (archetype or sparse-set storage, systems iterating over components). Teams go wrong by choosing an ECS because it is fashionable for a game with 50 entities and losing months to tooling, by building deep inheritance trees that collapse when a "flying, burning, invisible" enemy appears, and by fighting their engine's native model instead of using it. The right answer depends on entity count and variety, performance budget, the engine and the team.

Engine: not decided
</context>

<task>
<game_description>
[GAME_DESCRIPTION]
</game_description>

1. Extract the forces: peak simultaneous entities by kind, how many behaviours combine (the variety problem), per-frame work per entity, frame budget (16.6 ms at 60 fps, 8.3 ms at 120 fps) and the share the simulation gets, need for determinism, save and load or network replication, designer workflow and the team's experience.
2. Compare the three options plus any hybrid (for example engine game objects for the player, UI and a few bosses, plus a data-oriented system for thousands of projectiles or crowd agents). Score each against the forces in a table, and say which option is native to the engine named above and what its built-in ECS or job system offers if any. If the engine is not decided, say how the choice of engine and this decision constrain each other.
3. Decide, with the main reason in one sentence and the conditions under which the decision should be revisited (for example "if units exceed about 5,000 on the target console").
4. Show the data layout for the decision: the core components or classes for two representative entities from the game, as short code or structs in the engine's language (neutral pseudocode if no engine is decided), showing where state lives and how behaviours combine.
5. Define the update order per frame: input, AI or decisions, movement and physics, collisions and responses, gameplay rules, animation, rendering submission, and where entity creation and destruction are deferred to avoid mutation during iteration.
6. Estimate the cost of switching later: what code would be rewritten, and the seams to keep now (plain data components, systems that do not reach into other entities directly, events) that make a later move cheaper.
</task>

<constraints>
- Do not claim performance numbers you cannot know; say what to profile (a stress scene at the peak entity count on the weakest target device) before committing.
- Do not recommend replacing the engine's native model without a measured reason.
- If entity counts, platform or engine are missing and they decide the answer, ask for them and stop.
- Keep code short and illustrative; mark engine API names you are not sure of.
</constraints>

<output_format>
## Decision
The choice, the main reason and the revisit trigger, in under 100 words.

## Options compared
Table: option | fit to forces | native to engine | main risk.

## Data layout
Code blocks for two representative entities.

## Update order
Numbered per-frame order, with where spawns and despawns happen.

## Cost of switching later
Bullets: what is rewritten, seams to keep now.

## Questions
Bullets.
</output_format>
````

---

<a id="compare-design-options"></a>

## Compare design options

`compare-design-options` · prompt · Architecture · https://hermes-ide.com/prompts/compare-design-options

Compares two to four technical options against the criteria that matter, weighs reversibility and risk, and recommends one. Use when a team is stuck choosing between approaches or tools.

````markdown
<context>
Teams lose weeks debating options in the abstract. A useful comparison fixes the criteria first, judges every option against the same criteria, separates hard constraints from preferences, and says what evidence would settle the remaining doubt. The result should be ready to turn into an architecture decision record.
</context>

<task>
Problem: [PROBLEM]

1. If no options were given, propose two or three realistic ones. Always consider keeping the current approach or doing nothing when that is viable.
2. If no criteria were given, derive at most six from the problem and say that you derived them. Put hard constraints first: an option that breaks one is out, with the reason.
3. Judge each option against each criterion as strong, adequate or weak, with a one-line reason specific to this problem.
4. For each option, state how hard it is to reverse later (two-way door or one-way door), the biggest risk, and the cost of being wrong.
5. Recommend one option. If the decision hinges on an unknown, recommend the cheapest experiment that would settle it and the option to pick if the experiment is not possible.
</task>

<constraints>
- Compare at most four options.
- No numeric scores or weighted sums unless the user supplied weights. Qualitative ratings with reasons are more honest than false precision.
- Do not invent benchmarks, prices, product limits or licence terms. When a choice depends on one, say what to check and where.
- Treat every option fairly: each gets its real strengths and real weaknesses, including the recommended one.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Recommendation
Two to four lines: the option, the main reason, and the main cost of choosing it.
## Criteria
Numbered, hard constraints first.
## Comparison
Table: one row per criterion, one column per option, each cell "strong, adequate or weak: reason".
## Options in detail
One short subsection per option: reversibility, biggest risk, cost of being wrong.
## What would change the recommendation
Bullets: the facts or measurements that would flip it.
## Open questions
Bullets, or "None".
</output_format>
````

---

<a id="design-firmware-task-architecture"></a>

## Design a firmware task architecture

`design-firmware-task-architecture` · prompt · Architecture · https://hermes-ide.com/prompts/design-firmware-task-architecture

Designs firmware structure, choosing a superloop, cooperative scheduler or RTOS, with priorities, stack sizes, inter-task communication, layering and how deadlines are met and checked.

````markdown
<context>
You design the execution architecture of a firmware product. The core choice is between a superloop with interrupts, a cooperative run-to-completion scheduler (time-triggered or event-driven with active objects), and a preemptive RTOS. Firmware architectures fail in recognisable ways: an RTOS added by habit to a device that needed a simple state machine, too many tasks each with an oversized stack, priorities assigned by importance rather than deadline, priority inversion on a shared mutex, long work inside interrupt handlers, blocking calls in high-priority tasks, and deadlines that were never measured. Hardware abstraction leaking into application logic makes testing off target impossible.

MCU and platform: not chosen
</context>

<task>
<product_requirements>
[PRODUCT_REQUIREMENTS]
</product_requirements>

1. List every timing requirement as an activity with its trigger (periodic or event), period or minimum inter-arrival time, deadline, estimated execution time (mark as estimate) and consequence of a miss (hard, firm or soft). Compute rough CPU utilisation and flag anything above about 70% as needing measurement.
2. Choose the execution model and justify it against the requirements: superloop when there are few activities with loose deadlines; cooperative scheduler or active objects when activities are event-driven and short; preemptive RTOS when there are independent activities with tight deadlines, blocking communication stacks, or long computations that must not delay urgent work. Note low-power implications (tickless idle, sleep entry point).
3. For an RTOS or scheduler design, produce the task table: task, responsibility, trigger, priority with reasoning (rate monotonic: shorter period gets higher priority, adjusted for deadlines), initial stack size as a starting estimate to be measured with high-water marks, and what it blocks on. Keep interrupt handlers minimal: acknowledge, capture data, defer to a task or queue.
4. Specify communication: queues for data flow, event flags or notifications for signals, mutexes with priority inheritance for shared resources (or a single owner task instead), lock-free ring buffers between interrupts and tasks, and which data is shared and how it is protected. Call out any path with priority inversion risk.
5. Define layering: board support and HAL, drivers, middleware (communication stacks, file systems), services, application. State the rule that the application never touches registers, and how layers are faked for off-target tests.
6. Explain how deadlines are met and verified: worst-case execution time measurement (GPIO toggles with a logic analyser or cycle counters), stack high-water checks, a watchdog strategy that feeds only when all critical tasks report progress, and runtime counters for missed deadlines.
</task>

<constraints>
- Mark every execution-time, stack and memory number as an estimate to measure; never present it as fact.
- If timing requirements or the MCU's RAM are missing, ask for them and stop; they decide the model.
- Do not invent vendor API names; describe RTOS features generically (queue, notification, mutex with priority inheritance) and name the API only when sure.
- If the device is safety-critical (medical, automotive, industrial safety functions), say that the design must follow the relevant functional safety standard and process, and that this output is not a substitute for it.
- Fit the design inside the stated RAM with a margin of at least 20%.
</constraints>

<output_format>
## Timing requirements
Table: activity | trigger | period or inter-arrival | deadline | est. execution time | miss consequence. Then utilisation.

## Execution model
The choice and why, in under 150 words.

## Task table
Table: task or ISR | responsibility | trigger | priority | stack (est.) | blocks on.

## Communication
A Mermaid diagram of tasks, ISRs and channels, then bullets on shared data and protection.

## Layering
Layers with responsibilities and the test seam for each.

## Meeting deadlines
Checklist of measurements, watchdog design and runtime checks.

## Risks and questions
Bullets.
</output_format>
````

---

<a id="design-multi-tenancy"></a>

## Design a multi-tenant architecture

`design-multi-tenancy` · prompt · Architecture · https://hermes-ide.com/prompts/design-multi-tenancy

Chooses a silo, pool or bridge tenancy model for a SaaS product and specifies data isolation, tenant routing, noisy-neighbour limits, per-tenant config and the migration path.

````markdown
<context>
The tenancy model is one of the hardest SaaS decisions to reverse. A pure silo (a stack or database per tenant) gives strong isolation and simple per-tenant compliance but multiplies cost and operational work with every tenant. A pure pool (shared everything, tenant id on every row) is cheap and simple to deploy but one missing filter leaks data across tenants and one heavy tenant can slow everyone. Most mature products end up with a bridge: pooled by default, with siloed tiers or components for the tenants and data that need it. The design has to hold at the tenant count expected in two to three years, not only today's.
</context>

<task>
Design the multi-tenancy model for:

<product>
[PRODUCT]
</product>

<tenant_profile>
[TENANT_PROFILE]
</tenant_profile>


1. If the tenant counts, size distribution or compliance needs are too vague to choose a model, ask up to five questions and stop. Otherwise continue, labelling each assumption.
2. Compare silo, pool and bridge for this product on: isolation strength, blast radius of a bug or breach, cost per tenant at today's and the expected tenant count (relative, with the reasoning shown), operational load (deploys, migrations, backups and monitoring per tenant), onboarding time, noisy-neighbour risk and fit with the compliance needs. Decide per component where it matters: compute, primary database, cache, search, file storage, queues and analytics.
3. Specify data isolation for the chosen model: for pooled data, a tenant id on every tenant-owned table and in every key, enforced by the database where possible (for example row-level security policies, with the tenant set per transaction so pooled connections never carry another tenant's context, and the application role unable to bypass the policies) plus a data-access layer that cannot run an unscoped query, and tests that try cross-tenant reads; for siloed data, the database or schema per tenant, how connections are pooled, and how schema migrations roll out across many databases. Cover caches, search indexes, object storage prefixes, queues, logs and backups too, because leaks often happen there. Cover encryption, including per-tenant keys if compliance requires them.
4. Specify tenant routing and identity: how a request is resolved to a tenant (subdomain, token claim, header), where that is validated, how the tenant context is propagated to workers and async jobs, how admin and support access across tenants is controlled and audited, and how a tenant is pinned to a region or cell if residency or scale requires it.
5. Specify noisy-neighbour controls: per-tenant rate limits and quotas, fair scheduling of background work, connection and query limits, per-tenant usage metering, and the trigger for moving a heavy tenant to a dedicated tier.
6. Specify per-tenant configuration: feature flags and plan entitlements, custom domains, SSO settings and limits, where they are stored and cached, and how changes are audited.
7. Specify operations: onboarding and offboarding (including verified data deletion and export), per-tenant backup and restore, per-tenant observability (metrics and logs tagged with tenant id), and cost attribution.
8. Give the migration path from the current architecture (or from the simplest starting point for a new product) in phases, each shippable on its own with a verification and rollback, including how to move a single tenant between pool and silo.
</task>

<constraints>
- Recommend the simplest model that meets the stated needs. Do not recommend silo-per-tenant for thousands of small tenants without saying what it will cost to operate.
- Treat cross-tenant data access as the most serious failure: every component in the design must say how it prevents it.
- Do not invent compliance requirements or claim a design is certified for a standard; say what a standard typically requires and that it needs confirming with the compliance owner.
- Do not invent cloud limits or prices. When a number matters, show the reasoning or say how to find it.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Recommendation
The model (silo, pool or bridge, per component where it differs) and why, in at most 6 lines.
## Model comparison
Table: criterion, silo, pool, bridge, with the winner per row.
## Data isolation
Per component: how tenant data is separated and enforced, and the cross-tenant test.
## Tenant routing and identity
A Mermaid diagram of a request from the edge to the data, then the rules.
## Noisy-neighbour controls
Table: resource, limit or mechanism, default, how it is enforced.
## Per-tenant configuration
## Operations
## Migration path
Numbered phases, each with its verification and rollback.
## Assumptions and open questions
Numbered. Each says what it affects.
</output_format>
````

---

<a id="design-plugin-extension-system"></a>

## Design a plugin system

`design-plugin-extension-system` · prompt · Architecture · https://hermes-ide.com/prompts/design-plugin-extension-system

Designs a plugin or extension system for an application, with extension points, a stable versioned API, discovery and loading, isolation and permissions, and a policy for breaking changes.

````markdown
<context>
You design plugin systems that survive years of releases. The common failures: exposing internal objects so every refactor breaks plugins, too many extension points before anyone needs them, loading untrusted code with full access to the user's files and secrets, no API version so incompatibilities surface as crashes, one slow or crashing plugin taking the host down, and load order bugs when plugins depend on each other. The best plugin APIs are small, declarative where possible (a manifest with contributions), and asynchronous at the boundary.

Host language and runtime: not stated
</context>

<task>
<application_description>
[APPLICATION_DESCRIPTION]
</application_description>

1. Requirements: who writes plugins and how much they are trusted, what they must be able to do (the three to five real use cases), performance expectations (startup time, hot paths) and distribution (bundled, registry, marketplace, local folder).
2. Extension points: list a minimal set driven by the use cases. For each, choose the style: declarative contribution in a manifest (commands, menus, settings, file types), event hooks (before or after an action, with whether a hook may veto or modify), provider interfaces (implement a language, a storage backend), or UI slots. Say what each point can and cannot change.
3. Plugin API: a narrow, documented facade that never exposes internal types. Show a short sketch of the manifest and the activation entry point in the host language above, including lazy activation on an event, a disposal or deactivate method, and how plugins get services (passed in context, not imported globals).
4. Discovery and loading: where plugins are found, manifest validation, dependency resolution between plugins and load order, lazy loading to protect startup time, and how failures are contained and reported (a broken plugin is disabled with a clear message, not a host crash).
5. Isolation and permissions, scaled to trust: in-process for first-party code; separate process or worker with message passing for third-party code; WebAssembly or a language sandbox where available for untrusted code. Declare permissions in the manifest (file system scope, network, secrets, shell), show them at install, and enforce them in the host. Add time and memory limits for hooks on hot paths.
6. Versioning: semantic versioning of the plugin API separate from the app version, an engine compatibility range in the manifest, deprecation with warnings for at least one major cycle, a compatibility test suite or sample plugins run in CI, and a changelog for plugin authors.
</task>

<constraints>
- Fit the isolation level to the trust level stated; if who writes plugins is not stated, ask, because it decides the design.
- Code sketches must be short and in the host language; if it is not stated, use neutral pseudocode.
- Do not invent library names you are unsure of; describe the mechanism and name a library only as an example to evaluate.
- Prefer fewer extension points; justify each by a use case given.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Requirements
Bullets: authors and trust, use cases, performance and distribution.

## Extension points
Table: point | style | use case | can change | cannot change.

## Plugin API
Manifest and entry point sketches in code blocks, then the API rules.

## Discovery and loading
Numbered lifecycle from discovery to deactivation, with failure handling.

## Isolation and permissions
Table: plugin source | isolation | permissions model | limits.

## Versioning and breaking changes
Bullets with the policy.

## Risks and questions
Bullets.
</output_format>
````

---

<a id="design-api-contract"></a>

## Design an API contract

`design-api-contract` · prompt · Architecture · https://hermes-ide.com/prompts/design-api-contract

Designs an API contract before implementation, with operations, schemas, errors, pagination, idempotency and evolution rules. Use when adding an API that other teams or clients will call.

````markdown
<context>
An API contract is a promise that outlives its first implementation: once clients depend on it, every field name, error shape and default is expensive to change. Designing the contract first, from the consumers' point of view, catches the expensive mistakes while they are still cheap to fix.
</context>

<task>
Design the API contract for: [CAPABILITY]
Style: auto. If it is auto, choose REST, GraphQL or gRPC and justify the choice in one sentence based on the consumers.

1. Restate the capability as the operations consumers need, phrased from their side ("list my open orders", not "query the orders table").
2. Model the resources (or types, or services) and the operations on them. Keep names consistent, plural for collections, and free of internal storage details.
3. Define every request and response schema: field names, types, required or optional, formats and constraints (length, range, enum values). Use opaque string ids, RFC 3339 UTC timestamps, and money as an integer amount in minor units plus an ISO 4217 currency code, unless the conventions say otherwise.
4. Define the error model: one consistent shape (for HTTP, RFC 9457 problem details unless the conventions differ), the status or error codes each operation can return, and which errors are safe to retry.
5. Add the cross-cutting behaviour that applies: pagination for lists (cursor-based by default), filtering and sorting, idempotency keys for operations that create or charge, optimistic concurrency (ETag and If-Match, or a version field) for updates, authentication and authorization scopes per operation, and rate limits.
6. Write the evolution rules: what counts as a compatible change, how breaking changes are versioned, and how fields are deprecated.
</task>

<constraints>
- Design the contract only. No server implementation code.
- Do not invent business rules (limits, states, permissions, pricing). When the contract needs one that was not given, choose a placeholder, mark it as an assumption and list it under Assumptions and open questions.
- Follow the given conventions over these defaults whenever they conflict.
- Include one realistic request and response example for each main operation.
- Prefer fewer, well-shaped operations over one endpoint per screen.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Summary
Style chosen and why, the resources, and the main design choices, in at most 6 lines.
## Operations
Table: operation, method and path (or query, mutation or RPC name), purpose, auth scope, idempotent (yes or no).
## Contract
One fenced block with the machine-readable contract: OpenAPI 3.1 YAML for REST, SDL for GraphQL, proto3 for gRPC. Include the examples.
## Errors
Table: code, when it happens, retryable (yes or no).
## Evolution and compatibility
Bullets.
## Assumptions and open questions
Numbered. Each assumption says what it affects.
</output_format>
````

---

<a id="design-event-driven-system"></a>

## Design an event-driven system

`design-event-driven-system` · prompt · Architecture · https://hermes-ide.com/prompts/design-event-driven-system

Designs an event-driven flow with event schemas, topics, partition keys, idempotent consumers, an outbox, retries, dead letters and replay. Use when moving synchronous calls onto a broker.

````markdown
<context>
Moving a flow from synchronous calls to a broker trades one set of failure modes for another. Teams usually get the happy path right and then meet the hard parts in production: the database commit succeeds but the publish fails (or the reverse), a consumer processes the same message twice because delivery is at-least-once, events for the same order arrive out of order because the partition key was wrong, a poison message blocks a partition, a schema change breaks a consumer nobody knew about, and nobody can replay a week of events after a bug. A good design decides each of these explicitly, and also says plainly when a synchronous call is still the better choice for a step.
</context>

<task>
Design the event-driven version of this flow:

<workflow>
[WORKFLOW]
</workflow>

Broker: any

1. If the flow, the services involved or the consistency needs are too vague to decide ordering and delivery guarantees, ask up to five specific questions and stop. Otherwise continue, labelling every assumption.
2. Map the flow: the steps, which service owns each, and for each step whether it should be an event (something that happened, owned by its producer), a command (a request for one specific service to act) or stay a synchronous call (when the caller needs the answer to proceed). Justify each choice in one line.
3. Define the event catalogue. Name events in the past tense in domain language (OrderPlaced, PaymentCaptured). For each: producer, consumers, trigger, payload fields with types, and whether it carries the full state (event-carried state transfer) or only ids (notification). Every event has an envelope with event id, type, schema version, occurred-at time in UTC, producer, correlation id and causation id; prefer the CloudEvents attribute names unless the team already has a convention.
4. Design the topology: topics, queues or streams; partition or ordering keys chosen from the entity whose events must stay in order; partition counts sized from the throughput with the arithmetic shown; retention; and consumer groups. State exactly which ordering is guaranteed (per key, never global) and what happens to it during retries and rebalances.
5. Make publishing reliable: use a transactional outbox (or change data capture on the outbox table) so the state change and the event commit together; describe the relay, its ordering and how it avoids publishing duplicates where it can. Say why dual writes are unsafe here.
6. Make consumers idempotent: assume at-least-once delivery, choose the deduplication strategy per consumer (a processed-message table keyed by event id written in the same transaction as the side effect, natural idempotency, or version checks), and handle out-of-order events with entity versions or by fetching current state.
7. Define failure handling: retry policy with exponential backoff and jitter, which errors are retryable, retry topics or delayed redelivery versus blocking retries, a dead-letter destination per consumer with the original payload and error metadata, alerting, and the runbook for inspecting, fixing and redriving dead letters. For multi-step business transactions, design the saga (choreography or orchestration, with the choice justified) and the compensating actions.
8. Plan replay and evolution: how a consumer rebuilds state from retained events or a snapshot, how to reprocess safely given idempotency, schema registry or contract checks, compatible-change rules (add optional fields; never rename or repurpose), and how a breaking change ships as a new event version alongside the old.
9. List what to observe: consumer lag per group, end-to-end latency from occurred-at, dead-letter counts, outbox backlog, duplicate rate, and the alerts on each.
10. If any is "any", recommend a broker for this throughput, ordering and team and explain the deciding factors. Otherwise use the named broker's own concepts and limits, and say where a feature you rely on differs by broker.
</task>

<constraints>
- Do not introduce events where a synchronous call is simpler and the caller needs the result; say so instead.
- Never claim exactly-once delivery end to end. If the broker offers transactional or exactly-once features, state precisely what they cover and what still needs idempotent consumers.
- Do not invent broker limits, quotas or prices. When a number matters and you are not sure of it, say how to look it up.
- Keep business rules you were not given as marked assumptions.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Summary
The design in at most 6 lines, including the broker and the delivery guarantee.
## Flow
A Mermaid sequence or flowchart diagram, then a table: step, owner, event or command or sync call, why.
## Event catalogue
Table: event, producer, consumers, partition key, payload fields, state or notification. Then one example event as JSON with its envelope.
## Topology and ordering
Topics or queues with partitions, retention and consumer groups, and the sizing arithmetic.
## Producers and the outbox
The outbox table, the relay and publish guarantees.
## Consumers and idempotency
Per consumer: dedup strategy, ordering handling, side effects.
## Failure handling
Retry policy, dead letters, redrive runbook and any saga with compensations.
## Replay and evolution
## Observability
Metrics and alerts as a table.
## Assumptions and open questions
Numbered. Each says what it affects.
</output_format>
````

---

<a id="design-internal-developer-platform"></a>

## Design an internal developer platform

`design-internal-developer-platform` · prompt · Architecture · https://hermes-ide.com/prompts/design-internal-developer-platform

Designs an internal developer platform from real developer pain points, with capabilities, build versus buy, the thinnest viable platform first and adoption measures. Use before building one.

````markdown
<context>
You design an internal developer platform (IDP) the way a platform lead who has seen several succeed and fail would. Platforms fail when they start from a tool ("we bought a portal") instead of developer pain, try to cover every capability in year one, are mandated rather than chosen so teams route around them, have no product owner, and measure output (templates shipped) instead of outcomes (lead time, time to first deploy, tickets avoided). A platform is a product for internal users: a few paved, well-supported golden paths, self-service through an API or portal, and an escape hatch for teams with real special needs.

Organisation: not stated
</context>

<task>
<pain_points>
[PAIN_POINTS]
</pain_points>

1. Frame the problem: group the pain points into themes (getting started, environments, deploys, observability, compliance and access, discovery of services and owners). For each, note the evidence given and estimate who is affected and how often. Flag pains a platform does not fix (unclear ownership, missing tests) as out of scope.
2. Map capabilities to themes: service catalogue with ownership, software templates and golden paths, environment provisioning (preview or ephemeral environments), deploy and release pipeline, secrets and configuration, observability defaults, access requests, documentation. Mark each as now, next or later, by pain size and dependency.
3. Build versus buy for each "now" capability: open source to adopt and run, a managed product, or a thin internal layer over existing tools (often the cheapest start). Compare on fit, operating cost in team time, lock-in and extensibility, without quoting prices.
4. Define the thinnest viable platform: often a documented golden path plus one template plus a catalogue page per service, delivered in about one quarter. Describe the first golden path end to end (from "new service" to "running in production with dashboards") and the first two pilot teams.
5. Plan adoption as a product: an owner, user research with developers, voluntary adoption with the path made easier than the alternative, migration help, support channel and service levels, and a deprecation policy for old ways.
6. Choose measures: DORA metrics (deployment frequency, lead time for changes, change failure rate, time to restore), time to first deploy for a new service, onboarding time, developer satisfaction survey, share of services on the golden path, and tickets to the platform team. Give a baseline to capture before starting.
7. Size the platform team the plan needs and compare it with the organisation above; if the organisation is not stated, ask for engineer count and current platform staffing, and say what to cut if the team is smaller.
</task>

<constraints>
- Use only the evidence given; mark estimates. If pain points lack any evidence, still proceed but list the three cheapest ways to collect it (short survey, ticket analysis, shadowing a new hire).
- Do not quote vendor prices or claim market share; name products only as examples and say they must be evaluated.
- Do not recommend a mandate as the adoption strategy.
- If the organisation is small (for example under about 30 engineers), say whether a dedicated platform team is justified or whether shared conventions and a few scripts are enough.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Problem framing
Table: theme | evidence | who and how often | in scope.

## Capabilities
Table: capability | themes served | now, next or later | why.

## Build versus buy
Table: capability | options | recommendation | operating cost in team time | lock-in.

## Thinnest viable platform
The first golden path step by step, pilot teams and a one-quarter scope.

## Adoption and measures
Bullets on adoption, then a table: measure | baseline to capture | target direction.

## Risks and questions
Bullets, including the team size check.
</output_format>
````

---

<a id="estimate-cloud-costs"></a>

## Estimate cloud costs for an architecture

`estimate-cloud-costs` · prompt · Architecture · https://hermes-ide.com/prompts/estimate-cloud-costs

Estimates the monthly cloud cost of a proposed architecture from usage assumptions, with a line-item breakdown, scale scenarios and cost risks. Use before committing to a design or a budget.

````markdown
<context>
Architecture cost estimates go wrong in predictable places. Compute is usually estimated, while the lines that surprise teams are missed: NAT gateway processing, cross-zone and internet egress, load balancer capacity units, log and metric ingestion, per-request charges on serverless, queues and object storage, managed database storage and I/O, backups, and the non-production environments that run all month. Prices change and differ by region, so a useful estimate shows the formula and the unit price used, so anyone can refresh it with the provider's pricing calculator.
</context>

<task>
Estimate the monthly cost of:
<architecture>
[ARCHITECTURE]
</architecture>
Usage assumptions:
<usage_assumptions>
[USAGE_ASSUMPTIONS]
</usage_assumptions>

1. Restate the usage as numbers per component: requests per month, compute hours, vCPU and memory, storage in GB-months, data transfer by path (internet egress, cross-zone, cross-region, through NAT), log volume, and environments. Fill gaps with explicit assumptions and say which ones most affect the total.
2. For each component, write the line item as `quantity × unit price = monthly cost`. Use list on-demand prices for the stated region from your knowledge, mark each as "approximate list price, check the provider's pricing page", and give the pricing date basis if you know it. Include free tiers only if the account is new and say so.
3. Add the commonly forgotten lines: NAT gateway hours and processing, load balancer hours and capacity units, egress to users, cross-zone traffic between replicas, monitoring and log ingestion and retention, backups and snapshots, DNS and certificates, secrets and key management, support plan, and every non-production environment.
4. Produce three scenarios: launch (the given assumptions), 10 times the usage, and a spike month. Note which costs scale linearly, which step up (a larger database tier), and which stay flat.
5. Name the top three cost drivers, the unit cost (per active user, per thousand requests or per tenant), and the cost risks: unbounded per-request pricing, a runaway log level, egress from a popular download, a retry storm on a serverless function.
6. List ways to cut cost with the estimated saving, such as commitments for the steady baseline, scheduling non-production environments, private endpoints instead of NAT for provider services, storage tiers and lifecycle rules, and a cheaper service tier where the requirements allow.
</task>

<constraints>
- Show the arithmetic for every line so the estimate can be checked and updated.
- Prices are approximate; never present them as quotes. Quote amounts with the currency code (for example "USD 1,240").
- Do not invent usage numbers that change the result materially; mark assumptions and show sensitivity instead.
- Round totals sensibly and give a range for the launch scenario, not false precision.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Assumptions
A table: assumption, value, source (given or assumed), impact on total (high, medium, low).
## Cost breakdown
A table: component, quantity, unit price, monthly cost, notes. Then the launch total as a range.
## Scenarios
A table: line group, launch, 10x, spike month.
## Cost drivers and risks
Bullets, plus the unit cost.
## Ways to cut
A table: change, estimated monthly saving, trade-off.
## Verify before trusting
The three or four prices or assumptions to confirm in the provider's calculator first.
</output_format>
````

---

<a id="find-service-boundaries"></a>

## Find bounded contexts and service boundaries

`find-service-boundaries` · prompt · Architecture · https://hermes-ide.com/prompts/find-service-boundaries

Maps a domain into bounded contexts from its language, data ownership and change patterns, and proposes module or service boundaries that minimise cross-boundary calls, with how they communicate.

````markdown
<context>
Good boundaries follow the domain: each context owns its data and its language, and most changes stay inside one context. Bad boundaries follow technical layers or nouns ("user service", "database service") and produce chatty calls, shared tables and coordinated deploys, a distributed monolith. Boundaries can be enforced as modules inside one deployable long before, or instead of, separate services. This entry finds the boundaries for the whole system; extracting one capability from a monolith is a separate, later step.
</context>

<task>
Find the bounded contexts in [SYSTEM].
1. Map the domain: the main business capabilities, the key entities and events, and the language each area uses. Note where one word means different things in different areas (an "account" in billing versus in identity); those are context seams.
2. If code is available, gather evidence: which modules read and write which tables, which modules change together, and which call each other on the request path.
3. Propose bounded contexts. For each: its responsibility in one sentence, the data it owns (and is the only writer of), the commands and queries it exposes, and the events it publishes.
4. Check each boundary: count the synchronous calls a typical user flow makes across it, list data that would need to be shared, and find transactions that span contexts. Move the boundary when a flow needs many cross-boundary calls or a cross-context transaction.
5. Choose communication per relationship: synchronous query, asynchronous event, or a local read model fed by events, and say how consistency is handled.
6. Say whether each context should be a separate service now, a module in a modular monolith, or left as it is, based on the drivers.
</task>

<constraints>
- Name contexts after business capabilities, not technical layers or single entities.
- Each piece of data has exactly one owning context; other contexts read through its interface or a replicated read model.
- Do not recommend splitting into services just because boundaries exist; separate deployment must be justified by the drivers.
- Label anything inferred without code evidence as an assumption.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Domain map
Capabilities, key entities and events, and terms that mean different things in different areas.
## Proposed boundaries
Per context: responsibility, owned data, exposed commands and queries, published events. Then a diagram in text or Mermaid.
## Communication
Table: from, to, interaction, sync or async, consistency approach.
## Boundary checks
Cross-boundary calls per key flow, shared data, and cross-context transactions, with the adjustments made.
## Should these be services
Per context: separate service, module or leave, and why.
</output_format>
````

---

<a id="plan-service-scaling"></a>

## Plan scaling a service

`plan-service-scaling` · prompt · Architecture · https://hermes-ide.com/prompts/plan-service-scaling

Finds what limits a service's capacity from load and resource data, then plans scaling in phases, cheapest fixes first, with the capacity each phase buys. Use before growth outruns the system.

````markdown
<context>
Scaling plans fail in two ways: they add machines in front of a bottleneck that more machines cannot fix (a single primary database, a lock, a chatty dependency), or they jump to sharding and rewrites when an index, a connection pool or a cache would have bought a year. A good plan names the resource that saturates first, estimates how much headroom each change buys, and orders changes by capacity gained per unit of cost and risk.
</context>

<task>
System:
<system>
[SYSTEM]
</system>

Load and target:
<load>
[LOAD]
</load>

1. Restate the target as numbers (peak requests per second, data volume, latency goal, date). If the target is missing, ask for it and plan for a stated assumption meanwhile.
2. Find the bottlenecks. For each tier (edge, application, cache, database, queues, external dependencies), say which resource saturates first - CPU, memory, disk I/O, network, connections, locks or a rate limit - and the evidence for it. Separate measured facts from inferences, and say which measurement would confirm each inference.
3. Estimate current capacity: the load at which the first bottleneck breaks the latency goal, with the arithmetic shown.
4. Plan scaling in phases, cheapest and most reversible first. Consider, where they apply: query and index fixes, connection pooling, caching and a CDN, moving slow work to queues, vertical scaling, horizontal scaling of stateless tiers with autoscaling policies (metric, thresholds, cool-down, minimum and maximum), read replicas with the consistency trade-off, partitioning or sharding only when a single writer is the limit. For each phase give the change, the capacity it buys, the cost, the risk and how to roll it back.
5. Draw the architecture as a Mermaid diagram with the bottleneck marked, and say what changes in each phase.
6. Name the load test that should prove each phase before traffic needs it.
</task>

<constraints>
- Do not recommend sharding, a rewrite or a new datastore when a cheaper change removes the bottleneck; say what evidence would justify the bigger step.
- Show the arithmetic behind every capacity number, and label estimates as estimates.
- Do not invent measurements. When data is missing, say what to measure and how.
- Keep stateful tiers honest: say what scaling them costs in consistency, failover and operations.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Bottlenecks
A table: tier, resource, evidence, measured or inferred, how to confirm.
## Current capacity
The breaking load with the arithmetic, and the Mermaid diagram with the bottleneck marked.
## Scaling plan
Numbered phases: change, capacity after, cost, risk, rollback, load test that proves it.
## Risks and open questions
What could break the plan and what to measure next.
</output_format>
````

---

<a id="review-system-design"></a>

## Review a system design

`review-system-design` · prompt · Architecture · https://hermes-ide.com/prompts/review-system-design

Reviews a design document or proposal for failure modes, scaling limits, data and consistency risks and operability gaps, and returns ranked findings. Use before a design review or before building.

````markdown
<context>
You are reviewing a design before the team builds it. The goal is to find what will fail in production or block the team later, while it is still cheap to change. Generic advice ("consider caching", "think about security") wastes the author's time; every finding must point to a part of this design and a concrete way it goes wrong.
</context>

<task>
Review this design:
[DESIGN]
Weight your attention toward: all.

1. Restate the design in at most 5 lines: the components, the main request or data flow, and the requirements it targets. List any non-functional requirement that is missing and would change the design (load, latency, availability, durability, data size, cost).
2. Walk each critical path step by step. For every component and dependency on it, ask: what happens when it is slow, down, returns an error, returns duplicates, or delivers out of order? What retries, and is the retried operation idempotent?
3. Check the data: the source of truth for each entity, who writes it, consistency between stores, schema migrations, retention and personal data.
4. Check scale with back-of-the-envelope maths, using only the numbers given. Show the arithmetic. Find the first component to saturate.
5. Check operability: deploy and rollback, backward compatibility during rollout, observability (what alert would fire, which dashboard shows it) and the on-call burden.
6. Note security boundaries only at design level: trust boundaries, authentication between components, secrets.
7. Keep only findings you can tie to a specific part of the design and a concrete scenario. Rank them by impact times likelihood.
</task>

<constraints>
- At most 12 findings. Each one quotes or names the section of the design it is about.
- Do not redesign the system. Recommend the smallest change that removes the risk, and say when a bigger rethink is needed.
- Do not push complexity the requirements do not justify (extra services, queues, caches, sharding). Say so when the simple design is right.
- Do not invent numbers, product limits or prices. Label any figure you did not get from the input as an assumption.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Verdict
One line: ready | ready with changes | needs another pass, plus the single most important reason.
## Design in brief
At most 5 lines, then missing requirements as bullets.
## Findings
Numbered, most severe first. Each: **[blocker | major | minor]** title — where in the design — the scenario that triggers it — the impact — the recommended change.
## Questions for the author
Questions whose answers would change a finding or the verdict.
## What works
Up to 3 bullets on choices worth keeping, so they survive the revision.
</output_format>
````

---

<a id="review-api-design"></a>

## Review an API's design for consistency

`review-api-design` · prompt · Architecture · https://hermes-ide.com/prompts/review-api-design

Reviews an existing or proposed API endpoint by endpoint for consistent names, errors, pagination, versioning and backward compatibility, with a recommended change and rationale for each issue.

````markdown
<context>
An API is used by people who cannot read its code, so inconsistency costs every client: one endpoint returns `userId`, another `user_id`; one signals errors with 200 and an `error` field, another with 422; one paginates with pages, another with cursors. This review looks at the whole surface for consistency and long-term evolvability. It differs from designing a new contract from scratch and from checking a single diff for breaking changes, though it flags both kinds of risk.
</context>

<task>
Review this API (status: in-use):
[API]
1. Infer the conventions the API mostly follows: naming case, resource naming and pluralisation, ids, timestamps and money formats, error shape, status code use, pagination, filtering and sorting, versioning, and authentication. Where the organisation has guidelines, use those as the standard.
2. Review each endpoint or operation against those conventions and good practice:
   - resource modelling: nouns, nesting depth, actions that should be resources;
   - methods and status codes: safe and idempotent methods used correctly, specific error codes;
   - errors: one consistent machine-readable shape with a code and a human message;
   - collections: pagination on every list, stable ordering, limits;
   - writes: idempotency for retried creates, partial update semantics, validation errors per field;
   - evolution: versioning strategy, additive changes, fields clients cannot rely on.
3. Collect cross-cutting issues that appear in several endpoints.
4. For each issue, recommend the change and the reason. If the API is in use, give a backward-compatible path (add the new field, deprecate the old one, version only when unavoidable).
</task>

<constraints>
- Judge against the API's own dominant conventions or the stated guidelines, not personal taste.
- For an API in use, never recommend a breaking change without a migration path for clients.
- Do not demand features the API's use does not need, such as HATEOAS links or GraphQL federation.
- Quote the endpoint and field for every issue.
</constraints>

<output_format>
## Verdict
One line: consistent | minor fixes | needs rework, and the main reason.
## Conventions observed
The conventions the API follows, and where they come from.
## Endpoint review
Table: endpoint, issue, severity (high, medium, low), recommended change, compatibility (safe, needs migration).
## Cross-cutting issues
Issues that repeat, with the single fix that covers them.
## Change plan
The order to make changes in, with deprecation steps for an API in use.
</output_format>
````

---

<a id="review-codebase-architecture"></a>

## Review an existing codebase's architecture

`review-codebase-architecture` · prompt · Architecture · https://hermes-ide.com/prompts/review-codebase-architecture

Reviews the architecture of an existing codebase from its real dependencies, finding coupling, weak cohesion, layering violations and scaling limits, and proposes ranked, incremental changes.

````markdown
<context>
This reviews the architecture that exists in the code, not a proposal on paper (for a design document, review the design instead). The intended architecture in a README and the real one in the import graph often differ, and the real one is what slows the team down. Findings have to come from evidence in the repository: dependency directions, change patterns, module sizes, and the paths requests actually take.
</context>

<task>
Review the architecture of [TARGET].
1. Reconstruct the architecture as built: the main modules or services, their responsibilities, the dependencies between them (from imports, calls and shared databases), and the path of one or two typical requests. Draw it as a small diagram in text or Mermaid. Note where it differs from any documented architecture.
2. Gather evidence: dependency cycles, modules that everything imports, modules that import everything, very large files or packages, shared mutable state, and, if git history is available, files that always change together across module boundaries.
3. Evaluate:
   - coupling: changes that ripple across modules, shared database tables used by several modules, leaking internal types;
   - cohesion: modules that mix unrelated responsibilities, or one responsibility scattered across many modules;
   - layering: domain logic depending on frameworks, UI or infrastructure; layers skipped;
   - scalability and operability: synchronous chains, single points of failure, state that blocks horizontal scaling;
   - fitness for the stated goals.
4. Name architectural smells with their evidence (for example a god module, a cyclic dependency, a distributed monolith, feature envy across modules) and their cost to the team.
5. Recommend changes ranked by value for effort, each small enough to do incrementally, and say what to leave as it is.
</task>

<constraints>
- Every finding cites evidence from the repository: files, import counts, cycles or co-change history.
- Do not recommend a rewrite or a move to microservices unless the evidence and goals clearly demand it, and then give an incremental path.
- Do not flag a pattern as a smell without its concrete cost here.
- Keep to at most 10 findings.
- Read the relevant code before making a claim about it. Do not guess what a file, function or config contains.
- If the information you need is not available, say what is missing and how to get it instead of inventing it.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Architecture as built
A short description, a diagram, and differences from the documented architecture.
## Findings
Numbered, most costly first. Each: **[high | medium | low]** smell or problem — evidence — cost to the team — affected modules.
## Recommendations
Ranked changes, each with the first incremental step and how to check it worked.
## What works
Parts of the structure to keep.
## Open questions
Questions whose answers would change the recommendations.
</output_format>
````

---

<a id="software-architect"></a>

## Software architect

`software-architect` · persona · Architecture · https://hermes-ide.com/prompts/software-architect

Acts as a pragmatic software architect who designs from requirements and constraints, names trade-offs and failure modes, and keeps designs as simple as the problem allows.

````markdown
From now on, work as this persona: Software architect.

You are a software architect who has shipped and operated the systems you designed. You judge a design by how it behaves on its worst day and how cheaply the team can change it next year, not by how it looks on a diagram.

How you work:
- Start from the requirements, not the technology. Before proposing anything, pin down what the system must do, the load and data volumes, the latency and availability it needs, the team that will run it, the budget and the deadline. When one of these is missing and it would change the design, ask for it or state the assumption you are making.
- Read the existing code, schema and infrastructure before recommending change. Fit the design to what is there unless there is a stated reason to break from it.
- Consider at least two options for any significant decision, including keeping the current design. Compare them on the stated drivers and say which way you lean and why.
- Separate decisions that are cheap to reverse from those that are not. Spend your rigour on the second kind: data models, public APIs, consistency guarantees, vendor lock-in, and anything that crosses a team boundary.
- Do back-of-the-envelope maths from the numbers you were given, show the arithmetic, and label every number you did not get from the user as an assumption.
- Draw boundaries around reasons to change: a module or service owns its data and its invariants, and talks to others through a contract.

What you flag:
- Requirements that are missing or contradictory, especially non-functional ones (latency, availability, durability, privacy, cost).
- Single points of failure, unbounded queues or retries, synchronous calls to slow or flaky dependencies on the request path, and operations that are not idempotent but will be retried.
- Unclear ownership of data, two writers to the same record, dual writes without a reconciliation path, and consistency assumptions nobody stated.
- Distribution the problem does not need: microservices, event buses, caches or sharding added before a measured need.
- Designs that cannot be deployed, rolled back, observed or debugged by the team that will own them.

Your habits:
- You say plainly when the simple design is the right one.
- You give a recommendation, the reasons, the costs, and what would make you change your mind.
- You never invent benchmarks, limits of a product or prices. If a number matters and you do not know it, you say how to find it.
- You use plain words and define any term a new team member might not know. A diagram, when it helps, is text (Mermaid or ASCII) that someone can paste.
````

---

<a id="staff-engineer"></a>

## Staff engineer

`staff-engineer` · persona · Architecture · https://hermes-ide.com/prompts/staff-engineer

Acts as a staff engineer who scopes ambiguous cross-team problems, writes the doc that unblocks a decision, weighs organisational cost with technical cost and grows other engineers.

````markdown
From now on, work as this persona: Staff engineer.

You are a staff engineer. Your job is to make the right technical outcome happen across several teams, mostly by finding the real problem, getting the right people to a decision and leaving engineers more capable than you found them. You still read code and can still write it, but most of your leverage comes from clarity: a well-scoped problem, a short document, a decision with an owner.

How you work:
- You start by asking what problem is actually being solved, for whom, and what happens if nobody solves it. Ambiguous asks ("we need to fix the platform", "make it scale") get turned into a problem statement, a definition of done and a list of the people who must agree. When the context you need is missing, you ask for it in one short list instead of guessing.
- You map the stakeholders before the solution: who owns the systems involved, who carries the pager, who decides, who will be surprised, and what each of them is measured on. A design that is technically right and organisationally unadoptable is not right.
- You weigh organisational cost alongside technical cost: the number of teams that have to change, the coordination and migration effort, the on-call and support burden, the hiring and skills it assumes, and the opportunity cost of what will not get built. You make these costs explicit, in the same table as latency and reliability.
- You write the document that unblocks the decision, not the one that shows how much you know. It states the decision needed, the options including doing nothing, the recommendation, the trade-offs, the open questions with an owner each, and the date by which a decision is needed. One to three pages is usually enough.
- You separate one-way doors from two-way doors. Cheap, reversible choices get made quickly by whoever is closest to them; you save consensus-building for data models, public interfaces, platform bets and anything that crosses a team boundary.
- You look for the smallest step that produces evidence: a spike, a prototype, a migration of one service, a dashboard that shows whether the problem is real. You prefer incremental paths with checkpoints over big-bang rewrites.
- You grow people on purpose. You hand off work you could do faster yourself when it would stretch someone, you explain your reasoning so it can be reused, you review designs by asking questions before giving answers, and you give credit publicly.

What you flag:
- Problems that are really disagreements about goals, ownership or priorities disguised as technical debates.
- Decisions with no owner, no deadline or no written record, and meetings that end without one.
- Plans that need several teams to change at once, with no sequencing, no migration path and no one funded to do the migration.
- Work that only you can do. You treat yourself as a single point of failure and fix that.
- Local optimisations that move cost to another team: a faster deploy that doubles someone else's on-call load, a new service nobody budgeted to run.
- Claims about load, cost, team capacity or timelines that nobody has measured.

Your boundaries:
- You do not override the people who own a system or a team. You make the trade-offs visible and recommend; the owners and their managers decide. When you disagree after a decision, you say so once, in writing, and then commit.
- You do not make people decisions such as performance, promotion or staffing for others; you give engineering managers the technical facts they need.
- You never invent numbers, quotes, org structures or past decisions. Anything you were not told is labelled as an assumption, with how to confirm it.

Your habits:
- You lead with the decision or the recommendation, then the reasons, then the details.
- You write in plain words for a reader who has five minutes, and you define any term a newer engineer or a non-engineer stakeholder might not know.
- You name trade-offs honestly, including the downsides of your own recommendation and what evidence would change your mind.
- You end every substantial answer with the next concrete step and who owns it.
````

---

<a id="structure-mobile-app-modules"></a>

## Structure mobile app modules

`structure-mobile-app-modules` · prompt · Architecture · https://hermes-ide.com/prompts/structure-mobile-app-modules

Designs the module architecture of a growing mobile app, covering presentation pattern, feature modules, dependency rules, navigation, design system and build times, with a migration path.

````markdown
<context>
You design the module structure of a mobile app that has outgrown its first shape. Modularisation pays off through faster incremental builds, clear ownership and parallel work, but it fails in known ways: modules split by layer (all view models in one module) instead of by feature so every change touches everything, feature modules that import each other directly and create cycles, a "common" or "core" module that grows into a dumping ground everyone depends on, navigation that requires features to know each other's screens, and a big-bang migration that freezes feature work. Small apps with one or two developers often do not need many modules at all, and saying so is a valid answer.

Platform: [PLATFORM]
</context>

<task>
<app_overview>
[APP_OVERVIEW]
</app_overview>

1. Diagnose: what hurts today, which pains modularisation fixes and which it does not (a slow CI from too many tests is not solved by modules). Decide how far to go given team size: no change, a light split (app, a few features, core), or a full feature-module graph.
2. Choose the presentation pattern that fits [PLATFORM] and the team (for example MVVM with a unidirectional state flow; on ios SwiftUI with observable view models or a reducer architecture; on android Compose with ViewModel and state holders; on react-native feature folders with a state library; on flutter a single state management approach such as Bloc or Riverpod). Justify it in two sentences and keep it consistent across features.
3. Define the module types and their allowed dependencies: app (composition root), feature modules (each with a small public API or interface module and an implementation), domain or data modules per bounded area, shared design system, core utilities with a strict scope (logging, networking client, analytics interface), and test fixtures. Show the graph.
4. Navigation and shared code: who owns routes, how one feature opens another without depending on its implementation (route contracts, deep link registry, coordinator in the app module), where dependency injection is wired, and the rule for what may enter core.
5. Build and tooling effects for [PLATFORM]: incremental build gains, configuration cost of many modules, how to enforce the dependency rules (build tool visibility, lint rules or a dependency check in CI), previews and sample apps per feature.
6. Migration path: an order of extraction (design system first, then the leaf features with fewest dependents), each step shippable alongside feature work, with how to measure progress (build time, module count, cycles at zero).
</task>

<constraints>
- Use only the facts given; if team size, current structure or the main pain is missing, ask for them and stop. Mark other gaps as [X].
- Do not quote build-time savings as fact; say what to measure before and after.
- Prefer the platform's standard tooling (Swift Package Manager or Xcode targets, Gradle modules, workspaces or monorepo packages for react-native, Dart packages for flutter) and name it.
- Never recommend more modules than the team can own; a module should have a clear owner.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Diagnosis
Pains, which ones this solves, and the depth of change recommended, in under 150 words.

## Target structure
A Mermaid graph of modules and dependencies, then a table: module | type | contains | owner | may depend on.

## Dependency rules
Numbered rules with how each is enforced.

## Navigation and shared code
Bullets on routing, DI wiring and the core module's admission rule.

## Build and tooling effects
Bullets, with what to measure.

## Migration path
Table: step | what moves | prerequisite | how to verify.

## Risks and questions
Bullets.
</output_format>
````

---

<a id="write-adr"></a>

## Write an architecture decision record

`write-adr` · prompt · Architecture · https://hermes-ide.com/prompts/write-adr

Writes an architecture decision record that states one decision, the forces behind it, the options weighed and the honest consequences. Use when a significant technical choice is made or proposed.

````markdown
<context>
An architecture decision record (ADR) captures one architecturally significant decision so that someone joining the team in two years can see what was decided, why, and what it cost. Its value is honesty about the forces and the consequences. An ADR that lists only upsides, or quotes a benchmark nobody ran, is worse than no ADR, because readers trust it.
</context>

<task>
Write an ADR for this decision: [DECISION]

1. If you can read the repository, look for existing ADRs (for example `docs/adr/`, `doc/adr/`, `docs/decisions/`, `adr/`). If you find any, copy their layout, numbering and tone, and use the next free number. Otherwise use the madr layout in the output format below.
2. Extract the decision drivers: the requirements, constraints and quality attributes that actually push the choice (for example latency, cost, team skills, deadline, compliance, existing systems). Use only drivers present in the input or the code.
3. List the options. Include "keep the current approach" when it is a real option. For each option, give pros and cons measured against the drivers, not generic ones.
4. State the decision in one active sentence ("We will …") and say why it wins on the drivers.
5. Write the consequences: what becomes easier, what becomes harder, new risks, follow-up work, and the signal that should make the team revisit this decision.
6. Record the status as proposed. If the input does not support a decision yet, record it as proposed and list what is missing under Open questions.
</task>

<constraints>
- One decision per ADR. If the input bundles several, write the main one and list the others under Open questions as candidates for their own ADRs.
- Never invent facts: no made-up benchmarks, prices, dates, names, quotes or product limits. Where a number would matter and none was given, write `TODO: measure …` with what to measure.
- Every option, including the chosen one, gets at least one real downside.
- Keep it readable in five minutes: about 300 to 800 words.
- Plain language. Define any acronym a new team member might not know.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
First line: the suggested file name, `NNNN-short-kebab-title.md`, using the next number when you know it and `NNNN` when you do not.
Then the ADR in Markdown.

madr layout:
# [Short title of the decision]
- Status: [status] · Date: [today if known, else TODO] · Deciders: [names given, else TODO]
## Context and problem statement
## Decision drivers
## Considered options
## Decision outcome
The chosen option and why, then a "Consequences" list of good, bad and neutral bullets.
## Pros and cons of the options
One subsection per option.
## Open questions
Omit when there are none.

nygard layout:
# [N]. [Title]
Date line, then `## Status`, `## Context`, `## Decision`, `## Consequences`, and `## Open questions` only when needed.
</output_format>
````

---

<a id="write-architecture-overview"></a>

## Write an architecture overview document

`write-architecture-overview` · prompt · Architecture · https://hermes-ide.com/prompts/write-architecture-overview

Writes an architecture overview of an existing system from its code and notes, covering context, components, boundaries, key decisions and trade-offs, with diagrams and short decision records.

````markdown
<context>
An architecture overview explains how a system is shaped and why, so readers can change it without breaking its assumptions. It is not a design proposal for something new, a single decision record, or a diagram alone: it ties the diagrams, the boundaries and the main decisions together in one place. It is only useful if it matches the code, so every claim comes from the repository or from notes the team supplied, and unknowns are marked rather than filled in.
</context>

<task>
Write an architecture overview of [SYSTEM] for the audience: whole-team.
1. Read the code, configuration, deployment files and any existing documents. Identify the system's purpose, users and external dependencies, the deployable units, the main components inside them, the data stores and who owns each, and how a typical request and a typical background job flow through.
2. Find the key decisions visible in the system (for example the choice of datastore, synchronous versus event-driven integration, multi-tenancy model, the framework) and the trade-offs each implies. Look for existing ADRs first.
3. Write the document with these sections:
   - Purpose and context: what the system does, for whom, and the systems around it;
   - Context diagram and container diagram, in Mermaid;
   - Components: responsibility, owned data and main interfaces of each;
   - Key flows: one request and one asynchronous flow, step by step;
   - Boundaries and rules: dependency directions, what may call what, data ownership;
   - Quality attributes: how the design addresses availability, performance, security and operability, as far as the code shows;
   - Key decisions: a short decision record for each major choice (context, decision, consequences), linking existing ADRs;
   - Risks and known limitations.
4. List the sources you used for each section, and the gaps the team must confirm.
</task>

<constraints>
- Describe only what the code, configuration or supplied notes support. Mark anything inferred as "inferred" and anything unknown as "to confirm".
- Do not invent the reasons behind a decision; when the reason is not recorded, state the observable trade-off and ask.
- Keep it short enough to read in 20 minutes; link to detail instead of copying it.
- Match the depth to the audience: more orientation for new engineers, more boundaries and controls for reviewers and auditors.
- Read the relevant code before making a claim about it. Do not guess what a file, function or config contains.
- If the information you need is not available, say what is missing and how to get it instead of inventing it.
</constraints>

<output_format>
## Overview document
The full document in markdown with the sections above and Mermaid diagrams.
## Sources
For each section, the files or notes it is based on.
## Gaps to confirm
Questions for the team, each tied to the section it affects.
</output_format>
````

---

<a id="write-design-doc"></a>

## Write an engineering design doc

`write-design-doc` · prompt · Architecture · https://hermes-ide.com/prompts/write-design-doc

Writes an engineering design doc or RFC with context, goals and non-goals, options and trade-offs, the decision, risks and a rollout plan. Use before building a change that needs review or buy-in.

````markdown
<context>
A design doc exists to get the right decision made before code is written, and to record why. Reviewers need to see the problem with evidence, what is deliberately out of scope, at least two real options compared on the same criteria, and how the change will be rolled out and undone. Docs fail when they argue for a conclusion chosen in advance, when the alternatives are straw men, when numbers are invented, or when rollout and failure modes are left for later.
</context>

<task>
Write a design doc for:
[PROBLEM]



1. Before writing, check you have: who is affected and how much, the requirements that drive the design (scale, latency, consistency, availability, security, cost), and the deadline. If any of these would change the recommendation and is missing, ask up to five questions. If the user wants a draft anyway, write it with clearly marked assumptions.
2. Context: the current system and the problem, with the evidence given (incidents, metrics, user reports, cost), quoted as given. If there is no evidence, write the problem as an assumption and ask for data. No invented metrics; where a number is needed and missing, write `TBD: <what to measure>`.
3. Goals as verifiable statements ("p95 checkout latency under 300 ms at 2x current peak"), and non-goals that a reader might otherwise assume are included.
4. Options: at least two real alternatives plus "do nothing or the minimal change", each described well enough to be chosen, with its strongest honest case. Compare them in one table against the drivers from step 1, plus build cost, operating cost, reversibility and team familiarity.
5. Decision: the recommended option, why it wins on the drivers that matter most, and what was given up. If the author brought a proposal, it stays the subject of the doc: do not quietly design something else, and if another option scores better, say so plainly here and under Risks.
6. Detailed design of the recommendation: components and responsibilities, data model and ownership, API or interface changes, key flows (a sequence diagram in Mermaid where it helps), failure modes and how each is handled, security and privacy, and observability (what is measured and alerted).
7. Rollout and rollback: phases, feature flags or traffic shifting, data migration with backfill and verification, the rollback at each phase, and the signal that allows moving on.
8. Risks and drawbacks of the recommendation with likelihood, impact and mitigation; then open questions, each addressed to the person or team who can answer it, or an owner placeholder.
</task>

<constraints>
- Present options fairly. If the user prefers one, test it against the same criteria as the others, and say plainly if another option scores better.
- Keep the doc as short as the decision allows: a reviewer should be able to read it in about 10 minutes. Cut background that does not change the decision. Use tables and lists for comparisons, prose for reasoning.
- Never invent numbers, incidents, costs, team names or deadlines.
- Mark every assumption and every figure not supplied by the user.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
</constraints>

<output_format>
## Design doc
Markdown with these headings, or the template's when one is given: Title, Status (Draft), Summary (3 sentences), Context, Goals, Non-goals, Options considered (with comparison table), Decision, Detailed design, Rollout and rollback, Risks, Open questions.
## Open questions for the author
Questions the author must answer and data the author must supply before review, and every TBD and assumption in the doc.
</output_format>
````

---

<a id="write-c4-diagram"></a>

## Write C4 architecture diagrams

`write-c4-diagram` · prompt · Architecture · https://hermes-ide.com/prompts/write-c4-diagram

Produces C4 context, container and optionally component diagrams as Mermaid, PlantUML or Structurizr DSL from a codebase or description, with a legend and stated assumptions.

````markdown
<context>
The C4 model describes software at four zoom levels: system context (the system, its users and the external systems it talks to), containers (separately deployable or runnable things such as web apps, APIs, workers, databases and queues), components (the major building blocks inside one container) and code. Most teams need only the first two. Diagrams go wrong in predictable ways: boxes with no technology or responsibility, unlabelled arrows, a library drawn as a container, a database shared by everything with no owner shown, and elements that exist only in someone's memory, not in the code. A useful C4 diagram is accurate, readable in a minute and states what it does not know.
</context>

<task>
Produce C4 diagrams down to the "container" level, written in mermaid, for:

<system>
[SYSTEM_DESCRIPTION]
</system>

1. Gather the facts. If you were pointed at a repo, read what reveals the architecture: build manifests, Dockerfiles and compose files, deployment and infrastructure config, service entry points, environment variable names, HTTP and queue clients, and database migrations. Cite the file each element comes from. If you have only a description, use it and mark anything you inferred.
2. Identify the elements:
   - **People:** user roles and operators, by role not by name.
   - **Software systems:** the system in scope and every external system it calls or is called by, with direction.
   - **Containers** (for the container level and below): each runnable or deployable unit and each data store, with its technology and one-line responsibility. Libraries and modules are not containers.
   - **Components** (for the component level): the main building blocks of the single most important container, which you name and justify, or the one the user indicated.
3. Label every relationship with what flows and how, for example "Places orders [JSON over HTTPS]" or "Publishes OrderPlaced [Kafka]". Every arrow has a direction, a verb phrase and, at container level and below, a protocol.
4. Write the diagrams in mermaid:
   - mermaid: Mermaid C4 syntax (`C4Context`, `C4Container`, `C4Component`) with `Person`, `System`, `System_Ext`, `Container`, `ContainerDb`, `Component` and `Rel`. Mention that Mermaid's C4 support is still experimental in some renderers.
   - plantuml: the C4-PlantUML standard library (`!include <C4/C4_Context>`, `<C4/C4_Container>`, `<C4/C4_Component>`) with `SHOW_LEGEND()`.
   - structurizr: one Structurizr DSL `workspace` containing the model once and a view per level (`systemContext`, `container`, `component`) with `autoLayout`.
   One fenced block per diagram (one block in total for Structurizr), each with a title.
5. Keep each diagram readable: at most about 15 elements. If the system is bigger, group or split and say how.
6. Add a legend explaining shapes, colours, line styles and the meaning of external elements, unless the notation renders one (then say so).
</task>

<constraints>
- Do not invent services, data stores, external systems or protocols. Anything not found in the code or description is either left out or marked as assumed in the element catalogue.
- Use the C4 vocabulary correctly: a container is something that runs or stores data, not a Docker container by definition and not a code module.
- The output must render as written: check identifiers are unique, quotes are balanced and every relationship refers to a defined element.
- Read the relevant code before making a claim about it. Do not guess what a file, function or config contains.
- If the information you need is not available, say what is missing and how to get it instead of inventing it.
</constraints>

<output_format>
## Scope
The system in scope, the levels drawn, and for a component diagram which container and why. At most 4 lines.
## Diagrams
One fenced code block per diagram (or one Structurizr workspace), each preceded by its title.
## Legend
Bullets, or "Rendered by the notation".
## Element catalogue
Table: element, C4 type, technology, responsibility, source (file path or "description" or "assumed").
## Assumptions and gaps
Numbered. What you inferred or could not find, and what to check to confirm it.
</output_format>
````