feat: planner agent backend — PlannerConfig schema, system prompt, planner utility

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: ryaneggz <kre8mymedia@gmail.com>

Author: ryaneggz

backend/src/schemas/entities/llm.py

@@ -18,6 +18,7 @@
     SystemMessage,
     ToolMessage,
 )
+from src.schemas.entities.planner import PlannerConfig
 from src.services.prompt.defaults import get_default_system_prompt
 from src.utils.format import slugify
 
@@ -110,6 +111,7 @@ def validate_system_prompt_or_instructions(self):
         default_factory=dict,
         description="File system storage for the assistant. Key is the file path, value is the file content.",
     )
+    planner: Optional[PlannerConfig] = Field(default=None, description="Planner agent configuration")
     metadata: dict = {}
     updated_at: Optional[datetime] = None
     created_at: Optional[datetime] = None

backend/src/schemas/entities/planner.py

@@ -0,0 +1,12 @@
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+
+class PlannerConfig(BaseModel):
+    """Configuration for the planner pre-execution phase."""
+
+    enabled: bool = False
+    auto_approve: bool = True  # False = pause for user approval via HITL
+    model: Optional[str] = None  # Override model for planner (e.g., use Opus)
+    scope_level: Literal["conservative", "ambitious"] = "ambitious"

backend/src/static/prompts/md/planner.md

@@ -0,0 +1,38 @@
+You are a product planning agent. Your job is to expand a short user prompt into a structured product specification.
+
+## Your Role
+
+- Be ambitious about scope — include features the user didn't explicitly request but would clearly benefit from
+- Stay high-level: product context, feature list, user stories, design direction
+- Do NOT specify granular implementation details (file names, function signatures, database schemas)
+- Identify opportunities to weave AI-powered features into the product
+- Think about what would make this product genuinely impressive, not just functional
+
+## Output Format
+
+Structure your plan as markdown with these sections:
+
+### Overview
+A 2-3 sentence summary of what we're building and why.
+
+### Features
+A numbered list of features, each with:
+- Feature name
+- One-line description
+- 1-2 user stories in "As a [user], I want [action] so that [benefit]" format
+
+### Design Direction
+- Visual style and tone
+- Key UX principles
+- Reference points or inspirations
+
+### Technical Considerations
+- Recommended tech stack (if relevant)
+- Key architectural decisions
+- Performance or scale considerations
+
+### Success Criteria
+- How we'll know this is done and done well
+- Key metrics to track
+
+Keep the plan concise but comprehensive. Aim for 300-800 words.

backend/src/utils/planner.py

@@ -0,0 +1,67 @@
+"""Planner pre-execution phase — expands short prompts into structured product specs."""
+
+from pathlib import Path
+
+from langchain.chat_models import init_chat_model
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from src.schemas.entities.planner import PlannerConfig
+from src.utils.llm import resolve_api_key
+from src.utils.logger import logger
+
+# Load the planner system prompt
+_PLANNER_PROMPT_PATH = Path(__file__).parent.parent / "static" / "prompts" / "md" / "planner.md"
+_PLANNER_PROMPT = ""
+if _PLANNER_PROMPT_PATH.exists():
+    _PLANNER_PROMPT = _PLANNER_PROMPT_PATH.read_text()
+
+
+async def run_planner(
+    user_message: str,
+    planner_config: PlannerConfig,
+    default_model: str,
+    api_key: str | None = None,
+    user_keys: dict[str, str] | None = None,
+) -> str:
+    """Run the planner to expand a short prompt into a structured spec.
+
+    Returns the plan as markdown text.
+    """
+    model_name = planner_config.model or default_model
+
+    # Resolve API key for the planner model
+    planner_api_key = api_key
+    if planner_config.model:
+        resolved = resolve_api_key(planner_config.model, user_keys)
+        if resolved:
+            planner_api_key = resolved
+
+    llm = init_chat_model(model_name, api_key=planner_api_key)
+
+    scope_instruction = ""
+    if planner_config.scope_level == "conservative":
+        scope_instruction = (
+            "\n\nIMPORTANT: Keep the scope conservative. "
+            "Only include features explicitly requested by the user. Do not add extras."
+        )
+    else:
+        scope_instruction = (
+            "\n\nBe ambitious about scope. Include features that would make this product impressive, "
+            "even if the user didn't explicitly request them."
+        )
+
+    system_prompt = _PLANNER_PROMPT + scope_instruction
+
+    messages = [
+        SystemMessage(content=system_prompt),
+        HumanMessage(content=f"Please create a product plan for the following request:\n\n{user_message}"),
+    ]
+
+    logger.info(f"planner_phase model={model_name} scope={planner_config.scope_level}")
+
+    response = await llm.ainvoke(messages)
+    plan_text = response.content if isinstance(response.content, str) else str(response.content)
+
+    logger.info(f"planner_phase_complete plan_length={len(plan_text)}")
+
+    return plan_text