diff --git a/standards/src/wiki/03_build_recipe.md b/standards/src/lib/01_build_recipe.md similarity index 55% rename from standards/src/wiki/03_build_recipe.md rename to standards/src/lib/01_build_recipe.md index 9021a59..289de8a 100644 --- a/standards/src/wiki/03_build_recipe.md +++ b/standards/src/lib/01_build_recipe.md @@ -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 /standards/src/templates/app apps/ cd apps/ ``` -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//`. 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//`. + 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//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//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//` 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//` 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.`. 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//` | services, openapi route registry | | 6 ยท Bootstrap | `main.py`, `worker.py` | composition root | -| 7 ยท Pipelines | `pipelines//` | library pipeline engine | +| 7 ยท Pipelines | `pipelines//`, `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) \ No newline at end of file +- [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) diff --git a/standards/src/lib/index.md b/standards/src/lib/index.md index fbc72ff..220e88e 100644 --- a/standards/src/lib/index.md +++ b/standards/src/lib/index.md @@ -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. diff --git a/standards/src/mkdocs.lib.yml b/standards/src/mkdocs.lib.yml index dd4fdf5..62bc019 100644 --- a/standards/src/mkdocs.lib.yml +++ b/standards/src/mkdocs.lib.yml @@ -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 diff --git a/standards/src/mkdocs.wiki.yml b/standards/src/mkdocs.wiki.yml index 6ab4fff..1c9d338 100644 --- a/standards/src/mkdocs.wiki.yml +++ b/standards/src/mkdocs.wiki.yml @@ -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 \ No newline at end of file diff --git a/standards/src/wiki/01_overview.md b/standards/src/wiki/01_overview.md index 4c94019..acb07dd 100644 --- a/standards/src/wiki/01_overview.md +++ b/standards/src/wiki/01_overview.md @@ -97,4 +97,4 @@ root: ## โžก๏ธ Read Next -- [02 โ€“ App Components](02_components.md) ยท [03 โ€“ Build Recipe](03_build_recipe.md) \ No newline at end of file +- [02 โ€“ App Components](02_components.md) ยท [03 โ€“ Start an App](03_start_an_app.md) \ No newline at end of file diff --git a/standards/src/wiki/02_components.md b/standards/src/wiki/02_components.md index 5d0fe84..c6cc7d5 100644 --- a/standards/src/wiki/02_components.md +++ b/standards/src/wiki/02_components.md @@ -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) \ No newline at end of file +- [01 โ€“ Overview](01_overview.md) ยท [03 โ€“ Start an App](03_start_an_app.md) ยท [04 โ€“ Testing & Quality](04_development/01_testing.md) \ No newline at end of file diff --git a/standards/src/wiki/03_start_an_app.md b/standards/src/wiki/03_start_an_app.md new file mode 100644 index 0000000..02e9bb3 --- /dev/null +++ b/standards/src/wiki/03_start_an_app.md @@ -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 /standards/src/templates/app apps/ +``` + +--- + +## ๐Ÿ“š 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) diff --git a/standards/src/wiki/04_development/01_testing.md b/standards/src/wiki/04_development/01_testing.md index 36fb371..3774d00 100644 --- a/standards/src/wiki/04_development/01_testing.md +++ b/standards/src/wiki/04_development/01_testing.md @@ -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) \ No newline at end of file +- [02 โ€“ App Components](../02_components.md) ยท [03 โ€“ Start an App](../03_start_an_app.md) ยท [Overview](../01_overview.md) \ No newline at end of file diff --git a/standards/src/wiki/index.md b/standards/src/wiki/index.md index afafd65..7ba6f49 100644 --- a/standards/src/wiki/index.md +++ b/standards/src/wiki/index.md @@ -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 ---