pdd-cli 0.0.55__py3-none-any.whl → 0.0.57__py3-none-any.whl

pdd/sync_determine_operation.py

@@ -209,7 +209,7 @@ def get_extension(language: str) -> str:
     return extensions.get(language.lower(), language.lower())
 
 
-def get_pdd_file_paths(basename: str, language: str, prompts_dir: str = "prompts") -> Dict[str, Path]:
+def get_pdd_file_paths(basename: str, language: str, prompts_dir: str = "prompts", context_override: Optional[str] = None) -> Dict[str, Path]:
     """Returns a dictionary mapping file types to their expected Path objects."""
     import logging
     logger = logging.getLogger(__name__)
@@ -233,7 +233,8 @@ def get_pdd_file_paths(basename: str, language: str, prompts_dir: str = "prompts
                     force=True,
                     quiet=True,
                     command="sync",
-                    command_options={"basename": basename, "language": language}
+                    command_options={"basename": basename, "language": language},
+                    context_override=context_override
                 )
                 
                 import logging
@@ -299,7 +300,8 @@ def get_pdd_file_paths(basename: str, language: str, prompts_dir: str = "prompts
             force=True,  # Use force=True to avoid interactive prompts during sync
             quiet=True,
             command="sync",  # Use sync command to get more tolerant path handling
-            command_options={"basename": basename, "language": language}
+            command_options={"basename": basename, "language": language},
+            context_override=context_override
         )
         
         # For sync command, output_file_paths contains the configured paths
@@ -332,7 +334,8 @@ def get_pdd_file_paths(basename: str, language: str, prompts_dir: str = "prompts
                 # Get example path using example command
                 _, _, example_output_paths, _ = construct_paths(
                     input_file_paths={"prompt_file": prompt_path, "code_file": code_path},
-                    force=True, quiet=True, command="example", command_options={}
+                    force=True, quiet=True, command="example", command_options={},
+                    context_override=context_override
                 )
                 example_path = Path(example_output_paths.get('output', f"{basename}_example.{get_extension(language)}"))
                 
@@ -340,7 +343,8 @@ def get_pdd_file_paths(basename: str, language: str, prompts_dir: str = "prompts
                 try:
                     _, _, test_output_paths, _ = construct_paths(
                         input_file_paths={"prompt_file": prompt_path, "code_file": code_path},
-                        force=True, quiet=True, command="test", command_options={}
+                        force=True, quiet=True, command="test", command_options={},
+                        context_override=context_override
                     )
                     test_path = Path(test_output_paths.get('output', f"test_{basename}.{get_extension(language)}"))
                 except FileNotFoundError:
@@ -365,14 +369,16 @@ def get_pdd_file_paths(basename: str, language: str, prompts_dir: str = "prompts
                 # Get configured directories by using construct_paths with just the prompt file
                 _, _, example_output_paths, _ = construct_paths(
                     input_file_paths={"prompt_file": prompt_path},
-                    force=True, quiet=True, command="example", command_options={}
+                    force=True, quiet=True, command="example", command_options={},
+                    context_override=context_override
                 )
                 example_path = Path(example_output_paths.get('output', f"{basename}_example.{get_extension(language)}"))
                 
                 try:
                     _, _, test_output_paths, _ = construct_paths(
                         input_file_paths={"prompt_file": prompt_path},
-                        force=True, quiet=True, command="test", command_options={}
+                        force=True, quiet=True, command="test", command_options={},
+                        context_override=context_override
                     )
                     test_path = Path(test_output_paths.get('output', f"test_{basename}.{get_extension(language)}"))
                 except Exception:
@@ -768,7 +774,7 @@ def _check_example_success_history(basename: str, language: str) -> bool:
     return False
 
 
-def sync_determine_operation(basename: str, language: str, target_coverage: float, budget: float = 10.0, log_mode: bool = False, prompts_dir: str = "prompts", skip_tests: bool = False, skip_verify: bool = False) -> SyncDecision:
+def sync_determine_operation(basename: str, language: str, target_coverage: float, budget: float = 10.0, log_mode: bool = False, prompts_dir: str = "prompts", skip_tests: bool = False, skip_verify: bool = False, context_override: Optional[str] = None) -> SyncDecision:
     """
     Core decision-making function for sync operations with skip flag awareness.
     
@@ -788,14 +794,14 @@ def sync_determine_operation(basename: str, language: str, target_coverage: floa
     
     if log_mode:
         # Skip locking for read-only analysis
-        return _perform_sync_analysis(basename, language, target_coverage, budget, prompts_dir, skip_tests, skip_verify)
+        return _perform_sync_analysis(basename, language, target_coverage, budget, prompts_dir, skip_tests, skip_verify, context_override)
     else:
         # Normal exclusive locking for actual operations
         with SyncLock(basename, language) as lock:
-            return _perform_sync_analysis(basename, language, target_coverage, budget, prompts_dir, skip_tests, skip_verify)
+            return _perform_sync_analysis(basename, language, target_coverage, budget, prompts_dir, skip_tests, skip_verify, context_override)
 
 
-def _perform_sync_analysis(basename: str, language: str, target_coverage: float, budget: float, prompts_dir: str = "prompts", skip_tests: bool = False, skip_verify: bool = False) -> SyncDecision:
+def _perform_sync_analysis(basename: str, language: str, target_coverage: float, budget: float, prompts_dir: str = "prompts", skip_tests: bool = False, skip_verify: bool = False, context_override: Optional[str] = None) -> SyncDecision:
     """
     Perform the sync state analysis without locking concerns.
     
@@ -846,7 +852,7 @@ def _perform_sync_analysis(basename: str, language: str, target_coverage: float,
         # Check test failures (after crash verification check)
         if run_report.tests_failed > 0:
             # First check if the test file actually exists
-            pdd_files = get_pdd_file_paths(basename, language, prompts_dir)
+            pdd_files = get_pdd_file_paths(basename, language, prompts_dir, context_override=context_override)
             test_file = pdd_files.get('test')
             
             # Only suggest 'fix' if test file exists
@@ -945,7 +951,7 @@ def _perform_sync_analysis(basename: str, language: str, target_coverage: float,
                 )
     
     # 2. Analyze File State
-    paths = get_pdd_file_paths(basename, language, prompts_dir)
+    paths = get_pdd_file_paths(basename, language, prompts_dir, context_override=context_override)
     current_hashes = calculate_current_hashes(paths)
     
     # 3. Implement the Decision Tree
@@ -1264,7 +1270,14 @@ def _perform_sync_analysis(basename: str, language: str, target_coverage: float,
     )
 
 
-def analyze_conflict_with_llm(basename: str, language: str, fingerprint: Fingerprint, changed_files: List[str], prompts_dir: str = "prompts") -> SyncDecision:
+def analyze_conflict_with_llm(
+    basename: str,
+    language: str,
+    fingerprint: Fingerprint,
+    changed_files: List[str],
+    prompts_dir: str = "prompts",
+    context_override: Optional[str] = None,
+) -> SyncDecision:
     """
     Resolve complex sync conflicts using an LLM.
     
@@ -1297,7 +1310,7 @@ def analyze_conflict_with_llm(basename: str, language: str, fingerprint: Fingerp
             )
         
         # 2. Gather file paths and diffs
-        paths = get_pdd_file_paths(basename, language, prompts_dir)
+        paths = get_pdd_file_paths(basename, language, prompts_dir, context_override=context_override)
         
         # Generate diffs for changed files
         diffs = {}

pdd/sync_main.py

@@ -192,6 +192,7 @@ def sync_main(
                 log=True,
                 verbose=verbose,
                 quiet=quiet,
+                context_override=context_override,
             )
         return {}, 0.0, ""
 
@@ -280,6 +281,7 @@ def sync_main(
                 review_examples=review_examples,
                 local=local,
                 context_config=resolved_config,
+                context_override=context_override,
             )
 
             lang_cost = sync_result.get("total_cost", 0.0)
@@ -330,4 +332,4 @@ def sync_main(
     aggregated_results["total_cost"] = total_cost
     aggregated_results["primary_model"] = primary_model
 
-    return aggregated_results, total_cost, primary_model
+    return aggregated_results, total_cost, primary_model

pdd/sync_orchestration.py

@@ -341,6 +341,7 @@ def sync_orchestration(
     review_examples: bool = False,
     local: bool = False,
     context_config: Optional[Dict[str, str]] = None,
+    context_override: Optional[str] = None,
 ) -> Dict[str, Any]:
     """
     Orchestrates the complete PDD sync workflow with parallel animation.
@@ -358,7 +359,7 @@ def sync_orchestration(
 
     # --- Initialize State and Paths ---
     try:
-        pdd_files = get_pdd_file_paths(basename, language, prompts_dir)
+        pdd_files = get_pdd_file_paths(basename, language, prompts_dir, context_override=context_override)
         # Debug: Print the paths we got
         print(f"DEBUG: get_pdd_file_paths returned:")
         print(f"  test: {pdd_files.get('test', 'N/A')}")
@@ -457,7 +458,7 @@ def sync_orchestration(
                         "percentage": (budget_remaining / budget) * 100
                     })
 
-                decision = sync_determine_operation(basename, language, target_coverage, budget_remaining, False, prompts_dir, skip_tests, skip_verify)
+                decision = sync_determine_operation(basename, language, target_coverage, budget_remaining, False, prompts_dir, skip_tests, skip_verify, context_override)
                 operation = decision.operation
                 
                 # Create log entry with decision info

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,183 @@
+---
+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
+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 -e PRD_FILE=docs/specs.md --output architecture.json pdd/templates/architecture/architecture_json.prompt
+    - name: With tech stack overview
+      command: pdd generate -e PRD_FILE=docs/specs.md -e TECH_STACK_FILE=docs/tech_stack.md --output architecture.json pdd/templates/architecture/architecture_json.prompt
+
+discover:
+  enabled: false
+  max_per_pattern: 5
+  max_total: 10
+
+output_schema:
+  type: array
+  items:
+    type: object
+    required: [reason, description, dependencies, priority, filename]
+    properties:
+      reason: { type: string }
+      description: { type: string }
+      dependencies: { type: array, items: { type: string } }
+      priority: { type: integer, minimum: 1 }
+      filename: { type: string }
+      tags: { type: array, items: { type: string } }
+      interface:
+        type: object
+        properties:
+          type: { 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 } }
+              dataSources: { type: array, items: { type: object } }
+              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, description, dependencies (filenames), priority (1 = highest), filename, 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.
+- Valid JSON only. No comments or trailing commas.
+
+OUTPUT FORMAT (authoritative):
+```json
+{
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["reason", "description", "dependencies", "priority", "filename"],
+    "properties": {
+      "reason": {"type": "string"},
+      "description": {"type": "string"},
+      "dependencies": {"type": "array", "items": {"type": "string"}},
+      "priority": {"type": "integer", "minimum": 1},
+      "filename": {"type": "string"},
+      "tags": {"type": "array", "items": {"type": "string"}},
+      "interface": {
+        "type": "object",
+        "properties": {
+          "type": {"enum": ["component", "page", "module", "api", "graphql", "cli", "job", "message", "config"]},
+          "component": {"type": "object"},
+          "page": {"type": "object", "properties": {"route": {"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), 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.
+
+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.