aetos/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(standards): move build recipe into the MCP bundle; add Start an App entry point

Browse Source
This commit is contained in:
Vishesh 'ironeagle' Bangotra
2026-10-12 21:26:40 +05:30
parent 2d1278911c
commit 3e5905eacb
9 changed files with 133 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
standards/src/wiki/03_build_recipe.md → standards/src/lib/01_build_recipe.md
View File

@@ -1,22 +1,38 @@
# Build Recipe
## Summary
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.
standard shape. Every step is fixed; only the resource model (step 2) and the
pipeline family (step 7) need app-specific authoring.
This page is served by the `standards` MCP as `doc://modules/build_recipe`. The
`start_app` prompt on that server collects the two axes and hands off here; pull
exact files with `get_app_component`.
---
## 🚀 Quick start
## 🚀 Bootstrap
From the standards docs checkout:
```bash
# 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.
Install the internal libraries — editable local checkouts (preferred in
development) or the private index (CI / fresh machines). Credentials are
environment-only; never commit them.
```bash
# local checkouts
pip install -e ../aetos/openapi-first -e ../aetos/mongo-ops -e ../aetos/hexa \
-e ../aetos/dagpipe -e ../aetos/doc-forge
# private index
pip install --extra-index-url \
"https://$PIP_REGISTRY_USERNAME:$PIP_REGISTRY_PASSWORD@pip.aetoskia.com/simple" .
```
---
@@ -29,16 +45,24 @@ 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.
## Before writing any code
1. **Scaffold** — copy `src/templates/app/` into `apps/<your-app>/`. Keep the
package tree: `domain/`, `infra/`, `interfaces/`, `pipelines/`, `tests/`,
Connect to the `standards` MCP server and read:
- `doc://nav` (the module list)
- `doc://modules/genericity_matrix` (Tier A library / Tier B template / Tier C authored)
- `doc://modules/layering_rules` (the dependency rules)
Then:
- call `find_library` with `db`, `di`, `routing`, `ingestion`, `pipeline`, `docs`
and note the Tier A libraries that already exist — never reimplement one;
- call `list_app_components()` and pull each file you need with
`get_app_component(kind, resource=..., family=...)` instead of writing it from
scratch.
## Steps
1. **Scaffold** — copy `standards/src/templates/app/` into `apps/<your-app>/`.
Keep the 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`.
@@ -46,35 +70,37 @@ exist. Never reimplement one.
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.
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.
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.
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.
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.
7. **Add pipeline families (only if data-driven)** — copy `pipelines/example/`
to `pipelines/<family>/` with `abc.py`, `impl.py`, `pipeline.yaml`,
`resources/`, and reuse `pipelines/shared/` (loader + registry). 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.
8. **Add infrastructure only where needed** — Tier A capability: use the
library. Tier B capability: copy the template. Never hand-write a Tier A
library.
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()`.
`init()` / `get_svc()` / `shutdown()`; run as `python -m scripts.<name>`.
11. **Docs** — author GSDFC docstrings, generate `.pyi` stubs, mark the package
`py.typed`, and build the docs.
@@ -84,7 +110,7 @@ exist. Never reimplement one.
- `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.
- No Tier A library was reimplemented.
````
---
@@ -101,7 +127,7 @@ The steps map onto the layers as follows:
| 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 |
| 7 · Pipelines | `pipelines/<family>/`, `shared/` | library pipeline engine |
| 8 · Infra | `infra/` | domain ports |
| 9 · Tests | `tests/` | app + fixtures |
| 10 · Scripts | `scripts/` | composition root |
@@ -115,10 +141,10 @@ The steps map onto the layers as follows:
- `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.
- No Tier A library was reimplemented.
---
## Related
- [01 – Overview](01_overview.md) · [02 – App Components](02_components.md) · [04 – Testing & Quality](04_development/01_testing.md)
- [02 – Layering Rules](02_layering_rules.md) · [05 – CRUD Template](05_crud_template.md) · [06 – Pipeline Scaffold](06_pipeline_scaffold.md) · [12 – Genericity Matrix](12_genericity_matrix.md)

1
standards/src/lib/index.md
View File

@@ -3,6 +3,7 @@
The reference half of the Standards description: the enforceable rules,
patterns, and the internal library catalog that agents consult while coding.
- **Build Recipe** — the ordered, agentic checklist for a new app.
- **Layering Rules** — the strict request → domain → repository layering and
the rules that enforce it.
- **Composition Root** — a single composition point wiring the whole app.

1
standards/src/mkdocs.lib.yml
View File

@@ -54,6 +54,7 @@ plugins:
nav:
- Home: index.md
- Build Recipe: 01_build_recipe.md
- Layering Rules: 02_layering_rules.md
- Composition Root: 03_composition_root.md
- Spec-First Routing: 04_spec_first_routing.md

2
standards/src/mkdocs.wiki.yml
View File

@@ -66,5 +66,5 @@ nav:
- Home: index.md
- Overview: 01_overview.md
- App Components: 02_components.md
- Build Recipe: 03_build_recipe.md
- Start an App: 03_start_an_app.md
- Testing & Quality: 04_development/01_testing.md

2
standards/src/wiki/01_overview.md
View File

@@ -97,4 +97,4 @@ root:
## ➡️ Read Next
- [02 – App Components](02_components.md) · [03 – Build Recipe](03_build_recipe.md)
- [02 – App Components](02_components.md) · [03 – Start an App](03_start_an_app.md)

2
standards/src/wiki/02_components.md
View File

@@ -154,4 +154,4 @@ sequenceDiagram
## Related
- [01 – Overview](01_overview.md) · [03 – Build Recipe](03_build_recipe.md) · [04 – Testing & Quality](04_development/01_testing.md)
- [01 – Overview](01_overview.md) · [03 – Start an App](03_start_an_app.md) · [04 – Testing & Quality](04_development/01_testing.md)

61
standards/src/wiki/03_start_an_app.md Normal file
View File

@@ -0,0 +1,61 @@
# 🚀 Start an App
This is the entry point for building a new application from the blueprint. The
goal is one deterministic pass: you supply only the **two axes**, and the agent
does the rest by reading the `standards` MCP, importing Tier A libraries, and
copying Tier B template components.
> **Doc model:** this page is the human entry point. The deterministic,
> machine-facing checklist lives in the reference page
> [Build Recipe](../lib/01_build_recipe/), served as `doc://modules/build_recipe`.
---
## 🧾 What the agent needs from you
Gather these before starting — the `start_app` MCP prompt asks for them:
1. **App name + one-line purpose.**
2. **Axis 1 — resources.** Each resource, its fields, and relationships. Paste
`openapi.yaml` if you already have it.
3. **Axis 2 — pipelines.** Only if an input needs a multi-step transformation:
the families and their input formats (or "none").
4. **Auth needed now?** Default no; auth is deferred (`py-jwt` only).
5. **Integrations.** Mongo, ingestion formats, email, LLM provider.
If you can state axes 1 and 2, the rest is mechanical.
---
## ▶️ How to start
From an MCP client connected to the `standards` server:
1. Invoke the **`start_app`** prompt with no arguments to get the intake
questions.
2. Answer them, then invoke
`start_app(app_name=..., resources=..., pipelines=..., auth=...)`.
3. The prompt hands off to `doc://modules/build_recipe`; the agent pulls exact
files with `get_app_component(kind, resource=..., family=...)` and authors
only the app-specific parts.
Manual alternative — copy the skeleton and follow the reference recipe:
```bash
cp -r <docs>/standards/src/templates/app apps/<your-app>
```
---
## 📚 Reference
- [Build Recipe](../lib/01_build_recipe/) — the deterministic checklist
- [Genericity Matrix](../lib/12_genericity_matrix/) — Tier A / B / C
- [Library Registry](../lib/13_library_registry/) — the Tier A catalog
- [App Components](02_components.md) — the component model
---
## Related
- [01 – Overview](01_overview.md) · [02 – App Components](02_components.md) · [04 – Testing & Quality](04_development/01_testing.md)

2
standards/src/wiki/04_development/01_testing.md
View File

@@ -78,4 +78,4 @@ A **definition of done** for any standard app:
## Related
- [02 – App Components](02_components.md) · [03 – Build Recipe](03_build_recipe.md) · [Overview](../01_overview.md)
- [02 – App Components](../02_components.md) · [03 – Start an App](../03_start_an_app.md) · [Overview](../01_overview.md)

8
standards/src/wiki/index.md
View File

@@ -37,11 +37,11 @@ the same shape underneath.
|-----------------------------------------------------|--------------------------------------------------------|
| [Overview](01_overview.md) | Philosophy, the one-way dependency rule, architecture |
| [App Components](02_components.md) | The component model and how the pieces wire together |
| [Build Recipe](03_build_recipe.md) | The ordered, agentic checklist for a new app |
| [Start an App](03_start_an_app.md) | The entry point: gather the two axes, then build |
| [Testing & Quality](04_development/01_testing.md) | Test layout and acceptance gates |
**Reference** (separate site, mirrors the MCP bundle): the enforceable
rules — [Layering](../lib/02_layering_rules/), [Composition
rules — [Build Recipe](../lib/01_build_recipe/), [Layering](../lib/02_layering_rules/), [Composition
Root](../lib/03_composition_root/), [Spec-First
Routing](../lib/04_spec_first_routing/), [CRUD
Template](../lib/05_crud_template/), [Pipeline
@@ -60,8 +60,8 @@ Registry](../lib/13_library_registry/).
- **Library registry** — the catalog of internal libraries behind every app
(`libraries.json`, served as `registry://libraries`)
- **Template** — the runnable skeleton at `standards/src/templates/app/`
- **Copy the repo's `AGENTS.md`-style build prompt** from
[Build Recipe](03_build_recipe.md)
- **Start a build** — invoke the `start_app` prompt on the `standards` server,
or read the [Start an App](03_start_an_app.md) guide
---