feat(plugin): add greenfield project detection and UI mockup generation

Detect project maturity (greenfield/early/established) via commit count
and source file heuristics to skip unnecessary scanning in new projects.
Add mandatory UI mockup step during elaboration for any intent with a
frontend component, with ascii/html format controlled by settings.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jwaldrip

plugin/hooks/inject-context.sh

@@ -35,6 +35,19 @@ if [ -f "$DAG_LIB" ]; then
   source "$DAG_LIB"
 fi
 
+# Source config library once (used for providers, maturity detection, etc.)
+CONFIG_LIB="${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
+if [ -f "$CONFIG_LIB" ]; then
+  # shellcheck source=/dev/null
+  source "$CONFIG_LIB"
+fi
+
+# Detect project maturity (greenfield / early / established)
+PROJECT_MATURITY=""
+if type detect_project_maturity &>/dev/null; then
+  PROJECT_MATURITY=$(detect_project_maturity)
+fi
+
 # Load workflows from plugin (defaults) and project (overrides)
 # Project workflows merge with plugin workflows (project takes precedence)
 PLUGIN_WORKFLOWS="${CLAUDE_PLUGIN_ROOT}/workflows.yml"
@@ -123,6 +136,34 @@ if [ -z "$ITERATION_JSON" ] && [[ "$CURRENT_BRANCH" == ai-dlc/*/* ]] && [[ "$CUR
 fi
 
 if [ -z "$ITERATION_JSON" ]; then
+  # Greenfield fast-path: skip all scanning for brand new projects
+  if [ "$PROJECT_MATURITY" = "greenfield" ]; then
+    echo "## AI-DLC Available (Greenfield Project)"
+    echo ""
+    echo "**Project maturity:** greenfield"
+    echo ""
+    echo "No active AI-DLC task. This looks like a new project — run \`/elaborate\` to start defining your first intent."
+    echo ""
+    if [ ! -f ".ai-dlc/settings.yml" ]; then
+      echo "> **First time?** Run \`/setup\` to configure AI-DLC for this project (auto-detects providers, VCS settings, etc.)"
+      echo ""
+    fi
+    # Inject provider context
+    if type format_providers_markdown &>/dev/null; then
+      PROVIDERS_MD=$(format_providers_markdown)
+      if [ -n "$PROVIDERS_MD" ]; then
+        echo "$PROVIDERS_MD"
+        echo ""
+      fi
+    fi
+    if [ -n "$AVAILABLE_WORKFLOWS" ]; then
+      echo "**Available workflows:**"
+      echo "$AVAILABLE_WORKFLOWS"
+      echo ""
+    fi
+    exit 0
+  fi
+
   # Discover resumable intents from filesystem and git branches
   declare -A FILESYSTEM_INTENTS
   declare -A BRANCH_INTENTS
@@ -218,10 +259,7 @@ if [ -z "$ITERATION_JSON" ]; then
       echo ""
     fi
     # Inject provider context for pre-elaboration awareness
-    CONFIG_LIB="${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
-    if [ -f "$CONFIG_LIB" ]; then
-      # shellcheck source=/dev/null
-      source "$CONFIG_LIB"
+    if type format_providers_markdown &>/dev/null; then
       PROVIDERS_MD=$(format_providers_markdown)
       if [ -n "$PROVIDERS_MD" ]; then
         echo "$PROVIDERS_MD"
@@ -233,17 +271,18 @@ if [ -z "$ITERATION_JSON" ]; then
     if [ -n "$AVAILABLE_WORKFLOWS" ]; then
       echo "## AI-DLC Available"
       echo ""
+      if [ -n "$PROJECT_MATURITY" ]; then
+        echo "**Project maturity:** $PROJECT_MATURITY"
+        echo ""
+      fi
       echo "No active AI-DLC task. Run \`/elaborate\` to start a new task."
       echo ""
       if [ ! -f ".ai-dlc/settings.yml" ]; then
         echo "> **First time?** Run \`/setup\` to configure AI-DLC for this project (auto-detects providers, VCS settings, etc.)"
         echo ""
       fi
       # Inject provider context
-      CONFIG_LIB="${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
-      if [ -f "$CONFIG_LIB" ]; then
-        # shellcheck source=/dev/null
-        source "$CONFIG_LIB"
+      if type format_providers_markdown &>/dev/null; then
         PROVIDERS_MD=$(format_providers_markdown)
         if [ -n "$PROVIDERS_MD" ]; then
           echo "$PROVIDERS_MD"
@@ -323,17 +362,18 @@ echo ""
 echo "**Iteration:** $ITERATION | **Hat:** $HAT | **Workflow:** $WORKFLOW_NAME ($WORKFLOW_HATS_STR)"
 echo ""
 
-# Inject provider context
-CONFIG_LIB="${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
-if [ -f "$CONFIG_LIB" ]; then
-  # shellcheck source=/dev/null
-  source "$CONFIG_LIB"
+# Inject provider context and maturity signal
+if type format_providers_markdown &>/dev/null; then
   PROVIDERS_MD=$(format_providers_markdown)
   if [ -n "$PROVIDERS_MD" ]; then
     echo "$PROVIDERS_MD"
     echo ""
   fi
 fi
+if [ -n "$PROJECT_MATURITY" ]; then
+  echo "**Project maturity:** $PROJECT_MATURITY"
+  echo ""
+fi
 
 # Batch load all han keep values at once (single subprocess call)
 # This is much faster than 5+ separate han keep load calls

plugin/lib/config.sh

@@ -348,6 +348,56 @@ detect_ci_cd() {
   fi
 }
 
+# Detect project maturity based on commit count and source file count
+# Usage: detect_project_maturity [directory]
+# Returns: greenfield | early | established
+detect_project_maturity() {
+  local dir="${1:-.}"
+
+  # Guard: shallow clone — commit count is unreliable
+  local is_shallow
+  is_shallow=$(git -C "$dir" rev-parse --is-shallow-repository 2>/dev/null || echo "false")
+
+  local commit_count=0
+  if [ "$is_shallow" != "true" ]; then
+    commit_count=$(git -C "$dir" rev-list --count HEAD 2>/dev/null || echo "0")
+  fi
+
+  # Count source files excluding scaffolding
+  # Excludes: *.md, *.json, *.yml, *.yaml, *.lock, *.toml, LICENSE*, Dockerfile*,
+  #           .github/*, .gitlab-ci*, .circleci/*, .ai-dlc/*
+  local source_file_count
+  source_file_count=$(git -C "$dir" ls-files 2>/dev/null \
+    | grep -cvE '\.(md|json|ya?ml|lock|toml)$|^LICENSE|^Dockerfile|^\.github/|^\.gitlab-ci|^\.circleci/|^\.ai-dlc/' \
+    2>/dev/null || true)
+  : "${source_file_count:=0}"
+
+  # Shallow clone: use source file count only
+  if [ "$is_shallow" = "true" ]; then
+    if [ "$source_file_count" -le 5 ]; then
+      echo "greenfield"
+    elif [ "$source_file_count" -le 20 ]; then
+      echo "early"
+    else
+      echo "established"
+    fi
+    return
+  fi
+
+  # Full repo heuristics
+  if [ "$commit_count" -le 3 ]; then
+    echo "greenfield"
+  elif [ "$commit_count" -le 20 ]; then
+    if [ "$source_file_count" -le 5 ]; then
+      echo "greenfield"
+    else
+      echo "early"
+    fi
+  else
+    echo "established"
+  fi
+}
+
 # Load provider configuration with fallback chain
 # Usage: load_providers [repo_root]
 # Returns: JSON object with all provider categories

plugin/schemas/settings.schema.json

@@ -16,6 +16,12 @@
 		"providers": {
 			"$ref": "#/definitions/providersConfig",
 			"description": "External system providers for spec, ticketing, design, and comms"
+		},
+		"mockup_format": {
+			"type": "string",
+			"enum": ["ascii", "html"],
+			"default": "ascii",
+			"description": "Format for UI mockups generated during elaboration. 'ascii' produces text-based wireframes in markdown code blocks. 'html' produces self-contained HTML files written to .ai-dlc/{intent-slug}/mockups/."
 		}
 	},
 	"additionalProperties": false,

plugin/skills/elaborate/SKILL.md

@@ -61,6 +61,12 @@ Before any elaboration, verify the working environment:
    IS_COWORK="${CLAUDE_CODE_IS_COWORK:-}"
    IN_REPO=$(git rev-parse --git-dir 2>/dev/null && echo "true" || echo "false")
    ```
+1b. **Detect project maturity**: Read `**Project maturity:**` from the session context injected by the SessionStart hook. If not present, detect directly:
+   ```bash
+   source "${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
+   PROJECT_MATURITY=$(detect_project_maturity)
+   ```
+   Values: `greenfield` (brand new, 0-3 commits or minimal source files), `early` (some code but still small), `established` (mature codebase). This value gates Phase 2.5 exploration behavior.
 2. If **not cowork** (`IS_COWORK` is empty) **and in a repo** (`IN_REPO` is `true`): proceed to Phase 0 (Existing Intent Check) below.
 3. If **cowork** (`IS_COWORK=1`) **or not in a repo**:
    a. **Ask how to access the project**:
@@ -271,19 +277,33 @@ This ensures:
 
 **This phase is mandatory.** Before defining success criteria or decomposing into units, you MUST deeply understand the technical landscape. Shallow understanding here causes builders to build the wrong thing.
 
+### Greenfield Adaptation
+
+**Gate exploration based on project maturity** (detected in Phase 0):
+
+- **Greenfield** (`PROJECT_MATURITY=greenfield`):
+  - **Skip** items 2 (Existing Codebases) and 5 (Existing Implementations) below — there is no codebase to explore. Do NOT spawn Explore subagents for codebase research.
+  - **Keep** items 1 (APIs/Schemas), 3 (Data Sources), 4 (Domain Model — from user input + external research), 6 (External Docs/Libraries), 7 (Providers).
+  - Focus domain discovery on external research, API introspection, and user input rather than codebase analysis.
+- **Early** (`PROJECT_MATURITY=early`):
+  - Use `Glob` and `Read` directly instead of Explore subagents — the codebase is small enough to read directly without subagent overhead.
+  - All items apply, but codebase exploration should be lightweight.
+- **Established** (`PROJECT_MATURITY=established`):
+  - Full exploration as described below. Use Explore subagents for deep codebase research.
+
 ### What to Explore
 
 Based on what the user described in Phase 2, identify every relevant technical surface and explore it thoroughly. Use ALL available research tools — codebase exploration, API introspection, web searches, and documentation fetching:
 
 1. **APIs and Schemas**: If the intent involves an API, query it. Run introspection queries. Read the actual schema. Map every type, field, query, mutation, and subscription. Don't guess what data is available — verify it.
 
-2. **Existing Codebases**: If the intent builds on or integrates with existing code, explore it via Explore subagents. Have them find relevant files, read source code, and report back on existing patterns, conventions, and architecture.
+2. **Existing Codebases** *(skip for greenfield)*: If the intent builds on or integrates with existing code, explore it via Explore subagents (or `Glob`/`Read` for early-maturity projects). Have them find relevant files, read source code, and report back on existing patterns, conventions, and architecture.
 
 3. **Data Sources**: If the intent involves data, understand where it lives. Query for real sample data. Understand what fields are populated, what's empty, what's missing. Identify gaps between what's available and what's needed.
 
 4. **Domain Model**: From your exploration, build a domain model — the key entities, their relationships, and their lifecycle. This is not a database schema; it's a conceptual map of the problem space.
 
-5. **Existing Implementations**: If there are related features, similar tools, or reference implementations, read them. Understand what already exists so you don't build duplicates or miss integration points.
+5. **Existing Implementations** *(skip for greenfield)*: If there are related features, similar tools, or reference implementations, read them. Understand what already exists so you don't build duplicates or miss integration points.
 
 6. **External Documentation and Libraries**: Use `WebSearch` and `WebFetch` to research relevant libraries, frameworks, APIs, standards, or prior art. If the intent involves a third-party system, find its documentation and understand its capabilities. If the intent involves a design pattern or technique, research best practices and common pitfalls.
 
@@ -298,7 +318,7 @@ Based on what the user described in Phase 2, identify every relevant technical s
 
 Use every research tool available. Spawn multiple explorations in parallel for independent concerns:
 
-1. **Subagents for deep codebase/API exploration**: Use `Task` with `subagent_type: "Explore"` for multi-step research that requires reading many files, querying APIs, and synthesizing findings:
+1. **Subagents for deep codebase/API exploration** *(established projects only)*: Use `Task` with `subagent_type: "Explore"` for multi-step research that requires reading many files, querying APIs, and synthesizing findings. **If greenfield: do NOT spawn Explore subagents for codebase research — there is no codebase to explore.** If early: use `Glob`/`Read` directly instead of Explore subagents.
 
 ```
 Task({
@@ -357,6 +377,111 @@ Spawn one subagent per design file, in parallel with codebase Explore agents. Wh
 - Append to `discovery.md` under `## Design Analysis: {file name}`
 - If no design MCP tools are discoverable, the subagent reports unavailability — log a warning and continue without design analysis
 
+5. **UI Mockups**: If the intent involves user-facing interfaces (frontend, CLI, TUI, etc.), generate mockups for every distinct screen or view. This step is **mandatory** for any intent with a UI component — it serves different purposes depending on whether designs exist:
+
+   - **Designs exist** (item 4 returned design analysis): Translate the design analysis into mockups that demonstrate your understanding of the designs. This is *verification* — the user confirms that you correctly interpreted the designer's intent before builders act on it. Misunderstanding a design is expensive; catching it here is cheap.
+   - **No designs exist**: Generate mockups collaboratively with the user as *pre-build visual design*. This is where layout, information hierarchy, and interaction flow get decided. Without this step, builders guess — and they guess wrong. This applies regardless of whether a design provider is configured — having a Figma account doesn't mean designs exist yet. In AI-DLC workflows, design may come later as its own unit with `discipline: design`.
+
+   #### Mockup Format
+
+   Read the mockup format from settings (default: `ascii`):
+   ```bash
+   source "${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
+   REPO_SETTINGS=$(load_repo_settings)
+   MOCKUP_FORMAT=$(echo "$REPO_SETTINGS" | jq -r '.mockup_format // "ascii"')
+   ```
+
+   - **`ascii`** (default): Text-based wireframes rendered in markdown code blocks. Inline in `discovery.md`. Works everywhere, no tooling needed, visible in any terminal or editor.
+   - **`html`**: Self-contained HTML files written to `.ai-dlc/{intent-slug}/mockups/{view-slug}.html`. Use semantic HTML with inline CSS — no external dependencies. Each file should be viewable by opening it directly in a browser. Reference the file path in `discovery.md` instead of inlining the mockup.
+
+   #### Per-View Mockup Process
+
+   For each distinct screen or view identified in the domain model:
+   - Create a mockup showing layout structure, key UI elements, and data placement
+   - Annotate with interaction notes (what happens on click, hover, submit, error states)
+   - Show which domain entities map to which UI regions
+   - If working from designs: note where your interpretation might diverge from the source
+
+   Present mockups to the user with `AskUserQuestion`:
+   ```json
+   {
+     "questions": [{
+       "question": "Does this mockup capture the right layout and information hierarchy for {view name}?",
+       "header": "Mockup",
+       "options": [
+         {"label": "Looks right", "description": "Layout and information hierarchy are correct"},
+         {"label": "Wrong layout", "description": "The arrangement of elements needs changes"},
+         {"label": "Missing elements", "description": "Important UI elements are not shown"},
+         {"label": "Wrong data", "description": "The data shown doesn't match what I expect"}
+       ],
+       "multiSelect": true
+     }]
+   }
+   ```
+
+   Iterate on mockups until the user confirms. Then persist:
+
+   **For `ascii` format** — append to `discovery.md`:
+   ```bash
+   cat >> "$DISCOVERY_FILE" << 'EOF'
+
+   ## UI Mockup: {View Name}
+
+   **Confirmed:** {ISO timestamp}
+   **Source:** {design provider analysis | collaborative}
+
+   ### Layout
+   ```
+   {ASCII mockup}
+   ```
+
+   ### Interactions
+   - {element}: {behavior on click/hover/submit}
+   - {element}: {error states, loading states}
+
+   ### Data Mapping
+   - {UI region} ← {domain entity}.{field}
+
+   EOF
+   ```
+
+   **For `html` format** — write HTML file and reference in `discovery.md`:
+   ```bash
+   MOCKUP_DIR=".ai-dlc/${INTENT_SLUG}/mockups"
+   mkdir -p "$MOCKUP_DIR"
+   cat > "${MOCKUP_DIR}/{view-slug}.html" << 'HTMLEOF'
+   <!DOCTYPE html>
+   <html lang="en">
+   <head><meta charset="UTF-8"><title>{View Name} — Mockup</title>
+   <style>/* inline CSS — no external deps */</style>
+   </head>
+   <body>
+   {semantic HTML mockup with inline styles}
+   </body>
+   </html>
+   HTMLEOF
+
+   # Reference in discovery.md
+   cat >> "$DISCOVERY_FILE" << EOF
+
+   ## UI Mockup: {View Name}
+
+   **Confirmed:** {ISO timestamp}
+   **Source:** {design provider analysis | collaborative}
+   **File:** \`.ai-dlc/${INTENT_SLUG}/mockups/{view-slug}.html\`
+
+   ### Interactions
+   - {element}: {behavior on click/hover/submit}
+   - {element}: {error states, loading states}
+
+   ### Data Mapping
+   - {UI region} ← {domain entity}.{field}
+
+   EOF
+   ```
+
+   **Skip this step only if:** the intent has no user-facing interface (pure backend, API, data pipeline, infrastructure, etc.).
+
 **Spawn multiple research paths in parallel.** Don't serialize explorations that are independent — launch all of them at once and synthesize when results return.
 
 If a VCS MCP is available (e.g., GitHub MCP), use it for code browsing alongside or instead of local file tools.
@@ -405,6 +530,10 @@ EOF
 - `## External Research: {topic}` — For web research, library docs, prior art
 - `## Data Source: {name}` — For data source exploration (what's available, what's missing)
 - `## Provider Context: {type}` — For ticketing, spec, or comms provider findings
+- `## UI Mockup: {view}` — ASCII mockups of user-facing views with interaction notes and data mapping
+- `## Architecture Decision: {topic}` — For greenfield/early projects: key architecture choices (frameworks, patterns, structure)
+- `## Technology Choice: {name}` — For greenfield/early projects: technology selection rationale
+- `## Reference Implementation: {name}` — For greenfield/early projects: external reference implementations or prior art informing the design
 
 **After appending to `discovery.md`, keep only a brief summary in your context** — the full details are safely on disk and will be available to builders. This is the key benefit: your context stays lean for continued exploration while nothing is lost.