Require explicit CrewAI project definitions (#6358)

* Require explicit CrewAI project definitions

JSON crews and declarative flows now resolve from `[tool.crewai]`
metadata instead of implicit filename discovery. This makes project type
selection deterministic, prevents stray `crew.json(c)` files from changing
CLI behavior, and centralizes definition path validation for run, install,
deploy validation, plotting, and memory reset paths.

`[tool.crewai].definition` must be a project-local file path. Absolute
paths, `~`, missing files, directories, and paths escaping the project root
are rejected so deploy and runtime commands use the same contract.

Breaking changes and migration paths:

* JSON crew projects are no longer discovered from `crew.json` or
  `crew.jsonc` alone. Add explicit metadata:

  ```toml
  [tool.crewai]
  type = "crew"
  definition = "crew.jsonc"
  ```

* Declarative flow projects must use a valid project-local definition path:

  ```toml
  [tool.crewai]
  type = "flow"
  definition = "flows/research.yaml"
  ```

* `Flow.from_definition(definition)` is removed. Use:

  ```python
  Flow.from_declaration(contents=definition)
  ```

* `FlowDefinition.to_json()` and `FlowDefinition.to_yaml()` are removed.
  Use `FlowDefinition.to_dict()` and serialize with the caller's JSON or
  YAML library.

* `FlowDefinition.from_dict()` is removed. Use:

  ```python
  FlowDefinition.from_declaration(contents=data)
  ```

* `FlowDefinition.json_schema()` is removed. Use Pydantic's schema API only
  where schema generation is intentionally needed:

  ```python
  FlowDefinition.model_json_schema(by_alias=True)
  ```

* `crewai_cli.run_crew.find_crew_json_file()` and `_has_json_crew()` are
  removed. Use `configured_project_json_crew()` or the shared
  `crewai_core.project.configured_project_definition("crew")` helper.

* `crewai reset-memories` now only loads JSON crews declared through
  `[tool.crewai].definition`, and invalid declared JSON crew definitions
  fail instead of silently falling back to classic crew discovery.

* Address code review comments

lib/cli/src/crewai_cli/create_json_crew.py

@@ -102,6 +102,7 @@ only-include = ["agents", "crew.jsonc", "tools", "knowledge", "skills"]
 
 [tool.crewai]
 type = "crew"
+definition = "crew.jsonc"
 """
 
 _GITIGNORE = """\

lib/cli/src/crewai_cli/deploy/validate.py

@@ -40,14 +40,18 @@ from typing import Any
 
 from crewai.project.json_loader import (
     JSONProjectValidationError,
-    find_crew_json_file,
     find_json_project_file,
     validate_crew_project,
 )
+from crewai_core.project import (
+    ProjectDefinitionError,
+    configured_project_definition,
+    get_crewai_project_config,
+    get_crewai_project_type,
+    read_toml,
+)
 from rich.console import Console
 
-from crewai_cli.utils import parse_toml
-
 
 console = Console()
 logger = logging.getLogger(__name__)
@@ -159,24 +163,16 @@ class DeployValidator:
 
     @property
     def _is_json_crew(self) -> bool:
-        """True for JSON crew projects, deferring to the declared type.
-
-        A flow project that also contains a crew.json(c) file validates as
-        the flow it declares in pyproject.toml, not as a JSON crew.
-        """
-        if find_crew_json_file(self.project_root) is None:
-            return False
+        """True for JSON crew projects with configured crew definitions."""
         pyproject_path = self.project_root / "pyproject.toml"
         if not pyproject_path.exists():
-            return True
+            return False
         try:
-            data = parse_toml(pyproject_path.read_text())
+            data = read_toml(pyproject_path)
         except Exception:
-            return True
-        declared_type: str | None = (
-            (data.get("tool") or {}).get("crewai", {}).get("type")
-        )
-        return declared_type != "flow"
+            return False
+        crewai_config = get_crewai_project_config(data)
+        return crewai_config.get("type") == "crew" and "definition" in crewai_config
 
     def run(self) -> list[ValidationResult]:
         """Run all checks. Later checks are skipped when earlier ones make
@@ -208,14 +204,32 @@ class DeployValidator:
 
     def _run_json_checks(self) -> list[ValidationResult]:
         """Validation suite for JSON-defined crew projects."""
-        crew_path = find_crew_json_file(self.project_root)
+        self._check_pyproject()
+        self._check_lockfile()
+
+        try:
+            crew_path = configured_project_definition(
+                "crew",
+                pyproject_data=self._pyproject,
+                project_root=self.project_root,
+            )
+        except ProjectDefinitionError as exc:
+            self._add(
+                Severity.ERROR,
+                "invalid_crew_definition",
+                "[tool.crewai] definition is invalid",
+                detail=str(exc),
+                hint=(
+                    "Set `[tool.crewai] definition` to a project-local JSON "
+                    "or JSONC crew file."
+                ),
+            )
+            return self.results
+
         if crew_path is None:
             return self.results
 
-        agents_dir = self.project_root / "agents"
-
-        self._check_pyproject()
-        self._check_lockfile()
+        agents_dir = crew_path.parent / "agents"
         agents_dir_ok = self._check_json_agents_dir(agents_dir)
 
         project = None
@@ -346,7 +360,7 @@ class DeployValidator:
             return False
 
         try:
-            self._pyproject = parse_toml(pyproject_path.read_text())
+            self._pyproject = read_toml(pyproject_path)
         except Exception as e:
             self._add(
                 Severity.ERROR,
@@ -374,9 +388,7 @@ class DeployValidator:
 
         self._project_name = name
         self._package_name = normalize_package_name(name)
-        self._is_flow = (self._pyproject.get("tool") or {}).get("crewai", {}).get(
-            "type"
-        ) == "flow"
+        self._is_flow = get_crewai_project_type(self._pyproject) == "flow"
         return True
 
     def _check_lockfile(self) -> None:

lib/cli/src/crewai_cli/install_crew.py

@@ -2,53 +2,35 @@ from pathlib import Path
 import subprocess
 
 import click
+from crewai_core.project import configured_project_definition, read_toml
 
 from crewai_cli.deploy.validate import normalize_package_name
-from crewai_cli.utils import build_env_with_all_tool_credentials, parse_toml
-
-
-def _find_json_crew_file(project_root: Path | None = None) -> Path | None:
-    """Return the JSON crew definition path when present."""
-    root = project_root or Path.cwd()
-    for filename in ("crew.jsonc", "crew.json"):
-        crew_path = root / filename
-        if crew_path.is_file():
-            return crew_path
-    return None
+from crewai_cli.utils import build_env_with_all_tool_credentials
 
 
 def _is_json_crew_project(project_root: Path | None = None) -> bool:
     """Return True for JSON crew projects that do not need package install."""
     root = project_root or Path.cwd()
-    if _find_json_crew_file(root) is None:
-        return False
-
     pyproject_path = root / "pyproject.toml"
     if not pyproject_path.is_file():
-        return True
+        return False
 
-    try:
-        pyproject = parse_toml(pyproject_path.read_text())
-    except Exception:
-        return True
-    if not isinstance(pyproject, dict):
-        return True
+    pyproject = read_toml(pyproject_path)
 
-    tool_config = pyproject.get("tool") or {}
-    crewai_config = tool_config.get("crewai") if isinstance(tool_config, dict) else None
-    declared_type = (
-        crewai_config.get("type") if isinstance(crewai_config, dict) else None
-    )
-    project_config = pyproject.get("project") or {}
-    project_name = (
-        project_config.get("name") if isinstance(project_config, dict) else None
-    )
-    if isinstance(project_name, str):
-        package_name = normalize_package_name(project_name)
-        if package_name and (root / "src" / package_name / "crew.py").is_file():
-            return False
+    if (
+        configured_project_definition(
+            "crew", pyproject_data=pyproject, project_root=root
+        )
+        is None
+    ):
+        return False
 
-    return declared_type != "flow"
+    project_name = pyproject.get("project", {}).get("name", "")
+    package_name = normalize_package_name(project_name)
+    if package_name and (root / "src" / package_name / "crew.py").is_file():
+        return False
+
+    return True
 
 
 # Be mindful about changing this.

lib/cli/src/crewai_cli/run_crew.py

@@ -1,23 +1,27 @@
 from __future__ import annotations
 
-from collections.abc import Callable
 from contextlib import AbstractContextManager, nullcontext
 import os
 from pathlib import Path
 import re
 import subprocess
 import sys
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any
 
 import click
 from crewai_core.constants import CREWAI_TRAINED_AGENTS_FILE_ENV
+from crewai_core.project import (
+    ProjectDefinitionError,
+    configured_project_definition,
+    get_crewai_project_type,
+    read_toml,
+)
 from packaging import version
 
 from crewai_cli.utils import (
     build_env_with_all_tool_credentials,
     enable_prompt_line_editing,
     is_dmn_mode_enabled,
-    read_toml,
 )
 from crewai_cli.version import get_crewai_tools_dependency, get_crewai_version
 
@@ -32,6 +36,7 @@ if TYPE_CHECKING:
 _INPUT_PLACEHOLDER_RE = re.compile(r"(?<!{){([A-Za-z_][A-Za-z0-9_\-]*)}(?!})")
 _CREWAI_CLI_RUNNER_PACKAGE_DIR_ENV = "CREWAI_CLI_RUNNER_PACKAGE_DIR"
 _CREWAI_RUNNER_SOURCE_DIR_ENV = "CREWAI_RUNNER_SOURCE_DIR"
+_CREWAI_JSON_CREW_DEFINITION_ENV = "CREWAI_JSON_CREW_DEFINITION"
 _FULL_CREWAI_INSTALL_MESSAGE = f"""\
 CrewAI CLI is installed without the `crewai` package required to run crews.
 
@@ -75,22 +80,20 @@ module_spec.loader.exec_module(module)
 
 from crewai_core.constants import CREWAI_TRAINED_AGENTS_FILE_ENV
 
+kwargs = {
+    "trained_agents_file": os.getenv(CREWAI_TRAINED_AGENTS_FILE_ENV),
+}
+if crew_definition := os.getenv("CREWAI_JSON_CREW_DEFINITION"):
+    kwargs["crew_path"] = crew_definition
+
 try:
-    module._run_json_crew(
-        trained_agents_file=os.getenv(CREWAI_TRAINED_AGENTS_FILE_ENV)
-    )
+    module._run_json_crew(**kwargs)
 except module.click.ClickException as exc:
     exc.show()
     raise SystemExit(exc.exit_code)
 """.strip()
 
 
-def _import_find_crew_json_file() -> Callable[[], Path | None]:
-    from crewai.project.json_loader import find_crew_json_file as _find_crew_json_file
-
-    return cast("Callable[[], Path | None]", _find_crew_json_file)
-
-
 def _is_missing_crewai_package(exc: ModuleNotFoundError) -> bool:
     return bool(exc.name and exc.name.startswith("crewai"))
 
@@ -99,32 +102,23 @@ def _full_crewai_install_error() -> click.ClickException:
     return click.ClickException(_FULL_CREWAI_INSTALL_MESSAGE)
 
 
-def find_crew_json_file() -> Path | None:
+def configured_project_json_crew(
+    pyproject_data: dict[str, Any] | None = None,
+    project_root: Path | None = None,
+) -> Path | None:
+    """Return the configured JSON crew definition for crew projects."""
+    root = project_root or Path.cwd()
+    if pyproject_data is None and not (root / "pyproject.toml").is_file():
+        return None
+
     try:
-        return _import_find_crew_json_file()()
-    except ModuleNotFoundError as exc:
-        if _is_missing_crewai_package(exc):
-            raise _full_crewai_install_error() from exc
-        raise
-
-
-def _has_json_crew() -> bool:
-    """Check if this is a JSON-defined crew project.
-
-    The project type declared in pyproject.toml wins: a flow project that
-    happens to contain a crew.json(c) file still runs as a flow. A missing
-    or unreadable pyproject means a bare JSON crew project.
-    """
-    if find_crew_json_file() is None:
-        return False
-    try:
-        pyproject_data = read_toml()
-    except Exception:
-        return True
-    declared_type: str | None = (
-        pyproject_data.get("tool", {}).get("crewai", {}).get("type")
-    )
-    return declared_type != "flow"
+        return configured_project_definition(
+            "crew",
+            pyproject_data=pyproject_data,
+            project_root=root,
+        )
+    except ProjectDefinitionError as exc:
+        raise click.UsageError(str(exc)) from exc
 
 
 def _extract_input_placeholders(text: str | None) -> set[str]:
@@ -199,7 +193,12 @@ def _json_loading_status(message: str) -> AbstractContextManager[Any]:
 
 
 def _load_json_crew(crew_path: Path) -> tuple[Any, dict[str, Any]]:
-    from crewai.project.crew_loader import load_crew
+    try:
+        from crewai.project.crew_loader import load_crew
+    except ModuleNotFoundError as exc:
+        if _is_missing_crewai_package(exc):
+            raise _full_crewai_install_error() from exc
+        raise
 
     return load_crew(crew_path)
 
@@ -262,7 +261,10 @@ def _run_json_crew_without_tui(crew_path: Path) -> Any:
     return result
 
 
-def _run_json_crew(trained_agents_file: str | None = None) -> Any:
+def _run_json_crew(
+    trained_agents_file: str | None = None,
+    crew_path: str | Path | None = None,
+) -> Any:
     """Load and run a JSON-defined crew."""
     from dotenv import load_dotenv
 
@@ -275,9 +277,13 @@ def _run_json_crew(trained_agents_file: str | None = None) -> Any:
     if trained_agents_file:
         os.environ[CREWAI_TRAINED_AGENTS_FILE_ENV] = trained_agents_file
 
-    crew_path = find_crew_json_file()
     if crew_path is None:
-        raise FileNotFoundError("No crew.jsonc or crew.json found")
+        crew_path = configured_project_json_crew()
+    if crew_path is None:
+        raise FileNotFoundError(
+            "No JSON crew definition configured in [tool.crewai].definition"
+        )
+    crew_path = Path(crew_path)
 
     if is_dmn_mode_enabled():
         return _run_json_crew_without_tui(crew_path)
@@ -391,10 +397,16 @@ def _json_crew_run_command(project_root: Path | None = None) -> list[str]:
     return ["uv", "run", "--no-sync", "python", "-c", _JSON_CREW_RUNNER_CODE]
 
 
-def _run_json_crew_in_project_env(trained_agents_file: str | None = None) -> Any:
+def _run_json_crew_in_project_env(
+    trained_agents_file: str | None = None,
+    crew_path: str | Path | None = None,
+) -> Any:
     """Run JSON crews from the project's uv-managed environment."""
     if not (Path.cwd() / "pyproject.toml").is_file():
-        return _run_json_crew(trained_agents_file=trained_agents_file)
+        return _run_json_crew(
+            trained_agents_file=trained_agents_file,
+            crew_path=crew_path,
+        )
 
     _install_json_crew_dependencies_if_needed()
 
@@ -405,6 +417,8 @@ def _run_json_crew_in_project_env(trained_agents_file: str | None = None) -> Any
         env[_CREWAI_RUNNER_SOURCE_DIR_ENV] = str(local_crewai_source_dir)
     if trained_agents_file:
         env[CREWAI_TRAINED_AGENTS_FILE_ENV] = trained_agents_file
+    if crew_path is not None:
+        env[_CREWAI_JSON_CREW_DEFINITION_ENV] = str(crew_path)
 
     try:
         subprocess.run(  # noqa: S603
@@ -557,13 +571,16 @@ def run_crew(
         )
         return
 
-    if _has_json_crew():
-        _run_json_crew_in_project_env(trained_agents_file=trained_agents_file)
+    pyproject_data = read_toml()
+    if json_crew_definition := configured_project_json_crew(pyproject_data):
+        _run_json_crew_in_project_env(
+            trained_agents_file=trained_agents_file,
+            crew_path=json_crew_definition,
+        )
         return
 
-    pyproject_data = read_toml()
     _warn_if_old_poetry_project(pyproject_data)
-    project_type = _get_project_type(pyproject_data)
+    project_type = get_crewai_project_type(pyproject_data)
 
     if project_type == "flow":
         _run_flow_project(
@@ -627,11 +644,6 @@ def _run_classic_crew_project(
     )
 
 
-def _get_project_type(pyproject_data: dict[str, Any]) -> str | None:
-    project_type = pyproject_data.get("tool", {}).get("crewai", {}).get("type")
-    return project_type if isinstance(project_type, str) else None
-
-
 def _warn_if_old_poetry_project(pyproject_data: dict[str, Any]) -> None:
     crewai_version = get_crewai_version()
     min_required_version = "0.71.0"

lib/cli/src/crewai_cli/run_declarative_flow.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
 import json
-from pathlib import Path, PureWindowsPath
+from pathlib import Path
 import subprocess
 from typing import Any
 
 import click
+from crewai_core.project import ProjectDefinitionError, configured_project_definition
 from pydantic import ValidationError
 
 from crewai_cli.utils import build_env_with_all_tool_credentials
@@ -105,80 +106,18 @@ def configured_project_declarative_flow(
     project_root: Path | None = None,
 ) -> Path | None:
     """Return the configured declarative flow source for flow projects."""
-    if pyproject_data is None:
-        try:
-            from crewai_cli.utils import read_toml
-
-            pyproject_data = read_toml()
-        except Exception:
-            return None
-
-    crewai_config = pyproject_data.get("tool", {}).get("crewai", {})
-    if crewai_config.get("type") != "flow":
+    root = project_root or Path.cwd()
+    if pyproject_data is None and not (root / "pyproject.toml").is_file():
         return None
-    definition = crewai_config.get("definition")
-    if not isinstance(definition, str):
-        return None
-    definition = definition.strip()
-    if not definition:
-        return None
-
-    return _resolve_project_definition_path(
-        definition=definition,
-        project_root=project_root or Path.cwd(),
-    )
-
-
-def _resolve_project_definition_path(definition: str, project_root: Path) -> Path:
-    definition_path = Path(definition)
-    windows_definition_path = PureWindowsPath(definition)
-
-    if definition.startswith("~"):
-        raise click.UsageError(
-            "[tool.crewai] definition must be a project-local path; "
-            f"got {definition!r}."
-        )
-
-    if definition_path.is_absolute() or windows_definition_path.is_absolute():
-        raise click.UsageError(
-            "[tool.crewai] definition must be relative to the project root; "
-            f"got {definition!r}."
-        )
 
     try:
-        root = project_root.resolve(strict=True)
-    except OSError as exc:
-        raise click.UsageError(
-            f"Invalid project root for [tool.crewai] definition: {exc}"
-        ) from exc
-
-    candidate = root / definition_path
-    try:
-        resolved_candidate = candidate.resolve(strict=False)
-    except OSError as exc:
-        raise click.UsageError(
-            f"Invalid [tool.crewai] definition path {definition!r}: {exc}"
-        ) from exc
-
-    if not resolved_candidate.is_relative_to(root):
-        raise click.UsageError(
-            "[tool.crewai] definition must resolve inside the project root; "
-            f"got {definition!r}."
+        return configured_project_definition(
+            "flow",
+            pyproject_data=pyproject_data,
+            project_root=root,
         )
-
-    if not resolved_candidate.exists():
-        raise click.UsageError(
-            "[tool.crewai] definition must point to an existing file; "
-            f"got {definition!r}."
-        )
-
-    if not resolved_candidate.is_file():
-        raise click.UsageError(
-            "[tool.crewai] definition must point to a regular file; "
-            f"got {definition!r}."
-        )
-
-    return resolved_candidate
+    except ProjectDefinitionError as exc:
+        raise click.UsageError(str(exc)) from exc
 
 
 def _execute_declarative_flow_command(command: list[str]) -> None: