cadence-skill-installer 0.2.32 → 0.2.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cadence-skill-installer",
-  "version": "0.2.32",
+  "version": "0.2.33",
   "description": "Install the Cadence skill into supported AI tool skill directories.",
   "repository": "https://github.com/snowdamiz/cadence",
   "private": false,

package/skill/SKILL.md

@@ -66,7 +66,7 @@ description: Structured project operating system for end-to-end greenfield or br
 
 ## Prerequisite Gate (Conditional)
 1. Invoke `skills/prerequisite-gate/SKILL.md` only when `route.skill_name` is `prerequisite-gate`.
-2. If `route.skill_name` is not `prerequisite-gate` (for example `brownfield-intake`, `brownfield-documenter`, `ideator`, or `researcher`), skip prerequisite gate and follow the active route instead.
+2. If `route.skill_name` is not `prerequisite-gate` (for example `brownfield-intake`, `brownfield-documenter`, `ideator`, `researcher`, or `planner`), skip prerequisite gate and follow the active route instead.
 
 ## Project Mode Intake Gate (Conditional)
 1. Invoke `skills/brownfield-intake/SKILL.md` only when `route.skill_name` is `brownfield-intake`.
@@ -107,6 +107,12 @@ description: Structured project operating system for end-to-end greenfield or br
 2. Enforce one research pass per conversation so context stays bounded.
 3. When the researcher flow reports additional passes remain (`handoff_required=true`), end with this exact line: `Start a new chat and say "continue research".`
 4. Continue routing to researcher on subsequent chats until workflow reports the research task complete.
+5. For greenfield projects, when research completes and route advances to `planner`, invoke `skills/planner/SKILL.md` in the next routed conversation.
+
+## Planner Flow
+1. If the workflow route is `planner`, invoke `skills/planner/SKILL.md`.
+2. Planner is greenfield-only and should not run for brownfield routes.
+3. Keep planner output at milestone/phase level in `.cadence/cadence.json` and defer waves/tasks decomposition to a later planning subskill.
 
 ## Ideation Update Flow
 1. If the user wants to modify or discuss existing ideation, invoke `skills/ideation-updater/SKILL.md`.

package/skill/agents/openai.yaml

@@ -14,4 +14,4 @@ interface:
     For each successful subskill conversation, run scripts/finalize-skill-checkpoint.py from PROJECT_ROOT with
     that subskill's --scope/--checkpoint and --paths ., allow status=no_changes, and treat checkpoint/push
     failures as blocking.
-    Use the exact handoff lines in SKILL.md for ideator, brownfield-documenter, and researcher transitions.
+    Use the exact handoff lines in SKILL.md for ideator, brownfield-documenter, researcher, and planner transitions.

package/skill/assets/cadence.json

@@ -10,7 +10,7 @@
         "brownfield-documentation-completed": false
     },
     "workflow": {
-        "schema_version": 5,
+        "schema_version": 6,
         "plan": [
             {
                 "id": "milestone-foundation",
@@ -86,6 +86,16 @@
                                             "skill_path": "skills/researcher/SKILL.md",
                                             "reason": "Ideation research agenda has not been completed yet."
                                         }
+                                    },
+                                    {
+                                        "id": "task-roadmap-planning",
+                                        "kind": "task",
+                                        "title": "Plan project roadmap",
+                                        "route": {
+                                            "skill_name": "planner",
+                                            "skill_path": "skills/planner/SKILL.md",
+                                            "reason": "Project roadmap planning has not been completed yet."
+                                        }
                                     }
                                 ]
                             }
@@ -135,5 +145,16 @@
             "handoff_required": false,
             "handoff_message": "Start a new chat and say \"continue research\"."
         }
+    },
+    "planning": {
+        "version": 1,
+        "status": "pending",
+        "detail_level": "",
+        "decomposition_pending": true,
+        "created_at": "",
+        "updated_at": "",
+        "summary": "",
+        "assumptions": [],
+        "milestones": []
     }
 }

package/skill/config/commit-conventions.json

@@ -133,6 +133,12 @@
             "checkpoints": {
                 "research-pass-recorded": "persist one ideation research pass"
             }
+        },
+        "planner": {
+            "description": "Greenfield roadmap planning persistence",
+            "checkpoints": {
+                "plan-created": "persist milestone and phase roadmap plan"
+            }
         }
     }
 }

package/skill/scripts/run-planner.py

@@ -0,0 +1,573 @@
+#!/usr/bin/env python3
+"""Discover and persist roadmap planning for greenfield Cadence projects."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from project_root import resolve_project_root, write_project_root_hint
+from workflow_state import default_data, reconcile_workflow_state, set_workflow_item_status
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+ROUTE_GUARD_SCRIPT = SCRIPT_DIR / "assert-workflow-route.py"
+FUZZY_QUERY_SCRIPT = SCRIPT_DIR / "query-json-fuzzy.py"
+CADENCE_JSON_REL = Path(".cadence") / "cadence.json"
+DETAIL_LEVEL = "milestone_phase_v1"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Discover and persist Cadence roadmap planning.",
+    )
+    parser.add_argument(
+        "--project-root",
+        default="",
+        help="Explicit project root path override.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    discover = subparsers.add_parser(
+        "discover",
+        help="Extract planning-ready context from cadence state.",
+    )
+    discover.add_argument(
+        "--fuzzy-query",
+        action="append",
+        default=[],
+        help="Optional fuzzy query text to search against cadence.json (repeatable).",
+    )
+    discover.add_argument(
+        "--fuzzy-threshold",
+        type=float,
+        default=0.76,
+        help="Minimum fuzzy score threshold when using --fuzzy-query (default: 0.76).",
+    )
+    discover.add_argument(
+        "--fuzzy-limit",
+        type=int,
+        default=8,
+        help="Maximum results per fuzzy query (default: 8).",
+    )
+    discover.add_argument(
+        "--fuzzy-field",
+        action="append",
+        default=[],
+        help="Optional field path pattern passed to query-json-fuzzy.py --field (repeatable).",
+    )
+
+    complete = subparsers.add_parser(
+        "complete",
+        help="Persist roadmap planning payload and advance workflow.",
+    )
+    payload_group = complete.add_mutually_exclusive_group(required=True)
+    payload_group.add_argument("--file", help="Path to planner payload JSON file")
+    payload_group.add_argument("--json", help="Inline planner payload JSON")
+    payload_group.add_argument("--stdin", action="store_true", help="Read planner payload JSON from stdin")
+
+    return parser.parse_args()
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def run_command(command: list[str], cwd: Path) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def assert_expected_route(project_root: Path) -> None:
+    result = run_command(
+        [
+            sys.executable,
+            str(ROUTE_GUARD_SCRIPT),
+            "--skill-name",
+            "planner",
+            "--project-root",
+            str(project_root),
+        ],
+        project_root,
+    )
+    if result.returncode != 0:
+        detail = result.stderr.strip() or result.stdout.strip() or "WORKFLOW_ROUTE_CHECK_FAILED"
+        print(detail, file=sys.stderr)
+        raise SystemExit(result.returncode)
+
+
+def cadence_json_path(project_root: Path) -> Path:
+    return project_root / CADENCE_JSON_REL
+
+
+def load_state(project_root: Path) -> dict[str, Any]:
+    state_path = cadence_json_path(project_root)
+    if not state_path.exists():
+        return default_data()
+
+    try:
+        payload = json.loads(state_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"INVALID_CADENCE_JSON: {exc} path={state_path}", file=sys.stderr)
+        raise SystemExit(1)
+    if not isinstance(payload, dict):
+        return default_data()
+    return reconcile_workflow_state(payload, cadence_dir_exists=True)
+
+
+def save_state(project_root: Path, data: dict[str, Any]) -> None:
+    path = cadence_json_path(project_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=4) + "\n", encoding="utf-8")
+
+
+def _coerce_text(value: Any) -> str:
+    return str(value).strip() if value is not None else ""
+
+
+def _coerce_text_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, (list, tuple, set)):
+        raw_values = list(value)
+    else:
+        raw_values = [value]
+
+    values: list[str] = []
+    for raw in raw_values:
+        text = _coerce_text(raw)
+        if text and text not in values:
+            values.append(text)
+    return values
+
+
+def _slug_token(value: Any, fallback: str) -> str:
+    token = re.sub(r"[^a-z0-9]+", "-", _coerce_text(value).lower()).strip("-")
+    if token:
+        return token
+    fallback_token = re.sub(r"[^a-z0-9]+", "-", _coerce_text(fallback).lower()).strip("-")
+    return fallback_token or "item"
+
+
+def ensure_planner_prerequisites(data: dict[str, Any]) -> None:
+    state = data.get("state")
+    state = state if isinstance(state, dict) else {}
+    mode = _coerce_text(state.get("project-mode", "unknown")).lower()
+    if mode != "greenfield":
+        raise ValueError(f"PLANNER_REQUIRES_GREENFIELD_MODE: project-mode={mode or 'unknown'}")
+    if not bool(state.get("ideation-completed", False)):
+        raise ValueError("IDEATION_NOT_COMPLETE")
+    if not bool(state.get("research-completed", False)):
+        raise ValueError("RESEARCH_NOT_COMPLETE")
+
+
+def planning_contract() -> dict[str, Any]:
+    return {
+        "detail_level": DETAIL_LEVEL,
+        "required_fields": ["summary", "milestones"],
+        "optional_fields": ["assumptions"],
+        "milestone_fields": [
+            "milestone_id",
+            "title",
+            "objective",
+            "success_criteria",
+            "phases",
+        ],
+        "phase_fields": [
+            "phase_id",
+            "title",
+            "objective",
+            "deliverables",
+            "exit_criteria",
+            "notes",
+        ],
+        "constraints": [
+            "At least one milestone is required.",
+            "Each milestone must include at least one phase.",
+            "Do not include waves or tasks in this planner version.",
+        ],
+    }
+
+
+def summarize_context(data: dict[str, Any]) -> dict[str, Any]:
+    ideation = data.get("ideation")
+    ideation = ideation if isinstance(ideation, dict) else {}
+    agenda = ideation.get("research_agenda")
+    agenda = agenda if isinstance(agenda, dict) else {}
+    agenda_summary = agenda.get("summary")
+    agenda_summary = agenda_summary if isinstance(agenda_summary, dict) else {}
+    execution = ideation.get("research_execution")
+    execution = execution if isinstance(execution, dict) else {}
+    execution_summary = execution.get("summary")
+    execution_summary = execution_summary if isinstance(execution_summary, dict) else {}
+    blocks = agenda.get("blocks")
+    blocks = blocks if isinstance(blocks, list) else []
+    pass_history = execution.get("pass_history")
+    pass_history = pass_history if isinstance(pass_history, list) else []
+
+    block_summaries: list[dict[str, Any]] = []
+    for block in blocks:
+        if not isinstance(block, dict):
+            continue
+        topics = block.get("topics")
+        topics = topics if isinstance(topics, list) else []
+        topic_titles = [
+            _coerce_text(topic.get("title", ""))
+            for topic in topics
+            if isinstance(topic, dict) and _coerce_text(topic.get("title", ""))
+        ]
+        block_summaries.append(
+            {
+                "block_id": _coerce_text(block.get("block_id")),
+                "title": _coerce_text(block.get("title")),
+                "rationale": _coerce_text(block.get("rationale")),
+                "topic_count": len(topics),
+                "topic_titles": topic_titles[:8],
+            }
+        )
+
+    recent_passes: list[dict[str, Any]] = []
+    for entry in pass_history[-4:]:
+        if not isinstance(entry, dict):
+            continue
+        topics = entry.get("topics")
+        topics = topics if isinstance(topics, list) else []
+        recent_passes.append(
+            {
+                "pass_id": _coerce_text(entry.get("pass_id")),
+                "completed_at": _coerce_text(entry.get("completed_at")),
+                "pass_summary": _coerce_text(entry.get("pass_summary")),
+                "topic_count": len(topics),
+            }
+        )
+
+    planning = data.get("planning")
+    planning = planning if isinstance(planning, dict) else {}
+    milestones = planning.get("milestones")
+    milestones = milestones if isinstance(milestones, list) else []
+
+    return {
+        "objective": _coerce_text(ideation.get("objective")),
+        "core_outcome": _coerce_text(ideation.get("core_outcome")),
+        "target_audience": ideation.get("target_audience", ""),
+        "in_scope": _coerce_text_list(ideation.get("in_scope")),
+        "out_of_scope": _coerce_text_list(ideation.get("out_of_scope")),
+        "constraints": _coerce_text_list(ideation.get("constraints")),
+        "risks": _coerce_text_list(ideation.get("risks")),
+        "success_signals": _coerce_text_list(ideation.get("success_signals")),
+        "research_agenda_summary": {
+            "block_count": int(agenda_summary.get("block_count", 0) or 0),
+            "topic_count": int(agenda_summary.get("topic_count", 0) or 0),
+            "entity_count": int(agenda_summary.get("entity_count", 0) or 0),
+        },
+        "research_execution_summary": {
+            "topic_total": int(execution_summary.get("topic_total", 0) or 0),
+            "topic_complete": int(execution_summary.get("topic_complete", 0) or 0),
+            "pass_complete": int(execution_summary.get("pass_complete", 0) or 0),
+        },
+        "research_blocks": block_summaries,
+        "recent_research_passes": recent_passes,
+        "existing_plan_summary": {
+            "status": _coerce_text(planning.get("status", "pending")),
+            "detail_level": _coerce_text(planning.get("detail_level")),
+            "milestone_count": len(milestones),
+            "updated_at": _coerce_text(planning.get("updated_at")),
+        },
+        "planner_payload_contract": planning_contract(),
+    }
+
+
+def run_fuzzy_queries(args: argparse.Namespace, project_root: Path) -> list[dict[str, Any]]:
+    queries = [query for query in (_coerce_text(value) for value in args.fuzzy_query) if query]
+    if not queries:
+        return []
+
+    threshold = float(args.fuzzy_threshold)
+    if threshold < 0.0 or threshold > 1.0:
+        raise ValueError("INVALID_FUZZY_THRESHOLD: must be between 0.0 and 1.0")
+
+    limit = int(args.fuzzy_limit)
+    if limit < 1:
+        raise ValueError("INVALID_FUZZY_LIMIT: must be >= 1")
+
+    fields = [field for field in (_coerce_text(value) for value in args.fuzzy_field) if field]
+    cadence_path = cadence_json_path(project_root)
+    responses: list[dict[str, Any]] = []
+
+    for query in queries:
+        command = [
+            sys.executable,
+            str(FUZZY_QUERY_SCRIPT),
+            "--file",
+            str(cadence_path),
+            "--text",
+            query,
+            "--threshold",
+            str(threshold),
+            "--limit",
+            str(limit),
+        ]
+        for field in fields:
+            command.extend(["--field", field])
+
+        result = run_command(command, project_root)
+        if result.returncode != 0:
+            responses.append(
+                {
+                    "query": query,
+                    "status": "error",
+                    "error": result.stderr.strip() or result.stdout.strip() or "FUZZY_QUERY_FAILED",
+                }
+            )
+            continue
+
+        raw = result.stdout.strip()
+        if not raw:
+            responses.append(
+                {
+                    "query": query,
+                    "status": "error",
+                    "error": "FUZZY_QUERY_EMPTY_OUTPUT",
+                }
+            )
+            continue
+
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            responses.append(
+                {
+                    "query": query,
+                    "status": "error",
+                    "error": f"FUZZY_QUERY_INVALID_JSON: {exc}",
+                }
+            )
+            continue
+
+        responses.append(
+            {
+                "query": query,
+                "status": "ok",
+                "summary": payload.get("summary", {}),
+                "results": payload.get("results", []),
+            }
+        )
+
+    return responses
+
+
+def parse_payload(args: argparse.Namespace, project_root: Path) -> dict[str, Any]:
+    if args.file:
+        payload_path = Path(args.file).expanduser()
+        if not payload_path.is_absolute():
+            payload_path = (project_root / payload_path).resolve()
+        try:
+            raw = payload_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ValueError(f"PAYLOAD_READ_FAILED: {exc}") from exc
+    elif args.json:
+        raw = args.json
+    else:
+        raw = sys.stdin.read()
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"INVALID_PAYLOAD_JSON: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise ValueError("PLANNER_PAYLOAD_MUST_BE_OBJECT")
+    return payload
+
+
+def normalize_phase(raw_phase: Any, *, fallback_index: int, milestone_seed: str) -> dict[str, Any]:
+    phase = dict(raw_phase) if isinstance(raw_phase, dict) else {}
+    if phase.get("waves") is not None or phase.get("tasks") is not None:
+        raise ValueError("PHASE_WAVES_AND_TASKS_NOT_ALLOWED_IN_V1")
+
+    phase_id_raw = phase.get("phase_id", phase.get("id", ""))
+    title = _coerce_text(phase.get("title")) or f"Phase {fallback_index}"
+    phase_id = _slug_token(phase_id_raw, f"{milestone_seed}-phase-{fallback_index}")
+
+    return {
+        "phase_id": phase_id,
+        "title": title,
+        "objective": _coerce_text(phase.get("objective")),
+        "deliverables": _coerce_text_list(phase.get("deliverables")),
+        "exit_criteria": _coerce_text_list(phase.get("exit_criteria")),
+        "notes": _coerce_text(phase.get("notes")),
+    }
+
+
+def normalize_milestone(raw_milestone: Any, *, fallback_index: int) -> dict[str, Any]:
+    milestone = dict(raw_milestone) if isinstance(raw_milestone, dict) else {}
+    if milestone.get("waves") is not None or milestone.get("tasks") is not None:
+        raise ValueError("MILESTONE_WAVES_AND_TASKS_NOT_ALLOWED_IN_V1")
+
+    milestone_id_raw = milestone.get("milestone_id", milestone.get("id", ""))
+    title = _coerce_text(milestone.get("title")) or f"Milestone {fallback_index}"
+    milestone_id = _slug_token(milestone_id_raw, f"milestone-{fallback_index}")
+
+    raw_phases = milestone.get("phases")
+    if not isinstance(raw_phases, list) or not raw_phases:
+        raise ValueError(f"MILESTONE_PHASES_REQUIRED: milestone_id={milestone_id}")
+
+    phases: list[dict[str, Any]] = []
+    seen_phase_ids: set[str] = set()
+    for index, raw_phase in enumerate(raw_phases, start=1):
+        normalized_phase = normalize_phase(raw_phase, fallback_index=index, milestone_seed=milestone_id)
+        phase_id = normalized_phase["phase_id"]
+        if phase_id in seen_phase_ids:
+            raise ValueError(f"DUPLICATE_PHASE_ID: {phase_id}")
+        seen_phase_ids.add(phase_id)
+        phases.append(normalized_phase)
+
+    return {
+        "milestone_id": milestone_id,
+        "title": title,
+        "objective": _coerce_text(milestone.get("objective")),
+        "success_criteria": _coerce_text_list(milestone.get("success_criteria")),
+        "phases": phases,
+    }
+
+
+def normalize_planning_payload(payload: dict[str, Any], *, current_planning: dict[str, Any]) -> dict[str, Any]:
+    seed = payload.get("planning")
+    seed = seed if isinstance(seed, dict) else payload
+
+    detail_level = _coerce_text(seed.get("detail_level", DETAIL_LEVEL)) or DETAIL_LEVEL
+    if detail_level != DETAIL_LEVEL:
+        raise ValueError(f"UNSUPPORTED_DETAIL_LEVEL: {detail_level}")
+
+    raw_milestones = seed.get("milestones")
+    if not isinstance(raw_milestones, list) or not raw_milestones:
+        raise ValueError("PLANNER_MILESTONES_REQUIRED")
+
+    milestones: list[dict[str, Any]] = []
+    seen_milestones: set[str] = set()
+    for index, raw_milestone in enumerate(raw_milestones, start=1):
+        milestone = normalize_milestone(raw_milestone, fallback_index=index)
+        milestone_id = milestone["milestone_id"]
+        if milestone_id in seen_milestones:
+            raise ValueError(f"DUPLICATE_MILESTONE_ID: {milestone_id}")
+        seen_milestones.add(milestone_id)
+        milestones.append(milestone)
+
+    created_at = _coerce_text(current_planning.get("created_at")) or utc_now()
+    return {
+        "version": 1,
+        "status": "complete",
+        "detail_level": detail_level,
+        "decomposition_pending": True,
+        "created_at": created_at,
+        "updated_at": utc_now(),
+        "summary": _coerce_text(seed.get("summary")),
+        "assumptions": _coerce_text_list(seed.get("assumptions")),
+        "milestones": milestones,
+    }
+
+
+def discover_flow(args: argparse.Namespace, project_root: Path, data: dict[str, Any]) -> dict[str, Any]:
+    ensure_planner_prerequisites(data)
+    fuzzy_results = run_fuzzy_queries(args, project_root)
+
+    return {
+        "status": "ok",
+        "mode": "greenfield",
+        "action": "discover",
+        "project_root": str(project_root),
+        "context": summarize_context(data),
+        "fuzzy_context": fuzzy_results,
+    }
+
+
+def complete_flow(args: argparse.Namespace, project_root: Path, data: dict[str, Any]) -> dict[str, Any]:
+    ensure_planner_prerequisites(data)
+    payload = parse_payload(args, project_root)
+
+    planning_seed = data.get("planning")
+    planning_seed = planning_seed if isinstance(planning_seed, dict) else {}
+    normalized = normalize_planning_payload(payload, current_planning=planning_seed)
+    data["planning"] = normalized
+
+    data, found = set_workflow_item_status(
+        data,
+        item_id="task-roadmap-planning",
+        status="complete",
+        cadence_dir_exists=True,
+    )
+    if not found:
+        raise ValueError("WORKFLOW_ITEM_NOT_FOUND: task-roadmap-planning")
+
+    data = reconcile_workflow_state(data, cadence_dir_exists=True)
+    save_state(project_root, data)
+
+    milestones = normalized.get("milestones")
+    milestones = milestones if isinstance(milestones, list) else []
+    phase_count = sum(
+        len(milestone.get("phases", []))
+        for milestone in milestones
+        if isinstance(milestone, dict) and isinstance(milestone.get("phases"), list)
+    )
+
+    return {
+        "status": "ok",
+        "mode": "greenfield",
+        "action": "complete",
+        "project_root": str(project_root),
+        "planning_summary": {
+            "detail_level": normalized.get("detail_level", DETAIL_LEVEL),
+            "milestone_count": len(milestones),
+            "phase_count": phase_count,
+            "decomposition_pending": bool(normalized.get("decomposition_pending", True)),
+        },
+        "next_route": data.get("workflow", {}).get("next_route", {}),
+    }
+
+
+def main() -> int:
+    args = parse_args()
+    explicit_project_root = args.project_root.strip() or None
+    try:
+        project_root, project_root_source = resolve_project_root(
+            script_dir=SCRIPT_DIR,
+            explicit_project_root=explicit_project_root,
+            require_cadence=True,
+            allow_hint=True,
+        )
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    write_project_root_hint(SCRIPT_DIR, project_root)
+    assert_expected_route(project_root)
+    data = load_state(project_root)
+
+    try:
+        if args.command == "discover":
+            response = discover_flow(args, project_root, data)
+        else:
+            response = complete_flow(args, project_root, data)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    response["project_root_source"] = project_root_source
+    print(json.dumps(response))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skill/scripts/scaffold-project.sh

@@ -29,7 +29,7 @@ else
         "brownfield-documentation-completed": false
     },
     "workflow": {
-        "schema_version": 5,
+        "schema_version": 6,
         "plan": [
             {
                 "id": "milestone-foundation",
@@ -105,6 +105,16 @@ else
                                             "skill_path": "skills/researcher/SKILL.md",
                                             "reason": "Ideation research agenda has not been completed yet."
                                         }
+                                    },
+                                    {
+                                        "id": "task-roadmap-planning",
+                                        "kind": "task",
+                                        "title": "Plan project roadmap",
+                                        "route": {
+                                            "skill_name": "planner",
+                                            "skill_path": "skills/planner/SKILL.md",
+                                            "reason": "Project roadmap planning has not been completed yet."
+                                        }
                                     }
                                 ]
                             }
@@ -154,6 +164,17 @@ else
             "handoff_required": false,
             "handoff_message": "Start a new chat and say \"continue research\"."
         }
+    },
+    "planning": {
+        "version": 1,
+        "status": "pending",
+        "detail_level": "",
+        "decomposition_pending": true,
+        "created_at": "",
+        "updated_at": "",
+        "summary": "",
+        "assumptions": [],
+        "milestones": []
     }
 }
 JSON

package/skill/scripts/workflow_state.py

@@ -12,10 +12,11 @@ from typing import Any
 
 from ideation_research import ensure_ideation_research_defaults
 
-WORKFLOW_SCHEMA_VERSION = 5
+WORKFLOW_SCHEMA_VERSION = 6
 VALID_STATUSES = {"pending", "in_progress", "complete", "blocked", "skipped"}
 COMPLETED_STATUSES = {"complete", "skipped"}
 LEGACY_PRESERVE_STATUSES = {"in_progress", "blocked", "skipped"}
+PLANNING_STATUSES = {"pending", "in_progress", "complete", "skipped"}
 
 ROUTE_KEYS = {"skill_name", "skill_path", "reason"}
 DEFAULT_ROUTE_BY_ITEM_ID = {
@@ -49,6 +50,11 @@ DEFAULT_ROUTE_BY_ITEM_ID = {
         "skill_path": "skills/researcher/SKILL.md",
         "reason": "Ideation research agenda has not been completed yet.",
     },
+    "task-roadmap-planning": {
+        "skill_name": "planner",
+        "skill_path": "skills/planner/SKILL.md",
+        "reason": "Project roadmap planning has not been completed yet.",
+    },
 }
 
 DERIVED_WORKFLOW_KEYS = {
@@ -126,6 +132,12 @@ def default_workflow_plan() -> list[dict[str, Any]]:
                                     "title": "Research ideation agenda",
                                     "route": DEFAULT_ROUTE_BY_ITEM_ID["task-research"],
                                 },
+                                {
+                                    "id": "task-roadmap-planning",
+                                    "kind": "task",
+                                    "title": "Plan project roadmap",
+                                    "route": DEFAULT_ROUTE_BY_ITEM_ID["task-roadmap-planning"],
+                                },
                             ],
                         }
                     ],
@@ -149,6 +161,17 @@ def default_data() -> dict[str, Any]:
         },
         "project-details": {},
         "ideation": ensure_ideation_research_defaults({}),
+        "planning": {
+            "version": 1,
+            "status": "pending",
+            "detail_level": "",
+            "decomposition_pending": True,
+            "created_at": "",
+            "updated_at": "",
+            "summary": "",
+            "assumptions": [],
+            "milestones": [],
+        },
         "workflow": {
             "schema_version": WORKFLOW_SCHEMA_VERSION,
             "plan": default_workflow_plan(),
@@ -222,6 +245,7 @@ def _normalize_plan(plan: Any) -> list[dict[str, Any]]:
     _ensure_brownfield_intake_task(normalized)
     _ensure_brownfield_documentation_task(normalized)
     _ensure_research_task(normalized)
+    _ensure_roadmap_planning_task(normalized)
     return normalized
 
 
@@ -418,6 +442,57 @@ def _ensure_research_task(plan: list[dict[str, Any]]) -> None:
         plan.append(deepcopy(research_task))
 
 
+def _ensure_roadmap_planning_task(plan: list[dict[str, Any]]) -> None:
+    if _find_item_by_id(plan, "task-roadmap-planning") is not None:
+        return
+
+    planning_task = _normalize_item(
+        {
+            "id": "task-roadmap-planning",
+            "kind": "task",
+            "title": "Plan project roadmap",
+            "route": DEFAULT_ROUTE_BY_ITEM_ID["task-roadmap-planning"],
+        },
+        "task-roadmap-planning",
+    )
+
+    def inject_after_research(items: list[dict[str, Any]]) -> bool:
+        for item in items:
+            children = item.get("children", [])
+            if not isinstance(children, list):
+                continue
+
+            for index, child in enumerate(children):
+                if not isinstance(child, dict):
+                    continue
+                if child.get("id") == "task-research":
+                    children.insert(index + 1, deepcopy(planning_task))
+                    return True
+
+            if inject_after_research(children):
+                return True
+        return False
+
+    if inject_after_research(plan):
+        return
+
+    # Fallback for custom plans lacking task-research; append to first actionable container.
+    def append_to_first_container(items: list[dict[str, Any]]) -> bool:
+        for item in items:
+            children = item.get("children", [])
+            if not isinstance(children, list):
+                continue
+            if children and all(isinstance(child, dict) and not child.get("children") for child in children):
+                children.append(deepcopy(planning_task))
+                return True
+            if append_to_first_container(children):
+                return True
+        return False
+
+    if not append_to_first_container(plan):
+        plan.append(deepcopy(planning_task))
+
+
 def _set_item_status(items: list[dict[str, Any]], item_id: str, status: str) -> bool:
     found = False
     for item in items:
@@ -515,6 +590,10 @@ def _collect_nodes(
 def _legacy_completion_map(data: dict[str, Any], *, cadence_dir_exists: bool) -> dict[str, bool]:
     state = data.get("state")
     state = state if isinstance(state, dict) else {}
+    planning = data.get("planning")
+    planning = planning if isinstance(planning, dict) else {}
+    planning_status = str(planning.get("status", "pending")).strip().lower()
+    planning_completed = planning_status in COMPLETED_STATUSES
     mode = _normalize_project_mode(state.get("project-mode", "unknown"))
     brownfield_completed = state.get("brownfield-intake-completed")
     if brownfield_completed is None:
@@ -529,6 +608,7 @@ def _legacy_completion_map(data: dict[str, Any], *, cadence_dir_exists: bool) ->
         "task-brownfield-documentation": bool(brownfield_doc_completed),
         "task-ideation": bool(state.get("ideation-completed", False)),
         "task-research": bool(state.get("research-completed", False)),
+        "task-roadmap-planning": bool(planning_completed),
     }
 
 
@@ -563,6 +643,7 @@ def _sync_legacy_flags_from_plan(data: dict[str, Any], plan: list[dict[str, Any]
     brownfield_doc_item = _find_item_by_id(plan, "task-brownfield-documentation")
     ideation_item = _find_item_by_id(plan, "task-ideation")
     research_item = _find_item_by_id(plan, "task-research")
+    planner_item = _find_item_by_id(plan, "task-roadmap-planning")
     mode = _normalize_project_mode(state.get("project-mode", "unknown"))
 
     if prerequisite_item is not None:
@@ -580,6 +661,18 @@ def _sync_legacy_flags_from_plan(data: dict[str, Any], plan: list[dict[str, Any]
     if research_item is not None:
         state["research-completed"] = _is_complete_status(_coerce_status(research_item.get("status")))
 
+    planning = data.get("planning")
+    planning = dict(planning) if isinstance(planning, dict) else {}
+    if planner_item is not None:
+        planner_status = _coerce_status(planner_item.get("status", "pending"))
+        if planner_status in PLANNING_STATUSES:
+            planning["status"] = planner_status
+        else:
+            planning["status"] = "pending"
+        if planning["status"] == "skipped":
+            planning["decomposition_pending"] = False
+    data["planning"] = planning
+
 
 def _normalize_project_mode(value: Any) -> str:
     mode = str(value).strip().lower()
@@ -591,7 +684,8 @@ def _normalize_project_mode(value: Any) -> str:
 def _apply_project_mode_status_overrides(plan: list[dict[str, Any]], *, project_mode: str) -> None:
     ideation_item = _find_item_by_id(plan, "task-ideation")
     brownfield_doc_item = _find_item_by_id(plan, "task-brownfield-documentation")
-    if ideation_item is None and brownfield_doc_item is None:
+    planner_item = _find_item_by_id(plan, "task-roadmap-planning")
+    if ideation_item is None and brownfield_doc_item is None and planner_item is None:
         return
 
     mode = _normalize_project_mode(project_mode)
@@ -600,6 +694,10 @@ def _apply_project_mode_status_overrides(plan: list[dict[str, Any]], *, project_
             current = _coerce_status(brownfield_doc_item.get("status", "pending"))
             if current == "pending":
                 brownfield_doc_item["status"] = "skipped"
+        if planner_item is not None:
+            current = _coerce_status(planner_item.get("status", "pending"))
+            if current == "skipped":
+                planner_item["status"] = "pending"
     elif mode == "brownfield":
         if ideation_item is not None:
             current = _coerce_status(ideation_item.get("status", "pending"))
@@ -609,6 +707,43 @@ def _apply_project_mode_status_overrides(plan: list[dict[str, Any]], *, project_
             current = _coerce_status(brownfield_doc_item.get("status", "pending"))
             if current == "skipped":
                 brownfield_doc_item["status"] = "pending"
+        if planner_item is not None:
+            current = _coerce_status(planner_item.get("status", "pending"))
+            if current == "pending":
+                planner_item["status"] = "skipped"
+    else:
+        if planner_item is not None:
+            current = _coerce_status(planner_item.get("status", "pending"))
+            if current == "pending":
+                planner_item["status"] = "skipped"
+
+
+def _ensure_planning_defaults(planning: Any) -> dict[str, Any]:
+    payload = dict(planning) if isinstance(planning, dict) else {}
+
+    status = str(payload.get("status", "pending")).strip().lower()
+    if status not in PLANNING_STATUSES:
+        status = "pending"
+
+    assumptions = payload.get("assumptions")
+    if not isinstance(assumptions, list):
+        assumptions = []
+
+    milestones = payload.get("milestones")
+    if not isinstance(milestones, list):
+        milestones = []
+
+    return {
+        "version": 1,
+        "status": status,
+        "detail_level": str(payload.get("detail_level", "")).strip(),
+        "decomposition_pending": bool(payload.get("decomposition_pending", True)),
+        "created_at": str(payload.get("created_at", "")).strip(),
+        "updated_at": str(payload.get("updated_at", "")).strip(),
+        "summary": str(payload.get("summary", "")).strip(),
+        "assumptions": assumptions,
+        "milestones": milestones,
+    }
 
 
 def _build_node_ref(node: dict[str, Any]) -> dict[str, Any]:
@@ -751,6 +886,7 @@ def reconcile_workflow_state(data: dict[str, Any], *, cadence_dir_exists: bool)
     if "ideation" not in data or not isinstance(data.get("ideation"), dict):
         data["ideation"] = {}
     data["ideation"] = ensure_ideation_research_defaults(data.get("ideation"))
+    data["planning"] = _ensure_planning_defaults(data.get("planning"))
 
     workflow_seed = data.get("workflow")
     workflow_seed = dict(workflow_seed) if isinstance(workflow_seed, dict) else {}

package/skill/skills/planner/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: planner
+description: Create a greenfield project roadmap from cadence ideation and research by producing high-level milestones and phases only. Use when Cadence route points to planner after research is complete.
+---
+
+# Planner
+
+1. Run shared skill entry gates once at conversation start:
+   - `python3 ../../scripts/run-skill-entry-gate.py --require-cadence --assert-skill-name planner`
+   - Parse JSON and store `PROJECT_ROOT` from `project_root`, `CADENCE_SCRIPTS_DIR` from `cadence_scripts_dir`, and push mode from `repo_enabled` (`false` means local-only commits).
+   - Never manually edit `.cadence/cadence.json`; all Cadence state writes must go through Cadence scripts.
+2. Discover planning context directly from Cadence state:
+   - `python3 "$CADENCE_SCRIPTS_DIR/run-planner.py" --project-root "$PROJECT_ROOT" discover`
+3. Optionally enrich discovery with targeted fuzzy search when details are unclear:
+   - `python3 "$CADENCE_SCRIPTS_DIR/run-planner.py" --project-root "$PROJECT_ROOT" discover --fuzzy-query "<query>"`
+4. Use discovery output to draft a roadmap payload with this scope:
+   - Include overarching milestones and phases only.
+   - Do not include waves or tasks in this planner version.
+   - Keep `detail_level` as `milestone_phase_v1`.
+5. Present the proposed milestone/phase roadmap to the user and ask for confirmation.
+6. After confirmation, persist the finalized roadmap by piping payload JSON:
+   - `python3 "$CADENCE_SCRIPTS_DIR/run-planner.py" --project-root "$PROJECT_ROOT" complete --stdin`
+7. Verify persistence and route progression:
+   - `python3 "$CADENCE_SCRIPTS_DIR/read-workflow-state.py" --project-root "$PROJECT_ROOT"`
+8. At end of this successful skill conversation, run:
+   - `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope planner --checkpoint plan-created --paths .`
+9. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
+10. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.
+11. In normal user-facing updates, report roadmap outcomes without raw command traces or internal routing details unless explicitly requested.

package/skill/skills/planner/agents/openai.yaml

@@ -0,0 +1,15 @@
+interface:
+  display_name: "Planner"
+  short_description: "Generate high-level greenfield milestones and phases roadmap"
+  default_prompt: >-
+    Follow skills/planner/SKILL.md for exact planning behavior.
+    Run scripts/run-skill-entry-gate.py --require-cadence --assert-skill-name planner, then use its JSON output
+    for PROJECT_ROOT (project_root), CADENCE_SCRIPTS_DIR (cadence_scripts_dir), and push/local-only mode
+    (repo_enabled).
+    Never edit .cadence/cadence.json manually.
+    Gather context with scripts/run-planner.py --project-root "$PROJECT_ROOT" discover, then draft and confirm a
+    roadmap containing milestones and phases only (no waves/tasks) using detail_level milestone_phase_v1.
+    Persist with scripts/run-planner.py --project-root "$PROJECT_ROOT" complete --stdin.
+    Finalize from PROJECT_ROOT with scripts/finalize-skill-checkpoint.py --scope planner
+    --checkpoint plan-created --paths . (allow status=no_changes; treat failures as blocking).
+    Keep replies concise and hide internal traces unless asked.

package/skill/skills/researcher/SKILL.md

@@ -30,7 +30,10 @@ description: Execute ideation research agenda topics through dynamic multi-pass
    - `python3 "$CADENCE_SCRIPTS_DIR/run-research-pass.py" --project-root "$PROJECT_ROOT" complete --pass-id "<pass_id_from_start_output>" --stdin`
 7. Never start a second pass in the same conversation.
 8. If complete output returns `handoff_required=true`, end with this exact handoff line and stop: `Start a new chat and say "continue research".`
-9. If complete output returns `research_complete=true`, report that research phase is complete.
+9. If complete output returns `research_complete=true`:
+   - Run `python3 "$CADENCE_SCRIPTS_DIR/read-workflow-state.py" --project-root "$PROJECT_ROOT"` and inspect `route.skill_name`.
+   - If `route.skill_name` is `planner`, end with this exact handoff line: `Start a new chat and say "plan my project".`
+   - If workflow is complete, report that research and currently tracked workflow items are complete.
 10. At end of this successful skill conversation, run `cd "$PROJECT_ROOT" && python3 "$CADENCE_SCRIPTS_DIR/finalize-skill-checkpoint.py" --scope researcher --checkpoint research-pass-recorded --paths .`.
 11. If `finalize-skill-checkpoint.py` returns `status=no_changes`, continue without failure.
 12. If `finalize-skill-checkpoint.py` reports an error, stop and surface it verbatim.

package/skill/skills/researcher/agents/openai.yaml

@@ -10,5 +10,7 @@ interface:
     Run exactly one pass per chat: scripts/run-research-pass.py start, research only that pass's topics,
     then persist with scripts/run-research-pass.py complete. Do not run a second pass in the same chat.
     If more work remains, end with: Start a new chat and say "continue research".
+    If research is complete and route advances to planner, end with:
+    Start a new chat and say "plan my project".
     Finalize from PROJECT_ROOT with scripts/finalize-skill-checkpoint.py --scope researcher
     --checkpoint research-pass-recorded --paths . (allow status=no_changes; treat failures as blocking).

package/skill/tests/test_run_planner.py

@@ -0,0 +1,174 @@
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).resolve().parents[1] / "scripts"
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from workflow_state import default_data, set_workflow_item_status
+
+RUN_PLANNER_SCRIPT = SCRIPTS_DIR / "run-planner.py"
+
+
+def build_planner_ready_state() -> dict:
+    data = default_data()
+    state = data.setdefault("state", {})
+    state["project-mode"] = "greenfield"
+
+    for task_id in (
+        "task-scaffold",
+        "task-prerequisite-gate",
+        "task-brownfield-intake",
+        "task-ideation",
+        "task-research",
+    ):
+        data, found = set_workflow_item_status(
+            data,
+            item_id=task_id,
+            status="complete",
+            cadence_dir_exists=True,
+        )
+        if not found:
+            raise RuntimeError(f"Missing workflow item in fixture: {task_id}")
+
+    ideation = data.setdefault("ideation", {})
+    ideation["objective"] = "Ship an MVP"
+    ideation["core_outcome"] = "Deliver an end-to-end first release"
+    ideation["in_scope"] = ["core authentication", "dashboard"]
+    ideation["out_of_scope"] = ["native mobile"]
+    ideation["constraints"] = ["small team", "6-week target"]
+    ideation["risks"] = ["scope creep"]
+    ideation["success_signals"] = ["first 50 active users"]
+    return data
+
+
+class RunPlannerTests(unittest.TestCase):
+    def test_discover_returns_context(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            cadence_dir = project_root / ".cadence"
+            cadence_dir.mkdir(parents=True, exist_ok=True)
+            cadence_json = cadence_dir / "cadence.json"
+            cadence_json.write_text(json.dumps(build_planner_ready_state(), indent=4) + "\n", encoding="utf-8")
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(RUN_PLANNER_SCRIPT),
+                    "--project-root",
+                    str(project_root),
+                    "discover",
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr or result.stdout)
+            payload = json.loads(result.stdout)
+            self.assertEqual(payload.get("status"), "ok")
+            self.assertEqual(payload.get("action"), "discover")
+            self.assertEqual(payload.get("mode"), "greenfield")
+            self.assertIn("context", payload)
+            self.assertEqual(payload["context"]["planner_payload_contract"]["detail_level"], "milestone_phase_v1")
+
+    def test_complete_persists_milestone_phase_plan(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            cadence_dir = project_root / ".cadence"
+            cadence_dir.mkdir(parents=True, exist_ok=True)
+            cadence_json = cadence_dir / "cadence.json"
+            cadence_json.write_text(json.dumps(build_planner_ready_state(), indent=4) + "\n", encoding="utf-8")
+
+            planner_payload = {
+                "summary": "Roadmap for MVP and launch readiness.",
+                "milestones": [
+                    {
+                        "milestone_id": "milestone-mvp",
+                        "title": "MVP",
+                        "objective": "Release first usable product.",
+                        "success_criteria": ["Core flows complete", "Smoke tests pass"],
+                        "phases": [
+                            {
+                                "phase_id": "phase-foundations",
+                                "title": "Foundations",
+                                "objective": "Set up architecture and standards.",
+                                "deliverables": ["repo setup", "baseline app shell"],
+                                "exit_criteria": ["CI green"],
+                            }
+                        ],
+                    }
+                ],
+            }
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(RUN_PLANNER_SCRIPT),
+                    "--project-root",
+                    str(project_root),
+                    "complete",
+                    "--json",
+                    json.dumps(planner_payload),
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 0, msg=result.stderr or result.stdout)
+            payload = json.loads(result.stdout)
+            self.assertEqual(payload.get("status"), "ok")
+            self.assertEqual(payload.get("action"), "complete")
+            self.assertEqual(payload["planning_summary"]["milestone_count"], 1)
+            self.assertEqual(payload["planning_summary"]["phase_count"], 1)
+
+            updated = json.loads(cadence_json.read_text(encoding="utf-8"))
+            self.assertEqual(updated["planning"]["detail_level"], "milestone_phase_v1")
+            self.assertEqual(updated["planning"]["status"], "complete")
+            self.assertEqual(updated["workflow"]["next_item"]["id"], "complete")
+
+    def test_complete_rejects_waves_in_v1_payload(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            project_root = Path(tmp_dir)
+            cadence_dir = project_root / ".cadence"
+            cadence_dir.mkdir(parents=True, exist_ok=True)
+            cadence_json = cadence_dir / "cadence.json"
+            cadence_json.write_text(json.dumps(build_planner_ready_state(), indent=4) + "\n", encoding="utf-8")
+
+            planner_payload = {
+                "summary": "Invalid payload with waves.",
+                "milestones": [
+                    {
+                        "title": "MVP",
+                        "waves": ["wave-1"],
+                        "phases": [{"title": "Phase 1"}],
+                    }
+                ],
+            }
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(RUN_PLANNER_SCRIPT),
+                    "--project-root",
+                    str(project_root),
+                    "complete",
+                    "--json",
+                    json.dumps(planner_payload),
+                ],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+
+            self.assertEqual(result.returncode, 2)
+            self.assertIn("MILESTONE_WAVES_AND_TASKS_NOT_ALLOWED_IN_V1", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skill/tests/test_workflow_state.py

@@ -29,9 +29,11 @@ class WorkflowStateStatusTests(unittest.TestCase):
         order = [child.get("id") for child in children if isinstance(child, dict)]
         self.assertIn("task-brownfield-intake", order)
         self.assertIn("task-brownfield-documentation", order)
+        self.assertIn("task-roadmap-planning", order)
         self.assertLess(order.index("task-prerequisite-gate"), order.index("task-brownfield-intake"))
         self.assertLess(order.index("task-brownfield-intake"), order.index("task-brownfield-documentation"))
         self.assertLess(order.index("task-brownfield-documentation"), order.index("task-ideation"))
+        self.assertLess(order.index("task-research"), order.index("task-roadmap-planning"))
 
     def test_brownfield_mode_routes_to_documenter_not_ideator(self) -> None:
         data = default_data()
@@ -101,6 +103,55 @@ class WorkflowStateStatusTests(unittest.TestCase):
         self.assertIsNotNone(intake)
         self.assertEqual(intake["status"], "complete")
 
+    def test_greenfield_routes_to_planner_after_research(self) -> None:
+        data = default_data()
+        state = data.setdefault("state", {})
+        state["project-mode"] = "greenfield"
+
+        for task_id in (
+            "task-scaffold",
+            "task-prerequisite-gate",
+            "task-brownfield-intake",
+            "task-ideation",
+            "task-research",
+        ):
+            data, found = set_workflow_item_status(
+                data,
+                item_id=task_id,
+                status="complete",
+                cadence_dir_exists=True,
+            )
+            self.assertTrue(found)
+
+        route = data["workflow"]["next_route"]
+        self.assertEqual(route.get("skill_name"), "planner")
+
+    def test_brownfield_skips_planner(self) -> None:
+        data = default_data()
+        state = data.setdefault("state", {})
+        state["project-mode"] = "brownfield"
+
+        for task_id in (
+            "task-scaffold",
+            "task-prerequisite-gate",
+            "task-brownfield-intake",
+            "task-brownfield-documentation",
+            "task-research",
+        ):
+            data, found = set_workflow_item_status(
+                data,
+                item_id=task_id,
+                status="complete",
+                cadence_dir_exists=True,
+            )
+            self.assertTrue(found)
+
+        updated = reconcile_workflow_state(data, cadence_dir_exists=True)
+        planner_task = find_item(updated["workflow"]["plan"], "task-roadmap-planning")
+        self.assertIsNotNone(planner_task)
+        self.assertEqual(planner_task["status"], "skipped")
+        self.assertEqual(updated["workflow"]["next_item"]["id"], "complete")
+
 
 if __name__ == "__main__":
     unittest.main()