Skip to content

Build Recipe

The ordered, deterministic checklist for generating a new application of the standard shape. Every step is fixed; only steps 2 and 3 need app-specific authoring. Give an AI agent the copyable prompt below (or read it from the standards MCP bundle as doc://modules/build_recipe) and it can produce a complete app in one pass.

🚀 Quick start

1
2
3
# Copy the runnable skeleton (from the standards docs checkout)
cp -r <docs>/standards/src/templates/app apps/<your-app>
cd apps/<your-app>

Then follow the numbered steps in the prompt.

📋 Agent prompt (copyable)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# Build a new application from the Aetos Standards blueprint

You are coding a complete new backend application conforming to the Aetos
standard app blueprint. Execute every step in order. Only steps 2 and 3 use the
app-specific details provided by the user; everything else is deterministic.

Before writing any code, connect to the `standards` MCP server and read:
- `doc://nav` (the module list)
- `doc://modules/layering_rules` (the dependency rules)
- `doc://modules/genericity_matrix` (what is generic vs app-specific)
Then call `find_library` with capabilities like `db`, `di`, `routing`,
`ingestion`, `auth`, `docs`, `pipeline`, and note the libraries that already
exist. Never reimplement one.

1. **Scaffold** — copy `src/templates/app/` into `apps/<your-app>/`. Keep the
   package tree: `domain/`, `infra/`, `interfaces/`, `pipelines/`, `tests/`,
   `scripts/`, plus `pyproject.toml`, `openapi.yaml`, `config.py`, `init.py`,
   `main.py`, `worker.py`, `Dockerfile`, `docker-compose.yaml`, `.env.example`.

2. **Author the spec (app-specific)** — write `openapi.yaml`: resources,
   schemas, `operationId`s, security, and extension metadata. This is the
   contract and drives all routing.

3. **Write each CRUD slice (app-specific)** — per resource create the
   four-file slice: `models.py`, `ports/db.py`, `ports/service.py`, and
   optional `converters.py`. Follow the CRUD template.

4. **Wire the composition root** — in `init.py`, build leaf repositories, then
   dependent repositories, then services; add infra adapters (db, cache,
   stores, progress bus, fetchers). Expose `get_svc` overloads.

5. **Add routes** — create `interfaces/<resource>/routes.py` thin handlers
   bound to `operationId`s and re-export them in `interfaces/openapi.py`. Add
   the cache decorator to read endpoints.

6. **Bootstrap app and worker** — confirm `main.py` runs the OpenAPI-first app
   with its lifespan. If the app has long-running jobs, adapt `worker.py` to
   poll the job collection, run the pipeline, and publish progress.

7. **Add pipeline families (only if data-driven)** — create
   `pipelines/<family>/` with `abc.py`, `impl.py`, `pipeline.yaml`,
   `resources/`, and register the root. Add fixtures and a parity test.

8. **Add infrastructure only where needed** — prefer a library-backed adapter.
   Never hand-write what an internal library already provides.

9. **Tests** — integration tests with fakes at the HTTP edge; unit tests for
   domain and pipeline logic; a config-consistency test for rule-driven
   pipelines.

10. **Scripts and seeds** — operator scripts under `scripts/` using
    `init()` / `get_svc()` / `shutdown()`.

11. **Docs** — author GSDFC docstrings, generate `.pyi` stubs, mark the package
    `py.typed`, and build the docs.

**Definition of done:**
- `python -c "import main"` succeeds.
- `pytest` passes.
- The app serves every operation in the spec; the worker drains its queue.
- No domain module imports a web framework.
- No infrastructure was reimplemented that a library already provides.

🧭 Where the steps land

The steps map onto the layers as follows:

Step Package / file Depends on
1 · Scaffold whole templates/app/ —
2 · Spec openapi.yaml —
3 · CRUD slices domain/<resource>/ spec, CRUD template
4 · Wiring init.py every slice
5 · Routes interfaces/<resource>/ services, openapi route registry
6 · Bootstrap main.py, worker.py composition root
7 · Pipelines pipelines/<family>/ library pipeline engine
8 · Infra infra/ domain ports
9 · Tests tests/ app + fixtures
10 · Scripts scripts/ composition root
11 · Docs docstrings + docs build code, Doc Forge

⚠️ Definition of done

  • python -c "import main" succeeds.
  • pytest passes.
  • The app serves the spec's operations; the worker drains its queue.
  • No domain module imports a web framework.
  • No infrastructure was reimplemented that a library already provides.