pdd-cli 0.0.42__py3-none-any.whl → 0.0.90__py3-none-any.whl

pdd/template_registry.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import re
+import shutil
+from collections.abc import Iterable as IterableABC
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from importlib.resources import as_file
+
+try:
+    from importlib.resources import files as pkg_files
+except ImportError:  # pragma: no cover
+    # Fallback for Python < 3.11 if needed.
+    from importlib_resources import files as pkg_files  # type: ignore[attr-defined]
+
+
+_FRONT_MATTER_PATTERN = re.compile(r"^---\s*\r?\n(.*?)\r?\n---\s*\r?\n?", re.DOTALL)
+_SOURCE_PRIORITY = {"packaged": 0, "project": 1}
+
+
+@dataclass
+class TemplateMeta:
+    name: str
+    path: Path
+    description: str = ""
+    version: str = ""
+    tags: List[str] = field(default_factory=list)
+    language: str = ""
+    output: str = ""
+    variables: Dict[str, Any] = field(default_factory=dict)
+    usage: Dict[str, Any] = field(default_factory=dict)
+    discover: Dict[str, Any] = field(default_factory=dict)
+    output_schema: Dict[str, Any] = field(default_factory=dict)
+    notes: str = ""
+    source: str = "packaged"
+
+    @property
+    def alias(self) -> str:
+        return self.path.stem
+
+
+def _safe_load_yaml(text: str) -> Optional[Dict[str, Any]]:
+    try:
+        import yaml  # type: ignore
+    except ImportError as exc:  # pragma: no cover - PyYAML is an install requirement
+        raise RuntimeError("PyYAML is required to parse template front matter") from exc
+
+    try:
+        data = yaml.safe_load(text) or {}
+    except Exception:
+        return None
+    if not isinstance(data, dict):
+        return None
+    return data
+
+
+def _parse_front_matter(text: str) -> Tuple[Optional[Dict[str, Any]], str]:
+    match = _FRONT_MATTER_PATTERN.match(text)
+    if not match:
+        return None, text
+    meta_text = match.group(1)
+    rest = text[match.end():]
+    meta = _safe_load_yaml(meta_text)
+    return meta, rest
+
+
+def _normalize_tags(tags: Any) -> List[str]:
+    if tags is None:
+        return []
+    if isinstance(tags, str):
+        return [tags.lower()]
+    if isinstance(tags, IterableABC):
+        normalized: List[str] = []
+        for tag in tags:
+            if tag is None:
+                continue
+            normalized.append(str(tag).lower())
+        return normalized
+    return []
+
+
+def _ensure_mapping(value: Any) -> Dict[str, Any]:
+    if isinstance(value, dict):
+        return dict(value)
+    return {}
+
+
+def _normalize_meta(raw: Dict[str, Any], path: Path, source: str) -> TemplateMeta:
+    name = str(raw.get("name") or path.stem)
+    description = str(raw.get("description") or "")
+    version = str(raw.get("version") or "")
+    language = str(raw.get("language") or "")
+    output = str(raw.get("output") or "")
+    tags = _normalize_tags(raw.get("tags"))
+    notes_raw = raw.get("notes")
+    notes = "" if notes_raw is None else str(notes_raw)
+
+    return TemplateMeta(
+        name=name,
+        path=path.resolve(),
+        description=description,
+        version=version,
+        tags=tags,
+        language=language,
+        output=output,
+        variables=_ensure_mapping(raw.get("variables")),
+        usage=_ensure_mapping(raw.get("usage")),
+        discover=_ensure_mapping(raw.get("discover")),
+        output_schema=_ensure_mapping(raw.get("output_schema")),
+        notes=notes,
+        source=source,
+    )
+
+
+def _iter_project_templates() -> Iterable[Path]:
+    root = Path.cwd() / "prompts"
+    if not root.exists():
+        return ()
+    return (path for path in root.rglob("*.prompt") if path.is_file())
+
+
+def _iter_packaged_templates() -> Iterable[Path]:
+    try:
+        pkg_root = pkg_files("pdd").joinpath("templates")
+    except ModuleNotFoundError:  # pragma: no cover - package missing
+        return ()
+    if not pkg_root.is_dir():
+        return ()
+
+    resolved: List[Path] = []
+    for entry in pkg_root.rglob("*.prompt"):  # type: ignore[attr-defined]
+        try:
+            with as_file(entry) as concrete:
+                path = Path(concrete)
+                if path.is_file():
+                    resolved.append(path)
+        except FileNotFoundError:
+            continue
+    return resolved
+
+
+def _load_meta_from_path(path: Path, source: str) -> Optional[TemplateMeta]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    front_matter, _ = _parse_front_matter(text)
+    if not front_matter:
+        return None
+    return _normalize_meta(front_matter, path, source)
+
+
+def _index_templates() -> Tuple[Dict[str, TemplateMeta], Dict[str, TemplateMeta]]:
+    by_name: Dict[str, TemplateMeta] = {}
+    priority: Dict[str, int] = {}
+
+    def register(meta: TemplateMeta) -> None:
+        current_priority = priority.get(meta.name, -1)
+        new_priority = _SOURCE_PRIORITY.get(meta.source, 0)
+        if new_priority < current_priority:
+            return
+        by_name[meta.name] = meta
+        priority[meta.name] = new_priority
+
+    for path in _iter_packaged_templates():
+        meta = _load_meta_from_path(Path(path), "packaged")
+        if meta:
+            register(meta)
+
+    for path in _iter_project_templates():
+        meta = _load_meta_from_path(Path(path), "project")
+        if meta:
+            register(meta)
+
+    lookup = dict(by_name)
+    lookup_priority = priority.copy()
+
+    for meta in by_name.values():
+        alias = meta.alias
+        alias_priority = lookup_priority.get(alias, -1)
+        meta_priority = priority.get(meta.name, 0)
+        if alias_priority <= meta_priority:
+            lookup[alias] = meta
+            lookup_priority[alias] = meta_priority
+
+    return by_name, lookup
+
+
+def _meta_to_payload(meta: TemplateMeta) -> Dict[str, Any]:
+    return {
+        "name": meta.name,
+        "path": str(meta.path),
+        "description": meta.description,
+        "version": meta.version,
+        "tags": list(meta.tags),
+        "language": meta.language,
+        "output": meta.output,
+        "variables": dict(meta.variables),
+        "usage": dict(meta.usage),
+        "discover": dict(meta.discover),
+        "output_schema": dict(meta.output_schema),
+        "notes": meta.notes,
+    }
+
+
+def list_templates(filter_tag: Optional[str] = None) -> List[Dict[str, Any]]:
+    by_name, _ = _index_templates()
+    normalized_tag = filter_tag.lower() if filter_tag else None
+    items: List[Dict[str, Any]] = []
+    for meta in by_name.values():
+        if normalized_tag and normalized_tag not in meta.tags:
+            continue
+        items.append({
+            "name": meta.name,
+            "path": str(meta.path),
+            "description": meta.description,
+            "version": meta.version,
+            "tags": list(meta.tags),
+        })
+    items.sort(key=lambda item: item["name"].lower())
+    return items
+
+
+def load_template(name: str) -> Dict[str, Any]:
+    _, lookup = _index_templates()
+    meta = lookup.get(name)
+    if not meta:
+        raise FileNotFoundError(f"Template '{name}' not found.")
+    return _meta_to_payload(meta)
+
+
+def show_template(name: str) -> Dict[str, Any]:
+    meta = load_template(name)
+    summary = {
+        "name": meta["name"],
+        "path": meta["path"],
+        "description": meta.get("description", ""),
+        "version": meta.get("version", ""),
+        "tags": meta.get("tags", []),
+        "language": meta.get("language", ""),
+        "output": meta.get("output", ""),
+    }
+    return {
+        "summary": summary,
+        "variables": meta.get("variables", {}),
+        "usage": meta.get("usage", {}),
+        "discover": meta.get("discover", {}),
+        "output_schema": meta.get("output_schema", {}),
+        "notes": meta.get("notes", ""),
+    }
+
+
+def copy_template(name: str, dest_dir: str) -> str:
+    meta = load_template(name)
+    src = Path(meta["path"])
+    if not src.exists():
+        raise FileNotFoundError(f"Template '{name}' file is missing at {src}")
+    dest_root = Path(dest_dir)
+    dest_root.mkdir(parents=True, exist_ok=True)
+    dest_path = dest_root / src.name
+    shutil.copy2(src, dest_path)
+    return str(dest_path.resolve())

pdd/templates/architecture/architecture_json.prompt

@@ -0,0 +1,242 @@
+---
+name: architecture/architecture_json
+description: Unified architecture template for multiple tech stacks
+version: 1.0.0
+tags: [architecture, template, json]
+language: json
+output: architecture.json
+post_process_python: ./pdd/render_mermaid.py
+post_process_args:
+  - "{INPUT_FILE}"
+  - "{APP_NAME}"
+  - "{OUTPUT_HTML}"
+variables:
+  APP_NAME:
+    required: false
+    type: string
+    description: Optional app name for context.
+    example: Shop
+  PRD_FILE:
+    required: true
+    type: path
+    description: Primary product requirements document (PRD) describing scope and goals.
+    example_paths: [PRD.md, docs/specs.md, docs/product/prd.md]
+    example_content: |
+      Title: Order Management MVP
+      Goals: Enable customers to create and track orders end-to-end.
+      Key Features:
+        - Create Order: id, user_id, items[], total, status
+        - View Order: details page with status timeline
+        - List Orders: filter by status, date, user
+      Non-Functional Requirements:
+        - P95 latency < 300ms for read endpoints
+        - Error rate < 0.1%
+  TECH_STACK_FILE:
+    required: false
+    type: path
+    description: Tech stack overview (languages, frameworks, infrastructure, and tools).
+    example_paths: [docs/tech_stack.md, docs/architecture/stack.md]
+    example_content: |
+      Backend: Python (FastAPI), Postgres (SQLAlchemy), PyTest
+      Frontend: Next.js (TypeScript), shadcn/ui, Tailwind CSS
+      API: REST
+      Auth: Firebase Auth (GitHub Device Flow), JWT for API
+      Infra: Vercel (frontend), Cloud Run (backend), Cloud SQL (Postgres)
+      Observability: OpenTelemetry traces, Cloud Logging
+  DOC_FILES:
+    required: false
+    type: list
+    description: Additional documentation files (comma/newline-separated).
+    example_paths: [docs/ux.md, docs/components.md]
+    example_content: |
+      Design overview, patterns and constraints
+  INCLUDE_FILES:
+    required: false
+    type: list
+    description: Specific source files to include (comma/newline-separated).
+    example_paths: [src/app.py, src/api.py, frontend/app/layout.tsx, frontend/app/page.tsx]
+usage:
+  generate:
+    - name: Minimal (PRD only)
+      command: pdd generate --template architecture/architecture_json -e PRD_FILE=docs/specs.md --output architecture.json
+    - name: With tech stack overview
+      command: pdd generate --template architecture/architecture_json -e PRD_FILE=docs/specs.md -e TECH_STACK_FILE=docs/tech_stack.md --output architecture.json
+
+discover:
+  enabled: false
+  max_per_pattern: 5
+  max_total: 10
+
+output_schema:
+  type: array
+  items:
+    type: object
+    required: [reason, description, dependencies, priority, filename, filepath]
+    properties:
+      reason: { type: string }
+      description: { type: string }
+      dependencies: { type: array, items: { type: string } }
+      priority: { type: integer, minimum: 1 }
+      filename: { type: string }
+      filepath: { type: string }
+      tags: { type: array, items: { type: string } }
+      interface:
+        type: object
+        properties:
+          type: { type: string, enum: [component, page, module, api, graphql, cli, job, message, config] }
+          component: { type: object }
+          page:
+            type: object
+            properties:
+              route: { type: string }
+              params:
+                type: array
+                items:
+                  type: object
+                  required: [name, type]
+                  properties:
+                    name: { type: string }
+                    type: { type: string }
+                    description: { type: string }
+              dataSources:
+                type: array
+                items:
+                  type: object
+                  required: [kind, source]
+                  properties:
+                    kind: { type: string, enum: [api, query, stream, file, cache, message, job, other] }
+                    source: { type: string }
+                    method: { type: string }
+                    description: { type: string }
+                    auth: { type: string }
+                    inputs: { type: array, items: { type: string } }
+                    outputs: { type: array, items: { type: string } }
+                    refreshInterval: { type: string }
+                    notes: { type: string }
+              layout: { type: object }
+          module: { type: object }
+          api: { type: object }
+          graphql: { type: object }
+          cli: { type: object }
+          job: { type: object }
+          message: { type: object }
+          config: { type: object }
+---
+
+Purpose: Produce an architecture JSON that enumerates prompt files to generate code files for the project.
+
+<PRD_FILE><include>${PRD_FILE}</include></PRD_FILE>
+<TECH_STACK_FILE><include>${TECH_STACK_FILE}</include></TECH_STACK_FILE>
+<DOC_FILES><include-many>${DOC_FILES}</include-many></DOC_FILES>
+
+<INCLUDE_FILES><include-many>${INCLUDE_FILES}</include-many></INCLUDE_FILES>
+
+INSTRUCTIONS:
+- Use only the facts from the included documents and files. Do not invent technologies or filenames.
+- If TECH_STACK_FILE is absent, infer a reasonable tech stack from the PRD and included files; state key assumptions within each item's description.
+- Output a single top-level JSON array of items. Each item must include:
+  - reason (briefly explain why this code module needs to exist), description, dependencies (filenames), priority (1 = highest), filename, filepath, optional tags.
+  - interface: include only the applicable sub-object (component, page, module, api, graphql, cli, job, message, or config). Omit all non-applicable sub-objects entirely.
+  - When interface.type is "page", each entry in `dataSources` must be an object with at least `kind` and `source` (e.g., URL or identifier). The `kind` field MUST be exactly one of: `"api"`, `"query"`, `"stream"`, `"file"`, `"cache"`, `"message"`, `"job"`, or `"other"`. Do not invent new values like `"api/mutation"`; instead, use `"api"` (for any HTTP/REST/GraphQL endpoint) or `"other"` and describe details such as queries vs. mutations in `description` or `notes`. Provide `method`, `description`, and any other useful metadata when known.
+- Valid JSON only. No comments or trailing commas.
+
+OUTPUT FORMAT (authoritative):
+```json
+{
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["reason", "description", "dependencies", "priority", "filename", "filepath"],
+    "properties": {
+      "reason": {"type": "string"},
+      "description": {"type": "string"},
+      "dependencies": {"type": "array", "items": {"type": "string"}},
+      "priority": {"type": "integer", "minimum": 1},
+      "filename": {"type": "string"},
+      "filepath": {"type": "string"},
+      "tags": {"type": "array", "items": {"type": "string"}},
+      "interface": {
+        "type": "object",
+        "properties": {
+          "type": {"type": "string", "enum": ["component", "page", "module", "api", "graphql", "cli", "job", "message", "config"]},
+          "component": {"type": "object"},
+          "page": {
+            "type": "object",
+            "properties": {
+              "route": {"type": "string"},
+              "params": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["name", "type"],
+                  "properties": {
+                    "name": {"type": "string"},
+                    "type": {"type": "string"},
+                    "description": {"type": "string"}
+                  }
+                }
+              }
+            }
+          },
+          "module": {"type": "object"},
+          "api": {"type": "object"},
+          "graphql": {"type": "object"},
+          "cli": {"type": "object"},
+          "job": {"type": "object"},
+          "message": {"type": "object"},
+          "config": {"type": "object"}
+        }
+      }
+    }
+  }
+}
+```
+
+INTERFACE TYPES (emit only applicable):
+- page: route (string), params? (array of {name, type, description?}), dataSources? (array), layout? (object)
+- component: props (array of {name, type, required?}), emits? (array), context? (array)
+- module: functions (array of {name, signature, returns?, errors?, sideEffects?})
+- api: endpoints (array of {method, path, auth?, requestSchema?, responseSchema?, errors?})
+- graphql: sdl? (string) or operations {queries?[], mutations?[], subscriptions?[]}
+- cli: commands (array of {name, args?[], flags?[], exitCodes?[]}), io? {stdin?, stdout?}
+- job: trigger {schedule? | event?}, inputs? (array), outputs? (array), retryPolicy? (string)
+- message: topics (array of {name, direction: "publish"|"subscribe", schema?, qos?})
+- config: keys (array of {name, type, default?, required?, source: "env"|"file"|"secret"})
+
+FILENAME CONVENTIONS:
+- The "filename" field is the prompt filename to generate (not the code file). Use PDD convention: <base>_<LangOrFramework>.prompt where <LangOrFramework> matches the tech stack.
+- Examples (adapt to your stack):
+  - Next.js (TypeScript React): page_TypeScriptReact.prompt -> generates page.tsx; layout_TypeScriptReact.prompt -> layout.tsx
+  - Python backend: api_Python.prompt -> api.py; orders_Python.prompt -> orders.py
+- Choose descriptive <base> names (e.g., orders_page, orders_api) and keep names consistent across dependencies.
+
+FILEPATH CONVENTIONS:
+- The "filepath" field specifies the path of the output source file from the source tree root, using conventions appropriate for the language and framework.
+- Examples (adapt to your stack):
+  - Next.js app router: app/orders/page.tsx, app/layout.tsx, app/api/orders/route.ts
+  - Next.js pages router: pages/orders.tsx, pages/api/orders.ts
+  - Python FastAPI: src/api.py, src/orders.py, src/models/order.py
+  - React components: src/components/OrderList.tsx, src/hooks/useOrders.ts
+  - Config files: .env.example, pyproject.toml, package.json
+- Use forward slashes (/) for path separators regardless of OS.
+- Include the appropriate file extension for the target language (.tsx, .py, .rs, .go, etc.).
+- Follow standard directory structures for the framework (e.g., app/ for Next.js 13+, src/ for typical React/Python projects).
+
+DEPENDENCY RULES:
+- The "dependencies" array must list other items by their prompt filenames (the "filename" values), not code filenames.
+- Do not reference files that are not part of this array unless they were explicitly provided via INCLUDE_FILES/DOC_FILES.
+- Avoid cycles; if a cycle is necessary, justify it in the description and clarify initialization order.
+
+PRIORITY AND ORDERING:
+- Use unique integer priorities starting at 1 without gaps (1,2,3,...).
+- Sort the top-level array by ascending priority.
+
+TAGS (optional):
+- Use short, lower-case tags for slicing (e.g., ["frontend","nextjs"], ["backend","api"], ["config"]).
+
+CONTENT GUIDANCE:
+- Descriptions must be architectural and actionable: responsibilities, interfaces, error handling, cross-cutting concerns.
+- For API items, outline endpoints (method, path, auth) and high-level request/response shapes.
+- For page/component items, include the route, key props, and data sources.
+
+DO NOT INCLUDE the schema or these conventions in the output; return only the JSON array.

pdd/templates/generic/generate_prompt.prompt

@@ -0,0 +1,174 @@
+---
+name: generic/generate_prompt
+description: Generate a module prompt (.prompt) for any stack (backend, frontend, CLI, jobs) using project docs and context
+version: 1.0.0
+tags: [template, prompt, generic]
+language: prompt
+output: prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt
+variables:
+  MODULE:
+    required: true
+    type: string
+    description: Module/component basename to generate a prompt for.
+    examples: [orders, auth, users]
+  LANG_OR_FRAMEWORK:
+    required: false
+    type: string
+    description: Target language or framework suffix used in prompt naming (matches your stack conventions).
+    examples: [Python, TypeScriptReact, Go, Java, Ruby]
+    default: Python
+  LAYER:
+    required: false
+    type: string
+    description: System layer or interface type for context.
+    examples: [backend, frontend, api, graphql, cli, job, message, config, module, component, page]
+  PRD_FILE:
+    required: false
+    type: path
+    description: Product requirements document providing overall context.
+    example_paths: [PRD.md, docs/product/prd.md]
+  API_DOC_FILE:
+    required: false
+    type: path
+    description: API documentation describing endpoints and conventions.
+    example_paths: [docs/api-documentation.md, docs/api.md]
+  DB_SCHEMA_FILE:
+    required: false
+    type: path
+    description: Database schema or ERD for backend data models.
+    example_paths: [context/database-schema.md, docs/db/schema.md]
+  BACKEND_FILES_CSV:
+    required: false
+    type: path
+    description: CSV listing backend Python files/modules (for context/reference).
+    example_paths: [prompts/backend/python_architecture.csv]
+  IO_DEPENDENCIES_CSV:
+    required: false
+    type: path
+    description: CSV of function inputs/outputs and dependencies for backend modules.
+    example_paths: [prompts/backend/io_dependencies.csv]
+  ARCHITECTURE_FILE:
+    required: true
+    type: path
+    description: Architecture JSON (from architecture/architecture_json) to drive module scope, dependencies, and interface.
+    example_paths: [architecture.json]
+  TECH_STACK_FILE:
+    required: false
+    type: path
+    description: Tech stack overview (languages, frameworks, infrastructure, tools) for shaping conventions.
+    example_paths: [docs/tech_stack.md, docs/architecture/stack.md]
+  CODE_GENERATOR_PROMPT:
+    required: false
+    type: path
+    description: Reference code generator prompt to mirror style and expectations.
+    example_paths: [prompts/code_generator_python.prompt, prompts/code_generator_main_python.prompt]
+  EXISTING_PROMPTS:
+    required: false
+    type: list
+    description: Existing prompt files to use as reference (comma/newline-separated).
+    example_paths: [prompts/orders_python.prompt, prompts/auth_python.prompt]
+  DEP_EXAMPLE_EXT:
+    required: false
+    type: string
+    description: File extension for dependency examples under context/ (for non-Python stacks).
+    examples: [py, ts, tsx, go, java]
+    default: py
+usage:
+  generate:
+    - name: Minimal (architecture only)
+      command: pdd generate --template generic/generate_prompt -e MODULE=orders -e LANG_OR_FRAMEWORK=Python -e ARCHITECTURE_FILE=architecture.json --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt'
+    - name: With project docs
+      command: pdd generate --template generic/generate_prompt -e MODULE=orders -e LANG_OR_FRAMEWORK=Python -e ARCHITECTURE_FILE=architecture.json -e PRD_FILE=docs/PRD.md -e API_DOC_FILE=docs/api-documentation.md -e DB_SCHEMA_FILE=context/database-schema.md --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt'
+    - name: With CSVs and references (backend/Python)
+      command: pdd generate --template generic/generate_prompt -e MODULE=orders -e LANG_OR_FRAMEWORK=Python -e ARCHITECTURE_FILE=architecture.json -e PRD_FILE=docs/PRD.md -e API_DOC_FILE=docs/api-documentation.md -e DB_SCHEMA_FILE=context/database-schema.md -e BACKEND_FILES_CSV=prompts/backend/python_architecture.csv -e IO_DEPENDENCIES_CSV=prompts/backend/io_dependencies.csv -e CODE_GENERATOR_PROMPT=prompts/code_generator_python.prompt --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt'
+    - name: Frontend (TypeScriptReact) variant
+      command: pdd generate --template generic/generate_prompt -e MODULE=profile_page -e LANG_OR_FRAMEWORK=TypeScriptReact -e LAYER=frontend -e ARCHITECTURE_FILE=architecture.json -e PRD_FILE=docs/PRD.md --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt'
+    - name: From architecture.json
+      command: pdd generate --template generic/generate_prompt -e MODULE=orders_api -e LANG_OR_FRAMEWORK=Python -e LAYER=api -e ARCHITECTURE_FILE=architecture.json --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt'
+
+discover:
+  enabled: false
+  max_per_pattern: 5
+  max_total: 10
+---
+
+% You are an expert prompt writer and software architect for PDD. Your goal is to write a high-quality prompt that will generate the code for the ${MODULE} module/component. The prompt you create will be used to produce a detailed implementation specification in a file named ${MODULE}_${LANG_OR_FRAMEWORK}.prompt, suitable for the specified stack and layer.
+
+IMPORTANT: Your reply MUST begin with `<prompt>` on the very first line and end with `</prompt>` on the final line. Do not include any text, whitespace, or code fences outside this block.
+
+% Project context (architecture required, others optional):
+<prd><include>${PRD_FILE}</include></prd>
+<api><include>${API_DOC_FILE}</include></api>
+<database><include>${DB_SCHEMA_FILE}</include></database>
+<backend_files_csv><include>${BACKEND_FILES_CSV}</include></backend_files_csv>
+<io_dependencies_csv><include>${IO_DEPENDENCIES_CSV}</include></io_dependencies_csv>
+<architecture><include>${ARCHITECTURE_FILE}</include></architecture>
+<tech_stack><include>${TECH_STACK_FILE}</include></tech_stack>
+<generate_code_cli_example><include>${CODE_GENERATOR_PROMPT}</include></generate_code_cli_example>
+
+% Existing prompt references (optional):
+<existing_backend_prompts><include-many>${EXISTING_PROMPTS}</include-many></existing_backend_prompts>
+
+% Do the following:
+- Explain concisely what you are going to do (create a prompt for the ${MODULE} module/component for the specified layer and stack).
+- Analyze any difficulties this prompt might encounter for ${MODULE} (e.g., data modeling, API or UI contracts, transactions, idempotency, auth, state management, error handling) and briefly state mitigation strategies tailored to the given LAYER and LANG_OR_FRAMEWORK.
+- Use the ARCHITECTURE_FILE to identify the item that corresponds to this prompt by matching `filename` to `${MODULE}_${LANG_OR_FRAMEWORK}.prompt` (or best match by basename and layer). Use that item’s `reason`, `description`, `dependencies`, `interface`, and `tags` to shape the sections below.
+- Then create the prompt content for ${MODULE} inside XML tags named prompt, ensuring conventions fit the stack and layer.
+- Ensure the final response consists solely of the `<prompt>...</prompt>` block; nothing else (including whitespace) may appear before `<prompt>` or after `</prompt>`.
+
+% The prompt you generate must follow this structure:
+1) First paragraph: describe the role and responsibility of the ${MODULE} module/component within the system (consider the LAYER if provided).
+2) A "Requirements" section with numbered points covering functionality, contracts, error handling, validation, logging, performance, and security.
+3) A "Dependencies" section using XML include tags for each dependency (see format below).
+4) An "Instructions" section with precise implementation guidance (clarify inputs/outputs, function/class responsibilities, edge cases, and testing notes).
+5) A clear "Deliverable" section describing the expected code artifacts and entry points.
+
+% Dependencies format and conventions:
+- Represent each dependency using an XML tag with the dependency name, and put the file path inside an <include> tag, e.g.:
+  <orders_service>
+    <include>context/orders_service_example.${DEP_EXAMPLE_EXT}</include>
+  </orders_service>
+- Prefer real example files available in the provided context (use <include-many> when listing multiple). If examples are not provided, assume dependency examples live under context/ using the pattern context/[dependency_name]_example.${DEP_EXAMPLE_EXT}.
+- Include all necessary dependencies for the module/component (based on the provided context and references).
+- The ARCHITECTURE_FILE lists `dependencies` referencing other prompt filenames. Convert each dependency prompt filename into a sensible dependency name (strip language suffix and `_prompt`), and map to context files with the `${DEP_EXAMPLE_EXT}` extension if present; otherwise, list the prompt filename explicitly in a "Prompt Dependencies" subsection.
+
+% Architecture awareness (ARCHITECTURE_FILE is required):
+- Align the "Requirements" and "Instructions" with the selected item’s `interface.type` (e.g., page, component, module, api, graphql, cli, job, message, config).
+- For `api`, outline endpoints (method, path, auth) consistent with the architecture description; for `page`/`component`, describe route/props/data sources; for `job`, include trigger and retry policy; for `config`, list keys and sources.
+
+% Style and quality requirements:
+- The generated prompt must be detailed enough to yield production-ready code.
+- Match the style and patterns of existing *_${LANG_OR_FRAMEWORK}.prompt files when present.
+- Do not invent technologies or files; rely on the included context. If assumptions are necessary, state them explicitly and conservatively.
+
+% Output contract:
+- Start the output with `<prompt>` on its own line and end with `</prompt>` on its own line.
+- Do not emit any characters (including whitespace, markdown fences, or commentary) outside the `<prompt>...</prompt>` block.
+- Within the tags, include the sections described above as plain text.
+- OUTPUT FORMAT (authoritative – copy/paste and replace the bracketed placeholders, keeping every literal token):
+  ```text
+  <prompt>
+  {ROLE_PARAGRAPH}
+  Requirements
+  1. {REQ_ITEM_1}
+  2. {REQ_ITEM_2}
+  Dependencies
+  <{DEPENDENCY_TAG_1}>
+    <include>{DEPENDENCY_INCLUDE_1}</include>
+  </{DEPENDENCY_TAG_1}>
+  {OPTIONAL_ADDITIONAL_DEPENDENCY_TAGS}
+  Prompt Dependencies:
+  {PROMPT_DEPENDENCIES_SECTION}
+  Instructions
+  - {INSTRUCTION_1}
+  - {INSTRUCTION_2}
+  Deliverable
+  - {DELIVERABLE_1}
+  - {DELIVERABLE_2}
+  Implementation assumptions (explicit)
+  - {ASSUMPTION_1}
+  - {ASSUMPTION_2}
+  Please produce production-ready prompt content that will generate the module consistent with the above.
+  </prompt>
+  ```
+  Replace each `{PLACEHOLDER}` with concrete content while preserving the surrounding structure and literal `<prompt>` / `<include>` tags.