ai-project-blueprints 0.2.0__tar.gz

ai_project_blueprints-0.2.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: ai-project-blueprints
+Version: 0.2.0
+Summary: Validated, versioned project blueprint catalog for coding agents
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: jsonschema<5,>=4.25
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.3; extra == "dev"
+Requires-Dist: pyright<2,>=1.1.405; extra == "dev"
+Requires-Dist: pytest<10,>=8.4; extra == "dev"
+Requires-Dist: pytest-xdist<4,>=3.8; extra == "dev"
+Requires-Dist: ruff<1,>=0.13; extra == "dev"
+Requires-Dist: twine<7,>=6.2; extra == "dev"
+
+# AI Project Blueprints
+
+Versioned, inspectable starter packs for agents that create new projects. A pack
+combines a machine-readable manifest, agent instructions, dependency policies,
+and template assets. It is deliberately separate from the orchestrator: the
+orchestrator resolves and previews a pack, while this repository owns its content.
+
+The current backend pack is `python-api-fastapi@1.1.0`; immutable `1.0.0`
+remains available. Its base profile uses FastAPI,
+Pydantic Settings, SQLAlchemy 2, Alembic, Ruff, Pyright, pytest and pytest-xdist.
+Exactly one database profile is selected: PostgreSQL by default or SQLite for
+bounded embedded/single-instance use. Testcontainers/PostgreSQL,
+Keycloak-compatible OIDC, Docker, and Kubernetes/Helm are explicit overlays.
+Version `1.1.0` adds feature-first vertical slices and lets agents choose the
+least elaborate internal structure for each use case.
+
+The UI pack `react-spa-vite@1.0.0` provides a browser-only React and strict
+TypeScript SPA with Vite, React Router, typed ESLint, Prettier, Vitest, and React
+Testing Library. Its feature-first structure keeps page-local journeys small and
+promotes reusable interactions or shared domain representations only when their
+boundaries are proven. Tailwind, OpenAPI client generation, TanStack Query,
+React Hook Form with Zod, OIDC/Keycloak, MSW, Playwright, runtime configuration,
+and non-root nginx delivery are explicit capabilities. The
+`react-admin-api-spa` service profile selects that recommended administrative UI
+combination without changing the minimal blueprint defaults.
+
+Project-level operations are modeled separately through immutable platform
+packs. `local-compose@1.0.0` provides a development dependency boundary;
+`kubernetes-standard@1.0.0` provides provider-neutral Helm, Argo CD, Gateway
+API, OIDC, OpenTelemetry with an explicit telemetry backend, secret-management,
+backup, scheduler and event decisions. Stateful additions such as Keycloak,
+Velero, a self-hosted observability stack or a message broker stay explicit
+capabilities rather than silent service defaults.
+
+## Installation and API
+
+```bash
+pip install ai-project-blueprints==0.2.0
+ai-project-blueprints list
+ai-project-blueprints platform-list
+ai-project-blueprints validate
+```
+
+Python consumers use `ai_project_blueprints` to discover and read resources.
+Access is backed by `importlib.resources`, so an installed wheel does not depend
+on a repository checkout:
+
+```python
+from ai_project_blueprints import load_manifest, load_platform_manifest, read_text
+
+manifest = load_manifest("python-api-fastapi", "1.1.0")
+coder_instructions = read_text("blueprints/python-api-fastapi/1.1.0/instructions/coder.md")
+platform = load_platform_manifest("kubernetes-standard", "1.0.0")
+```
+
+The API and CLI are inspect-only. They do not materialize or overwrite project
+files.
+
+## Layout
+
+```text
+src/ai_project_blueprints/resources/  packaged catalogs, schemas, docs, examples, and packs
+src/ai_project_blueprints/            public API, CLI, and trusted validation tooling
+tests/         catalog invariant tests
+```
+
+## Validate
+
+Python 3.11+ is required for the catalog tooling.
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/ai-project-blueprints validate
+.venv/bin/ruff check .
+.venv/bin/pyright
+.venv/bin/pytest -n auto
+```
+
+The current release is a catalog contract and authored template pack. It does not
+yet include a materializer; consumers must preview an exact manifest version and
+preserve caller-owned files when they implement materialization.
+
+## Multi-service orchestration
+
+[`catalog/service-workflows.json`](src/ai_project_blueprints/resources/catalog/service-workflows.json) separates
+three provider-neutral concepts: a `service_profile` chooses blueprint defaults,
+an `agent_bundle` supplies ordered role instructions, and a `workflow_bundle`
+describes one bounded service workflow. The consumer-owned
+[`examples/python-multiservice-project.json`](src/ai_project_blueprints/resources/examples/python-multiservice-project.json)
+shows backend services using different PostgreSQL/SQLite profiles and a React
+administrative UI using its own profile, instruction bundle, workflow bundle,
+and runtime-profile aliases under one workspace orchestrator.
+
+[`catalog/platform-workflows.json`](src/ai_project_blueprints/resources/catalog/platform-workflows.json)
+adds environment-level platform profiles, agent bundles and bounded platform
+workflows. Workspace schema version 2 binds `local` to Compose and
+`staging`/`production` to Kubernetes while retaining per-role runtime aliases.
+Service workflows consume the resulting operational contracts but do not own
+shared cluster resources.
+
+Concrete runtime aliases, models, providers, credentials and service-local
+instructions remain consumer-owned. The catalog only validates their safe
+logical bindings. Cross-service work is serialized and composed by the single
+host; a service workflow cannot start a nested orchestrator or independently
+claim the same checkout.
+
+See [the Python API stack policy](src/ai_project_blueprints/resources/docs/stack-policy.md)
+and [the React SPA stack policy](src/ai_project_blueprints/resources/docs/ui-stack-policy.md)
+and [the feature-first architecture policy](src/ai_project_blueprints/resources/docs/code-architecture-policy.md)
+and [the platform profile policy](src/ai_project_blueprints/resources/docs/platform-policy.md)
+for selection rationale. The [package contract](src/ai_project_blueprints/resources/docs/package-contract.md)
+and [release policy](src/ai_project_blueprints/resources/docs/release-policy.md)
+define resource compatibility and GitLab.com/PyPI publication gates.

ai_project_blueprints-0.2.0/README.md

@@ -0,0 +1,114 @@
+# AI Project Blueprints
+
+Versioned, inspectable starter packs for agents that create new projects. A pack
+combines a machine-readable manifest, agent instructions, dependency policies,
+and template assets. It is deliberately separate from the orchestrator: the
+orchestrator resolves and previews a pack, while this repository owns its content.
+
+The current backend pack is `python-api-fastapi@1.1.0`; immutable `1.0.0`
+remains available. Its base profile uses FastAPI,
+Pydantic Settings, SQLAlchemy 2, Alembic, Ruff, Pyright, pytest and pytest-xdist.
+Exactly one database profile is selected: PostgreSQL by default or SQLite for
+bounded embedded/single-instance use. Testcontainers/PostgreSQL,
+Keycloak-compatible OIDC, Docker, and Kubernetes/Helm are explicit overlays.
+Version `1.1.0` adds feature-first vertical slices and lets agents choose the
+least elaborate internal structure for each use case.
+
+The UI pack `react-spa-vite@1.0.0` provides a browser-only React and strict
+TypeScript SPA with Vite, React Router, typed ESLint, Prettier, Vitest, and React
+Testing Library. Its feature-first structure keeps page-local journeys small and
+promotes reusable interactions or shared domain representations only when their
+boundaries are proven. Tailwind, OpenAPI client generation, TanStack Query,
+React Hook Form with Zod, OIDC/Keycloak, MSW, Playwright, runtime configuration,
+and non-root nginx delivery are explicit capabilities. The
+`react-admin-api-spa` service profile selects that recommended administrative UI
+combination without changing the minimal blueprint defaults.
+
+Project-level operations are modeled separately through immutable platform
+packs. `local-compose@1.0.0` provides a development dependency boundary;
+`kubernetes-standard@1.0.0` provides provider-neutral Helm, Argo CD, Gateway
+API, OIDC, OpenTelemetry with an explicit telemetry backend, secret-management,
+backup, scheduler and event decisions. Stateful additions such as Keycloak,
+Velero, a self-hosted observability stack or a message broker stay explicit
+capabilities rather than silent service defaults.
+
+## Installation and API
+
+```bash
+pip install ai-project-blueprints==0.2.0
+ai-project-blueprints list
+ai-project-blueprints platform-list
+ai-project-blueprints validate
+```
+
+Python consumers use `ai_project_blueprints` to discover and read resources.
+Access is backed by `importlib.resources`, so an installed wheel does not depend
+on a repository checkout:
+
+```python
+from ai_project_blueprints import load_manifest, load_platform_manifest, read_text
+
+manifest = load_manifest("python-api-fastapi", "1.1.0")
+coder_instructions = read_text("blueprints/python-api-fastapi/1.1.0/instructions/coder.md")
+platform = load_platform_manifest("kubernetes-standard", "1.0.0")
+```
+
+The API and CLI are inspect-only. They do not materialize or overwrite project
+files.
+
+## Layout
+
+```text
+src/ai_project_blueprints/resources/  packaged catalogs, schemas, docs, examples, and packs
+src/ai_project_blueprints/            public API, CLI, and trusted validation tooling
+tests/         catalog invariant tests
+```
+
+## Validate
+
+Python 3.11+ is required for the catalog tooling.
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/ai-project-blueprints validate
+.venv/bin/ruff check .
+.venv/bin/pyright
+.venv/bin/pytest -n auto
+```
+
+The current release is a catalog contract and authored template pack. It does not
+yet include a materializer; consumers must preview an exact manifest version and
+preserve caller-owned files when they implement materialization.
+
+## Multi-service orchestration
+
+[`catalog/service-workflows.json`](src/ai_project_blueprints/resources/catalog/service-workflows.json) separates
+three provider-neutral concepts: a `service_profile` chooses blueprint defaults,
+an `agent_bundle` supplies ordered role instructions, and a `workflow_bundle`
+describes one bounded service workflow. The consumer-owned
+[`examples/python-multiservice-project.json`](src/ai_project_blueprints/resources/examples/python-multiservice-project.json)
+shows backend services using different PostgreSQL/SQLite profiles and a React
+administrative UI using its own profile, instruction bundle, workflow bundle,
+and runtime-profile aliases under one workspace orchestrator.
+
+[`catalog/platform-workflows.json`](src/ai_project_blueprints/resources/catalog/platform-workflows.json)
+adds environment-level platform profiles, agent bundles and bounded platform
+workflows. Workspace schema version 2 binds `local` to Compose and
+`staging`/`production` to Kubernetes while retaining per-role runtime aliases.
+Service workflows consume the resulting operational contracts but do not own
+shared cluster resources.
+
+Concrete runtime aliases, models, providers, credentials and service-local
+instructions remain consumer-owned. The catalog only validates their safe
+logical bindings. Cross-service work is serialized and composed by the single
+host; a service workflow cannot start a nested orchestrator or independently
+claim the same checkout.
+
+See [the Python API stack policy](src/ai_project_blueprints/resources/docs/stack-policy.md)
+and [the React SPA stack policy](src/ai_project_blueprints/resources/docs/ui-stack-policy.md)
+and [the feature-first architecture policy](src/ai_project_blueprints/resources/docs/code-architecture-policy.md)
+and [the platform profile policy](src/ai_project_blueprints/resources/docs/platform-policy.md)
+for selection rationale. The [package contract](src/ai_project_blueprints/resources/docs/package-contract.md)
+and [release policy](src/ai_project_blueprints/resources/docs/release-policy.md)
+define resource compatibility and GitLab.com/PyPI publication gates.

ai_project_blueprints-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=80,<81"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-project-blueprints"
+version = "0.2.0"
+description = "Validated, versioned project blueprint catalog for coding agents"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "jsonschema>=4.25,<5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.3,<2",
+    "pyright>=1.1.405,<2",
+    "pytest>=8.4,<10",
+    "pytest-xdist>=3.8,<4",
+    "ruff>=0.13,<1",
+    "twine>=6.2,<7",
+]
+
+[project.scripts]
+ai-project-blueprints = "ai_project_blueprints.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ai_project_blueprints = ["resources/**/*", "resources/**/.*"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/test_resources.py" = ["E501"] # Fixed path/hash pairs remain auditable one per line.
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+reportMissingModuleSource = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

ai_project_blueprints-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ai_project_blueprints-0.2.0/src/ai_project_blueprints/__init__.py

@@ -0,0 +1,27 @@
+"""Versioned project blueprints for coding agents."""
+
+from .resources import (
+    JsonValue,
+    list_blueprints,
+    list_platforms,
+    load_catalog,
+    load_manifest,
+    load_platform_manifest,
+    read_bytes,
+    read_json,
+    read_text,
+    resource_inventory,
+)
+
+__all__ = [
+    "JsonValue",
+    "list_blueprints",
+    "list_platforms",
+    "load_catalog",
+    "load_manifest",
+    "load_platform_manifest",
+    "read_bytes",
+    "read_json",
+    "read_text",
+    "resource_inventory",
+]

ai_project_blueprints-0.2.0/src/ai_project_blueprints/cli.py

@@ -0,0 +1,85 @@
+"""JSON-oriented command line interface for packaged blueprints."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import TextIO
+
+from .resources import (
+    list_blueprints,
+    list_platforms,
+    load_manifest,
+    load_platform_manifest,
+    read_text,
+)
+from .validate import validate_repository
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ai-project-blueprints")
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    validate = subcommands.add_parser("validate", help="validate packaged or checkout resources")
+    validate.add_argument(
+        "--root", type=Path, help="explicit resource root containing catalog/, schemas/, etc."
+    )
+
+    subcommands.add_parser("list", help="list available blueprint versions")
+    subcommands.add_parser("platform-list", help="list available platform versions")
+
+    manifest = subcommands.add_parser("manifest", help="read one exact blueprint manifest")
+    manifest.add_argument("blueprint_id")
+    manifest.add_argument("version")
+
+    platform_manifest = subcommands.add_parser(
+        "platform-manifest", help="read one exact platform manifest"
+    )
+    platform_manifest.add_argument("platform_id")
+    platform_manifest.add_argument("version")
+
+    read = subcommands.add_parser("read", help="read one safe relative text resource")
+    read.add_argument("path")
+    read.add_argument("--encoding", default="utf-8")
+    return parser
+
+
+def _emit(payload: object, *, stream: TextIO | None = None) -> None:
+    output = sys.stdout if stream is None else stream
+    json.dump(payload, output, ensure_ascii=False, sort_keys=True)
+    output.write("\n")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run a CLI command and return its process exit code."""
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "validate":
+            errors = validate_repository(args.root)
+            _emit({"errors": errors, "valid": not errors})
+            return 0 if not errors else 1
+        if args.command == "list":
+            _emit({"blueprints": list_blueprints()})
+            return 0
+        if args.command == "platform-list":
+            _emit({"platforms": list_platforms()})
+            return 0
+        if args.command == "manifest":
+            _emit(load_manifest(args.blueprint_id, args.version))
+            return 0
+        if args.command == "platform-manifest":
+            _emit(load_platform_manifest(args.platform_id, args.version))
+            return 0
+        if args.command == "read":
+            _emit({"path": args.path, "text": read_text(args.path, encoding=args.encoding)})
+            return 0
+    except (FileNotFoundError, IsADirectoryError, UnicodeError, ValueError) as error:
+        _emit({"error": str(error), "type": type(error).__name__}, stream=sys.stderr)
+        return 2
+    raise AssertionError(f"unhandled command {args.command!r}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ai_project_blueprints-0.2.0/src/ai_project_blueprints/resources/blueprints/python-api-fastapi/1.0.0/README.md

@@ -0,0 +1,19 @@
+# python-api-fastapi 1.0.0
+
+Preview release of a new Python HTTP API baseline. The base is intentionally small;
+every operationally expensive concern is an explicit capability.
+
+| Capability | Default | Purpose |
+|---|---:|---|
+| `base` | yes | FastAPI, typed settings, SQLAlchemy/Alembic, quality gates |
+| `database-postgresql` | yes | Recommended production database profile |
+| `database-sqlite` | no | Embedded database for bounded single-instance use |
+| `testcontainers-postgresql` | no | Real PostgreSQL migration and persistence tests |
+| `oidc-keycloak` | no | Standards-based OIDC bearer-token validation |
+| `docker` | no | Reproducible non-root application image |
+| `postgresql-local-compose` | no | Local API and PostgreSQL; requires Docker + PostgreSQL |
+| `kubernetes-helm` | no | Kubernetes chart; requires Docker, rejects SQLite |
+| `ai-docs-workflow` | no | Documentation-driven planning and agent handoff overlay |
+
+Read `instructions/orchestrator-intake.md` before resolving the pack and pass the
+resolved capability list to Coder and Reviewer.

ai_project_blueprints-0.2.0/src/ai_project_blueprints/resources/blueprints/python-api-fastapi/1.0.0/instructions/ai-docs-workflow.md

@@ -0,0 +1,22 @@
+# AI Docs workflow overlay
+
+Use this overlay only when the consumer repository has adopted the AI Docs Toolkit.
+The toolkit remains the source of truth for document schemas and lifecycle rules;
+do not copy its schemas or workflow implementation into the generated service.
+
+Before implementation:
+
+1. Convert the confirmed project brief into durable product scope, architecture
+   decisions, external/API contracts, business rules, acceptance criteria, and
+   executable test cases at their canonical consumer-owned locations.
+2. Create a bounded planning record that references those durable owners. Keep
+   user/product decisions with the host orchestrator rather than delegating them
+   implicitly to Coder.
+3. Give Coder only the relevant instruction sources and resolved blueprint
+   manifest. Give Reviewer the same acceptance and contract owners independently.
+4. Record validation evidence, promote durable conclusions out of temporary
+   planning records, and retire completed lifecycle records according to the
+   consumer's toolkit policy.
+
+If the toolkit is unavailable or invalid, stop before inventing look-alike AI Docs
+artifacts. The service can still use the base pack without this overlay.

ai_project_blueprints-0.2.0/src/ai_project_blueprints/resources/blueprints/python-api-fastapi/1.0.0/instructions/coder.md

@@ -0,0 +1,39 @@
+# Coder instructions
+
+Implement the smallest service that satisfies the confirmed brief. The supplied
+template is a structural baseline, not permission to invent domain behavior.
+
+## Architecture boundaries
+
+- Keep transport, application/domain behavior, and persistence seams explicit.
+- Create one SQLAlchemy `AsyncSession` per request or unit of work; never share a
+  session across concurrent tasks.
+- Implement only the selected database profile. For SQLite, enable Alembic batch
+  mode, document single-instance/write-concurrency limits, and avoid silently
+  relying on PostgreSQL-compatible behavior. For PostgreSQL, test material SQL
+  and migrations against PostgreSQL rather than SQLite substitutes.
+- Treat Alembic revisions as reviewed source. Generate a revision, inspect it,
+  exercise upgrade from an empty database, and define downgrade policy.
+- Use Pydantic models at HTTP/configuration boundaries. Do not return ORM objects
+  as an accidental public contract.
+- Put liveness at `/health/live` and dependency-aware readiness at
+  `/health/ready`; do not make liveness depend on the database.
+- Use structured logs and correlation identifiers. Never log access tokens,
+  authorization headers, database URLs, or secrets.
+
+## Verification loop
+
+Run focused tests while changing code, then the stable closure set:
+
+```bash
+ruff format --check .
+ruff check .
+pyright
+pytest -n auto -m 'not integration'
+pytest -n auto -m integration  # when the chosen profile supplies integration tests
+alembic upgrade head            # against an empty selected database
+```
+
+If an OpenAPI contract is caller-owned, export and compare it in CI. Add tests for
+authorization denial, invalid configuration, migration upgrade, readiness failure,
+and transaction rollback when those behaviors are in scope.

ai_project_blueprints-0.2.0/src/ai_project_blueprints/resources/blueprints/python-api-fastapi/1.0.0/instructions/deployment.md

@@ -0,0 +1,31 @@
+# Deployment instructions
+
+Build one immutable image from the project lock file. Run migrations as a separate,
+serialized release action; do not run them concurrently in every web replica.
+
+## Docker
+
+- Build from an official slim Python image and install locked dependencies.
+- Run as a non-root user with exec-form `CMD` so termination signals reach the
+  server process.
+- Keep configuration in environment variables and secrets in the target
+  platform's secret store. The image must not contain `.env` or credentials.
+- Add an image vulnerability scan and software-bill-of-materials step in CI.
+
+## Kubernetes/Helm
+
+- Pin the deployed image by immutable tag or digest.
+- Use separate startup, readiness, and liveness probes. Only readiness may depend
+  on PostgreSQL.
+- Define CPU/memory requests and limits, a rolling update policy, pod security
+  context, termination grace period, and disruption expectations.
+- Reference externally managed Secrets; do not put secret values in Helm values.
+- Provide rollback instructions that account for database migration compatibility.
+
+The Helm overlay in this release is PostgreSQL-only. SQLite deployment requires a
+separate single-replica persistence design, backup/restore policy, and durable
+volume contract; do not adapt the current two-replica chart implicitly.
+
+Observability is a project decision. If selected, prefer OpenTelemetry signals and
+make service name/environment resource attributes explicit; do not add a backend
+vendor by default.

ai_project_blueprints-0.2.0/src/ai_project_blueprints/resources/blueprints/python-api-fastapi/1.0.0/instructions/orchestrator-intake.md

@@ -0,0 +1,35 @@
+# Orchestrator intake: Python API
+
+Use this pack only for a new independently deployable Python HTTP API. Preserve
+these caller-owned decisions in the resolved brief:
+
+1. Service name, package/distribution name, ownership, and bounded responsibility.
+2. API consumers and compatibility policy.
+3. Data ownership and whether this service owns its database/schema.
+4. Authentication mode: none/internal gateway, OIDC resource server, or deferred.
+5. Deployment target: local only, Docker, or Kubernetes/Helm.
+6. Database profile and whether real-database integration tests are necessary.
+
+## Defaults and selection rules
+
+- Select `base` always.
+- Select exactly one database profile. Use `database-postgresql` by default. Use
+  `database-sqlite` only for a prototype, local tool, or bounded single-instance
+  service with no PostgreSQL-specific requirements and modest write concurrency.
+- Select `testcontainers-postgresql` when SQL queries, constraints, transaction
+  behavior, migrations, or PostgreSQL-specific types are material to correctness.
+- Select `oidc-keycloak` when the API directly accepts bearer tokens. Keycloak is
+  one compatible issuer, not an application SDK dependency.
+- Select `docker` for a container artifact.
+- Select `postgresql-local-compose` only with `docker` and
+  `database-postgresql` when a local containerized database is useful.
+- Select `kubernetes-helm` only when Kubernetes deployment is confirmed; it
+  requires `docker` and is incompatible with the SQLite profile in this release.
+- Select `ai-docs-workflow` only when the consumer repository has adopted a
+  compatible AI Docs Toolkit workflow; never bootstrap look-alike documents.
+- Do not infer brokers, caches, background workers, multi-tenancy, or an API
+  gateway. Record these as architecture decisions before adding dependencies.
+
+Before writing files, produce a preview containing the exact blueprint version,
+selected capabilities, dependency groups, rendered target paths, conflicts, and
+unresolved variables. Never overwrite an existing path without caller approval.

ai_project_blueprints-0.2.0/src/ai_project_blueprints/resources/blueprints/python-api-fastapi/1.0.0/instructions/reviewer.md

@@ -0,0 +1,22 @@
+# Reviewer instructions
+
+Review the generated service against its resolved manifest and project brief.
+Report concrete findings before optional improvements.
+
+- Confirm no target file was overwritten outside the approved preview.
+- Confirm dependency additions map to selected capabilities and constraints.
+- Verify the service owns its migrations and startup does not silently mutate the
+  schema.
+- Verify async database sessions are request-scoped and transactions have an
+  explicit commit/rollback owner.
+- Verify HTTP schemas do not leak persistence models or secret configuration.
+- With OIDC enabled, verify issuer, audience, signature, expiry, and required
+  claims/permissions; reject fail-open behavior.
+- With Kubernetes enabled, verify startup/readiness/liveness semantics, graceful
+  termination, resource requests/limits, non-root execution, and external secret
+  references.
+- Verify exactly one database profile is selected. Reject SQLite for horizontal
+  scaling, multiple writers, or PostgreSQL-specific behavior without a recorded
+  architecture decision.
+- Verify unit tests remain fast and integration tests have an explicit marker;
+  document Docker as a prerequisite only for Testcontainers-backed tests.