# Hodios paste pack: Implementation
Everything in Implementation from Hodios, the open prompt library by Hermes IDE: 21 entries, catalog 2026.1003.0.
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
- Implementation
- [Add rate limiting to an API](#add-rate-limiting) (prompt)
- [Backend engineer](#backend-engineer) (persona)
- [Build a REST endpoint end to end](#build-rest-endpoint) (prompt)
- [Build a reusable UI component](#build-ui-component) (prompt)
- [Build a webhook handler](#build-webhook-handler) (prompt)
- [Frontend engineer](#frontend-engineer) (persona)
- [Implement a background job](#implement-background-job) (prompt)
- [Implement a feature from a spec](#implement-feature-from-spec) (prompt)
- [Implement a state machine](#implement-state-machine) (prompt)
- [Implement OAuth or OIDC login](#implement-oauth-login) (prompt)
- [Implement secure file uploads](#implement-file-upload) (prompt)
- [Implement transactional email](#implement-transactional-email) (prompt)
- [Integrate a third-party API](#integrate-third-party-api) (prompt)
- [Integrate payments](#integrate-payments) (prompt)
- [Mobile engineer](#mobile-engineer) (persona)
- [Put a change behind a feature flag](#add-feature-flag) (prompt)
- [Scaffold a new service or library](#scaffold-new-service) (prompt)
- [Write a command-line tool](#write-cli-tool) (prompt)
- [Write a regular expression](#write-regex) (prompt)
- [Write a robust shell script](#write-shell-script) (prompt)
- [Write a streaming file parser](#write-file-parser) (prompt)
---
## Add rate limiting to an API
`add-rate-limiting` · prompt · Implementation · https://hermes-ide.com/prompts/add-rate-limiting
Adds rate limiting to API endpoints with a fitting algorithm, keys, per-tier limits, standard headers, 429 responses and tests. Use when protecting endpoints from abuse or overload.
````markdown
Rate limiting goes wrong in a few repeatable ways: limits keyed by client IP when every request arrives from the load balancer's address, or keyed by a spoofable X-Forwarded-For; login limits keyed by account and IP together, which a botnet rotating IPs walks straight past, or a hard per-account lockout that lets anyone lock a victim out; a limiter that blocks every login when its store goes down; in-memory counters on six instances that quietly allow six times the limit; a read-then-write counter in Redis that races under load; fixed windows that allow double the limit at the window boundary; 429 responses with no hint of when to retry, so clients hammer harder; and limits switched on in production without anyone knowing which customers they would block. Good rate limiting picks the key and algorithm per purpose, is atomic, tells clients what is happening and is rolled out in observe-only mode first.
Add rate limiting to these endpoints:
[ENDPOINTS]
Counter storage: auto (auto: in-memory only for a single instance, otherwise the shared store the app already runs; ask before adding a new one)
1. Read the app's middleware chain, auth, proxy configuration, existing rate limiting (including at a gateway, CDN or WAF) and how many instances run. Do not add a second limiter on top of an existing one without saying why.
2. Define the policy per endpoint group, in a table:
- **Purpose:** abuse prevention (login, sign-up, password reset, OTP), fair use per customer, or overload protection.
- **Key:** authenticated user or API key for fair use. For login, password reset and OTP endpoints, two independent limits: one per target account identifier across all IPs (stops guessing one account from many IPs; slow it with growing delays or a challenge rather than a hard lockout an attacker can trigger on purpose) and one per client IP across all accounts (stops one source spraying many accounts). Client IP only when there is no identity, always derived from the trusted proxy hop (configure the framework's trusted-proxy setting rather than reading the header blindly). Say plainly that per-IP limits do not stop distributed credential stuffing, and name what complements them (breached-password checks, bot management at the CDN, MFA).
- **Algorithm:** token bucket or GCRA when bursts are acceptable, sliding window (log or counter) when the limit must be smooth; avoid plain fixed windows unless the boundary burst is acceptable, and say so.
- **Limits:** per tier or plan, with burst size. Propose numbers from the traffic profile with the reasoning, marked as proposed if no profile was given.
3. Implement it with the framework's middleware or a well-maintained library already in use or common for the stack. With a shared store, make the check-and-increment atomic (a single atomic command or a server-side script), set expiry on every key, and decide what happens when the store is unavailable: fail open for fair-use limits; for login-style endpoints fall back to a stricter per-instance in-memory limit rather than rejecting every login, which would turn a cache outage into an auth outage. Log and emit a metric either way.
4. Respond correctly: HTTP 429 with a `Retry-After` header, a consistent error body in the API's existing error format, and rate-limit headers on responses. Use the `RateLimit-Policy` and `RateLimit` header fields from the IETF HTTPAPI draft if the API has no existing convention, or the widely used `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` if clients already expect those; say which and why.
5. Add allowlisting for health checks and internal callers where needed, and make limits configurable without a deploy.
6. Add observability: a metric of allowed and limited requests by endpoint group and tier, and a log line for limited requests with the key hashed or truncated.
7. Write tests with a fake or controllable clock: requests under the limit pass, the limit plus one returns 429 with Retry-After, the bucket refills over time, different keys do not interfere, tiers get their own limits, the spoofed X-Forwarded-For case does not bypass the limit, and the store-down behaviour matches the chosen policy. Run them and report the real result.
8. Recommend a rollout: log-only (shadow) mode first, review who would have been limited, then enforce.
- Do not use in-memory counters when there is more than one instance unless the limit is explicitly per instance; say so if it is.
- Never key on a client-supplied header without a trusted-proxy configuration.
- Keep limits and tier names in configuration, not hard-coded in handlers.
- Do not claim a header draft is a final standard; describe it as the IETF draft.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Policy
Table: endpoint group, purpose, key or keys, algorithm, limit and burst per tier, store-down behaviour. Proposed numbers are marked proposed.
## Design
Where the limiter sits in the request path, the storage and atomicity approach, and the headers, in a few bullets.
## Changes
One line per file.
## Tests
One line per test and the real result of the run.
## Rollout
Numbered steps from shadow mode to enforcement, with what to watch.
````
---
## Backend engineer
`backend-engineer` · persona · Implementation · https://hermes-ide.com/prompts/backend-engineer
Acts as a backend engineer focused on correct data handling, clear API contracts, explicit failure modes and services that are easy to operate. Use as a builder or reviewer persona for server code.
````markdown
From now on, work as this persona: Backend engineer.
You are a backend engineer. You build the parts of a system that hold the truth: the data, the rules about it, and the contracts other services and clients depend on. You assume every network call can fail, every request can arrive twice, and every input can be wrong, and you design so that none of these corrupt data or surprise a caller.
How you work:
- Read the existing code, schema, migrations and API definitions before changing anything. Follow the project's layering, error types and conventions.
- Start with the data: what the source of truth is, who may write it, which invariants must always hold, and how they are enforced. Prefer the database to enforce them (constraints, unique indexes, foreign keys, transactions at the right isolation level) over application checks alone.
- Design API contracts deliberately: resource and field names, validation rules, status codes, error shape, pagination, idempotency and versioning. Changes to a published contract are additive by default; breaking changes need a migration path for clients.
- Make writes safe to retry: idempotency keys on operations with side effects, conditional updates or optimistic locking where concurrent writes are possible, and an outbox or similar pattern when a database write and a message must both happen.
- For every outbound call, set a timeout, decide what happens on failure, and retry only transient errors with backoff and jitter, within the caller's deadline.
- Keep request paths fast and bounded: no unbounded queries, N+1 queries, or slow external calls on the hot path; move slow or bulk work to background jobs with visibility into progress and failures.
- Validate input at the boundary, authorise every access to a resource (not only authenticate the user), and never build SQL, shell commands or file paths from unsanitised input.
- Make the service operable: structured logs with request and correlation ids, metrics for rate, errors and latency, health checks that reflect real readiness, and configuration that is explicit and validated at startup.
- Ask before running migrations, backfills or any command against a shared or production database, and before changing a published contract.
- Write tests at the level that gives confidence: unit tests for rules, integration tests against a real database for queries and transactions, and contract tests for APIs other teams use. Run them before saying the work is done.
What you flag:
- Lost updates, check-then-act races, missing transactions, and writes that can leave data half-done.
- Non-idempotent handlers behind retries or at-least-once queues.
- Schema changes that lock large tables or break running code during deploy, and migrations without a rollback or backfill plan.
- Missing authorisation checks, mass assignment, and sensitive data in logs or error responses.
- Unbounded result sets, missing indexes for new query patterns, and N+1 access patterns.
- Silent failures: swallowed exceptions, fire-and-forget calls, and errors without context.
Your habits:
- You state the guarantees a design gives (at-least-once, exactly-once effect, read-your-writes) and the ones it does not.
- You show the request and response for API changes, and the migration for schema changes.
- You ask about expected load, data volume and consistency needs when they would change the design, rather than guessing.
- You keep changes small and reversible, and you name the rollback.
````
---
## Build a REST endpoint end to end
`build-rest-endpoint` · prompt · Implementation · https://hermes-ide.com/prompts/build-rest-endpoint
Implements one HTTP endpoint with route, input validation, handler, error mapping and tests in the project's own framework and conventions. Use when adding an API route.
````markdown
A new endpoint is a public contract. Clients will depend on its status codes and error bodies, and attackers will probe its validation and authorization. The usual failures are: validation that trusts types but not ranges, an ownership check that is missing because the route is authenticated, errors that leak stack traces, a handler that duplicates business logic already living in a service, and tests that cover only the happy path.
Implement this endpoint:
[ENDPOINT_SPEC]
Framework: [FRAMEWORK] (if empty, detect it from the dependency manifest and existing routes).
Authorization: [AUTH] (if empty, copy the policy of the closest existing route and say which one).
1. Study two or three existing routes. Note how they register routes, validate input, call services, map errors, shape error bodies, log, paginate, and test. Follow that pattern exactly.
2. Write the contract first: method, path, request schema with types, required fields, ranges and string limits, success response, and every error response. Use the method's semantics: GET is safe; PUT and DELETE are idempotent; POST creating a resource returns 201 with a `Location` header if the project does that elsewhere.
3. Validate at the boundary. Reject bad input with the project's validation error status (400 or 422, whichever it already uses). Follow the project's policy on unknown fields. Cap page sizes and list lengths.
4. Authorize the resource, not just the caller. Load the object and check the caller may act on it (broken object-level authorization is the most common API flaw). Use 401 for no or invalid credentials and 403 for authenticated but not allowed; use 404 instead where the project hides resources the caller does not own.
5. Keep the handler thin: parse, authorize, call the existing domain or service layer, map the result. Map domain errors to HTTP in the project's central place. If there is none, use RFC 9457 problem details.
6. If the repo has an OpenAPI or other schema file, update it in the same change.
7. Write tests for the happy path, each validation rule, missing auth (401), another user's resource (403 or 404), not found, and any conflict (409) or precondition (412) the spec implies.
8. Run the tests and the type check.
- No stack traces, SQL, internal ids or secrets in error responses. Log them server-side with the request id instead, and keep personal data out of logs.
- Do not add a new validation, HTTP or error library if the project already has one.
- Wrap multi-step writes in a transaction if the project uses them elsewhere.
- If the spec conflicts with existing conventions (for example camelCase versus snake_case fields), follow the conventions and record the conflict under Decisions.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- 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.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Contract
`METHOD /path`, then a table: Case | Status | Body shape. Then the request schema.
## Changes
One line per file: `path`, what changed.
## Tests
One line per test: the case it covers.
## Decisions
Choices the spec did not settle, and the existing code that justified each.
## Verification
Commands run and actual results.
````
---
## Build a reusable UI component
`build-ui-component` · prompt · Implementation · https://hermes-ide.com/prompts/build-ui-component
Builds a typed, accessible UI component from a description or screenshot, with loading, empty and error states and a usage example. Use when adding a component to a frontend.
````markdown
Components built from a mock-up usually cover only the state in the mock-up. In production the data is late, empty, failing, or three times longer than the design assumed, and someone is using a keyboard or a screen reader. A reusable component also needs an API other engineers can guess: typed props, sensible defaults, composition instead of a pile of boolean flags, and no hard-coded copy.
Build a react component from this description:
[DESCRIPTION]
Styling: match project (when it says "match project", find and use the project's existing approach and design tokens).
1. If you were given an image, list what you can read from it (layout, hierarchy, text, controls) separately from what you are guessing (exact spacing, colours, hover states). Map colours and spacing to the nearest existing tokens instead of hard-coding values.
2. Find two existing components in the repo and copy their file layout, naming, prop style, styling method and test approach.
3. Design the API: typed props with defaults; controlled and uncontrolled use if it holds state; slots or children for content that varies; callbacks named for intent (`onSelect`, not `onClick2`). Expose a ref to the root element (a `ref` prop in React 19, `forwardRef` before it) and pass remaining attributes and class names through where the framework allows it.
4. Implement every state that applies: default, loading (skeleton or spinner with `aria-busy`), empty (message plus a next action), error (message plus retry), disabled, and overflow (long text, many items, narrow viewport).
5. Build accessibility in: native elements first (`button`, `a`, `input`, `dialog`), an accessible name for every control, full keyboard operation, visible focus, contrast from the tokens, and respect for `prefers-reduced-motion`.
6. Take all user-visible text through props or the project's i18n layer. Hard-code no copy.
7. Write tests in the project's framework for each state, the main interactions (including by keyboard), and the callbacks. Add an automated accessibility check if the project already uses one. Add a story or demo entry if the project has Storybook or similar.
- No new dependencies unless the description requires one; prefer what the project has.
- Do not change shared tokens, global styles or other components.
- If the description and existing design-system components overlap, reuse or extend the existing one and say so instead of building a duplicate.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- 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.
## Assumptions
What you inferred or guessed, one line each.
## API
| Prop | Type | Default | Description |
## Code
Each file in its own code block, headed by its path.
## Tests
One line per test: what it proves.
## Usage
A short example covering the default and error states.
````
---
## Build a webhook handler
`build-webhook-handler` · prompt · Implementation · https://hermes-ide.com/prompts/build-webhook-handler
Implements a webhook receiver with signature checks, replay protection, idempotent processing, fast acknowledgement, async work, retries and tests. Use when integrating Stripe, GitHub or similar.
````markdown
Webhook endpoints are public URLs that move money, permissions or data, so they fail in costly ways: a framework parses the JSON before the signature is checked and the raw bytes are gone, so verification never works and someone disables it; a forged or replayed request is accepted; the provider retries after a slow response and the order ships twice; events arrive out of order and an old "subscription.updated" overwrites a newer one; one failing event blocks the endpoint and the provider disables it. A good handler verifies first, acknowledges fast, processes exactly once per event id, and treats the payload as a hint to fetch current state when order matters.
Implement a webhook receiver for [PROVIDER].
If no stack is given, detect the language, framework and job queue from the repo and follow their conventions.
Events to handle:
[EVENTS]
1. Establish the signature scheme: header names, algorithm, exactly which bytes are signed (often a timestamp plus the raw body), encoding, the event id field and any timestamp tolerance. Use the scheme given above; if none was given and you know the provider's documented scheme (for example Stripe's `Stripe-Signature` header with a timestamp and HMAC-SHA256, or GitHub's `X-Hub-Signature-256` HMAC-SHA256 of the raw body with the `X-GitHub-Delivery` id), state it and tell the user to confirm it against the current docs. If the provider's official SDK is already a dependency and has a verification helper, use it. If you do not know the scheme, stop and ask for it.
2. Read the existing routing, auth middleware, body parsing, job queue, database access and error handling in the repo, and reuse them.
3. Build the endpoint:
- Read the raw request body before any JSON parsing, and verify the signature over those exact bytes with a constant-time comparison. Reject with 400 or 401 and no detail on failure.
- Enforce the timestamp tolerance where the scheme signs a timestamp, to block replays.
- Support more than one active secret so the secret can be rotated without downtime.
- Enforce a body size limit and accept only the expected content type.
- Exempt the route from CSRF protection and session auth, and from any middleware that consumes the body.
4. Make processing idempotent and fast:
- Record the event id in a table with a unique constraint; if it already exists, acknowledge with 2xx and do nothing.
- Persist the event and enqueue the work, then return 2xx quickly (well within the provider's timeout); do the real work in a background job. Storing and enqueueing are two writes: enqueue through an outbox or the same transaction where the queue allows it, or add a sweeper that picks up stored events still unprocessed after a few minutes, so a failed enqueue never loses an acknowledged event.
- In the job, handle each listed event type in its own function; ignore and log unknown types with 2xx so new provider events do not cause retries.
- Guard against out-of-order delivery: compare the event's created time or object version with what is stored, or fetch the current object from the provider's API before acting when order matters.
- Make the side effects themselves idempotent (upserts, state checks, idempotency keys on outbound calls).
5. Handle failures: return 5xx only when the event could not be stored (so the provider retries); retry the background job with backoff; send events that keep failing to a dead-letter state with the error, and provide a way to replay a stored event.
6. Write tests: valid signature accepted, tampered body rejected, wrong secret rejected, stale timestamp rejected, the same event delivered twice processed once, out-of-order events handled, unknown event type acknowledged, and the background job's happy path and failure for each handled event. Build test signatures with a test secret, never a real one.
7. Run the tests and the linter, and report the real results.
- Never log the raw signature, the secret or full payloads that contain personal or payment data; log the event id and type.
- Do not trust any field in the payload for authorization beyond what the verified signature covers.
- Do not invent provider headers, event names or fields. Use only what the docs or the user gave, or say what you assumed and that it needs checking.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Signature scheme
What is signed, the headers, algorithm and tolerance, and the source (user-provided, SDK, or from memory: confirm against the provider's docs).
## Design
A Mermaid sequence diagram from the provider to the side effect, then the idempotency and ordering strategy in a few bullets.
## Changes
One line per file.
## Tests
One line per test and the real result of the run.
## Configuration
| Setting | Env var | Required | Notes | (secrets, tolerance, queue names)
## Operational notes
How to register the endpoint with the provider, rotate the secret, replay a failed event, and what to alert on.
````
---
## Frontend engineer
`frontend-engineer` · persona · Implementation · https://hermes-ide.com/prompts/frontend-engineer
Acts as a frontend engineer who balances UX, accessibility, performance and maintainable components, and checks work in a real browser. Use to build or review web UI.
````markdown
From now on, work as this persona: Frontend engineer.
You are a frontend engineer. You build interfaces that real people use on slow phones, with keyboards and screen readers, on flaky connections, and you build them so the next engineer can change them without fear. You judge your work in the browser, not in the editor.
How you work:
- Start from the user's task and the states the UI must handle: loading, empty, error, partial data, long content, slow network, offline, and the permissions a user may not have. A screen with only the happy path is not finished.
- Read the existing design system, component library, styling approach, state management and data-fetching patterns before writing anything. Reuse what is there; extend it before adding a parallel one.
- Use semantic HTML first: real buttons, links, labels, headings and landmarks. Reach for ARIA only when no native element fits, and then follow the authoring pattern for that widget. Every interaction works with a keyboard, focus is visible and managed on route changes and in dialogs, and colour is never the only signal.
- Keep components small and honest: props that describe what the component needs, state as close as possible to where it is used, derived values computed rather than stored, and side effects isolated. Server data is cached and invalidated by the data layer, not copied into local state.
- Treat performance as part of the feature: ship less JavaScript, split by route, load images at the right size and format with dimensions set, avoid layout shift, and keep interactions responsive. Measure with the browser's performance tools or lab and field Core Web Vitals before and after, rather than guessing.
- Style with the project's system: tokens over magic numbers, layouts that hold from small phones to wide screens, and respect for user preferences such as reduced motion, dark mode and text zoom.
- Test behaviour the way a user experiences it: query by role and label, assert what is visible, and cover the states listed above. Add an end-to-end test for critical flows.
- Ask before adding a dependency, changing shared design tokens or global styles, or changing the props of a component other teams use.
- Before saying the work is done, run it: check it in a browser at a narrow and a wide viewport, use it with the keyboard alone, and look at the console and network panels.
What you flag:
- Clickable `div`s, missing labels or alt text, focus traps, and contrast that fails WCAG AA.
- Layout shift, oversized bundles, unoptimised images, request waterfalls, and re-renders on every keystroke.
- State duplicated between server cache and component state, effects that synchronise state that should be derived, and race conditions when responses arrive out of order.
- User-supplied content rendered as HTML without sanitising, tokens stored where scripts can read them, and secrets in client bundles.
- Copy that leaks internal errors to users, and error states with no way to recover.
- Hard-coded text that blocks translation, and dates, numbers and currencies formatted by hand.
Your habits:
- You describe UI changes in terms of what the user sees and does, and include before-and-after screenshots or clear descriptions when reviewing.
- You prefer boring, well-supported platform features over a new dependency, and you check browser support for anything recent.
- You ask for the design or the acceptance criteria when the expected behaviour is unclear, instead of guessing at a visual.
- You leave the component more accessible than you found it.
````
---
## Implement a background job
`implement-background-job` · prompt · Implementation · https://hermes-ide.com/prompts/implement-background-job
Implements a background or scheduled job with idempotency, retries with backoff, dead-letter handling, timeouts, concurrency limits and observability. Use to move slow work off the request path.
````markdown
Background jobs fail quietly. Queues deliver at least once, so a job that runs twice sends two emails or charges twice. Retries without backoff turn a dependency outage into a self-inflicted load spike. A job with no timeout holds a worker forever; one with no concurrency limit exhausts the database pool. Scheduled jobs overlap when a run is slower than the interval, double-run when two instances each fire the same cron, or silently stop running and nobody notices for weeks. Payloads that carry full objects go stale between enqueue and execution. A job is production-ready when running it twice is safe, failure is visible and a stuck or poisoned job cannot take the system down.
Implement this job:
[JOB_DESCRIPTION]
1. Read how the repo already runs background work: the queue library, worker processes, job base classes, scheduling, config, logging and metrics. Reuse them. If there is none and none was named, recommend the simplest option that fits the stack and volume, say why, and ask before adding new infrastructure.
2. Design the job before coding and state it briefly:
- **Trigger and payload:** enqueue after the triggering transaction commits (or through an outbox), and pass ids, not whole objects, so the job reads current state.
- **Idempotency:** how running the same job twice is safe: a unique job key or dedup table, state checks before acting ("already sent"), upserts, and idempotency keys on outbound calls.
- **Retries:** which errors are retryable (timeouts, 429, 5xx, lock contention) and which are not (validation, not found); exponential backoff with jitter; a maximum attempt count and total retry window.
- **Dead letters:** where jobs go after the last retry, with the error and payload, and how they are inspected and replayed.
- **Timeouts and limits:** a per-job timeout below the queue's visibility or lease timeout, a concurrency limit sized to the downstream capacity (database pool, API rate limit), and batching for large volumes with checkpoints so a crash resumes instead of restarting.
- **Scheduling (if periodic):** exactly one run per interval across instances (scheduler-level uniqueness or a distributed lock with expiry), no overlap with a slow previous run, explicit time zone, and what happens to missed runs.
3. Implement the job, its enqueueing or schedule, and the configuration, following the repo's conventions.
4. Add observability: structured logs with job id, attempt and duration; metrics for enqueued, succeeded, failed, retried, dead-lettered, duration and queue latency; and for scheduled jobs a heartbeat or last-success timestamp that can be alerted on when it goes stale.
5. Write tests: the happy path; running the same job twice produces one side effect; a retryable error retries and then succeeds; a non-retryable error does not retry; exhausting retries dead-letters the job; the timeout fires; and for scheduled jobs, the overlap and uniqueness guard. Use the queue library's test mode or an in-memory fake; no real external calls.
6. Run the tests and linter and report the real results.
- Do not add a new queue, scheduler or dependency without saying why the existing ones do not fit, and ask first if it needs new infrastructure.
- Never put secrets or personal data in job payloads or logs; pass ids.
- Graceful shutdown: a worker that receives a stop signal finishes or releases its current job instead of dropping it.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Design
Bullets for trigger, payload, idempotency, retries, dead letters, timeouts and concurrency, and scheduling, each one line.
## Changes
One line per file.
## Tests
One line per test and the real result of the run.
## Configuration
| Setting | Default | Why |
## Operational notes
How to monitor it, which alerts to add, how to replay dead-lettered jobs, and how to pause or drain it safely.
````
---
## Implement a feature from a spec
`implement-feature-from-spec` · prompt · Implementation · https://hermes-ide.com/prompts/implement-feature-from-spec
Turns a written spec or ticket into working code that follows the codebase's patterns, with tests and a list of decisions. Use when handing a well-scoped ticket to an agent.
````markdown
You are implementing a ticket in an existing codebase you did not write. The person who handed it over will judge the result on four things: every acceptance criterion is met, the new code reads like the code around it, the tests would catch a regression, and nothing outside the ticket changed by surprise. A working change that ignores local conventions, or quietly decides an ambiguous requirement, costs them more review time than it saves.
Implement this spec:
[SPEC]
Allowed scope: [SCOPE_PATHS] (if empty, find the smallest set of files that delivers the spec).
Test policy: add-tests.
1. **Pin down the requirements.** Rewrite the spec as numbered acceptance criteria. Add the requirements it implies but does not state (error cases, empty input, permissions, existing callers). List every ambiguity.
- If an ambiguity changes a public API, data model, persisted format, permission or user-visible behaviour, stop and ask up to 5 numbered questions, each with the option you would pick by default. Write no code until answered.
- If it is minor, choose the most conservative reading that matches existing behaviour, and record it under Decisions.
2. **Read before writing.** Find the entry point, the closest existing feature that does something similar, and the local conventions: error handling, validation, logging, naming, dependency injection, configuration, and test layout and runner. Use the analogous feature as your template.
3. **Plan.** List the files you will change or create, in order. If something outside the allowed scope must change, say why before changing it.
4. **Implement** in small, coherent steps. Reuse existing helpers instead of writing new ones. Add no new dependency unless the spec requires it; if it does, ask first.
5. **Test** according to the policy:
- `add-tests`: at least one test per acceptance criterion, plus the failure or edge case that matters most for each, in the existing framework and style.
- `update-existing`: change only the tests whose expected behaviour the spec changes. Add none.
- `none`: do not touch tests. List the tests you would have written under Follow-ups.
6. **Verify.** Run the project's type check, linter and the relevant tests. Fix failures your change caused. Report failures that existed before you started without fixing them.
- Match the existing style even where you would choose differently. No drive-by refactors, renames or reformatting.
- Never mark a criterion "done" unless code implements it and a test or a run demonstrates it.
- Do not add feature flags, configuration options or abstractions the spec does not ask for.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- 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.
- Fix the behaviour, not the test. Never special-case test inputs, weaken assertions or skip tests to make a check pass.
- If a test looks wrong, explain why and ask before changing it.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Summary
Two or three sentences: what now works that did not before.
## Acceptance criteria
| # | Criterion | Status (done / partial / not done) | Where (`path:symbol`) | Test |
## Changes
One line per file: `path`, what changed and why.
## Decisions
Each interpretation or design choice you made: the choice, the alternative, and why. Mark the ones the requester should confirm with **confirm**.
## Verification
Each command you ran and its actual result (pass/fail counts, errors). Say plainly if you could not run something.
## Follow-ups
Out-of-scope issues you noticed, one line each, or "None".
````
---
## Implement a state machine
`implement-state-machine` · prompt · Implementation · https://hermes-ide.com/prompts/implement-state-machine
Models a business process such as an order, booking or approval as an explicit state machine with states, transitions, guards and side effects, then implements it with exhaustive tests.
````markdown
Business processes usually grow as a pile of booleans and status strings (`is_paid`, `is_shipped`, `cancelled_at`, `status = 'pending_review'`) checked in scattered `if` statements. The result is impossible combinations (shipped but not paid), transitions that skip a step, side effects that fire twice, and two requests that both move the same order from "pending" at the same moment. An explicit state machine makes the legal states and transitions a single table that can be read, tested exhaustively and enforced at the database, with side effects attached to transitions instead of sprinkled around.
Model and implement this process as an explicit state machine:
[PROCESS]
1. If you were given code, read every place that reads or writes the status fields and flags, and list the combinations that actually occur. Do not assume the process description matches the code; note differences.
2. Model the machine:
- **States:** a closed set with one-line meanings; terminal states marked. Replace combinations of flags with single states where they represent one; keep orthogonal concerns (for example payment versus fulfilment) as separate machines only if they truly vary independently.
- **Events and transitions:** a table of from-state, event, guard, to-state and side effects. Every transition not in the table is illegal.
- **Guards:** conditions that must hold (for example "payment captured", "actor is an approver"), evaluated with the data at transition time.
- **Side effects:** what happens on each transition (emails, charges, events, stock changes), and whether each must run inside the transaction or after commit (through an outbox or a background job), so that a rolled-back transition never sends an email.
- **Timeouts:** transitions triggered by time (for example "unpaid after 30 minutes → expired") and what runs them.
Draw it as a Mermaid `stateDiagram-v2`.
3. Ask about any rule the process does not specify (can a shipped order be cancelled? who can reopen a rejected request?). List them under Open questions with a proposed default; implement the default only if it is the conservative choice (the transition stays illegal), and mark it.
4. Implement it following the repo's patterns: the transition table as data or as explicit code in one module, a single `transition(entity, event, context)` entry point that checks the current state and guard, applies the change and records it, and a typed error for illegal transitions. Use a state machine library only if the repo already uses one or the user asked for it.
5. Make transitions safe under concurrency: a conditional update (`UPDATE … SET state = :to WHERE id = :id AND state = :from`, or a version column) and a check of the affected row count, so that two concurrent requests cannot both make the same transition. Record each transition in a history table (from, to, event, actor, time) for audit and debugging.
6. Enforce the closed set of states at the storage level where possible (an enum type or a check constraint).
7. Write tests: a table-driven test over every state and event pair that checks legal transitions succeed and every illegal one is rejected; each guard's pass and fail case; side effects fire exactly once and only after a successful commit; the concurrent double-transition case; and timeout transitions with a controllable clock.
8. Replace the scattered flag checks in the code you were given with calls to the state machine, keeping behaviour identical except where you fixed a documented impossible state. Run the tests and report the real results.
- Do not change business behaviour silently. Every behaviour difference from the current code is listed with the reason.
- If existing data contains combinations of flags that map to no state, write the mapping query and stop for a decision before migrating it.
- Keep the change as small as possible around the state machine; do not refactor unrelated code.
- 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.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## State model
The Mermaid state diagram, then the transition table: from, event, guard, to, side effects, in or after transaction.
## Open questions
Table: question, proposed default, implemented as.
## Changes
One line per file.
## Tests
One line per test group and the real result of the run.
## Migration notes
How existing rows map to the new states, the data migration, and anything that needs a decision first.
````
---
## Implement OAuth or OIDC login
`implement-oauth-login` · prompt · Implementation · https://hermes-ide.com/prompts/implement-oauth-login
Implements login with an OAuth 2 or OpenID Connect provider, covering flow choice, PKCE, state and nonce, token storage, sessions and logout. Use when adding social or SSO login.
````markdown
Current best practice (OAuth 2.0 Security Best Current Practice, RFC 9700) is the authorization code flow with PKCE for every client type, including confidential server apps; the implicit flow and the password grant are deprecated. Login bugs are rarely in the happy path: a missing or unchecked `state` enables login CSRF, a missing `nonce` check allows token replay, ID tokens accepted without checking issuer, audience, expiry and signature let anyone forge a login, access tokens stored in browser local storage are exposed to any XSS, and logout that only clears the app cookie leaves the provider session alive. OAuth alone (for example GitHub) gives authorization, not identity; identity needs OIDC's ID token or a trusted user-info call. A maintained, certified client library beats hand-rolled protocol code.
Implement login for:
[STACK]
1. If the app type or framework is unclear, ask once and stop. Read the existing auth and session code if you can, and fit into it.
2. **Flow choice.** Authorization code with PKCE (S256). For a single-page app, prefer a backend-for-frontend that holds tokens server-side and gives the browser an HttpOnly session cookie; explain the trade-off if the user insists on tokens in the browser. For native and CLI apps, use the system browser with a loopback or claimed redirect URI, never an embedded web view. Say whether the provider is OIDC or OAuth-only and how identity is established.
3. **Provider setup.** Exact redirect URIs per environment, scopes (minimal: `openid email profile` for OIDC), and which values are secrets. Use discovery (`.well-known/openid-configuration`) where supported.
4. **Code**, using a maintained library for the stack (name it and why):
- Start login: generate `state`, `nonce` and the PKCE verifier, store them server-side or in a short-lived, signed, HttpOnly cookie bound to the browser, then redirect. That cookie must survive the return trip: `SameSite=Lax` works for the default query response mode, but a `form_post` response is a cross-site POST and needs `SameSite=None; Secure` on the transaction cookie only.
- Callback: check `state`, exchange the code with the verifier, validate the ID token (signature through the provider's JWKS, `iss`, `aud`, `exp`, `nonce`), and handle the error parameter.
- Account linking: key users by issuer plus subject (`iss` + `sub`), never by email alone; only trust email if the provider marks it verified, and decide explicitly how to link an existing local account.
- Session: create the app session with a rotated session id, cookies `HttpOnly`, `Secure`, `SameSite=Lax` (or stricter), and a sensible lifetime. Store refresh tokens encrypted server-side only if the app calls provider APIs offline.
- Logout: clear the app session, and use the provider's RP-initiated logout where the product needs single sign-out.
5. **Tests.** State mismatch, nonce mismatch, expired or wrong-audience ID token, provider error callback, a first login creating the user, and a returning login linking to the same user. Mock the provider at the HTTP boundary or use a local test identity provider.
- Never implement the implicit flow or the password grant, and never put client secrets in front-end or mobile code.
- Never store access or refresh tokens in local storage or session storage.
- Use the library's documented API; if you are unsure of a function name or option for the version in use, say so rather than guessing.
- Do not invent client ids, secrets or tenant ids; use environment variables with placeholder names.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Flow choice
Short justification.
## Provider setup
A table: setting, value per environment, secret (yes or no).
## Code
Code blocks with file paths.
## Security checklist
Checkboxes covering every item in step 4.
## Tests
Code blocks with file paths, then the real result of running them, or a plain statement that they were not run.
## Open questions
Numbered, or "None".
````
---
## Implement secure file uploads
`implement-file-upload` · prompt · Implementation · https://hermes-ide.com/prompts/implement-file-upload
Implements secure file uploads with direct-to-storage signed URLs, type and size validation, a malware-scan hook, safe naming and orphan cleanup. Use for backends accepting user files.
````markdown
File uploads are a classic source of breaches and outages. Typical failures: trusting the file extension or the client's Content-Type, so an HTML or SVG file with script is served from the app's own domain; using the user's file name in the storage path (path traversal, overwrites, leaking names); streaming large files through the app server until it runs out of memory; signed upload URLs with no size limit or a long expiry; files that are uploaded but never attached to anything, piling up forever; and serving uploads publicly when they should be private. A sound design uploads straight to object storage with short-lived, constrained credentials, validates the actual bytes after upload, quarantines until scanned, and only then makes the file available.
Implement file uploads for this use case:
[USE_CASE]
Storage: s3-compatible
1. Read the repo's storage client, auth, models, background jobs and config, and reuse them. If the allowed file types, maximum size or who may read the files are not clear from the use case, ask before implementing.
2. Implement this flow:
1. **Request:** the client asks the API for an upload, sending the intended file name, size and declared type. The API checks authorization, the allowed type list and the size, creates an upload record in a pending state, and generates a random object key under a quarantine prefix (for example `pending/`); never use the user's file name in the key.
2. **Upload:** the API returns a short-lived signed URL (minutes, not hours) that is constrained as tightly as the storage allows: a presigned POST policy with a content-length range and fixed content type for S3-compatible stores, or the equivalent conditions on other providers. For files above the provider's single-request limit, or large files on mobile networks, use multipart or resumable uploads.
3. **Confirm:** the client tells the API the upload finished (or a storage event notifies it). The API checks the object exists and its real size matches.
4. **Validate and scan:** a background job reads the file's magic bytes to detect the real type and rejects mismatches, enforces content rules (image dimensions, page count, CSV row limit), calls a malware-scan hook (an interface with a no-op implementation for development and a place to plug in a scanner), and for images re-encodes them to strip metadata such as GPS location and neutralise polyglot files.
5. **Promote:** clean files move to the final prefix and the record becomes available; failed files are deleted or kept in quarantine with the reason, and the user gets a clear error.
3. Serve files safely: private by default with short-lived signed download URLs after an authorization check; `Content-Disposition: attachment` for anything that is not a safe inline type; the correct `Content-Type` plus `X-Content-Type-Options: nosniff`; and ideally a separate domain for user content. Store the original file name only as sanitised metadata for display.
4. Clean up orphans: a storage lifecycle rule that expires objects under the pending prefix after a day or so, plus a scheduled job that removes pending records with no object and objects whose owning record was deleted.
5. Configure CORS on the bucket for the web origin only, with just the methods and headers the upload needs.
6. Write tests: the request endpoint rejects disallowed types, oversize files and unauthorised users; the signed URL has the expected constraints and expiry; the validation job rejects a file whose magic bytes do not match its declared type; a scan failure leaves the file unavailable; promotion makes it available; download requires authorization; and cleanup removes expired pending uploads. Use a local emulator or a fake storage client; no real cloud calls.
7. Run the tests and linter and report the real results.
- Never accept SVG, HTML or other active content for inline display unless the use case requires it; if it does, say how it will be sanitised or served from an isolated domain.
- Never trust the client's file name, extension or Content-Type for security decisions.
- Never make the bucket public to make uploads work.
- Do not claim a malware scanner is integrated if only the hook exists; say what is left to wire up.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Flow
A Mermaid sequence diagram of request, upload, confirm, scan, promote and download.
## Changes
One line per file.
## Security checks
Table: threat, control, where it is implemented.
## Tests
One line per test and the real result of the run.
## Configuration
Allowed types, size limits, URL expiries, prefixes, lifecycle rule and CORS settings.
## Operational notes
What to monitor (quarantine backlog, rejection rate, scan failures) and what is still to wire up.
````
---
## Implement transactional email
`implement-transactional-email` · prompt · Implementation · https://hermes-ide.com/prompts/implement-transactional-email
Implements transactional email with templates, a provider integration, retries, bounce and complaint handling, and deliverability settings. Use when an app must send receipts, resets or alerts.
````markdown
Transactional email fails silently: a reset link that lands in spam, a receipt sent twice because a request retried, an email sent for an order whose transaction then rolled back, a provider outage that drops messages, or a bounced address the app keeps mailing until the provider suspends the account. Since 2024, large mailbox providers require SPF, DKIM and a DMARC policy for bulk senders, alignment between the visible From domain and the signing domain, and one-click unsubscribe for marketing mail. Transactional and marketing mail belong on separate streams or subdomains so one cannot damage the other's reputation.
Implement transactional email for:
[STACK]
1. If the stack is unclear, ask once and stop. Read existing mail, job and config code if you can.
2. **Design.** Send from a background job, never inside the web request. Enqueue the email in the same database transaction as the business change (an outbox table, or the job system's transactional enqueue) so no email is sent for a rolled-back change and none is lost. Give each message an idempotency key derived from the event (for example `order-receipt:`) and skip duplicates. Wrap the provider behind a small interface so tests use a fake and the provider can change.
3. **Templates.** One template per email with HTML and plain-text parts, variables escaped, a clear subject, the sender name, and localisation hooks if the app is multilingual. Keep secrets and long-lived tokens out of URLs except single-use, expiring tokens (password reset, magic link) that are invalidated on use.
4. **Sending and retries.** Use the provider's official SDK or HTTP API. Retry transient failures (timeouts, 429, 5xx) with exponential backoff and jitter up to a limit, then mark the message failed and alert. Do not retry permanent failures (invalid address, suppressed recipient). Log message id, template, recipient hash and status, never the full body of sensitive emails.
5. **Bounces and complaints.** Handle the provider's bounce, complaint and delivery webhooks with signature verification. Hard bounces and complaints add the address to a suppression list checked before sending; soft bounces are retried by the provider. Show a "we could not reach your email" state where it matters (password reset).
6. **Deliverability setup.** List the DNS records to create (SPF include, DKIM keys, DMARC starting at `p=none` with reporting and a plan to move to `quarantine` or `reject`, a custom return-path domain for alignment), a dedicated sending subdomain for transactional mail, and when a marketing stream needs one-click unsubscribe headers.
7. **Tests.** Unit tests with the fake provider for rendering, idempotency and suppression; a test that no email is sent when the transaction rolls back; and a local mail catcher for manual checks.
- Use the provider's documented API; if unsure of a method, header or webhook field for the version in use, say so rather than guessing.
- Do not invent DNS values, API keys or domains; use placeholders such as `mail.example.com`.
- Never send marketing content through the transactional stream.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Design
Bullets plus a short sequence of the send flow.
## Templates
One template in full as an example, then a table of the others with subject and variables.
## Code
Code blocks with file paths: interface, provider adapter, job, outbox or enqueue.
## Bounces and complaints
Webhook handler code and suppression logic.
## Deliverability setup
A table of DNS records with placeholder values and purpose.
## Tests
Code blocks with file paths, then the real result of running them, or a plain statement that they were not run.
## Open questions
Numbered, or "None".
````
---
## Integrate a third-party API
`integrate-third-party-api` · prompt · Implementation · https://hermes-ide.com/prompts/integrate-third-party-api
Implements a typed client for a third-party HTTP API from its docs, with auth, pagination, retries, rate limits and a test fake. Use when wiring an external service into your code.
````markdown
Integrations break in production, not in the demo. The token expires mid-batch, page 2 never loads because the cursor was ignored, a 429 storm turns into a retry storm, a non-idempotent POST is retried and charges twice, a new field in the response crashes a strict parser, and the tests hit the real API. The client you write must hold up against all of that, and must not invent endpoints or fields the docs do not describe.
Build a client for the operations below in [LANGUAGE] (if empty, use the repo's main language and its existing HTTP library).
Documentation: [API_DOCS]
Operations needed: [OPERATIONS]
1. Read the docs (fetch them if given a URL). Extract, with section references: base URL and versioning, auth scheme, each needed operation's method, path, parameters and response fields, the pagination style, rate limits and their headers, error format, and idempotency support. List anything the docs leave unclear under Doc gaps; do not fill gaps with guesses.
2. Look for an existing HTTP wrapper, config loader, logger and error types in the repo and reuse them.
3. Design a small interface: one method per operation, typed inputs, typed results, and a typed error hierarchy (auth, not found, validation, rate limited, server, transport) that keeps the status code and the provider's request id.
4. Implement:
- **Auth:** credentials from configuration, never hard-coded or logged. For OAuth, refresh before expiry and let only one refresh run at a time.
- **Timeouts** on every request, for both connect and read.
- **Retries** only for transport errors, 429, 502, 503 and 504, and only for idempotent methods or requests carrying an idempotency key. Use exponential backoff with full jitter, honour `Retry-After`, and cap both the attempts and the total time.
- **Rate limits:** a client-side limiter sized to the documented limit, plus backing off when the rate-limit headers say so.
- **Pagination:** a lazy iterator that follows the documented cursor, link header or offset, with a stop condition and a guard against a cursor that repeats.
- **Parsing:** model only the fields you use, ignore unknown fields, and parse dates and money explicitly (money as decimal or minor units, never float).
5. Write a test fake implementing the same interface for callers' tests, and transport-level tests with canned responses for: success, multi-page listing, 429 with `Retry-After` then success, a 5xx retried then succeeding, a non-retryable 4xx, 401, and a malformed body.
6. Run the tests. Unit tests must make no real network calls.
- Every endpoint, field and header you use must appear in the docs. If one you need does not, stop and report it.
- Redact authorization headers, tokens and personal data from logs and error messages.
- Do not add an SDK or HTTP dependency the repo does not already use unless the docs require it. If the provider publishes an official SDK, mention it in one line under Operational notes.
- 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.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Doc gaps
What the docs leave unclear and the assumption you made for each, or "None".
## Interface
The public methods with signatures, one line of purpose each.
## Changes
One line per file.
## Tests
One line per test: the scenario it covers.
## Configuration
| Setting | Env var | Default | Required |
## Operational notes
Rate limits, retry budget and worst-case latency per call, and what to monitor.
````
---
## Integrate payments
`integrate-payments` · prompt · Implementation · https://hermes-ide.com/prompts/integrate-payments
Implements a payment integration with the provider's official SDK, covering checkout, webhooks, idempotency, refunds and reconciliation. Use when adding one-time payments or subscriptions.
````markdown
Payment bugs cost money or trust: double charges from retried requests, orders marked paid because the browser hit a success URL, fulfilment that never happens because a webhook was missed, refunds recorded locally but not at the provider, and amounts in floating point. The provider is the source of truth for payment state; the app learns about it from verified webhooks, processes each event idempotently and reconciles daily. Hosted checkout pages or provider UI elements keep card data off the app's servers and reduce PCI DSS scope to the simplest self-assessment level.
Implement a one-time payment integration for:
[STACK]
1. If the provider or stack is missing, ask once and stop. Read the existing order, account and user models if you can.
2. **Design.** Use the provider's hosted checkout or embedded UI components, never raw card fields. Model payment state in the app as a small state machine (for one-time: pending, paid, failed, refunded or partially refunded; for subscriptions: trialing, active, past due, canceled, plus the provider's customer and subscription ids). Store amounts as integer minor units with an ISO 4217 currency code, and compute prices on the server, never from the client.
3. **Checkout.** Server endpoint that creates the checkout or payment intent with the official SDK, sends an idempotency key derived from the order or request, attaches the app's order or user id as metadata, and returns what the client needs. The success redirect only shows a "processing" or confirmation page; it never marks the order paid.
4. **Webhooks.** An endpoint that reads the raw body, verifies the signature with the provider's SDK and the webhook secret, rejects stale timestamps, stores the event id to skip duplicates, acknowledges quickly with a 2xx and does the work in a background job, tolerates out-of-order events by fetching the current object from the provider when order matters, and updates state through the state machine. List the event types to handle for one-time (for subscriptions include payment failure and dunning, renewal, plan changes, cancellation and the end of a trial).
5. **Refunds and reconciliation.** Refunds go through the provider API with an idempotency key and are confirmed by webhook. A daily job compares the provider's balance transactions or payouts with the app's records and reports mismatches. Handle disputes and chargebacks as events.
6. **Tests.** Use the provider's test mode, test cards and its CLI or fixtures for sending signed test webhooks. Cover the happy path, a declined payment, a duplicate webhook, an out-of-order webhook, an invalid signature, a refund, and (for subscriptions) a failed renewal.
- Use the provider's official SDK and its current documented API. If you are unsure of a method, event name or field for the SDK version in use, say so and point to the docs rather than guessing.
- Never log full card data, payment method details or webhook secrets; never put secret keys in client code.
- Never use floating point for amounts, and never trust amounts, prices or currencies sent by the client.
- Taxes, invoicing rules and refund policy are business and legal decisions; ask, or leave a marked hook, rather than inventing them.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Design
State machine (Mermaid `stateDiagram-v2`), data model changes, and the end-to-end flow in numbered steps.
## Code
Code blocks with file paths for checkout and models.
## Webhooks
Code with file paths, then a table of event types and the state transition each causes.
## Refunds and reconciliation
Code or job outline.
## Tests
Code with file paths, then the real result of running them, or a plain statement that they were not run.
## Go-live checklist
Checkboxes: live keys in the secrets store, webhook endpoint registered in live mode, idempotency verified, alerts on webhook failures, reconciliation job scheduled, refund policy confirmed.
## Open questions
Numbered.
````
---
## Mobile engineer
`mobile-engineer` · persona · Implementation · https://hermes-ide.com/prompts/mobile-engineer
Acts as a mobile engineer who designs for flaky networks, battery and memory limits, platform conventions and app-store releases. Use for iOS, Android or cross-platform work.
````markdown
From now on, work as this persona: Mobile engineer.
You are a mobile engineer who has shipped apps to real users on both major platforms. You know that a mobile release cannot be rolled back like a web deploy: old versions stay installed for months, reviews take time, and users update when they feel like it. You design for phones in pockets: interrupted sessions, weak signal, low battery, small screens and limited memory.
How you work:
- Identify the stack and its conventions first: native iOS (Swift, SwiftUI or UIKit), native Android (Kotlin, Jetpack Compose or Views), or cross-platform (React Native, Flutter). Follow the project's architecture and the platform's guidelines; a feature should feel native on each platform, not like a copy of the other.
- Treat the network as unreliable: timeouts and retries with backoff, requests that are safe to repeat, optimistic UI where appropriate, local persistence for anything the user created, and clear offline and sync states. Test on a throttled or lossy connection.
- Respect the lifecycle: the app can be backgrounded, killed and restored at any point. Save and restore state, cancel work tied to a screen when it goes away, and use the platform's background work APIs within their limits.
- Be frugal: avoid work on the main thread, keep scrolling smooth, size and cache images, batch network calls, and avoid polling, wake-ups and location or sensor use that drain the battery. Measure with the platform profilers rather than guessing.
- Ship for the long tail: support the agreed minimum OS versions, a range of screen sizes and densities, dynamic type and font scaling, dark mode, right-to-left layouts, and the platform screen readers.
- Plan releases: feature flags or remote config to turn features off without a release, a server API that stays compatible with every supported app version, forced-update paths only as a last resort, staged rollouts, crash and ANR monitoring, and release notes that follow store guidelines.
- Handle permissions and privacy with care: ask in context, degrade gracefully when denied, keep secrets out of the app bundle, store tokens in the platform's secure storage, and declare data use accurately for store privacy labels.
- Ask before changing signing, provisioning or release configuration, bumping app versions, or uploading builds to a store or test track.
- Test on real devices, including an older, low-end one, as well as simulators and emulators, and run the UI and unit test suites before calling something done.
What you flag:
- Network or disk work on the main thread, memory leaks from retained screens or listeners, and unbounded image caches.
- API changes that break older app versions still in use, and features with no remote off switch.
- Background tasks that will be killed or rejected by the platform, and excessive wake-ups or location use.
- Secrets, API keys or signing material in the repository or app bundle, and tokens in plain storage.
- Missing accessibility labels, fixed font sizes, and touch targets below platform minimums.
- Anything likely to fail app-store review: undeclared permissions or data collection, private APIs, or payment flows that break store rules.
Your habits:
- You say which platform and OS versions a recommendation applies to, and when behaviour differs between iOS and Android.
- You consider the user on an old phone with a weak connection before the one on the newest device.
- You treat every release as permanent and design the rollback as a server-side or flag change.
- You ask for the minimum supported versions and the analytics on installed versions when they matter to a decision.
````
---
## Put a change behind a feature flag
`add-feature-flag` · prompt · Implementation · https://hermes-ide.com/prompts/add-feature-flag
Wraps new behaviour behind a feature flag with a safe default, a kill switch, tests for both paths and a cleanup ticket. Use when shipping a risky change incrementally.
````markdown
A flag is only a safety net if turning it off really restores the old behaviour, and only cheap if it is removed once the rollout ends. Flags go wrong when the default is the new code, when an outage of the flag service flips everyone to the untested path, when the check is scattered across a dozen `if` statements that drift apart, when a schema change makes the old path impossible, or when nobody owns the removal and the flag lives for years.
Put this change behind a feature flag:
[CHANGE]
Flag system: existing system or env var (with the default, use the flag system the repo already has; if it has none, use an environment variable read through the existing config layer).
1. Find how the repo already defines, names, reads and tests flags. Follow that exactly, including the naming convention.
2. Classify the flag (release toggle, ops kill switch, experiment or permission) and choose its lifetime from that.
3. The default and every failure mode, such as the flag service being unreachable or the flag missing, must evaluate to the **old** behaviour.
4. Evaluate the flag once per request or unit of work, at the highest sensible point, and branch there. Do not scatter checks through the call tree or evaluate inside hot loops. Pass the decision down if deeper code needs it. For percentage rollouts, evaluate against a stable targeting key (user or account id) so one user does not flip between paths from one request to the next.
5. Keep both paths complete and independently correct. If the change touches persisted data or a schema, make sure both paths can read what the other writes (expand then contract). If they cannot, say so plainly: a flag cannot protect that part.
6. Record which path ran, using the project's logging or metrics conventions, so the rollout can be watched.
7. Tests: the old path with the flag off, the new path with the flag on, and the old path when flag evaluation fails. Reuse the existing test helpers for overriding flags.
8. Run the tests.
- Do not change the old path's behaviour, even to tidy it.
- Do not use a flag to gate a security fix; say so if the change is one.
- Targeting rules (percentages, user segments) only if the flag system supports them; do not build your own.
- Do only what was asked. If you notice something else worth changing, mention it in one line at the end instead of changing it.
- Keep the change as small as it can be while still being correct.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Flag
| Name | Type | Default | Evaluated at | Failure behaviour | Suggested expiry |
## Changes
One line per file.
## Tests
One line per test: which path and condition.
## Rollout and kill switch
Numbered steps to enable gradually, the signals to watch, and exactly how to turn it off without a deploy (or a warning if the chosen system needs a deploy).
## Cleanup ticket
Ready to paste: title, owner placeholder, due date placeholder, every code location to delete, and the tests to remove or keep.
````
---
## Scaffold a new service or library
`scaffold-new-service` · prompt · Implementation · https://hermes-ide.com/prompts/scaffold-new-service
Creates the minimal production-ready skeleton for a new service or library (layout, config, lint, tests, CI, README) and justifies each choice. Use when starting a new repo or package.
````markdown
Starter templates fail in two directions. Some are a hello-world with no tests, CI or config handling, so every production concern gets bolted on later in a different style. Others ship an ORM, a message bus, three layers of abstraction and twenty dependencies for a service that has one endpoint. The goal is the smallest skeleton that is safe to deploy and easy to grow, where every file earns its place.
Scaffold a new [LANGUAGE_OR_FRAMEWORK] project:
[DESCRIPTION]
Deploy target: [DEPLOY_TARGET] (if empty, treat it as undecided and keep the skeleton deploy-neutral).
1. If the description does not say whether this is a long-running service, a job, a function or a library, ask that one question and stop.
2. Use the ecosystem's official generator where one is standard (`cargo new`, `go mod init`, `uv init`, `npm init`, the framework CLI), then trim what it adds that the project does not need. Follow the ecosystem's conventional layout.
3. Include only these, adapted to the ecosystem:
- A manifest with a lockfile and a pinned runtime or toolchain version.
- The ecosystem's standard formatter and linter (ruff, eslint with prettier, golangci-lint, rustfmt with clippy) with default rules plus anything the description requires.
- A test runner with one real test of real behaviour.
- Configuration read from environment variables, validated at start-up, failing fast with a clear message. Include a `.env.example` with no secrets.
- For services: structured logging, a health endpoint and a separate readiness endpoint, and graceful shutdown on SIGTERM.
- A CI workflow stub that installs from the lockfile, lints, type checks, tests and builds, on pull requests and the main branch.
- If the target is a container: a multi-stage Dockerfile with a pinned base image that runs as a non-root user, plus a `.dockerignore`.
- `.gitignore`, `.editorconfig` and a README covering what it is, how to run, test and configure it (a table of environment variables), and how it deploys.
4. Run install, lint, test and build (and start the service if it is one, then hit the health endpoint). Fix anything that fails.
- No database layer, auth, queue, DI container or generic "utils" module unless the description requires it.
- Do not choose a licence; leave a README note asking the owner to add one.
- Pin versions you know are current and supported. If unsure of the latest version of a tool, say so instead of inventing a version number.
- Use no placeholder code that pretends to work. Mark intentional stubs with a TODO naming the owner decision they wait on.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Tree
The file tree.
## Files
Each file in its own code block, headed by its path. Generated lockfiles are summarised in one line, not printed.
## Why each piece
| File or tool | Why it is here | What to change later |
## Left out on purpose
Common additions you did not include and when to add them.
## Verification
Each command run and its actual result.
````
---
## Write a command-line tool
`write-cli-tool` · prompt · Implementation · https://hermes-ide.com/prompts/write-cli-tool
Designs and implements a small command-line tool with subcommands, help text, exit codes, config precedence and tests. Use when turning a manual workflow into a reusable command.
````markdown
A good CLI behaves the way experienced terminal users expect without reading its source. It prints help, keeps data on stdout and messages on stderr, returns exit codes that scripts can branch on, works in a pipe, asks before destroying anything, and takes configuration from flags, environment and files in a predictable order. Most quick tools get two of these right and surprise their users with the rest.
Build a command-line tool in python for this purpose:
[PURPOSE]
Planned commands: [COMMANDS] (if empty, design the smallest command set that covers the purpose).
1. If the purpose is too vague to name the commands and their inputs, ask up to 3 questions and stop.
2. Design the command surface before writing code: commands as verbs (`tool sync`, `tool list`), arguments and flags per command, defaults, output, and exit codes. Use `-h/--help` and `--version` everywhere. Add `--json` for any command whose output another program might read, and `--dry-run` plus `--yes` for anything destructive.
3. Use the ecosystem's standard parser, or the one the repo already uses: argparse or Typer for Python, Cobra or the standard `flag` package for Go, clap for Rust, Commander or `util.parseArgs` for Node.
4. Configuration precedence, highest first: flags, then environment variables with a tool prefix (`TOOL_*`), then a project config file, then a user config file under the platform config directory (`$XDG_CONFIG_HOME` on Linux), then defaults. Document it in `--help` and in the README.
5. Behaviour rules:
- Exit codes: 0 success, 1 failure, 2 usage error. Add specific codes only if callers need to tell failures apart, and document them.
- Data to stdout and progress, warnings and errors to stderr. Errors say what failed and what to do next.
- Detect a non-interactive terminal: no colours, spinners or prompts when piped. Respect `NO_COLOR`. Accept `-` for stdin where a file is expected.
- On Ctrl-C, stop cleanly, leave no partial files, and exit 130.
6. Write tests: argument parsing per command, exit codes for success, usage error and runtime failure, `--json` output shape, and one end-to-end run in a temporary directory. Do not test against the real network or the user's home directory.
7. Add a README section with installation, a usage example per command, the config precedence and the exit codes. Run the tests and a `--help` smoke check.
- Keep it small: no plugin system, no global state, and no dependencies beyond the parser and what the purpose truly needs.
- Never print secrets, including in `--verbose` or debug output.
- Keep business logic in plain functions the CLI layer calls, so it can be tested without a subprocess.
- Before saying the work is done, run the check that proves it (tests, build, type check or the command the user gave) and report the real result.
- If you could not run a check, say so plainly and say which one.
## Command surface
| Command | Arguments and flags | Output | Exit codes |
Then the config precedence in one line.
## Files
A tree, then each file in its own code block.
## Tests
One line per test: what it proves.
## Decisions
Choices you made that the purpose did not dictate, one line each.
## Verification
Commands run (tests, `--help`) and their actual results.
````
---
## Write a regular expression
`write-regex` · prompt · Implementation · https://hermes-ide.com/prompts/write-regex
Builds a regular expression from plain-language intent and example strings, explains each part and lists the edge cases it accepts or rejects. Use when you need a tested pattern.
````markdown
Regexes look right and fail quietly. The common faults are a missing anchor that lets the pattern match inside a longer string, a feature the target engine does not support, a `$` that also matches before a trailing newline, nested quantifiers that backtrack catastrophically on hostile input, and a pattern that was never actually run against the examples it was built from.
Write a javascript regular expression for: [INTENT]
Must match:
[SHOULD_MATCH]
Must not match:
[SHOULD_NOT_MATCH]
1. Decide the mode from the intent: full-string validation (anchor both ends), search within text (word boundaries or lookarounds), or extraction (capture groups, named if the engine supports them).
2. Respect the engine:
- javascript: use the `u` flag for Unicode; `\d` and `\w` are ASCII-only.
- python: use `re.fullmatch` for validation, or `\Z` rather than `$`; in Python 3, `\d` and `\w` match Unicode unless you pass `re.ASCII`.
- pcre: `$` matches before a final newline; use `\z` for a strict end. Possessive quantifiers and atomic groups are available.
- go: RE2 has no lookaround and no backreferences. Rewrite the logic without them, or say that code must do that part.
- posix: ERE only. No `\d`, lazy quantifiers or lookaround; use bracket expressions like `[0-9]` and `[[:alpha:]]`.
3. Prefer the simplest pattern that passes every example. Avoid nested quantifiers over overlapping classes such as `(a+)+` or `(\w|\d)*`.
4. Test it. Walk every example through the pattern and record the result. If a code tool is available, run them for real and say so. If any example fails, fix the pattern and repeat.
5. Probe the edges the examples do not cover: empty string, leading and trailing whitespace, newlines, Unicode letters and digits, very long input, and near-misses of the valid shape.
6. If the examples contradict the intent or each other, say which ones and which reading you followed.
- Never claim an example passes unless you checked it.
- If a regex is the wrong tool (nested structures, full email RFC compliance, real date validity such as 31 February, HTML), say so in one sentence, give the pragmatic pattern anyway, and name what code must check.
- Show the pattern both as a literal and as an escaped string for the language when they differ.
- 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.
## Pattern
A code block with the pattern and flags, then one line on the matching mode.
## How it works
| Part | Meaning |
## Test results
| Input | Expected | Result |
Every given example, then the edge cases you added.
## Edge cases
Inputs it accepts that someone might not expect, and inputs it rejects that might be valid. One line each.
## Usage
A 3 to 6 line snippet in the language of the chosen flavor (shell `grep -E` for posix).
Abridged to two sections; a real answer includes all five.
Intent: a hex colour in CSS, full-string. Should match: `#fff`, `#A1B2C3`. Should not match: `fff`, `#abcd`, `#12345g`. Flavor: javascript.
## Pattern
```
/^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i
```
Full-string validation.
## Edge cases
- Rejects 4- and 8-digit forms with alpha (`#abcd`, `#11223344`), which CSS Color Level 4 allows. Add `|[0-9a-f]{4}|[0-9a-f]{8}` if you need them.
````
---
## Write a robust shell script
`write-shell-script` · prompt · Implementation · https://hermes-ide.com/prompts/write-shell-script
Writes a portable shell script with strict mode, argument parsing, a dry-run flag, clear errors and idempotent steps. Use when automating a chore you will run more than once.
````markdown
Shell scripts written in a hurry fail in predictable ways: an unset variable expands to an empty string and `rm -rf` hits the wrong directory, a failed command in a pipeline is ignored, a filename with a space splits in two, GNU-only flags break on macOS, and a second run duplicates what the first run did. The person needs a script they can run twice, read in a year, and trust in a dry run first.
Write a bash script for this goal, to run on any:
[GOAL]
1. If the goal leaves out something that decides what gets deleted, overwritten or sent (which paths, which hosts, whether it needs root), ask up to 3 questions and stop. Otherwise state your assumptions and continue.
2. Choose the strict-mode preamble for the shell:
- bash: `set -Eeuo pipefail`, a `trap` that reports the failing line on ERR, and a cleanup trap on EXIT.
- zsh: `emulate -L zsh` and `setopt ERR_EXIT NO_UNSET PIPE_FAIL`.
- posix-sh: `set -eu`. Do not rely on `pipefail`, arrays, `[[ ]]`, `local` or `$'...'`; check pipeline stages explicitly where failure matters.
- powershell: a `param()` block with `[CmdletBinding(SupportsShouldProcess)]`, `Set-StrictMode -Version Latest` and `$ErrorActionPreference = 'Stop'`; check `$LASTEXITCODE` after native commands.
3. Parse arguments: `-h/--help` (usage to stdout, exit 0), long options, required values validated up front, unknown options rejected with usage on stderr and exit 2. In bash and zsh use a `while`/`case` loop so long options work; `getopts` handles only short ones.
4. Add a dry-run mode (`--dry-run`, or `-WhatIf` in PowerShell) that prints every state-changing command, safely quoted, instead of running it. Route all side effects through one helper so dry run cannot miss one.
5. Make each step idempotent: test before acting, use `mkdir -p` and `ln -sfn`, check before appending to a file, and write files to a temp file on the same filesystem and then move it into place.
6. Fail clearly: check required tools with `command -v` at start-up, print errors to stderr with the script name and a fix, and use distinct non-zero exit codes for distinct failures.
7. Check the script against ShellCheck (or PSScriptAnalyzer) rules in your head, and fix anything they would flag.
- Quote every expansion. Use `--` before user-supplied paths. Never parse `ls`; use `find ... -print0` with `while IFS= read -r -d ''` (bash/zsh) or a glob loop.
- Guard destructive commands against empty variables with `${VAR:?}`, and never `rm -rf` a path built from unchecked input.
- Portability for macOS and Linux: macOS ships bash 3.2 (no associative arrays, `mapfile` or `${var,,}`) and BSD tools (`sed -i ''`, no `date -d`, no `grep -P`, different `stat` flags). If `target_os` is `any` or `macos`, avoid these or branch on `uname` explicitly.
- No secrets in the script, arguments or logs. Read them from the environment or a file with restricted permissions.
- Never fetch remote code and execute it.
- If the job is better done by an existing tool (rsync, a package manager, a cron entry), say so in one line, then write the script anyway.
## Assumptions
Bullets, or "None".
## Script
One complete code block with a header comment: purpose, usage line, exit codes.
## Usage
Two or three example invocations, including a dry run.
## What it changes
Every file, directory, service or remote system it creates, modifies or deletes.
## How to test it
Steps to try it safely: dry run first, then a throwaway directory or container.
## Limitations
What it does not handle, one line each.
````
---
## Write a streaming file parser
`write-file-parser` · prompt · Implementation · https://hermes-ide.com/prompts/write-file-parser
Writes a streaming parser and validator for CSV, log, fixed-width or custom text files that reports malformed records with line numbers instead of crashing. Use for messy input files.
````markdown
Real input files are never as clean as the sample suggests. Quoted CSV fields hold commas and newlines, so a line is not a record. Files arrive with a byte-order mark, CRLF endings, Latin-1 bytes, a trailing delimiter or a truncated last line. A parser that throws on the first bad record and loses the line number makes someone grep a 2 GB file by hand. The parser must stream, keep going, and say exactly what was wrong and where.
Write a parser and validator in [LANGUAGE] (if empty, pick one suited to the job and say why) for files like this sample:
[SAMPLE]
Known format notes: [FORMAT_NOTES]
1. Infer the format and write it down as a spec before coding: record boundary, field delimiter or column positions, quoting and escaping, header row, encoding, line endings, and each field's name, type, required or optional status, and allowed values or ranges. Mark each item as stated (from the notes), observed (from the sample) or assumed.
2. If a structural question cannot be answered from the sample and notes (for example, whether fixed-width columns count bytes or characters, or whether a field may contain the delimiter), list it, state the assumption you will code to, and continue.
3. Implement a streaming parser that reads incrementally, uses constant memory, and yields one result per record: either a typed record or an error.
- For CSV-like formats, use the language's real CSV library rather than splitting on commas, and track the physical line where each record starts.
- For log lines, use one anchored pattern per line type, and join continuation lines such as stack traces onto their record.
- For fixed-width formats, slice by the documented unit and trim as the spec says.
4. Validate each record against the spec: field count, types, ranges, enums, required fields, and cross-field rules from the notes. Parse dates with explicit formats and time zones, and decimals without float rounding when they are money.
5. Errors must carry the line number, field name or column, a reason a human can act on, and a truncated excerpt of the raw text. Keep going after errors. Offer a strict mode that stops at the first error and an option to stop after N errors.
6. Handle these without crashing: an empty file, a header only, blank lines, a byte-order mark, CRLF, invalid bytes for the encoding (report the offset), a missing final newline, extra or missing columns, and a truncated last record.
7. Write tests from the sample plus one crafted bad line for each error type, and a test that streams a large generated input without loading it all into memory.
- Never silently coerce or drop a bad value. It is either valid or reported.
- Keep the parsing core free of I/O so it can be tested with strings.
- Do not echo whole records containing personal data in errors; truncate excerpts.
- 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.
## Format spec
| Field | Position or column | Type | Required | Rule | Source (stated / observed / assumed) |
Then record boundary, encoding and quoting in a few lines.
## Questions and assumptions
Numbered, or "None".
## Code
Complete code in one or more code blocks.
## Tests
Code, then one line per test explaining what it proves.
## Sample run
What the parser yields for the given sample: the record count, then each error with its line number and reason.
````