fix: handle empty/greenfield projects in spec creation (#1426)

apps/backend/prompts/spec_writer.md

@@ -24,7 +24,7 @@ You MUST create `spec.md` with ALL required sections (see template below).
 ## PHASE 0: LOAD ALL CONTEXT (MANDATORY)
 
 ```bash
-# Read all input files
+# Read all input files (some may not exist for greenfield/empty projects)
 cat project_index.json
 cat requirements.json
 cat context.json
@@ -35,6 +35,12 @@ Extract from these files:
 - **From requirements.json**: Task description, workflow type, services, acceptance criteria
 - **From context.json**: Files to modify, files to reference, patterns
 
+**IMPORTANT**: If any input file is missing, empty, or shows 0 files, this is likely a **greenfield/new project**. Adapt accordingly:
+- Skip sections that reference existing code (e.g., "Files to Modify", "Patterns to Follow")
+- Instead, focus on files to CREATE and the initial project structure
+- Define the tech stack, dependencies, and setup instructions from scratch
+- Use industry best practices as patterns rather than referencing existing code
+
 ---
 
 ## PHASE 1: ANALYZE CONTEXT

apps/backend/spec/phases/spec_phases.py

@@ -9,12 +9,36 @@
 from typing import TYPE_CHECKING
 
 from .. import validator, writer
+from ..discovery import get_project_index_stats
 from .models import MAX_RETRIES, PhaseResult
 
 if TYPE_CHECKING:
     pass
 
 
+def _is_greenfield_project(spec_dir) -> bool:
+    """Check if the project is empty/greenfield (0 discovered files)."""
+    stats = get_project_index_stats(spec_dir)
+    return stats.get("file_count", 0) == 0
+
+
+def _greenfield_context() -> str:
+    """Return additional context for greenfield/empty projects."""
+    return """
+**GREENFIELD PROJECT**: This is an empty or new project with no existing code.
+There are no existing files to reference or modify. You are creating everything from scratch.
+
+Adapt your approach:
+- Do NOT reference existing files, patterns, or code structures
+- Focus on what needs to be CREATED, not modified
+- Define the initial project structure, files, and directories
+- Specify the tech stack, frameworks, and dependencies to install
+- Provide setup instructions for the new project
+- For "Files to Modify" and "Files to Reference" sections, list files to CREATE instead
+- For "Patterns to Follow", describe industry best practices rather than existing code
+"""
+
+
 class SpecPhaseMixin:
     """Mixin for spec writing and critique phase methods."""
 
@@ -29,6 +53,13 @@ async def phase_quick_spec(self) -> PhaseResult:
                 "quick_spec", True, [str(spec_file), str(plan_file)], [], 0
             )
 
+        is_greenfield = _is_greenfield_project(self.spec_dir)
+        if is_greenfield:
+            self.ui.print_status(
+                "Greenfield project detected - adapting spec for new project",
+                "info",
+            )
+
         errors = []
         for attempt in range(MAX_RETRIES):
             self.ui.print_status(
@@ -42,7 +73,7 @@ async def phase_quick_spec(self) -> PhaseResult:
 
 This is a SIMPLE task. Create a minimal spec and implementation plan directly.
 No research or extensive analysis needed.
-
+{_greenfield_context() if is_greenfield else ""}
 Create:
 1. A concise spec.md with just the essential sections
 2. A simple implementation_plan.json with 1-2 subtasks
@@ -80,6 +111,15 @@ async def phase_spec_writing(self) -> PhaseResult:
                 "spec.md exists but has issues, regenerating...", "warning"
             )
 
+        is_greenfield = _is_greenfield_project(self.spec_dir)
+        if is_greenfield:
+            self.ui.print_status(
+                "Greenfield project detected - adapting spec for new project",
+                "info",
+            )
+
+        greenfield_ctx = _greenfield_context() if is_greenfield else ""
+
         errors = []
         for attempt in range(MAX_RETRIES):
             self.ui.print_status(
@@ -88,6 +128,7 @@ async def phase_spec_writing(self) -> PhaseResult:
 
             success, output = await self.run_agent_fn(
                 "spec_writer.md",
+                additional_context=greenfield_ctx,
                 phase_name="spec_writing",
             )
 

apps/backend/spec/pipeline/orchestrator.py

@@ -238,6 +238,41 @@
         task_logger.start_phase(LogPhase.PLANNING, "Starting spec creation process")
         TaskEventEmitter.from_spec_dir(self.spec_dir).emit("PLANNING_STARTED")
 
+        # Track whether we've already ended the planning phase (to avoid double-end)
+        planning_phase_ended = False
+
+        try:
+            return await self._run_phases(interactive, auto_approve, task_logger, ui)
+        except Exception as e:
+            # Ensure planning phase is always properly ended on unexpected errors
+            # This prevents the task from being stuck in "active" planning state
+            if not planning_phase_ended:
+                planning_phase_ended = True
+                task_logger.end_phase(
+                    LogPhase.PLANNING,
+                    success=False,
+                    message=f"Spec creation failed with unexpected error: {e}",
+                )
+            raise
+
+    async def _run_phases(
+        self,
+        interactive: bool,
+        auto_approve: bool,
+        task_logger,
+        ui,
+    ) -> bool:
+        """Execute all spec creation phases.
+
+        Args:
+            interactive: Whether to run in interactive mode
+            auto_approve: Whether to skip human review
+            task_logger: The task logger instance
+            ui: The UI module
+
+        Returns:
+            True if spec creation and review completed successfully
+        """
         print(
             box(
                 f"Spec Directory: {self.spec_dir}\n"