agent-scaffold-cli 0.1.1__tar.gz

agent_scaffold_cli-0.1.1/.env.example

@@ -0,0 +1,15 @@
+# Anthropic API key used by agent-scaffold to generate projects.
+ANTHROPIC_API_KEY=
+
+# Optional: override the default model (default: claude-opus-4-7).
+# AGENT_SCAFFOLD_MODEL=claude-opus-4-7
+
+# Optional: default path to your local agent-deployments repo.
+# AGENT_SCAFFOLD_DEPLOYMENTS_PATH=/absolute/path/to/agent-deployments
+
+# Optional: override the cache root (default: ~/.cache/agent-scaffold).
+# Used for the failures/ subdirectory where malformed LLM responses are saved.
+# AGENT_SCAFFOLD_CACHE_DIR=~/.cache/agent-scaffold
+
+# Optional: override the TOML config path (default: ~/.config/agent-scaffold/config.toml).
+# AGENT_SCAFFOLD_CONFIG_PATH=~/.config/agent-scaffold/config.toml

agent_scaffold_cli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Type check
+        run: uv run mypy src/
+
+      - name: Test
+        run: uv run pytest --cov=agent_scaffold --cov-report=term-missing

agent_scaffold_cli-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Sync bundled deployments
+        run: bash scripts/sync_deployments.sh
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_scaffold_cli-0.1.1/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# OS
+.DS_Store
+Thumbs.db
+# Allow the test fixture that intentionally exercises hidden-file filtering.
+!tests/fixtures/mock_deployments/**/.DS_Store
+
+# Editor
+.idea/
+.vscode/
+*.swp
+
+# Project local
+.env
+.env.local
+
+# Bundled deployments docs (fetched at build time via scripts/sync_deployments.sh)
+src/agent_scaffold/_bundled_deployments/docs/*
+!src/agent_scaffold/_bundled_deployments/docs/.gitkeep

agent_scaffold_cli-0.1.1/CLAUDE.md

@@ -0,0 +1,37 @@
+# agent-scaffold
+
+Generate runnable AI agent projects from markdown specs in an `agent-deployments` repo.
+
+## Commands
+
+```bash
+uv run pytest                  # run tests
+uv run pytest -m integration   # run integration tests only
+uv run ruff check src/ tests/  # lint
+uv run ruff format src/ tests/ # format
+uv run mypy src/               # type check
+uv run agent-scaffold --help      # CLI usage
+```
+
+## Architecture
+
+Pipeline: `config → discovery → context → generator → contract → writer → validator`
+
+| Module | Responsibility |
+|--------|---------------|
+| `config.py` | Load env vars + TOML config, resolve `Config` |
+| `discovery.py` | Scan `agent-deployments/docs/recipes/` for markdown recipe specs |
+| `context.py` | Assemble recipe + linked docs into a single prompt context |
+| `generator.py` | Call Anthropic API with system/user prompts, retry on transient errors |
+| `contract.py` | Parse + validate JSON response (path safety, required files) |
+| `writer.py` | Atomic file writing with skip/diff/overwrite modes |
+| `validator.py` | Post-generation validation: static lint, build, smoke check |
+| `cli.py` | Typer CLI orchestrating the full pipeline |
+
+## Conventions
+
+- Python 3.11+, strict mypy, ruff for lint+format
+- Pydantic models for all data structures
+- Custom exceptions carry context (e.g., `ContractParseError.raw`, `.reason`)
+- Tests use monkeypatching for Anthropic client; fixtures in `tests/fixtures/`
+- src layout: `src/agent_scaffold/`

agent_scaffold_cli-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jagadesh Varma Nadimpalli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_scaffold_cli-0.1.1/Makefile

@@ -0,0 +1,17 @@
+.PHONY: sync-deployments build test lint typecheck
+
+sync-deployments:
+	bash scripts/sync_deployments.sh
+
+build: sync-deployments
+	uv build
+
+test:
+	uv run pytest --cov=agent_scaffold
+
+lint:
+	uv run ruff check src/ tests/
+	uv run mypy src/
+
+typecheck:
+	uv run mypy src/

agent_scaffold_cli-0.1.1/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: agent-scaffold-cli
+Version: 0.1.1
+Summary: Generate runnable AI agent projects from markdown specs in the agent-deployments repo.
+Project-URL: Homepage, https://github.com/jagguvarma15/agent-scaffold
+Project-URL: Repository, https://github.com/jagguvarma15/agent-scaffold
+Project-URL: Issues, https://github.com/jagguvarma15/agent-scaffold/issues
+Project-URL: Changelog, https://github.com/jagguvarma15/agent-scaffold/releases
+Author: agent-scaffold contributors
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,anthropic,claude,cli,code-generation,scaffolding
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: anthropic==0.39.0
+Requires-Dist: click<8.2
+Requires-Dist: pydantic==2.7.4
+Requires-Dist: pyyaml==6.0.2
+Requires-Dist: questionary==2.0.1
+Requires-Dist: rich==13.7.1
+Requires-Dist: typer==0.12.5
+Description-Content-Type: text/markdown
+
+# agent-scaffold
+
+`agent-scaffold` generates runnable AI agent projects from markdown specs. It ships with bundled knowledge from [agent-deployments](https://github.com/jagguvarma15/agent-deployments) — pick a recipe, target language, and framework, and the CLI assembles the relevant docs, asks Claude to emit a complete project, validates the response, and writes the files atomically into your destination of choice.
+
+## Install
+
+The package is published on PyPI as **`agent-scaffold-cli`** (the CLI command itself is still `agent-scaffold`).
+
+```bash
+pipx install agent-scaffold-cli
+# or
+uv tool install agent-scaffold-cli
+# or, for one-off use:
+uvx --from agent-scaffold-cli agent-scaffold --help
+```
+
+### Local development
+
+```bash
+git clone https://github.com/jagguvarma15/agent-scaffold
+cd agent-scaffold
+uv sync
+```
+
+## Quickstart
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+agent-scaffold new
+```
+
+The bundled recipes work out of the box. To use a custom agent-deployments checkout instead:
+
+```bash
+export AGENT_SCAFFOLD_DEPLOYMENTS_PATH=/path/to/agent-deployments
+agent-scaffold new
+```
+
+The interactive `new` flow walks you through:
+
+1. The path to your `agent-deployments` repo (default from config).
+2. A recipe from `docs/recipes/*.md`.
+3. A target language (Python or TypeScript).
+4. A framework (e.g. `pydantic_ai`, `langgraph`, `vercel_ai_sdk`, or `none`).
+5. A project name and destination directory.
+
+You'll see a context summary, a generation step, a static validation pass, and a "next steps" footer with the smoke-check command.
+
+## Configuration
+
+| Source | Variable / key | Purpose |
+| --- | --- | --- |
+| Env | `ANTHROPIC_API_KEY` | Required. The Anthropic API key used by the generator. |
+| Env | `AGENT_SCAFFOLD_DEPLOYMENTS_PATH` | Default path to your `agent-deployments` checkout. |
+| Env | `AGENT_SCAFFOLD_MODEL` | Override the model (default `claude-opus-4-7`). |
+| Env | `AGENT_SCAFFOLD_CACHE_DIR` | Override the cache root (default `~/.cache/agent-scaffold`). |
+| Env | `AGENT_SCAFFOLD_CONFIG_PATH` | Override the TOML fallback location. |
+| TOML | `~/.config/agent-scaffold/config.toml` | Fallback for `deployments_path` and `model`. |
+
+Run `uv run agent-scaffold config` to print the resolved configuration (the API key is masked).
+
+A typical config file:
+
+```toml
+deployments_path = "/Users/me/code/agent-deployments"
+model = "claude-opus-4-7"
+```
+
+## Pointing at your own `agent-deployments`
+
+Either set `AGENT_SCAFFOLD_DEPLOYMENTS_PATH`, write `deployments_path` to the TOML config, or pass `--deployments-path` to `agent-scaffold new`. The directory must contain `docs/recipes/*.md` files; cross-cutting / framework / pattern / stack docs are picked up automatically based on the recipe's references.
+
+## Adding a new target language
+
+Drop a YAML file into [`src/agent_scaffold/languages/`](src/agent_scaffold/languages/) modeled after [python.yaml](src/agent_scaffold/languages/python.yaml) or [typescript.yaml](src/agent_scaffold/languages/typescript.yaml). Required keys:
+
+- `language`, `package_manager`, `project_layout`, `entry_point`, `manifest`
+- `required_tools` (formatter / type_checker / test)
+- `pinned_dependencies`, `framework_dependencies`
+- `forbidden`, `smoke_check`
+
+The CLI reads them on demand; no code changes needed unless you also want a language-specific static-validation tier (see [`src/agent_scaffold/validator.py`](src/agent_scaffold/validator.py)).
+
+## Troubleshooting
+
+### Contract parse failures
+
+If Claude returns malformed JSON, agent-scaffold:
+
+1. Saves the raw response to `~/.cache/agent-scaffold/failures/<timestamp>.json`.
+2. Prints a warning and asks Claude to repair the response.
+3. If the repair still fails, saves that raw response too and aborts with file pointers.
+
+You can re-run `agent-scaffold new` with `AGENT_SCAFFOLD_CACHE_DIR` set to inspect failures elsewhere.
+
+### `--write-mode` choices
+
+| Mode | Behavior |
+| --- | --- |
+| `abort` (default) | Refuse to write into a non-empty destination. |
+| `skip` | Keep existing files, write only new ones. |
+| `diff` | Show a unified diff per file and prompt before overwriting. |
+| `overwrite` | Replace everything. |
+
+All writes stage to a sibling temp directory and `os.replace` into place, so a failure mid-generation leaves the destination untouched.
+
+### Re-running validation
+
+`agent-scaffold validate /path/to/generated --tier static|build|smoke` reruns one of the post-generation tiers without re-invoking the LLM.
+
+
+
+## License
+
+MIT (see [LICENSE](LICENSE)).

agent_scaffold_cli-0.1.1/README.md

@@ -0,0 +1,115 @@
+# agent-scaffold
+
+`agent-scaffold` generates runnable AI agent projects from markdown specs. It ships with bundled knowledge from [agent-deployments](https://github.com/jagguvarma15/agent-deployments) — pick a recipe, target language, and framework, and the CLI assembles the relevant docs, asks Claude to emit a complete project, validates the response, and writes the files atomically into your destination of choice.
+
+## Install
+
+The package is published on PyPI as **`agent-scaffold-cli`** (the CLI command itself is still `agent-scaffold`).
+
+```bash
+pipx install agent-scaffold-cli
+# or
+uv tool install agent-scaffold-cli
+# or, for one-off use:
+uvx --from agent-scaffold-cli agent-scaffold --help
+```
+
+### Local development
+
+```bash
+git clone https://github.com/jagguvarma15/agent-scaffold
+cd agent-scaffold
+uv sync
+```
+
+## Quickstart
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+agent-scaffold new
+```
+
+The bundled recipes work out of the box. To use a custom agent-deployments checkout instead:
+
+```bash
+export AGENT_SCAFFOLD_DEPLOYMENTS_PATH=/path/to/agent-deployments
+agent-scaffold new
+```
+
+The interactive `new` flow walks you through:
+
+1. The path to your `agent-deployments` repo (default from config).
+2. A recipe from `docs/recipes/*.md`.
+3. A target language (Python or TypeScript).
+4. A framework (e.g. `pydantic_ai`, `langgraph`, `vercel_ai_sdk`, or `none`).
+5. A project name and destination directory.
+
+You'll see a context summary, a generation step, a static validation pass, and a "next steps" footer with the smoke-check command.
+
+## Configuration
+
+| Source | Variable / key | Purpose |
+| --- | --- | --- |
+| Env | `ANTHROPIC_API_KEY` | Required. The Anthropic API key used by the generator. |
+| Env | `AGENT_SCAFFOLD_DEPLOYMENTS_PATH` | Default path to your `agent-deployments` checkout. |
+| Env | `AGENT_SCAFFOLD_MODEL` | Override the model (default `claude-opus-4-7`). |
+| Env | `AGENT_SCAFFOLD_CACHE_DIR` | Override the cache root (default `~/.cache/agent-scaffold`). |
+| Env | `AGENT_SCAFFOLD_CONFIG_PATH` | Override the TOML fallback location. |
+| TOML | `~/.config/agent-scaffold/config.toml` | Fallback for `deployments_path` and `model`. |
+
+Run `uv run agent-scaffold config` to print the resolved configuration (the API key is masked).
+
+A typical config file:
+
+```toml
+deployments_path = "/Users/me/code/agent-deployments"
+model = "claude-opus-4-7"
+```
+
+## Pointing at your own `agent-deployments`
+
+Either set `AGENT_SCAFFOLD_DEPLOYMENTS_PATH`, write `deployments_path` to the TOML config, or pass `--deployments-path` to `agent-scaffold new`. The directory must contain `docs/recipes/*.md` files; cross-cutting / framework / pattern / stack docs are picked up automatically based on the recipe's references.
+
+## Adding a new target language
+
+Drop a YAML file into [`src/agent_scaffold/languages/`](src/agent_scaffold/languages/) modeled after [python.yaml](src/agent_scaffold/languages/python.yaml) or [typescript.yaml](src/agent_scaffold/languages/typescript.yaml). Required keys:
+
+- `language`, `package_manager`, `project_layout`, `entry_point`, `manifest`
+- `required_tools` (formatter / type_checker / test)
+- `pinned_dependencies`, `framework_dependencies`
+- `forbidden`, `smoke_check`
+
+The CLI reads them on demand; no code changes needed unless you also want a language-specific static-validation tier (see [`src/agent_scaffold/validator.py`](src/agent_scaffold/validator.py)).
+
+## Troubleshooting
+
+### Contract parse failures
+
+If Claude returns malformed JSON, agent-scaffold:
+
+1. Saves the raw response to `~/.cache/agent-scaffold/failures/<timestamp>.json`.
+2. Prints a warning and asks Claude to repair the response.
+3. If the repair still fails, saves that raw response too and aborts with file pointers.
+
+You can re-run `agent-scaffold new` with `AGENT_SCAFFOLD_CACHE_DIR` set to inspect failures elsewhere.
+
+### `--write-mode` choices
+
+| Mode | Behavior |
+| --- | --- |
+| `abort` (default) | Refuse to write into a non-empty destination. |
+| `skip` | Keep existing files, write only new ones. |
+| `diff` | Show a unified diff per file and prompt before overwriting. |
+| `overwrite` | Replace everything. |
+
+All writes stage to a sibling temp directory and `os.replace` into place, so a failure mid-generation leaves the destination untouched.
+
+### Re-running validation
+
+`agent-scaffold validate /path/to/generated --tier static|build|smoke` reruns one of the post-generation tiers without re-invoking the LLM.
+
+
+
+## License
+
+MIT (see [LICENSE](LICENSE)).

agent_scaffold_cli-0.1.1/pyproject.toml

@@ -0,0 +1,103 @@
+[project]
+name = "agent-scaffold-cli"
+version = "0.1.1"
+description = "Generate runnable AI agent projects from markdown specs in the agent-deployments repo."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "agent-scaffold contributors" }]
+keywords = ["ai", "agent", "anthropic", "claude", "cli", "code-generation", "scaffolding"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+    "typer==0.12.5",
+    "click<8.2",
+    "questionary==2.0.1",
+    "rich==13.7.1",
+    "anthropic==0.39.0",
+    "pydantic==2.7.4",
+    "pyyaml==6.0.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/jagguvarma15/agent-scaffold"
+Repository = "https://github.com/jagguvarma15/agent-scaffold"
+Issues = "https://github.com/jagguvarma15/agent-scaffold/issues"
+Changelog = "https://github.com/jagguvarma15/agent-scaffold/releases"
+
+[project.scripts]
+agent-scaffold = "agent_scaffold.cli:app"
+
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+exclude = ["**/.gitkeep"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_scaffold"]
+
+# Bundled deployments docs are .gitignored (synced by scripts/sync_deployments.sh
+# at build time), so the default VCS-aware package walk skips them. Force-include
+# them into both the wheel and the sdist explicitly.
+[tool.hatch.build.targets.wheel.force-include]
+"src/agent_scaffold/_bundled_deployments/docs" = "agent_scaffold/_bundled_deployments/docs"
+
+[tool.hatch.build.targets.sdist.force-include]
+"src/agent_scaffold/_bundled_deployments/docs" = "src/agent_scaffold/_bundled_deployments/docs"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B008"]
+"src/agent_scaffold/cli.py" = ["B008"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+disallow_untyped_decorators = false
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = ["questionary.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"
+markers = ["integration: marks tests requiring network or external tools"]
+
+[dependency-groups]
+dev = [
+    "pytest==8.2.2",
+    "pytest-cov==5.0.0",
+    "ruff==0.6.9",
+    "mypy==1.11.2",
+    "types-PyYAML==6.0.12.20240917",
+]
+
+[tool.coverage.run]
+source = ["agent_scaffold"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true

agent_scaffold_cli-0.1.1/scripts/sync_deployments.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Sync agent-deployments docs into the bundled package data directory.
+# Run this before building a release wheel.
+set -euo pipefail
+
+REPO_URL="${AGENT_DEPLOYMENTS_REPO:-https://github.com/jagguvarma15/agent-deployments.git}"
+DEST="src/agent_scaffold/_bundled_deployments/docs"
+TMP_DIR=$(mktemp -d)
+
+echo "Cloning agent-deployments (shallow)..."
+git clone --depth 1 "$REPO_URL" "$TMP_DIR"
+
+echo "Copying docs into $DEST..."
+rm -rf "$DEST"
+mkdir -p "$DEST"
+
+for subdir in recipes patterns frameworks stack cross-cutting; do
+    if [ -d "$TMP_DIR/docs/$subdir" ]; then
+        cp -r "$TMP_DIR/docs/$subdir" "$DEST/"
+        echo "  copied docs/$subdir"
+    fi
+done
+
+rm -rf "$TMP_DIR"
+echo "Done. Bundled docs ready at $DEST"

agent_scaffold_cli-0.1.1/src/agent_scaffold/__init__.py

@@ -0,0 +1,8 @@
+"""agent-scaffold: generate runnable AI agent projects from markdown specs."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("agent-scaffold-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"

agent_scaffold_cli-0.1.1/src/agent_scaffold/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m agent_scaffold`."""
+
+from agent_scaffold.cli import app
+
+if __name__ == "__main__":
+    app()

agent_scaffold_cli-0.1.1/src/agent_scaffold/_bundled_deployments/__init__.py

@@ -0,0 +1,15 @@
+"""Bundled agent-deployments docs for zero-config usage.
+
+The docs/ directory is populated at build time by scripts/sync_deployments.sh.
+When installed via PyPI/Homebrew, the bundled docs allow agent-scaffold to work
+without requiring a separate agent-deployments clone.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def bundled_docs_path() -> Path:
+    """Return the path to the bundled deployments root (contains docs/)."""
+    return Path(__file__).parent

agent_scaffold_cli-0.1.1/src/agent_scaffold/_bundled_deployments/docs/cross-cutting/README.md

@@ -0,0 +1,15 @@
+# Cross-cutting Concerns
+
+Shared production plumbing used by all agents. Each file answers: **"What production scaffolding do I need?"**
+
+| Concern | Library (Py / TS) | Reference |
+|---------|-------------------|-----------|
+| [Auth](auth-jwt.md) | python-jose / hono-jwt | Inline implementation below |
+| [Logging](logging-structured.md) | structlog / pino | Inline implementation below |
+| [Observability](observability.md) | Langfuse SDK | Inline implementation below |
+| [Rate Limiting](rate-limiting.md) | slowapi / hono-rate-limiter | Inline implementation below |
+| [Testing](testing-strategy.md) | pytest + DeepEval / vitest + Promptfoo | Inline implementation below |
+
+## The 11-point production checklist
+
+Every blueprint specifies these concerns. See [playbook/production-checklist.md](../playbook/production-checklist.md) for the full checklist.