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 latest backend pack is python-api-fastapi@1.2.0; immutable 1.0.0 and 1.1.0 remain 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. Version 1.2.0 limits pack instructions to the FastAPI layout, selected stack, overlays and concrete checks. Its application templates are unchanged. Existing service profiles stay pinned to 1.1.0; select 1.2.0 directly through its manifest when adopting the separated instruction layout.

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.

The standalone python-toolkit@2.0.0 pack provides a Python 3.14+ library, JSON CLI and packaged instructions/resources. It starts with a standard-library runtime, Ruff, strict Pyright, pytest, coverage, xdist, build and twine. A consumer-owned uv lock makes development reproducible. It includes portable Python verification scripts and an installed-wheel smoke outside the source tree. A single agent can use it directly, without service/platform profiles. See the Python toolkit policy.

The instruction-only set dotnet-project-guidance@2.5.0 provides portable C# vertical slices, compact compiler/analyzer-checked style, isolated parallel tests and document-owned test references and shared optional runner adapters. It can be adopted by existing services, workers, CLIs, libraries and fixture drivers. Version2.1.0 adds SDK build checks, CleanupCode formatting and local InspectCode after cohesive functionality blocks and at final task review before commit. Version2.5.0 adds one canonical documentation tree with module ownership, separate current procedures and dated evidence, and explicit migration checks. It is a portable convention for new applications; existing projects keep their layout until a scoped migration. Version2.4.0 moves test references into owner documents and uses shared evidence adapters with semantic closure review. It retains standard SDK/JetBrains checks and review gaps when retiring custom analyzers. Earlier versions remain immutable. Version2.2.0 adds explicit module contracts, matching functional test projects and bounded change context. Contract-first coordination supports repository-owned modules and internal functional blocks when the consumer workflow permits delegation; this guidance does not change the orchestrator's execution policy. Versions1.0.0,2.0.0 and2.1.0 remain available unchanged. It supplies guidance, without declaring an executable .NET starter or service profile. Existing projects explicitly record the exact adopted version and resource hashes; package updates do not rewrite their instructions.

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

pip install ai-project-blueprints==0.3.0
ai-project-blueprints list
ai-project-blueprints platform-list
ai-project-blueprints validate

Distribution 0.3.0 includes the toolkit packs, Python guidance and .NET instruction sets. Release notes and migration explain the Python 3.14 requirement and explicit resource adoption. Inspect the installed resources through the public CLI:

ai-project-blueprints manifest python-toolkit 2.0.0
ai-project-blueprints blueprint-smoke python-toolkit 2.0.0
ai-project-blueprints read catalog/instruction-sets.json
ai-project-blueprints read instruction-sets/dotnet-project-guidance/2.5.0/agent.md

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:

from ai_project_blueprints import load_manifest, load_platform_manifest, read_text

manifest = load_manifest("python-api-fastapi", "1.2.0")
coder_instructions = read_text("blueprints/python-api-fastapi/1.2.0/instructions/coder.md")
platform = load_platform_manifest("kubernetes-standard", "1.0.0")

For instruction-only sets, use load_catalog("instruction-sets"), then read_json(entry["manifest"]) and read_text() for each declared instruction relative to that manifest's directory. resource_inventory("instruction-sets") lists their packaged files. The same reads work from an installed wheel.

The API and CLI are inspect-only. They do not materialize or overwrite project files.

Python project guidance

python-project-guidance@1.0.0 owns general Python architecture, types, dependencies, persistence, diagnostics and verification. Its conditional worker guidance covers bounded I/O concurrency, task/process ownership, cancellation, durable acceptance, retries and recovery. The manifest declares all four instruction documents. The set selects no framework, database, broker or service profile and creates no worker starter.

Adopt the set independently of a blueprint. To use it alongside FastAPI 1.2.0, record both exact manifests, load the set's declared instructions, then apply the pack's stack-specific instructions. Neither selection implicitly loads the other. These resources are included in distribution 0.3.0 and can be read through the installed public API:

from ai_project_blueprints import read_json, read_text

prefix = "instruction-sets/python-project-guidance/1.0.0"
manifest = read_json(f"{prefix}/manifest.json")
entrypoint = read_text(f"{prefix}/agent.md")
engineering = read_text(f"{prefix}/engineering.md")
worker = read_text(f"{prefix}/worker.md")

Use ai-project-blueprints read instruction-sets/python-project-guidance/1.0.0/agent.md for JSON CLI output. Record the distribution version, set ID/version and complete resource hashes. Existing docs/python-engineering-policy.md and docs/python-worker-policy.md paths remain navigation pages; existing local copies retain their provenance until explicitly migrated. See the package contract and ownership and verification plan.

Compatibility inspection

Совместимость можно проверить через compatibility_matrix(), resolve_combination() и golden_smoke() либо команды compatibility-matrix и compatibility-smoke. Матрица schema version 1 детерминированно выводится из canonical service/platform catalog и manifest, поэтому неизвестный profile или capability отклоняется. Golden smoke собирает объявленные файлы только в памяти, подставляет manifest examples/defaults, сводит выбранные npm dependency records и прекращает работу при missing source или target collision; consumer-файлы он не создаёт и не перезаписывает.

Layout

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.14+ is required for the catalog tooling. CI quality checks, builds and publication use Python 3.14. Recreate older environments before upgrading to a new package release with this minimum.

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ai-project-blueprints validate
.venv/bin/ruff check .
.venv/bin/pyright --pythonpath .venv/bin/python
.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.

Обычная проверка использует bounded core tier. Команды, которым действительно нужны Docker, Helm, browser E2E или capability testcontainers-postgresql, попадают в отдельный heavyweight tier и появляются только при выборе соответствующей capability. Opt-in CI с BLUEPRINT_GENERATED_SMOKE=1 дополнительно материализует проекты во временный каталог и запускает install, lint, typecheck, tests, build и SQLite migration smoke. Временный каталог удаляется после проверки.

Standalone toolkit smoke resolves a fresh consumer lock and runs the generated sequential/parallel gates, build and runtime-only installation:

python scripts/generated_toolkit_smoke.py --execute --python 3.14 --uv /path/to/uv

The same opt-in CI flag runs the catalog driver on Python 3.14 and checks the generated 1.0.0 project on Python 3.11/3.14 and 2.0.0 on Python 3.14. These are the immutable packs' consumer runtimes, selected with --python independently of the catalog environment. The React smoke retains Node 24 and bootstraps a Python 3.14 driver with pinned uv. Without --execute, the script only renders into temporary storage and needs no uv or network. blueprint_smoke() provides the in-memory variant through the package API.

Multi-service orchestration

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 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 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 and the React SPA stack policy and the feature-first architecture policy and the platform profile policy for selection rationale. The package contract and release policy define resource compatibility and GitLab.com/PyPI publication gates.

.NET guidance2.0.0 adds one project per application, cohesive shared modules, EF Core persistence/migration bundles and copyable project-layout templates. Immutable1.0.0 remains available. These instruction/example changes are included in distribution0.3.0. Instruction-set versions are independent of the distribution version.