pdd-cli 0.0.61__py3-none-any.whl → 0.0.63__py3-none-any.whl

pdd/__init__.py

@@ -1,6 +1,6 @@
 """PDD - Prompt Driven Development"""
 
-__version__ = "0.0.61"
+__version__ = "0.0.63"
 
 # Strength parameter used for LLM extraction across the codebase
 # Used in postprocessing, XML tagging, code generation, and other extraction

pdd/cli.py

@@ -14,9 +14,11 @@ from typing import Any, Dict, List, Optional, Tuple
 from pathlib import Path # Import Path
 
 import click
+from rich import box
 from rich.console import Console
-from rich.theme import Theme
 from rich.markup import MarkupError, escape
+from rich.table import Table
+from rich.theme import Theme
 
 # --- Relative Imports for Internal Modules ---
 from . import DEFAULT_STRENGTH, __version__, DEFAULT_TIME
@@ -449,20 +451,138 @@ def templates_show(name: str):
     try:
         data = template_registry.show_template(name)
         summary = data.get("summary", {})
-        console.print(f"[bold]{summary.get('name','')}[/bold] — {summary.get('description','')}")
-        console.print(f"Version: {summary.get('version','')}  Tags: {', '.join(summary.get('tags',[]))}")
-        console.print(f"Language: {summary.get('language','')}  Output: {summary.get('output','')}")
-        console.print(f"Path: {summary.get('path','')}")
+
+        def _render_key_value_table(title: Optional[str], items: List[Tuple[str, Any]], *, highlight_path: bool = False):
+            """Render a 2-column Rich table for key/value pairs."""
+
+            table = Table(show_header=False, box=box.SIMPLE, expand=True)
+            table.add_column("Field", style="info", no_wrap=True)
+            table.add_column("Value", overflow="fold")
+
+            added_rows = False
+            for label, value in items:
+                if value in (None, "", [], {}):
+                    continue
+                if isinstance(value, (list, tuple)):
+                    value_str = ", ".join(str(v) for v in value)
+                else:
+                    value_str = str(value)
+
+                if highlight_path and label.lower() == "path":
+                    value_markup = f"[path]{escape(value_str)}[/path]"
+                else:
+                    value_markup = escape(value_str)
+
+                table.add_row(label, value_markup)
+                added_rows = True
+
+            if added_rows:
+                if title:
+                    console.print(f"[info]{title}[/info]")
+                console.print(table)
+
+        summary_items = [
+            ("Name", summary.get("name")),
+            ("Description", summary.get("description")),
+            ("Version", summary.get("version")),
+            ("Tags", summary.get("tags", [])),
+            ("Language", summary.get("language")),
+            ("Output", summary.get("output")),
+            ("Path", summary.get("path")),
+        ]
+        _render_key_value_table("Template Summary:", summary_items, highlight_path=True)
+
         if data.get("variables"):
             console.print("\n[info]Variables:[/info]")
-            for k, v in data["variables"].items():
-                console.print(f"- {k}: {v}")
+            variables_table = Table(box=box.SIMPLE_HEAD, show_lines=False, expand=True)
+            variables_table.add_column("Name", style="bold", no_wrap=True)
+            variables_table.add_column("Required", style="info", no_wrap=True)
+            variables_table.add_column("Type", no_wrap=True)
+            variables_table.add_column("Description", overflow="fold")
+            variables_table.add_column("Default/Examples", overflow="fold")
+
+            for var_name, var_meta in data["variables"].items():
+                required = var_meta.get("required")
+                if required is True:
+                    required_str = "Yes"
+                elif required is False:
+                    required_str = "No"
+                else:
+                    required_str = "-"
+
+                var_type = escape(str(var_meta.get("type", "-")))
+                description = escape(str(var_meta.get("description", "")))
+
+                default_parts: List[str] = []
+                default_value = var_meta.get("default")
+                if default_value not in (None, ""):
+                    default_parts.append(f"default: {default_value}")
+
+                examples_value = var_meta.get("examples")
+                if examples_value:
+                    if isinstance(examples_value, (list, tuple)):
+                        examples_str = ", ".join(str(example) for example in examples_value)
+                    else:
+                        examples_str = str(examples_value)
+                    default_parts.append(f"examples: {examples_str}")
+
+                example_paths_value = var_meta.get("example_paths")
+                if example_paths_value:
+                    if isinstance(example_paths_value, (list, tuple)):
+                        example_paths_str = ", ".join(str(example) for example in example_paths_value)
+                    else:
+                        example_paths_str = str(example_paths_value)
+                    default_parts.append(f"paths: {example_paths_str}")
+
+                default_examples = "\n".join(default_parts) if default_parts else "-"
+
+                variables_table.add_row(
+                    escape(str(var_name)),
+                    required_str,
+                    var_type,
+                    description,
+                    escape(default_examples),
+                )
+
+            console.print(variables_table)
+
         if data.get("usage"):
             console.print("\n[info]Usage:[/info]")
-            console.print(data["usage"])  # raw; CLI may format later
+            usage = data["usage"]
+            if isinstance(usage, dict):
+                for group_name, entries in usage.items():
+                    console.print(f"[bold]{escape(str(group_name))}[/bold]")
+                    usage_table = Table(box=box.SIMPLE, show_lines=False, expand=True)
+                    usage_table.add_column("Name", style="bold", no_wrap=True)
+                    usage_table.add_column("Command", overflow="fold")
+
+                    if isinstance(entries, (list, tuple)):
+                        iterable_entries = entries
+                    else:
+                        iterable_entries = [entries]
+
+                    for entry in iterable_entries:
+                        if isinstance(entry, dict):
+                            name_value = escape(str(entry.get("name", "")))
+                            command_value = escape(str(entry.get("command", "")))
+                        else:
+                            name_value = "-"
+                            command_value = escape(str(entry))
+                        usage_table.add_row(name_value, f"[command]{command_value}[/command]")
+
+                    if usage_table.row_count:
+                        console.print(usage_table)
+            else:
+                console.print(usage)
+
         if data.get("discover"):
             console.print("\n[info]Discover:[/info]")
-            console.print(data["discover"])  # raw dict
+            discover = data["discover"]
+            if isinstance(discover, dict):
+                discover_items = [(str(key), value) for key, value in discover.items()]
+                _render_key_value_table(None, discover_items)
+            else:
+                console.print(discover)
         if data.get("output_schema"):
             console.print("\n[info]Output Schema:[/info]")
             try:

pdd/data/language_format.csv

@@ -64,3 +64,6 @@ Log,del,.log
 reStructuredText,del,.rst
 Text,del,.txt
 INI,;,.ini
+Verilog,//,.v
+Systemverilog,//,.sv
+Prisma,///,.prisma

pdd/data/llm_model.csv

@@ -2,7 +2,7 @@ provider,model,input,output,coding_arena_elo,base_url,api_key,max_reasoning_toke
 OpenAI,gpt-5-nano,0.05,0.4,1249,,OPENAI_API_KEY,0,True,none
 Google,vertex_ai/gemini-2.5-flash,0.15,0.6,1290,,VERTEX_CREDENTIALS,0,True,effort
 Google,gemini/gemini-2.5-pro,1.25,10.0,1360,,GEMINI_API_KEY,0,True,none
-Google,vertex_ai/claude-sonnet-4,3.0,15.0,1359,,VERTEX_CREDENTIALS,64000,True,budget
+Google,vertex_ai/claude-sonnet-4-5,3.0,15.0,1359,,VERTEX_CREDENTIALS,64000,True,budget
 Google,vertex_ai/gemini-2.5-pro,1.25,10.0,1405,,VERTEX_CREDENTIALS,0,True,none
 OpenAI,gpt-5-mini,0.25,2.0,1325,,OPENAI_API_KEY,0,True,effort
 OpenAI,gpt-5,1.25,10.0,1482,,OPENAI_API_KEY,0,True,effort
@@ -15,6 +15,6 @@ OpenAI,openai/mlx-community/Qwen3-30B-A3B-4bit,0,0,1040,http://localhost:8080,,0
 OpenAI,lm_studio/openai-gpt-oss-120b-mlx-6,0.0001,0,1082,http://localhost:1234/v1,,0,True,none
 Fireworks,fireworks_ai/accounts/fireworks/models/glm-4p5,3.0,8.0,1364,,FIREWORKS_API_KEY,0,False,none
 OpenAI,groq/moonshotai/kimi-k2-instruct,1.0,3.0,1330,,GROQ_API_KEY,0,True,none
-Anthropic,anthropic/claude-sonnet-4-20250514,3.0,15.0,1356,,ANTHROPIC_API_KEY,64000,True,budget
+Anthropic,anthropic/claude-sonnet-4-5-20250929,3.0,15.0,1356,,ANTHROPIC_API_KEY,64000,True,budget
 Anthropic,anthropic/claude-opus-4-1-20250805,3.0,15.0,1474,,ANTHROPIC_API_KEY,32000,True,budget
 Anthropic,anthropic/claude-3-5-haiku-20241022,3.0,15.0,1133,,ANTHROPIC_API_KEY,8192,True,budget

pdd/preprocess.py

@@ -1,7 +1,7 @@
 import os
 import re
 import subprocess
-from typing import List, Optional
+from typing import List, Optional, Tuple
 import traceback
 from rich.console import Console
 from rich.panel import Panel
@@ -11,22 +11,110 @@ from rich.traceback import install
 install()
 console = Console()
 
+# Debug/Instrumentation controls
+_DEBUG_PREPROCESS = str(os.getenv("PDD_PREPROCESS_DEBUG", "")).lower() in ("1", "true", "yes", "on")
+_DEBUG_OUTPUT_FILE = os.getenv("PDD_PREPROCESS_DEBUG_FILE")  # Optional path to write a debug report
+_DEBUG_EVENTS: List[str] = []
+
+def _dbg(msg: str) -> None:
+    if _DEBUG_PREPROCESS:
+        console.print(f"[dim][PPD][preprocess][/dim] {escape(msg)}")
+        _DEBUG_EVENTS.append(msg)
+
+def _write_debug_report() -> None:
+    if _DEBUG_PREPROCESS and _DEBUG_OUTPUT_FILE:
+        try:
+            with open(_DEBUG_OUTPUT_FILE, "w", encoding="utf-8") as fh:
+                fh.write("Preprocess Debug Report\n\n")
+                for line in _DEBUG_EVENTS:
+                    fh.write(line + "\n")
+            console.print(f"[green]Debug report written to:[/green] {_DEBUG_OUTPUT_FILE}")
+        except Exception as e:
+            # Report the error so users know why the log file wasn't written
+            console.print(f"[yellow]Warning: Could not write debug report to {_DEBUG_OUTPUT_FILE}: {e}[/yellow]")
+    elif _DEBUG_PREPROCESS and not _DEBUG_OUTPUT_FILE:
+        console.print("[dim]Debug mode enabled but PDD_PREPROCESS_DEBUG_FILE not set (output shown in console only)[/dim]")
+
+def _extract_fence_spans(text: str) -> List[Tuple[int, int]]:
+    """Return list of (start, end) spans for fenced code blocks ```...```.
+
+    The spans are [start, end) indices in the original text.
+    """
+    spans: List[Tuple[int, int]] = []
+    try:
+        for m in re.finditer(r"```[\w\s]*\n[\s\S]*?```", text):
+            spans.append((m.start(), m.end()))
+    except Exception:
+        pass
+    return spans
+
+def _is_inside_any_span(idx: int, spans: List[Tuple[int, int]]) -> bool:
+    for s, e in spans:
+        if s <= idx < e:
+            return True
+    return False
+
+def _scan_risky_placeholders(text: str) -> Tuple[List[Tuple[int, str]], List[Tuple[int, str]]]:
+    """Scan for risky placeholders outside code fences.
+
+    Returns two lists of (line_no, snippet):
+      - single_brace: matches like {name} not doubled and not part of {{...}}
+      - template_brace: `${...}` occurrences (which include single { ... })
+    """
+    single_brace: List[Tuple[int, str]] = []
+    template_brace: List[Tuple[int, str]] = []
+    try:
+        fence_spans = _extract_fence_spans(text)
+        # Single-brace variable placeholders (avoid matching {{ or }})
+        for m in re.finditer(r"(?<!\{)\{([A-Za-z_][A-Za-z0-9_]*)\}(?!\})", text):
+            if not _is_inside_any_span(m.start(), fence_spans):
+                line_no = text.count("\n", 0, m.start()) + 1
+                single_brace.append((line_no, m.group(0)))
+        # JavaScript template placeholders like ${...}
+        for m in re.finditer(r"\$\{[^\}]+\}", text):
+            if not _is_inside_any_span(m.start(), fence_spans):
+                line_no = text.count("\n", 0, m.start()) + 1
+                template_brace.append((line_no, m.group(0)))
+    except Exception:
+        pass
+    return single_brace, template_brace
+
 def preprocess(prompt: str, recursive: bool = False, double_curly_brackets: bool = True, exclude_keys: Optional[List[str]] = None) -> str:
     try:
         if not prompt:
             console.print("[bold red]Error:[/bold red] Empty prompt provided")
             return ""
+        _DEBUG_EVENTS.clear()
+        _dbg(f"Start preprocess(recursive={recursive}, double_curly={double_curly_brackets}, exclude_keys={exclude_keys})")
+        _dbg(f"Initial length: {len(prompt)} characters")
         console.print(Panel("Starting prompt preprocessing", style="bold blue"))
         prompt = process_backtick_includes(prompt, recursive)
+        _dbg("After backtick includes processed")
         prompt = process_xml_tags(prompt, recursive)
+        _dbg("After XML-like tags processed")
         if double_curly_brackets:
             prompt = double_curly(prompt, exclude_keys)
+            _dbg("After double_curly execution")
+        # Scan for risky placeholders remaining outside code fences
+        singles, templates = _scan_risky_placeholders(prompt)
+        if singles:
+            _dbg(f"WARNING: Found {len(singles)} single-brace placeholders outside code fences (examples):")
+            for ln, frag in singles[:5]:
+                _dbg(f"  line {ln}: {frag}")
+        if templates:
+            _dbg(f"INFO: Found {len(templates)} template literals ${'{...'} outside code fences (examples):")
+            for ln, frag in templates[:5]:
+                _dbg(f"  line {ln}: {frag}")
         # Don't trim whitespace that might be significant for the tests
         console.print(Panel("Preprocessing complete", style="bold green"))
+        _dbg(f"Final length: {len(prompt)} characters")
+        _write_debug_report()
         return prompt
     except Exception as e:
         console.print(f"[bold red]Error during preprocessing:[/bold red] {str(e)}")
         console.print(Panel(traceback.format_exc(), title="Error Details", style="red"))
+        _dbg(f"Exception: {str(e)}")
+        _write_debug_report()
         return prompt
 
 def get_file_path(file_name: str) -> str:
@@ -45,14 +133,17 @@ def process_backtick_includes(text: str, recursive: bool) -> str:
                 content = file.read()
                 if recursive:
                     content = preprocess(content, recursive=True, double_curly_brackets=False)
+                _dbg(f"Included via backticks: {file_path} (len={len(content)})")
                 return f"```{content}```"
         except FileNotFoundError:
             console.print(f"[bold red]Warning:[/bold red] File not found: {file_path}")
+            _dbg(f"Missing backtick include: {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)}")
+            _dbg(f"Error processing backtick include {file_path}: {e}")
             return f"```[Error processing include: {file_path}]```"
     prev_text = ""
     current_text = text
@@ -80,14 +171,17 @@ def process_include_tags(text: str, recursive: bool) -> str:
                 content = file.read()
                 if recursive:
                     content = preprocess(content, recursive=True, double_curly_brackets=False)
+                _dbg(f"Included via XML tag: {file_path} (len={len(content)})")
                 return content
         except FileNotFoundError:
             console.print(f"[bold red]Warning:[/bold red] File not found: {file_path}")
+            _dbg(f"Missing XML include: {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)}")
+            _dbg(f"Error processing XML include {file_path}: {e}")
             return f"[Error processing include: {file_path}]"
     prev_text = ""
     current_text = text
@@ -113,15 +207,18 @@ def process_shell_tags(text: str, recursive: bool) -> str:
             # Defer execution until after env var expansion
             return match.group(0)
         console.print(f"Executing shell command: [cyan]{escape(command)}[/cyan]")
+        _dbg(f"Shell tag command: {command}")
         try:
             result = subprocess.run(command, shell=True, check=True, capture_output=True, text=True)
             return result.stdout
         except subprocess.CalledProcessError as e:
             error_msg = f"Command '{command}' returned non-zero exit status {e.returncode}."
             console.print(f"[bold red]Error:[/bold red] {error_msg}")
+            _dbg(f"Shell command error: {error_msg}")
             return f"Error: {error_msg}"
         except Exception as e:
             console.print(f"[bold red]Error executing shell command:[/bold red] {str(e)}")
+            _dbg(f"Shell execution exception: {e}")
             return f"[Shell execution error: {str(e)}]"
     return re.sub(pattern, replace_shell, text, flags=re.DOTALL)
 
@@ -133,24 +230,30 @@ def process_web_tags(text: str, recursive: bool) -> str:
             # Defer network operations until after env var expansion
             return match.group(0)
         console.print(f"Scraping web content from: [cyan]{url}[/cyan]")
+        _dbg(f"Web tag URL: {url}")
         try:
             try:
                 from firecrawl import FirecrawlApp
             except ImportError:
+                _dbg("firecrawl import failed; package not installed")
                 return f"[Error: firecrawl-py package not installed. Cannot scrape {url}]"
             api_key = os.environ.get('FIRECRAWL_API_KEY')
             if not api_key:
                 console.print("[bold yellow]Warning:[/bold yellow] FIRECRAWL_API_KEY not found in environment")
+                _dbg("FIRECRAWL_API_KEY not set")
                 return f"[Error: FIRECRAWL_API_KEY not set. Cannot scrape {url}]"
             app = FirecrawlApp(api_key=api_key)
             response = app.scrape_url(url, formats=['markdown'])
             if hasattr(response, 'markdown'):
+                _dbg(f"Web scrape returned markdown (len={len(response.markdown)})")
                 return response.markdown
             else:
                 console.print(f"[bold yellow]Warning:[/bold yellow] No markdown content returned for {url}")
+                _dbg("Web scrape returned no markdown content")
                 return f"[No content available for {url}]"
         except Exception as e:
             console.print(f"[bold red]Error scraping web content:[/bold red] {str(e)}")
+            _dbg(f"Web scraping exception: {e}")
             return f"[Web scraping error: {str(e)}]"
     return re.sub(pattern, replace_web, text, flags=re.DOTALL)
 
@@ -173,11 +276,14 @@ def process_include_many_tags(text: str, recursive: bool) -> str:
                 console.print(f"Including (many): [cyan]{full_path}[/cyan]")
                 with open(full_path, 'r', encoding='utf-8') as fh:
                     contents.append(fh.read())
+                _dbg(f"Included (many): {p}")
             except FileNotFoundError:
                 console.print(f"[bold red]Warning:[/bold red] File not found: {p}")
+                _dbg(f"Missing include-many: {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)}")
+                _dbg(f"Error processing include-many {p}: {e}")
                 contents.append(f"[Error processing include: {p}]")
         return "\n".join(contents)
     return re.sub(pattern, replace_many, text, flags=re.DOTALL)
@@ -187,6 +293,7 @@ def double_curly(text: str, exclude_keys: Optional[List[str]] = None) -> str:
         exclude_keys = []
     
     console.print("Doubling curly brackets...")
+    _dbg("double_curly invoked")
     
     # Special case handling for specific test patterns
     if "Mix of {excluded{inner}} nesting" in text and "excluded" in exclude_keys:
@@ -210,8 +317,8 @@ def double_curly(text: str, exclude_keys: Optional[List[str]] = None) -> str:
             "2": {{"id": "2", "name": "Resource Two"}}
         }}"""
     
-    # Protect ${IDENT} placeholders so they remain unchanged
-    # Use placeholders that won't collide with typical content
+    # Protect ${IDENT} placeholders so we can safely double braces, then restore
+    # them as ${{IDENT}} to avoid PromptTemplate interpreting {IDENT}.
     protected_vars: List[str] = []
     def _protect_var(m):
         protected_vars.append(m.group(0))
@@ -235,10 +342,22 @@ def double_curly(text: str, exclude_keys: Optional[List[str]] = None) -> str:
     # Restore already doubled brackets
     text = re.sub(r'__ALREADY_DOUBLED__(.*?)__END_ALREADY__', r'{{\1}}', text)
 
-    # Restore protected ${IDENT} placeholders
+    # Restore protected ${IDENT} placeholders as ${{IDENT}} so single braces
+    # don't leak into PromptTemplate formatting. This is safe for JS template
+    # literals and prevents missing-key errors in later formatting steps.
     def _restore_var(m):
         idx = int(m.group(1))
-        return protected_vars[idx] if 0 <= idx < len(protected_vars) else m.group(0)
+        if 0 <= idx < len(protected_vars):
+            original = protected_vars[idx]  # e.g., ${FOO}
+            try:
+                inner = re.match(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}", original)
+                if inner:
+                    # Build as concatenation to avoid f-string brace escaping confusion
+                    return "${{" + inner.group(1) + "}}"  # -> ${{FOO}}
+            except Exception:
+                pass
+            return original
+        return m.group(0)
     text = re.sub(r"__PDD_VAR_(\d+)__", _restore_var, text)
     
     # Special handling for code blocks

pdd/templates/architecture/architecture_json.prompt

@@ -66,13 +66,14 @@ output_schema:
   type: array
   items:
     type: object
-    required: [reason, description, dependencies, priority, filename]
+    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
@@ -83,8 +84,30 @@ output_schema:
             type: object
             properties:
               route: { type: string }
-              params: { type: array, items: { type: object } }
-              dataSources: { type: array, items: { type: object } }
+              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: { 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 }
@@ -107,8 +130,9 @@ 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.
+  - 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` (e.g., api/query) and `source` (e.g., URL or identifier). Provide `method`, `description`, and any other useful metadata when known.
 - Valid JSON only. No comments or trailing commas.
 
 OUTPUT FORMAT (authoritative):
@@ -117,20 +141,38 @@ OUTPUT FORMAT (authoritative):
   "type": "array",
   "items": {
     "type": "object",
-    "required": ["reason", "description", "dependencies", "priority", "filename"],
+    "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": {"enum": ["component", "page", "module", "api", "graphql", "cli", "job", "message", "config"]},
           "component": {"type": "object"},
-          "page": {"type": "object", "properties": {"route": {"type": "string"}}},
+          "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"},
@@ -146,7 +188,7 @@ OUTPUT FORMAT (authoritative):
 ```
 
 INTERFACE TYPES (emit only applicable):
-- page: route (string), params? (array), dataSources? (array), layout? (object)
+- 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?})
@@ -163,6 +205,18 @@ FILENAME CONVENTIONS:
   - 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.

pdd/templates/generic/generate_prompt.prompt

@@ -22,11 +22,11 @@ variables:
     type: string
     description: System layer or interface type for context.
     examples: [backend, frontend, api, graphql, cli, job, message, config, module, component, page]
-  README_FILE:
+  PRD_FILE:
     required: false
     type: path
-    description: Project README to provide overall context.
-    example_paths: [README.md, docs/README.md]
+    description: Product requirements document providing overall context.
+    example_paths: [PRD.md, docs/product/prd.md]
   API_DOC_FILE:
     required: false
     type: path
@@ -48,7 +48,7 @@ variables:
     description: CSV of function inputs/outputs and dependencies for backend modules.
     example_paths: [prompts/backend/io_dependencies.csv]
   ARCHITECTURE_FILE:
-    required: false
+    required: true
     type: path
     description: Architecture JSON (from architecture/architecture_json) to drive module scope, dependencies, and interface.
     example_paths: [architecture.json]
@@ -75,14 +75,14 @@ variables:
     default: py
 usage:
   generate:
-    - name: Minimal (module only)
-      command: pdd generate -e MODULE=orders -e LANG_OR_FRAMEWORK=Python --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt' pdd/templates/generic/generate_prompt.prompt
+    - name: Minimal (architecture only)
+      command: pdd generate -e MODULE=orders -e LANG_OR_FRAMEWORK=Python -e ARCHITECTURE_FILE=architecture.json --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt' pdd/templates/generic/generate_prompt.prompt
     - name: With project docs
-      command: pdd generate -e MODULE=orders -e LANG_OR_FRAMEWORK=Python -e README_FILE=README.md -e API_DOC_FILE=docs/api-documentation.md -e DB_SCHEMA_FILE=context/database-schema.md --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt' pdd/templates/generic/generate_prompt.prompt
+      command: pdd generate -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' pdd/templates/generic/generate_prompt.prompt
     - name: With CSVs and references (backend/Python)
-      command: pdd generate -e MODULE=orders -e LANG_OR_FRAMEWORK=Python -e README_FILE=README.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' pdd/templates/generic/generate_prompt.prompt
+      command: pdd generate -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' pdd/templates/generic/generate_prompt.prompt
     - name: Frontend (TypeScriptReact) variant
-      command: pdd generate -e MODULE=profile_page -e LANG_OR_FRAMEWORK=TypeScriptReact -e LAYER=frontend -e README_FILE=README.md --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt' pdd/templates/generic/generate_prompt.prompt
+      command: pdd generate -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' pdd/templates/generic/generate_prompt.prompt
     - name: From architecture.json
       command: pdd generate -e MODULE=orders_api -e LANG_OR_FRAMEWORK=Python -e LAYER=api -e ARCHITECTURE_FILE=architecture.json --output 'prompts/${MODULE}_${LANG_OR_FRAMEWORK}.prompt' pdd/templates/generic/generate_prompt.prompt
 
@@ -94,8 +94,10 @@ discover:
 
 % 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.
 
-% Project context (optional but recommended):
-<readme><include>${README_FILE}</include></readme>
+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>
@@ -110,8 +112,9 @@ discover:
 % 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.
-- If ARCHITECTURE_FILE is provided, 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.
+- 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).
@@ -127,9 +130,9 @@ discover:
   </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).
-- When using ARCHITECTURE_FILE, its `dependencies` reference 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.
+- 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 (when ARCHITECTURE_FILE provided):
+% 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.
 
@@ -139,4 +142,33 @@ discover:
 - Do not invent technologies or files; rely on the included context. If assumptions are necessary, state them explicitly and conservatively.
 
 % Output contract:
-- Return free-form text containing a single <prompt>...</prompt> XML section with the complete prompt content described above. Do not include additional commentary after the <prompt> block.
+- 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.

{pdd_cli-0.0.61.dist-info → pdd_cli-0.0.63.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdd-cli
-Version: 0.0.61
+Version: 0.0.63
 Summary: PDD (Prompt-Driven Development) Command Line Interface
 Author: Greg Tanaka
 Author-email: glt@alumni.caltech.edu
@@ -53,7 +53,7 @@ Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Dynamic: license-file
 
-.. image:: https://img.shields.io/badge/pdd--cli-v0.0.61-blue
+.. image:: https://img.shields.io/badge/pdd--cli-v0.0.63-blue
    :alt: PDD-CLI Version
 
 .. image:: https://img.shields.io/badge/Discord-join%20chat-7289DA.svg?logo=discord&logoColor=white&link=https://discord.gg/Yp4RTh8bG7
@@ -130,7 +130,7 @@ After installation, verify:
 
    pdd --version
 
-You'll see the current PDD version (e.g., 0.0.61).
+You'll see the current PDD version (e.g., 0.0.63).
 
 Getting Started with Examples
 -----------------------------

{pdd_cli-0.0.61.dist-info → pdd_cli-0.0.63.dist-info}/RECORD

@@ -1,4 +1,4 @@
-pdd/__init__.py,sha256=60zr1ZNOzlSl4emQ4nH962OEwIZiUFC4jsFk1CrMMHc,633
+pdd/__init__.py,sha256=poOT3ybYXYnjrM8EcduTkCl3sMnj5dXCF_LBZI3jQB8,633
 pdd/auto_deps_main.py,sha256=cpP3bbzVL3jomrGinpzTxzIDIC8tmDDYOwUAC1TKRaw,3970
 pdd/auto_include.py,sha256=OJcdcwTwJNqHPHKG9P4m9Ij-PiLex0EbuwJP0uiQi_Y,7484
 pdd/auto_update.py,sha256=w6jzTnMiYRNpwQHQxWNiIAwQ0d6xh1iOB3xgDsabWtc,5236
@@ -6,7 +6,7 @@ pdd/bug_main.py,sha256=EtaGTuucQ7VgqOhyg4o6GFG7_QtTsDPTrRdGJWT648M,4841
 pdd/bug_to_unit_test.py,sha256=BoQqNyKQpBQDW8-JwBH_RX4RHRSiU8Kk3EplFrkECt0,6665
 pdd/change.py,sha256=Hg_x0pa370-e6oDiczaTgFAy3Am9ReCPkqFrvqv4U38,6114
 pdd/change_main.py,sha256=04VHiO_D-jlfeRn6rrVH7ZTA5agXPoJGm1StGI8--XY,27804
-pdd/cli.py,sha256=phCEbNXjK-3Orjg7N-yhKb5DeXAhX9s1q7sWpqPlDps,55747
+pdd/cli.py,sha256=qjDBwwwE-sTWFqKTJOIiYh2nuimlTTgXtMDE0RUuVaU,60805
 pdd/cmd_test_main.py,sha256=M-i5x26ORXurt_pu8x1sgLAyVIItbuRThiux4wBg3Ls,7768
 pdd/code_generator.py,sha256=AxMRZKGIlLh9xWdn2FA6b3zSoZ-5TIZNIAzqjFboAQs,4718
 pdd/code_generator_main.py,sha256=UtoskalEPpMAvCO-zd6xmr1lbQqSWQ7BvYgNJCybqok,35151
@@ -50,7 +50,7 @@ pdd/pdd_completion.sh,sha256=xgx-g6aeCCrlh6loeLyJN5jCsX15YXrWyT1U499p3C0,6490
 pdd/pdd_completion.zsh,sha256=V9-V8jqw3osjlXNOvjYMJf0E771-_EQe-Cboo1xzPvY,17090
 pdd/postprocess.py,sha256=mNw3iSDxE-eTYo3QwJCj_EmdEnnB5ysUN62YPapC_IM,4433
 pdd/postprocess_0.py,sha256=OW17GyCFLYErCyWh2tL4syuho3q2yFf2wyekQ4BLdPM,2168
-pdd/preprocess.py,sha256=75-J1smdi1Uq7gRQRLtVdkIfwltkeIvIZE-TkxxxCz0,12326
+pdd/preprocess.py,sha256=tmZiYlpiJHFDPuwlYtl1htQ7ZA77roGdPRvO4sHXYGU,18162
 pdd/preprocess_main.py,sha256=WGhOB9qEu7MmFoyXNml_AmqGii73LJWngx4kTlZ526k,3262
 pdd/process_csv_change.py,sha256=ckNqVPRooWVyIvmqjdEgo2PDLnpoQ6Taa2dUaWGRlzU,27926
 pdd/pytest_output.py,sha256=IrRKYneW_F6zv9WaJwKFGnOBLFBFjk1CnhO_EVAjb9E,6612
@@ -72,8 +72,8 @@ pdd/update_main.py,sha256=SWCd7Us3YatrDR7B66dQCpRCIgQoMHysPzxa4dedVmk,4385
 pdd/update_model_costs.py,sha256=RfeOlAHtc1FCx47A7CjrH2t5WXQclQ_9uYtNjtQh75I,22998
 pdd/update_prompt.py,sha256=zc-HiI1cwGBkJHVmNDyoSZa13lZH90VdB9l8ajdj6Kk,4543
 pdd/xml_tagger.py,sha256=5Bc3HRm7iz_XjBdzQIcMb8KocUQ8PELI2NN5Gw4amd4,4825
-pdd/data/language_format.csv,sha256=shimgYTHMJtfKQ1wpjjLto27TaMKU4OzNJ4hLeoXHms,957
-pdd/data/llm_model.csv,sha256=UxllgS0btSpCKpPgPnaTFAtZsAynBhLeZyoIVo0Tpwc,1698
+pdd/data/language_format.csv,sha256=i4AfibdhmMnx_xAnv5jHA8TGSftjOJnLcKE53kS7kLY,1010
+pdd/data/llm_model.csv,sha256=u7naNW110fejsV443qlzs0_TmCAzxa8EJogjmmJSAZs,1702
 pdd/prompts/auto_include_LLM.prompt,sha256=sNF2rdJu9wJ8c0lwjCfZ9ZReX8zGXRUNehRs1ZiyDoc,12108
 pdd/prompts/bug_to_unit_test_LLM.prompt,sha256=KdMkvRVnjVSf0NTYIaDXIMT93xPttXEwkMpjWx5leLs,1588
 pdd/prompts/change_LLM.prompt,sha256=5rgWIL16p3VRURd2_lNtcbu_MVRqPhI8gFIBt1gkzDQ,2164
@@ -110,11 +110,11 @@ pdd/prompts/trim_results_start_LLM.prompt,sha256=OKz8fAf1cYWKWgslFOHEkUpfaUDARh3
 pdd/prompts/unfinished_prompt_LLM.prompt,sha256=vud_G9PlVv9Ig64uBC-hPEVFRk5lwpc8pW6tOIxJM4I,5082
 pdd/prompts/update_prompt_LLM.prompt,sha256=prIc8uLp2jqnLTHt6JvWDZGanPZipivhhYeXe0lVaYw,1328
 pdd/prompts/xml_convertor_LLM.prompt,sha256=YGRGXJeg6EhM9690f-SKqQrKqSJjLFD51UrPOlO0Frg,2786
-pdd/templates/architecture/architecture_json.prompt,sha256=uSNSsKTL-cuMMhi5a4GSpC94DKkOFAlXh7R0CUlo-hg,8126
-pdd/templates/generic/generate_prompt.prompt,sha256=EIE4vCEauJglLxS8OxuMx1S4JnPexi-yXxEOpIwaRW4,9276
-pdd_cli-0.0.61.dist-info/licenses/LICENSE,sha256=kvTJnnxPVTYlGKSY4ZN1kzdmJ0lxRdNWxgupaB27zsU,1066
-pdd_cli-0.0.61.dist-info/METADATA,sha256=iS6Mds35DEHVnnWEfrKI0tDsInfBj7V49NUFd8UWhdI,12687
-pdd_cli-0.0.61.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdd_cli-0.0.61.dist-info/entry_points.txt,sha256=Kr8HtNVb8uHZtQJNH4DnF8j7WNgWQbb7_Pw5hECSR-I,36
-pdd_cli-0.0.61.dist-info/top_level.txt,sha256=xjnhIACeMcMeDfVNREgQZl4EbTni2T11QkL5r7E-sbE,4
-pdd_cli-0.0.61.dist-info/RECORD,,
+pdd/templates/architecture/architecture_json.prompt,sha256=lmEM6f1EGK73wivONssvlSNXuTy2nYv-p-oRqBg1iFg,10745
+pdd/templates/generic/generate_prompt.prompt,sha256=4PhcNczpYpwSiaGt0r2f-vhSO3JFqeU1fTEy6YpPudQ,10758
+pdd_cli-0.0.63.dist-info/licenses/LICENSE,sha256=kvTJnnxPVTYlGKSY4ZN1kzdmJ0lxRdNWxgupaB27zsU,1066
+pdd_cli-0.0.63.dist-info/METADATA,sha256=LtF3JdpNk8hnTDvVoNhJzqdoOMINHkdVM9Luxda6sV4,12687
+pdd_cli-0.0.63.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdd_cli-0.0.63.dist-info/entry_points.txt,sha256=Kr8HtNVb8uHZtQJNH4DnF8j7WNgWQbb7_Pw5hECSR-I,36
+pdd_cli-0.0.63.dist-info/top_level.txt,sha256=xjnhIACeMcMeDfVNREgQZl4EbTni2T11QkL5r7E-sbE,4
+pdd_cli-0.0.63.dist-info/RECORD,,