hermes

Scaffold a new service or library

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.

context

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.

task

Scaffold a new project:

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.
  1. Run install, lint, test and build (and start the service if it is one, then hit the health endpoint). Fix anything that fails.
constraints
  • 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.
output format

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.

2 required values still a placeholder; the assistant will ask for them.

details

kind
Prompt: a task you run by name to get one finished thing back
domain
Software engineering
category
Implementation
level
Intermediate
depth
Specific
made for
Software engineer, Backend engineer, Tech lead / staff engineer, DevOps / platform engineer
needs
file-write, shell
risk
runs-commands
version
v1.0.0 · incubating
reviewed
2026-10-02
works in
Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md

Edit on GitHubReport a problem

use in

Hodios CLI
npx @hermes-hq/hodios install scaffold-new-service --target claude-code
Agent Skills
npx skills add hermes-hq/hodios-dist --skill scaffold-new-service -a claude-code
Add the Hodios marketplace (once)
claude plugin marketplace add hermes-hq/hodios-dist
Install the software-engineering plugin
claude plugin install hodios-software-engineering@hodios

The plugin brings every entry in this domain at once.

more in implementation

All of Implementation
PromptImplementation

Build a feature

Builds a feature from an idea rather than a full spec, asking the few questions that change the design, proposing a small plan, then implementing and testing it. Start here for new features.

build-a-feature
PersonaImplementation

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.

backend-engineer
PersonaImplementation

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.

frontend-engineer
PersonaImplementation

Game developer

Acts as a game developer who prototypes fast, tunes game feel through playtesting, keeps every system inside the frame budget and scopes ruthlessly to ship. Use for gameplay code in any engine.

game-developer
PromptImplementation

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.

implement-transactional-email
PromptImplementation

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.

integrate-payments