refactor: split backend into harness (deerflow.*) and app (app.*) (#1131)

* refactor: extract shared utils to break harness→app cross-layer imports

Move _validate_skill_frontmatter to src/skills/validation.py and
CONVERTIBLE_EXTENSIONS + convert_file_to_markdown to src/utils/file_conversion.py.
This eliminates the two reverse dependencies from client.py (harness layer)
into gateway/routers/ (app layer), preparing for the harness/app package split.

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

* refactor: split backend/src into harness (deerflow.*) and app (app.*)

Physically split the monolithic backend/src/ package into two layers:

- **Harness** (`packages/harness/deerflow/`): publishable agent framework
  package with import prefix `deerflow.*`. Contains agents, sandbox, tools,
  models, MCP, skills, config, and all core infrastructure.

- **App** (`app/`): unpublished application code with import prefix `app.*`.
  Contains gateway (FastAPI REST API) and channels (IM integrations).

Key changes:
- Move 13 harness modules to packages/harness/deerflow/ via git mv
- Move gateway + channels to app/ via git mv
- Rename all imports: src.* → deerflow.* (harness) / app.* (app layer)
- Set up uv workspace with deerflow-harness as workspace member
- Update langgraph.json, config.example.yaml, all scripts, Docker files
- Add build-system (hatchling) to harness pyproject.toml
- Add PYTHONPATH=. to gateway startup commands for app.* resolution
- Update ruff.toml with known-first-party for import sorting
- Update all documentation to reflect new directory structure

Boundary rule enforced: harness code never imports from app.
All 429 tests pass. Lint clean.

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

* chore: add harness→app boundary check test and update docs

Add test_harness_boundary.py that scans all Python files in
packages/harness/deerflow/ and fails if any `from app.*` or
`import app.*` statement is found. This enforces the architectural
rule that the harness layer never depends on the app layer.

Update CLAUDE.md to document the harness/app split architecture,
import conventions, and the boundary enforcement test.

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

* feat: add config versioning with auto-upgrade on startup

When config.example.yaml schema changes, developers' local config.yaml
files can silently become outdated. This adds a config_version field and
auto-upgrade mechanism so breaking changes (like src.* → deerflow.*
renames) are applied automatically before services start.

- Add config_version: 1 to config.example.yaml
- Add startup version check warning in AppConfig.from_file()
- Add scripts/config-upgrade.sh with migration registry for value replacements
- Add `make config-upgrade` target
- Auto-run config-upgrade in serve.sh and start-daemon.sh before starting services
- Add config error hints in service failure messages

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

* fix comments

* fix: update src.* import in test_sandbox_tools_security to deerflow.*

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

* fix: handle empty config and search parent dirs for config.example.yaml

Address Copilot review comments on PR #1131:
- Guard against yaml.safe_load() returning None for empty config files
- Search parent directories for config.example.yaml instead of only
  looking next to config.yaml, fixing detection in common setups

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

* fix: correct skills root path depth and config_version type coercion

- loader.py: fix get_skills_root_path() to use 5 parent levels (was 3)
  after harness split, file lives at packages/harness/deerflow/skills/
  so parent×3 resolved to backend/packages/harness/ instead of backend/
- app_config.py: coerce config_version to int() before comparison in
  _check_config_version() to prevent TypeError when YAML stores value
  as string (e.g. config_version: "1")
- tests: add regression tests for both fixes

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

* fix: update test imports from src.* to deerflow.*/app.* after harness refactor

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

backend/packages/harness/deerflow/skills/__init__.py

@@ -0,0 +1,5 @@
+from .loader import get_skills_root_path, load_skills
+from .types import Skill
+from .validation import ALLOWED_FRONTMATTER_PROPERTIES, _validate_skill_frontmatter
+
+__all__ = ["load_skills", "get_skills_root_path", "Skill", "ALLOWED_FRONTMATTER_PROPERTIES", "_validate_skill_frontmatter"]

backend/packages/harness/deerflow/skills/loader.py

@@ -0,0 +1,98 @@
+import os
+from pathlib import Path
+
+from .parser import parse_skill_file
+from .types import Skill
+
+
+def get_skills_root_path() -> Path:
+    """
+    Get the root path of the skills directory.
+
+    Returns:
+        Path to the skills directory (deer-flow/skills)
+    """
+    # loader.py lives at packages/harness/deerflow/skills/loader.py — 5 parents up reaches backend/
+    backend_dir = Path(__file__).resolve().parent.parent.parent.parent.parent
+    # skills directory is sibling to backend directory
+    skills_dir = backend_dir.parent / "skills"
+    return skills_dir
+
+
+def load_skills(skills_path: Path | None = None, use_config: bool = True, enabled_only: bool = False) -> list[Skill]:
+    """
+    Load all skills from the skills directory.
+
+    Scans both public and custom skill directories, parsing SKILL.md files
+    to extract metadata. The enabled state is determined by the skills_state_config.json file.
+
+    Args:
+        skills_path: Optional custom path to skills directory.
+                     If not provided and use_config is True, uses path from config.
+                     Otherwise defaults to deer-flow/skills
+        use_config: Whether to load skills path from config (default: True)
+        enabled_only: If True, only return enabled skills (default: False)
+
+    Returns:
+        List of Skill objects, sorted by name
+    """
+    if skills_path is None:
+        if use_config:
+            try:
+                from deerflow.config import get_app_config
+
+                config = get_app_config()
+                skills_path = config.skills.get_skills_path()
+            except Exception:
+                # Fallback to default if config fails
+                skills_path = get_skills_root_path()
+        else:
+            skills_path = get_skills_root_path()
+
+    if not skills_path.exists():
+        return []
+
+    skills = []
+
+    # Scan public and custom directories
+    for category in ["public", "custom"]:
+        category_path = skills_path / category
+        if not category_path.exists() or not category_path.is_dir():
+            continue
+
+        for current_root, dir_names, file_names in os.walk(category_path):
+            # Keep traversal deterministic and skip hidden directories.
+            dir_names[:] = sorted(name for name in dir_names if not name.startswith("."))
+            if "SKILL.md" not in file_names:
+                continue
+
+            skill_file = Path(current_root) / "SKILL.md"
+            relative_path = skill_file.parent.relative_to(category_path)
+
+            skill = parse_skill_file(skill_file, category=category, relative_path=relative_path)
+            if skill:
+                skills.append(skill)
+
+    # Load skills state configuration and update enabled status
+    # NOTE: We use ExtensionsConfig.from_file() instead of get_extensions_config()
+    # to always read the latest configuration from disk. This ensures that changes
+    # made through the Gateway API (which runs in a separate process) are immediately
+    # reflected in the LangGraph Server when loading skills.
+    try:
+        from deerflow.config.extensions_config import ExtensionsConfig
+
+        extensions_config = ExtensionsConfig.from_file()
+        for skill in skills:
+            skill.enabled = extensions_config.is_skill_enabled(skill.name, skill.category)
+    except Exception as e:
+        # If config loading fails, default to all enabled
+        print(f"Warning: Failed to load extensions config: {e}")
+
+    # Filter by enabled status if requested
+    if enabled_only:
+        skills = [skill for skill in skills if skill.enabled]
+
+    # Sort by name for consistent ordering
+    skills.sort(key=lambda s: s.name)
+
+    return skills

backend/packages/harness/deerflow/skills/parser.py

@@ -0,0 +1,65 @@
+import re
+from pathlib import Path
+
+from .types import Skill
+
+
+def parse_skill_file(skill_file: Path, category: str, relative_path: Path | None = None) -> Skill | None:
+    """
+    Parse a SKILL.md file and extract metadata.
+
+    Args:
+        skill_file: Path to the SKILL.md file
+        category: Category of the skill ('public' or 'custom')
+
+    Returns:
+        Skill object if parsing succeeds, None otherwise
+    """
+    if not skill_file.exists() or skill_file.name != "SKILL.md":
+        return None
+
+    try:
+        content = skill_file.read_text(encoding="utf-8")
+
+        # Extract YAML front matter
+        # Pattern: ---\nkey: value\n---
+        front_matter_match = re.match(r"^---\s*\n(.*?)\n---\s*\n", content, re.DOTALL)
+
+        if not front_matter_match:
+            return None
+
+        front_matter = front_matter_match.group(1)
+
+        # Parse YAML front matter (simple key-value parsing)
+        metadata = {}
+        for line in front_matter.split("\n"):
+            line = line.strip()
+            if not line:
+                continue
+            if ":" in line:
+                key, value = line.split(":", 1)
+                metadata[key.strip()] = value.strip()
+
+        # Extract required fields
+        name = metadata.get("name")
+        description = metadata.get("description")
+
+        if not name or not description:
+            return None
+
+        license_text = metadata.get("license")
+
+        return Skill(
+            name=name,
+            description=description,
+            license=license_text,
+            skill_dir=skill_file.parent,
+            skill_file=skill_file,
+            relative_path=relative_path or Path(skill_file.parent.name),
+            category=category,
+            enabled=True,  # Default to enabled, actual state comes from config file
+        )
+
+    except Exception as e:
+        print(f"Error parsing skill file {skill_file}: {e}")
+        return None

backend/packages/harness/deerflow/skills/types.py

@@ -0,0 +1,53 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Skill:
+    """Represents a skill with its metadata and file path"""
+
+    name: str
+    description: str
+    license: str | None
+    skill_dir: Path
+    skill_file: Path
+    relative_path: Path  # Relative path from category root to skill directory
+    category: str  # 'public' or 'custom'
+    enabled: bool = False  # Whether this skill is enabled
+
+    @property
+    def skill_path(self) -> str:
+        """Returns the relative path from the category root (skills/{category}) to this skill's directory"""
+        path = self.relative_path.as_posix()
+        return "" if path == "." else path
+
+    def get_container_path(self, container_base_path: str = "/mnt/skills") -> str:
+        """
+        Get the full path to this skill in the container.
+
+        Args:
+            container_base_path: Base path where skills are mounted in the container
+
+        Returns:
+            Full container path to the skill directory
+        """
+        category_base = f"{container_base_path}/{self.category}"
+        skill_path = self.skill_path
+        if skill_path:
+            return f"{category_base}/{skill_path}"
+        return category_base
+
+    def get_container_file_path(self, container_base_path: str = "/mnt/skills") -> str:
+        """
+        Get the full path to this skill's main file (SKILL.md) in the container.
+
+        Args:
+            container_base_path: Base path where skills are mounted in the container
+
+        Returns:
+            Full container path to the skill's SKILL.md file
+        """
+        return f"{self.get_container_path(container_base_path)}/SKILL.md"
+
+    def __repr__(self) -> str:
+        return f"Skill(name={self.name!r}, description={self.description!r}, category={self.category!r})"

backend/packages/harness/deerflow/skills/validation.py

@@ -0,0 +1,85 @@
+"""Skill frontmatter validation utilities.
+
+Pure-logic validation of SKILL.md frontmatter — no FastAPI or HTTP dependencies.
+"""
+
+import re
+from pathlib import Path
+
+import yaml
+
+# Allowed properties in SKILL.md frontmatter
+ALLOWED_FRONTMATTER_PROPERTIES = {"name", "description", "license", "allowed-tools", "metadata", "compatibility", "version", "author"}
+
+
+def _validate_skill_frontmatter(skill_dir: Path) -> tuple[bool, str, str | None]:
+    """Validate a skill directory's SKILL.md frontmatter.
+
+    Args:
+        skill_dir: Path to the skill directory containing SKILL.md.
+
+    Returns:
+        Tuple of (is_valid, message, skill_name).
+    """
+    skill_md = skill_dir / "SKILL.md"
+    if not skill_md.exists():
+        return False, "SKILL.md not found", None
+
+    content = skill_md.read_text()
+    if not content.startswith("---"):
+        return False, "No YAML frontmatter found", None
+
+    # Extract frontmatter
+    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
+    if not match:
+        return False, "Invalid frontmatter format", None
+
+    frontmatter_text = match.group(1)
+
+    # Parse YAML frontmatter
+    try:
+        frontmatter = yaml.safe_load(frontmatter_text)
+        if not isinstance(frontmatter, dict):
+            return False, "Frontmatter must be a YAML dictionary", None
+    except yaml.YAMLError as e:
+        return False, f"Invalid YAML in frontmatter: {e}", None
+
+    # Check for unexpected properties
+    unexpected_keys = set(frontmatter.keys()) - ALLOWED_FRONTMATTER_PROPERTIES
+    if unexpected_keys:
+        return False, f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}", None
+
+    # Check required fields
+    if "name" not in frontmatter:
+        return False, "Missing 'name' in frontmatter", None
+    if "description" not in frontmatter:
+        return False, "Missing 'description' in frontmatter", None
+
+    # Validate name
+    name = frontmatter.get("name", "")
+    if not isinstance(name, str):
+        return False, f"Name must be a string, got {type(name).__name__}", None
+    name = name.strip()
+    if not name:
+        return False, "Name cannot be empty", None
+
+    # Check naming convention (hyphen-case: lowercase with hyphens)
+    if not re.match(r"^[a-z0-9-]+$", name):
+        return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)", None
+    if name.startswith("-") or name.endswith("-") or "--" in name:
+        return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens", None
+    if len(name) > 64:
+        return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters.", None
+
+    # Validate description
+    description = frontmatter.get("description", "")
+    if not isinstance(description, str):
+        return False, f"Description must be a string, got {type(description).__name__}", None
+    description = description.strip()
+    if description:
+        if "<" in description or ">" in description:
+            return False, "Description cannot contain angle brackets (< or >)", None
+        if len(description) > 1024:
+            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters.", None
+
+    return True, "Skill is valid!", name