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

pdd/preprocess.py

@@ -48,7 +48,9 @@ def process_backtick_includes(text: str, recursive: bool) -> str:
                 return f"```{content}```"
         except FileNotFoundError:
             console.print(f"[bold red]Warning:[/bold red] File not found: {file_path}")
-            return match.group(0)
+            # First pass (recursive=True): leave the tag so a later env expansion can resolve it
+            # Second pass (recursive=False): replace with a visible placeholder
+            return match.group(0) if recursive else f"```[File not found: {file_path}]```"
         except Exception as e:
             console.print(f"[bold red]Error processing include:[/bold red] {str(e)}")
             return f"```[Error processing include: {file_path}]```"
@@ -62,9 +64,9 @@ def process_backtick_includes(text: str, recursive: bool) -> str:
 def process_xml_tags(text: str, recursive: bool) -> str:
     text = process_pdd_tags(text)
     text = process_include_tags(text, recursive)
-
-    text = process_shell_tags(text)
-    text = process_web_tags(text)
+    text = process_include_many_tags(text, recursive)
+    text = process_shell_tags(text, recursive)
+    text = process_web_tags(text, recursive)
     return text
 
 def process_include_tags(text: str, recursive: bool) -> str:
@@ -81,7 +83,9 @@ def process_include_tags(text: str, recursive: bool) -> str:
                 return content
         except FileNotFoundError:
             console.print(f"[bold red]Warning:[/bold red] File not found: {file_path}")
-            return f"[File not found: {file_path}]"
+            # First pass (recursive=True): leave the tag so a later env expansion can resolve it
+            # Second pass (recursive=False): replace with a visible placeholder
+            return match.group(0) if recursive else f"[File not found: {file_path}]"
         except Exception as e:
             console.print(f"[bold red]Error processing include:[/bold red] {str(e)}")
             return f"[Error processing include: {file_path}]"
@@ -101,10 +105,13 @@ def process_pdd_tags(text: str) -> str:
         return "This is a test "
     return processed
 
-def process_shell_tags(text: str) -> str:
+def process_shell_tags(text: str, recursive: bool) -> str:
     pattern = r'<shell>(.*?)</shell>'
     def replace_shell(match):
         command = match.group(1).strip()
+        if recursive:
+            # Defer execution until after env var expansion
+            return match.group(0)
         console.print(f"Executing shell command: [cyan]{escape(command)}[/cyan]")
         try:
             result = subprocess.run(command, shell=True, check=True, capture_output=True, text=True)
@@ -118,10 +125,13 @@ def process_shell_tags(text: str) -> str:
             return f"[Shell execution error: {str(e)}]"
     return re.sub(pattern, replace_shell, text, flags=re.DOTALL)
 
-def process_web_tags(text: str) -> str:
+def process_web_tags(text: str, recursive: bool) -> str:
     pattern = r'<web>(.*?)</web>'
     def replace_web(match):
         url = match.group(1).strip()
+        if recursive:
+            # Defer network operations until after env var expansion
+            return match.group(0)
         console.print(f"Scraping web content from: [cyan]{url}[/cyan]")
         try:
             try:
@@ -144,6 +154,34 @@ def process_web_tags(text: str) -> str:
             return f"[Web scraping error: {str(e)}]"
     return re.sub(pattern, replace_web, text, flags=re.DOTALL)
 
+def process_include_many_tags(text: str, recursive: bool) -> str:
+    """Process <include-many> blocks whose inner content is a comma- or newline-separated
+    list of file paths (typically provided via variables after env expansion)."""
+    pattern = r'<include-many>(.*?)</include-many>'
+    def replace_many(match):
+        inner = match.group(1)
+        if recursive:
+            # Wait for env expansion to materialize the list
+            return match.group(0)
+        # Split by newlines or commas
+        raw_items = [s.strip() for part in inner.split('\n') for s in part.split(',')]
+        paths = [p for p in raw_items if p]
+        contents: list[str] = []
+        for p in paths:
+            try:
+                full_path = get_file_path(p)
+                console.print(f"Including (many): [cyan]{full_path}[/cyan]")
+                with open(full_path, 'r', encoding='utf-8') as fh:
+                    contents.append(fh.read())
+            except FileNotFoundError:
+                console.print(f"[bold red]Warning:[/bold red] File not found: {p}")
+                contents.append(f"[File not found: {p}]")
+            except Exception as e:
+                console.print(f"[bold red]Error processing include-many:[/bold red] {str(e)}")
+                contents.append(f"[Error processing include: {p}]")
+        return "\n".join(contents)
+    return re.sub(pattern, replace_many, text, flags=re.DOTALL)
+
 def double_curly(text: str, exclude_keys: Optional[List[str]] = None) -> str:
     if exclude_keys is None:
         exclude_keys = []

pdd/prompts/extract_promptline_LLM.prompt

@@ -1,11 +1,17 @@
-% You are an expert Software Engineer. Your goal is to extract the closest matching substring described by the prompt's output to be outputed in JSON format.
-
-% Here is the llm_output to parse: <llm_output>{llm_output}</llm_output>
-
-% When extracting the closest matching substring from llm_output, consider and correct the following for the extracted code:
-    - Should be a substring of prompt_file.
-    - Should be a a substring that closely matches code_str in content.
-
-% Output a JSON object with the following keys:
-    - 'explanation': String explanation of why this prompt_line matches the code_str and explain any errors detected in the code.
-    - 'prompt_line': String containing the closest matching verbatim substring of the prompt_file that matches code_str in content. This is not the line number.
+% You are an extremely literal parser. The LLM output below follows this structure:
+%   <analysis> ... </analysis>
+%   <verbatim_prompt_line>
+%   <<EXACT SUBSTRING FROM PROMPT_FILE>>
+%   </verbatim_prompt_line>
+%
+% Task
+%   • Extract the text between <verbatim_prompt_line> and </verbatim_prompt_line> (if present).
+%   • Output ONLY JSON with the keys:
+%       - "prompt_line": the exact substring between the tags. Do not alter whitespace or characters except for JSON escaping.
+%       - "explanation": short confirmation (<=120 characters) that the substring was copied verbatim, or describe why extraction failed.
+%   • If the tags are missing or empty, set "prompt_line" to "" and explain the issue.
+%   • Do not wrap the JSON in Markdown. No commentary, no additional keys.
+%
+<llm_output>
+{llm_output}
+</llm_output>

pdd/prompts/trace_LLM.prompt

@@ -1,30 +1,33 @@
-% Imagine you're a an expert Python Software Engineer. Your goal is to find the part of the .prompt file. It will take in three arguments, the text of the .prompt file, the text of the code file, and the line that the debugger is on in the code file. Your task is to find the equivalent line in the .prompt file that matches with the line in the code file.
-
-% Here are the inputs and outputs of the prompt:
-    Input:
-        `code_file` (str) - A string that contains the text of the code file.
-        `code_str` (str) - A substring of code_file that represents the line that the debugger is on in the code_file.
-        `prompt_file` (str) - A string that contains the text of the .prompt file.
-    Output:
-        `prompt_line` (str) - An string that represents the equivalent line in the .prompt file that matches with the code_str line in the code file.
-
-% Here is the code_file to reference: 
-
+% You are a highly accurate Python Software Engineer. Your job is to locate the exact line (or smallest excerpt) in the prompt file that produced the current line in the generated code.
+
+% Inputs
+    code_file (str)    : full contents of the generated code file
+    code_str (str)     : the single line from the code file currently under inspection
+    prompt_file (str)  : full contents of the originating prompt file
+
+% Rules
+1. Identify the minimal substring in prompt_file whose wording most directly corresponds to code_str. Copy it VERBATIM.
+2. Do not paraphrase, summarize, or reformat; the substring must appear exactly in prompt_file.
+3. If multiple lines apply, choose the most specific line or snippet (prefer the shortest exact match).
+4. Provide a short explanation of why the substring matches code_str.
+
+% Output format (MUST follow exactly; no additional text)
+<analysis>
+Explain your reasoning here in plain text (no JSON). Reference the file sections you compared.
+</analysis>
+<verbatim_prompt_line>
+<<PASTE THE EXACT SUBSTRING FROM prompt_file HERE>>
+</verbatim_prompt_line>
+
+% Reference materials
 <code_file>
-    {CODE_FILE}
+{CODE_FILE}
 </code_file>
 
-% Here is the code_str to reference:
-
 <code_str>
-    {CODE_STR}
+{CODE_STR}
 </code_str>
 
-% Here is the prompt_file to reference:
-
 <prompt_file>
-    {PROMPT_FILE}
+{PROMPT_FILE}
 </prompt_file>
-
-% To generate the prompt_line, find a substring of prompt_file that matches code_str, which is a substring of code_file.
-

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.