refactor: conform standards docs to doc-forge wiki/lib layout; generic build.py; static kind links

standards/templates/README.md

@@ -0,0 +1,54 @@
+# Application Template
+
+A minimal, runnable skeleton of the standardized architecture. It demonstrates
+both axes of the blueprint (see `standards`):
+
+1. **Resource axis** — items and jobs, each a Claude-style generic CRUD slice
+   (model → document → repo → service → route), all driven from `openapi.yaml`.
+2. **Pipeline axis** — a background `worker.py` that polls pending jobs and runs
+   `pipelines/item_sync.py`, a deterministic async step chain.
+
+Everything here is deliberately small so an agent can rewrite each file rather
+than delete unused code. The domain is a neutral "item", not an app noun.
+
+## Instantiate a new app
+
+    cp -r templates/app apps/<your-app>
+    cd apps/<your-app>
+
+1. `pyproject.toml` — rename the package; keep the internal library pins.
+2. `config.py` — replace/add settings consumed by your domain.
+3. `openapi.yaml` — replace the `Item`/`Job` resources with your resources.
+4. `domain/` — rename `item` and `job` slices to your aggregates.
+5. `pipelines/item_sync.py` — replace the demo steps with your pipeline.
+6. `tests/` — keep the two test files as the pattern for your own.
+
+Run the API:
+
+    pip install -e ".[dev]"
+    uvicorn main:app --reload
+
+Run the worker:
+
+    python worker.py
+
+## What to keep, what to replace
+
+| Keep                         | Replace / rename                      |
+|------------------------------|---------------------------------------|
+| `config.py` shape            | Settings fields                       |
+| `init.py` wiring pattern     | Resource names                        |
+| openapi-first routing        | Paths, schemas, operationIds          |
+| mongo-ops repo factory       | Collections, doc models               |
+| generic CRUD adaptor         | Nothing (reuse as-is)                 |
+| worker poll + status loop    | Job payloads, pipeline steps          |
+
+## Where the internal libraries slot in
+
+- `openapi_first.app.OpenAPIFirstApp` — main.py, interfaces/openapi.py
+- `mongo_ops` — infra/db/setup.py, infra/db/repos/mongo.py, domain/*/ports/db.py
+- `hexa.build` — domain/*/ports/service.py
+- `dagpipe` — pipelines/ (wrap step chains in a DAG once they branch)
+
+Confirm current endpoints and ownership with the `standards` registry MCP tool:
+`find_library("pipeline")`, `find_library("auth")`, etc.

standards/templates/app/.dockerignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+.git/
+docs/
+dist/
+build/

standards/templates/app/.env.example

@@ -0,0 +1,5 @@
+DEBUG=false
+MONGO_URI=mongodb://localhost:27017
+MONGO_DB=app_template
+WORKER_POLL_SECONDS=30
+WORKER_MAX_RETRIES=3

standards/templates/app/Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY pyproject.toml ./
+COPY . .
+RUN pip install --no-cache-dir --upgrade pip \
+ && pip install --no-cache-dir .
+
+EXPOSE 8000
+
+# Two processes, per the two axes:
+#   - main.py   : the spec-first FastAPI application
+#   - worker.py : the pipeline consumer polling pending jobs
+CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port 8000 & exec python worker.py"]

standards/templates/app/config.py

@@ -0,0 +1,36 @@
+"""# Summary
+
+App configuration loaded from environment — a Settings dataclass with defaults
+plus a singleton settings instance populated from OS environment variables at
+import time.
+"""
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Settings:
+    """Runtime configuration settings for the application.
+
+    Attributes:
+        debug (bool): Enable debug behavior. Defaults to False.
+        mongo_uri (str): MongoDB connection URI. Defaults to mongodb://localhost:27017.
+        mongo_db (str): MongoDB database name. Defaults to app_template.
+        worker_poll_seconds (int): Worker poll interval in seconds. Defaults to 30.
+        worker_max_retries (int): Maximum job retries before skipping. Defaults to 3.
+    """
+
+    debug: bool = False
+    mongo_uri: str = "mongodb://localhost:27017"
+    mongo_db: str = "app_template"
+    worker_poll_seconds: int = 30
+    worker_max_retries: int = 3
+
+
+settings = Settings(
+    debug=os.environ.get("DEBUG", "").lower() in ("1", "true", "yes"),
+    mongo_uri=os.environ.get("MONGO_URI", "mongodb://localhost:27017"),
+    mongo_db=os.environ.get("MONGO_DB", "app_template"),
+    worker_poll_seconds=int(os.environ.get("WORKER_POLL_SECONDS", "30")),
+    worker_max_retries=int(os.environ.get("WORKER_MAX_RETRIES", "3")),
+)

standards/templates/app/docker-compose.yaml

@@ -0,0 +1,21 @@
+services:
+  api:
+    build: .
+    command: uvicorn main:app --host 0.0.0.0 --port 8000
+    env_file: .env
+    ports:
+      - "8000:8000"
+    depends_on:
+      - mongo
+
+  worker:
+    build: .
+    command: python worker.py
+    env_file: .env
+    depends_on:
+      - mongo
+
+  mongo:
+    image: mongo:7
+    ports:
+      - "27017:27017"

standards/templates/app/domain/item/models.py

@@ -0,0 +1,19 @@
+"""# Summary
+
+Item domain model — the neutral resource used throughout the template.
+"""
+from pydantic import BaseModel, Field
+
+
+class Item(BaseModel):
+    """A single countable resource.
+
+    Attributes:
+        name (str): Item name.
+        quantity (int): Item quantity. Defaults to 1.
+    """
+
+    name: str
+    quantity: int = Field(default=1)
+
+    model_config = {"extra": "ignore"}

standards/templates/app/domain/item/ports/db.py

@@ -0,0 +1,20 @@
+"""# Summary
+
+Mongo persistence for items: document schema and repository factory.
+"""
+from domain.item.models import Item
+from infra.db.repos.mongo import _repo_factory as mongo_repo_factory
+from mongo_ops import BaseDocument, BaseRepository
+
+
+class ItemDocument(Item, BaseDocument):
+    """Mongo document form of :class:`Item`."""
+
+
+def create_item_repo() -> BaseRepository:
+    """Create the Mongo-backed item repository.
+
+    Returns:
+        BaseRepository: Repository wired to the ``items`` collection.
+    """
+    return mongo_repo_factory("items", ItemDocument)

standards/templates/app/domain/item/ports/service.py

@@ -0,0 +1,33 @@
+"""# Summary
+
+CRUD service wiring for the item aggregate via the hexa container.
+"""
+from hexa import build
+
+from domain.item.models import Item
+from domain.item.ports.db import ItemDocument
+from infra.adapters.service import CrudsServiceAdaptor
+
+
+class ItemCrudsService(CrudsServiceAdaptor[Item, ItemDocument]):
+    """Item CRUD service resolving :class:`ItemDocument` from a repo.
+
+    Notes:
+        Instances are created by :func:`get_item_service`. The ``model`` and
+        ``schema`` class attributes bind the domain model and its document type.
+    """
+
+    model = Item
+    schema = ItemDocument
+
+
+def get_item_service(repo) -> ItemCrudsService:
+    """Build an item CRUD service wired to ``repo``.
+
+    Args:
+        repo (Any): Mongo-backed item repository from :func:`create_item_repo`.
+
+    Returns:
+        ItemCrudsService: Ready-to-use item CRUD service.
+    """
+    return build(ItemCrudsService, instances={"repo": repo})

standards/templates/app/domain/job/models.py

@@ -0,0 +1,26 @@
+"""# Summary
+
+Job domain model — a pipeline work item consumed by the background worker.
+"""
+from typing import Literal
+from pydantic import BaseModel, Field
+
+
+class Job(BaseModel):
+    """A unit of background work.
+
+    Attributes:
+        name (str): Job name.
+        status (str): Lifecycle status. Defaults to "pending".
+        retry_count (int): Times the job failed. Defaults to 0.
+        error_message (str | None): Last failure message. Defaults to None.
+        payload (dict | None): Arbitrary job payload. Defaults to None.
+    """
+
+    name: str
+    status: Literal["pending", "processing", "done", "failed"] = "pending"
+    retry_count: int = Field(default=0)
+    error_message: str | None = None
+    payload: dict | None = None
+
+    model_config = {"extra": "ignore"}

standards/templates/app/domain/job/ports/db.py

@@ -0,0 +1,20 @@
+"""# Summary
+
+Mongo persistence for jobs: document schema and repository factory.
+"""
+from domain.job.models import Job
+from infra.db.repos.mongo import _repo_factory as mongo_repo_factory
+from mongo_ops import BaseDocument, BaseRepository
+
+
+class JobDocument(Job, BaseDocument):
+    """Mongo document form of :class:`Job`."""
+
+
+def create_job_repo() -> BaseRepository:
+    """Create the Mongo-backed job repository.
+
+    Returns:
+        BaseRepository: Repository wired to the ``jobs`` collection.
+    """
+    return mongo_repo_factory("jobs", JobDocument)

standards/templates/app/domain/job/ports/service.py

@@ -0,0 +1,33 @@
+"""# Summary
+
+CRUD service wiring for the job aggregate via the hexa container.
+"""
+from hexa import build
+
+from domain.job.models import Job
+from domain.job.ports.db import JobDocument
+from infra.adapters.service import CrudsServiceAdaptor
+
+
+class JobCrudsService(CrudsServiceAdaptor[Job, JobDocument]):
+    """Job CRUD service resolving :class:`JobDocument` from a repo.
+
+    Notes:
+        Instances are created by :func:`get_job_service`. The ``model`` and
+        ``schema`` class attributes bind the domain model and its document type.
+    """
+
+    model = Job
+    schema = JobDocument
+
+
+def get_job_service(repo) -> JobCrudsService:
+    """Build a job CRUD service wired to ``repo``.
+
+    Args:
+        repo (Any): Mongo-backed job repository from :func:`create_job_repo`.
+
+    Returns:
+        JobCrudsService: Ready-to-use job CRUD service.
+    """
+    return build(JobCrudsService, instances={"repo": repo})

standards/templates/app/infra/adapters/service.py

@@ -0,0 +1,128 @@
+"""# Summary
+
+Generic CRUD service adaptor over a Mongo repository.
+
+Bridge pydantic models and mongo-ops documents, exposing create, read, update,
+patch, delete, and search operations for every domain that needs them.
+"""
+from typing import Generic, Type, TypeVar
+
+from infra.db.repos import mongo
+
+from pydantic import BaseModel
+from mongo_ops import BaseDocument
+from mongo_ops.models import PyObjectId
+
+Model = TypeVar("Model", bound=BaseModel)
+Schema = TypeVar("Schema", bound=BaseDocument)
+
+
+class CrudsServiceAdaptor(Generic[Model, Schema]):
+    """Adapt a generic Mongo repository to a model/schema CRUD service.
+
+    Attributes:
+        repo (mongo.BaseRepository): Repository backing all CRUD operations.
+        model (Type[Model]): Pydantic model type handled by this service.
+        schema (Type[Schema]): Document schema type persisted by the repository.
+    """
+
+    repo: mongo.BaseRepository
+    model: Type[Model]
+    schema: Type[Schema]
+
+    def __init__(self, *, repo=None):
+        """Initialize the adaptor with a backing repository.
+
+        Args:
+            repo (mongo.BaseRepository): Repository used for all operations.
+        """
+        self.repo = repo
+
+    @staticmethod
+    def model_to_dict(model_obj: Model) -> dict:
+        """Serialize a model into a sparse dictionary.
+
+        Args:
+            model_obj (Model): Model instance to serialize.
+
+        Returns:
+            dict: Fields that are set and not ``None``.
+        """
+        return model_obj.model_dump(exclude_unset=True, exclude_none=True)
+
+    async def create(self, data: Model | dict) -> Schema:
+        """Create a document from a model or raw mapping.
+
+        Args:
+            data (Model | dict): Model instance or field mapping to persist.
+
+        Returns:
+            Schema: Persisted document.
+        """
+        if isinstance(data, dict):
+            data = self.schema(**data)
+        return await self.repo.create(data)
+
+    async def read(self, id: PyObjectId) -> Schema | None:
+        """Read a document by primary key.
+
+        Args:
+            id (PyObjectId): Document identifier.
+
+        Returns:
+            Schema | None: Matching document, or ``None`` when absent.
+        """
+        return await self.repo.get_by_id(id)
+
+    async def update(self, id: PyObjectId, data: Model | dict) -> Schema | None:
+        """Replace a document by primary key.
+
+        Args:
+            id (PyObjectId): Document identifier.
+            data (Model | dict): Replacement model or field mapping.
+
+        Returns:
+            Schema | None: Updated document, or ``None`` when absent.
+        """
+        return await self.repo.update(
+            id,
+            data if isinstance(data, dict) else self.model_to_dict(data),
+        )
+
+    async def patch(self, id: PyObjectId, data: dict) -> Schema | None:
+        """Partially update a document by primary key.
+
+        Args:
+            id (PyObjectId): Document identifier.
+            data (dict): Fields to patch.
+
+        Returns:
+            Schema | None: Updated document, or ``None`` when absent.
+        """
+        return await self.repo.patch(id, data)
+
+    async def delete(self, id: PyObjectId) -> bool:
+        """Delete a document by primary key.
+
+        Args:
+            id (PyObjectId): Document identifier.
+
+        Returns:
+            bool: ``True`` when a document was deleted.
+        """
+        return await self.repo.delete(id)
+
+    async def search(self, filter: dict | None = None, *args, **kwargs) -> list[Schema]:
+        """List documents matching an optional filter.
+
+        Args:
+            filter (dict | None): Query filter passed to the repository.
+
+        Returns:
+            list[Schema]: Matching documents.
+
+        Notes:
+            Extra positional and keyword arguments are forwarded to the
+            repository.
+        """
+        return await self.repo.get_many(filter=filter, *args, **kwargs)

standards/templates/app/infra/db/repos/mongo.py

@@ -0,0 +1,42 @@
+"""# Summary
+
+Generic MongoDB CRUD repo — single implementation for all domains.
+
+Select a concrete mongo-ops repository (base, cached, or populating) from the
+options supplied to the factory.
+"""
+from typing import List, Optional, Type
+
+from mongo_ops import BaseRepository, CachedBaseRepository, PopulatingRepository
+from mongo_ops.cache import CacheBackend, CacheConfig
+from mongo_ops.models import BaseDocument
+from mongo_ops.populate import PopulationEngine, PopulateRule
+
+
+def _repo_factory(
+    collection: str,
+    db_model: Type[BaseDocument],
+    cache_backend: Optional[CacheBackend] = None,
+    cache_config: Optional[CacheConfig] = None,
+    engine: Optional[PopulationEngine] = None,
+    populate_rules: Optional[List[PopulateRule]] = None,
+) -> BaseRepository:
+    """Build the appropriate mongo-ops repository.
+
+    Args:
+        collection (str): Collection name to operate on.
+        db_model (Type[BaseDocument]): Document model bound to the collection.
+        cache_backend (Optional[CacheBackend]): Cache backend enabling cached reads.
+        cache_config (Optional[CacheConfig]): Cache configuration for the backend.
+        engine (Optional[PopulationEngine]): Population engine for reference expansion.
+        populate_rules (Optional[List[PopulateRule]]): Rules applied by the engine.
+
+    Returns:
+        BaseRepository: Repository instance matching the supplied options.
+    """
+    if engine and populate_rules is not None:
+        return PopulatingRepository(collection, db_model, engine, populate_rules)
+    elif cache_backend is not None:
+        return CachedBaseRepository(collection, db_model, cache_backend, cache_config)
+    else:
+        return BaseRepository(collection, db_model)

standards/templates/app/infra/db/setup.py

@@ -0,0 +1,23 @@
+"""# Summary
+
+Database setup — connection lifecycle only. No domain imports.
+
+Connect and disconnect the shared Mongo connection manager at application
+startup and shutdown.
+"""
+from mongo_ops import MongoConnectionManager
+
+
+async def setup_database(uri: str, db_name: str):
+    """Connect the shared Mongo connection manager.
+
+    Args:
+        uri (str): Mongo connection URI.
+        db_name (str): Target database name.
+    """
+    await MongoConnectionManager.connect(uri=uri, db_name=db_name)
+
+
+async def shutdown_database():
+    """Disconnect the shared Mongo connection manager."""
+    await MongoConnectionManager.disconnect()

standards/templates/app/init.py

@@ -0,0 +1,51 @@
+"""# Summary
+
+Infrastructure initialization — connects MongoDB and wires all repos and services.
+Shared bootstrap for both the FastAPI app and the worker, guarded against
+repeated initialization via a module-level flag.
+"""
+from typing import Any, Dict
+
+from config import settings
+from domain.item.ports.db import create_item_repo
+from domain.item.ports.service import get_item_service
+from domain.job.ports.db import create_job_repo
+from domain.job.ports.service import get_job_service
+from infra.db.setup import setup_database, shutdown_database
+
+_resources: Dict[str, Any] = {}
+_initialized: bool = False
+
+
+async def init() -> Dict[str, Any]:
+    """Connect MongoDB, wire all repos and services, and return the resources dict.
+
+    Idempotent: repeated calls short-circuit and return the cached resources.
+
+    Returns:
+        Dict[str, Any]: Named services keyed by resource name.
+    """
+    global _resources, _initialized
+    if _initialized:
+        return _resources
+
+    await setup_database(uri=settings.mongo_uri, db_name=settings.mongo_db)
+
+    item_repo = create_item_repo()
+    job_repo = create_job_repo()
+
+    _resources["item_repo"] = item_repo
+    _resources["job_repo"] = job_repo
+    _resources["item_svc"] = get_item_service(item_repo)
+    _resources["job_svc"] = get_job_service(job_repo)
+
+    _initialized = True
+    return _resources
+
+
+async def shutdown() -> None:
+    """Disconnect MongoDB and reset the resources cache."""
+    global _initialized
+    await shutdown_database()
+    _resources.clear()
+    _initialized = False

standards/templates/app/interfaces/item/routes.py

@@ -0,0 +1,42 @@
+"""# Summary
+
+Item route handlers — names must match openapi.yaml operationIds.
+"""
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from domain.item.models import Item
+
+
+def svc(request: Request):
+    """Resolve the item CRUD service from app state."""
+    return request.app.state.db_resources["item_svc"]
+
+
+async def create_item(request: Request, body: dict):
+    """Create an item from the request body."""
+    data = body.model_dump() if hasattr(body, "model_dump") else dict(body)
+    doc = await svc(request).create(Item(**data))
+    return JSONResponse(status_code=201, content=doc.model_dump(mode="json", by_alias=True))
+
+
+async def get_item(request: Request, id: str):
+    """Fetch one item by id."""
+    doc = await svc(request).read(id)
+    if doc is None:
+        return JSONResponse(status_code=404, content={"detail": "item not found"})
+    return doc.model_dump(mode="json", by_alias=True)
+
+
+async def list_items(request: Request):
+    """List all items."""
+    docs = await svc(request).search({})
+    return [d.model_dump(mode="json", by_alias=True) for d in docs]
+
+
+async def delete_item(request: Request, id: str):
+    """Delete one item by id."""
+    ok = await svc(request).delete(id)
+    if not ok:
+        return JSONResponse(status_code=404, content={"detail": "item not found"})
+    return {"deleted": True}

standards/templates/app/interfaces/job/routes.py

@@ -0,0 +1,34 @@
+"""# Summary
+
+Job route handlers — names must match openapi.yaml operationIds.
+"""
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+from domain.job.models import Job
+
+
+def svc(request: Request):
+    """Resolve the job CRUD service from app state."""
+    return request.app.state.db_resources["job_svc"]
+
+
+async def create_job(request: Request, body: dict):
+    """Create a job from the request body."""
+    data = body.model_dump() if hasattr(body, "model_dump") else dict(body)
+    doc = await svc(request).create(Job(**data))
+    return JSONResponse(status_code=201, content=doc.model_dump(mode="json", by_alias=True))
+
+
+async def get_job(request: Request, id: str):
+    """Fetch one job by id."""
+    doc = await svc(request).read(id)
+    if doc is None:
+        return JSONResponse(status_code=404, content={"detail": "job not found"})
+    return doc.model_dump(mode="json", by_alias=True)
+
+
+async def list_jobs(request: Request):
+    """List all jobs."""
+    docs = await svc(request).search({})
+    return [d.model_dump(mode="json", by_alias=True) for d in docs]

standards/templates/app/interfaces/openapi.py

@@ -0,0 +1,8 @@
+"""# Summary
+
+All handler functions — names must match openapi.yaml operationId values. The
+OpenAPI-first router resolves each operation to a handler by name, so this module
+re-exports every route handler from the subpackages into one flat namespace.
+"""
+from interfaces.item.routes import *
+from interfaces.job.routes import *

standards/templates/app/main.py

@@ -0,0 +1,54 @@
+"""# Summary
+
+FastAPI application bootstrap — uses OpenAPIFirstApp for spec-driven routing.
+Handlers are looked up by operationId in interfaces.openapi, so no router tables
+are declared here; the lifespan initializes and shuts down app resources.
+"""
+import logging
+from contextlib import asynccontextmanager
+
+from dotenv import load_dotenv
+from openapi_first.app import OpenAPIFirstApp
+from starlette.middleware.cors import CORSMiddleware
+
+from init import init, shutdown
+
+load_dotenv()
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+)
+
+import interfaces.openapi as openapi_routes
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: OpenAPIFirstApp):
+    """Initialize resource wiring on startup and shut it down on exit.
+
+    Args:
+        app (OpenAPIFirstApp): The ASGI application exposing app.state.
+
+    Yields:
+        None: The application runs while the context is open.
+    """
+    resources = await init()
+    app.state.db_resources = resources
+
+    yield
+
+    await shutdown()
+
+
+app = OpenAPIFirstApp(
+    openapi_path="openapi.yaml",
+    routes_module=openapi_routes,
+    title="Item API",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])

standards/templates/app/openapi.yaml

@@ -0,0 +1,161 @@
+openapi: 3.0.3
+info:
+  title: Item API
+  version: 0.1.0
+paths:
+  /items:
+    get:
+      operationId: list_items
+      summary: List items
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Item"
+    post:
+      operationId: create_item
+      summary: Create an item
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ItemInput"
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Item"
+  /items/{id}:
+    get:
+      operationId: get_item
+      summary: Get an item
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Item"
+        "404":
+          description: Not found
+    delete:
+      operationId: delete_item
+      summary: Delete an item
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Deleted
+        "404":
+          description: Not found
+  /jobs:
+    get:
+      operationId: list_jobs
+      summary: List jobs
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Job"
+    post:
+      operationId: create_job
+      summary: Create a job
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/JobInput"
+      responses:
+        "201":
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Job"
+  /jobs/{id}:
+    get:
+      operationId: get_job
+      summary: Get a job
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Job"
+        "404":
+          description: Not found
+components:
+  schemas:
+    Item:
+      type: object
+      required: [name, quantity]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        quantity:
+          type: integer
+    ItemInput:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+        quantity:
+          type: integer
+          default: 1
+    Job:
+      type: object
+      required: [name, status]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        status:
+          type: string
+          enum: [pending, processing, done, failed]
+        retry_count:
+          type: integer
+        error_message:
+          type: string
+        payload:
+          type: object
+    JobInput:
+      type: object
+      required: [name]
+      properties:
+        name:
+          type: string
+        payload:
+          type: object

standards/templates/app/pipelines/item_sync.py

@@ -0,0 +1,32 @@
+"""# Summary
+
+Item-sync pipeline — the demo pipeline axis of the blueprint.
+
+Runs on the worker, consumes a pending job, and materializes its payload as an
+item. Steps are plain async functions here; once the chain branches or needs
+deterministic replay, wrap the steps in a dagpipe DAG (see standards
+"06_pipeline_scaffold").
+"""
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+async def run_item_sync(job, resources: dict) -> None:
+    """Materialize a pending job payload as an item.
+
+    Step 1: extract the payload from the job.
+    Step 2: create the item through the item service.
+
+    Args:
+        job: The pending job document.
+        resources (dict): Wired services and adaptors.
+    """
+    payload = job.payload or {}
+    item_svc = resources["item_svc"]
+
+    await item_svc.create({
+        "name": payload.get("name", job.name),
+        "quantity": payload.get("quantity", 1),
+    })
+    logger.info("Created item from job %s", str(job.id))

standards/templates/app/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "app-template"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi",
+    "uvicorn[standard]",
+    "pydantic>=2",
+    "motor",
+    "python-dotenv",
+    "openapi-first",
+    "mongo-ops",
+    "hexa",
+    "dagpipe",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "httpx",
+    "ruff",
+    "doc-forge",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["domain*", "infra*", "interfaces*", "pipelines*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

standards/templates/app/tests/integration/test_item_routes.py

@@ -0,0 +1,21 @@
+import importlib
+
+import interfaces.openapi as routes_module
+
+from openapi_first.app import OpenAPIFirstApp
+
+
+def test_openapi_app_builds():
+    """The spec-first app must build and plant each route handler."""
+    module = importlib.import_module(routes_module.__name__)
+    for operation in ("create_item", "get_item", "list_items", "delete_item",
+                      "create_job", "get_job", "list_jobs"):
+        assert hasattr(module, operation)
+
+    app = OpenAPIFirstApp(
+        openapi_path="openapi.yaml",
+        routes_module=module,
+        title="Item API",
+        version="0.1.0",
+    )
+    assert app is not None

standards/templates/app/tests/unit/test_item_models.py

@@ -0,0 +1,22 @@
+from domain.item.models import Item
+from domain.job.models import Job
+
+
+def test_item_defaults():
+    item = Item(name="widget")
+    assert item.quantity == 1
+
+
+def test_job_defaults():
+    job = Job(name="sync")
+    assert job.status == "pending"
+    assert job.retry_count == 0
+    assert job.error_message is None
+
+
+def test_job_rejects_unknown_status():
+    try:
+        Job(name="sync", status="exploded")
+    except Exception:
+        return
+    raise AssertionError("status should be rejected")

standards/templates/app/tests/unit/test_item_sync.py

@@ -0,0 +1,28 @@
+from types import SimpleNamespace
+
+from pipelines.item_sync import run_item_sync
+
+
+class FakeItemSvc:
+    def __init__(self):
+        self.created = []
+
+    async def create(self, data: dict):
+        self.created.append(dict(data))
+
+
+async def test_run_item_sync_creates_item():
+    svc = FakeItemSvc()
+    job = SimpleNamespace(id="j1", name="widget", payload={"quantity": 4})
+    await run_item_sync(job, {"item_svc": svc})
+
+    assert len(svc.created) == 1
+    assert svc.created[0] == {"name": "widget", "quantity": 4}
+
+
+async def test_run_item_sync_uses_payload_name():
+    svc = FakeItemSvc()
+    job = SimpleNamespace(id="j1", name="ignored", payload={"name": "gadget"})
+    await run_item_sync(job, {"item_svc": svc})
+
+    assert svc.created[0]["name"] == "gadget"

standards/templates/app/worker.py

@@ -0,0 +1,67 @@
+"""# Summary
+
+Background worker — polls for pending jobs and runs the item-sync pipeline.
+The poll loop is the pipeline axis of the blueprint: resources are created by
+the API axis, workers consume them on a fixed cadence.
+
+Notes:
+- This process is separate from the API process. Any in-memory event bus is per
+  process — if the pipeline must surface live progress to the API, swap the bus
+  adaptor for a broker-backed one (see standards 07_worker_and_progress).
+"""
+import asyncio
+import logging
+
+from config import settings
+from pipelines.item_sync import run_item_sync
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def poll_jobs(resources: dict):
+    """Poll for pending jobs and run the item-sync pipeline on each.
+
+    Args:
+        resources (dict): Wired services from :func:`init.init`.
+    """
+    job_svc = resources["job_svc"]
+    logger.info("WORKER STARTED — poll=%ss max_retries=%d",
+                settings.worker_poll_seconds, settings.worker_max_retries)
+
+    while True:
+        pending = await job_svc.search(filter={"status": "pending"}, limit=10)
+        logger.info("Found %d pending job(s)", len(pending) if pending else 0)
+
+        for job in pending:
+            job_id = str(job.id)
+            if (job.retry_count or 0) >= settings.worker_max_retries:
+                logger.warning("SKIPPING job %s — retries exhausted", job_id)
+                continue
+
+            await job_svc.patch(job_id, {"status": "processing"})
+            try:
+                await run_item_sync(job, resources)
+                await job_svc.patch(job_id, {"status": "done", "error_message": ""})
+            except Exception as exc:  # noqa: BLE001
+                logger.exception("job %s FAILED: %s", job_id, exc)
+                await job_svc.patch(job_id, {"status": "failed", "error_message": str(exc)})
+
+        await asyncio.sleep(settings.worker_poll_seconds)
+
+
+if __name__ == "__main__":
+    from init import init, shutdown
+
+    async def _run():
+        resources = await init()
+        try:
+            await poll_jobs(resources)
+        finally:
+            await shutdown()
+
+    asyncio.run(_run())