deepmodel-dmx 0.1.0__py3-none-any.whl

deepmodel_dmx-0.1.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: deepmodel-dmx
+Version: 0.1.0
+Summary: AI SDLC MCP server — skills and rules for any AI IDE.
+License: AGPL-3.0
+License-File: LICENSE
+Keywords: ai,claude,cursor,mcp,sdlc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: python-frontmatter>=1.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: starlette>=0.40
+Provides-Extra: dev
+Requires-Dist: httpx2>=2.2.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: syrupy>=4; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: watch
+Requires-Dist: watchfiles>=0.21; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# dmx
+
+[![PyPI](https://img.shields.io/pypi/v/deepmodel-dmx)](https://pypi.org/project/deepmodel-dmx/)
+[![Test](https://github.com/deepmodel-ai/dmx/actions/workflows/test.yml/badge.svg)](https://github.com/deepmodel-ai/dmx/actions/workflows/test.yml)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
+
+The official implementation of the [AI SDLC](https://github.com/deepmodel-ai/ai-sdlc) — delivered as an MCP server for any AI IDE.
+
+`dmx` turns the AI SDLC framework into slash commands and always-apply engineering rules. Connect it to Cursor, Claude Code, GitHub Copilot, Antigravity, or any MCP-compatible IDE and get a structured, phase-gated AI engineering workflow out of the box.
+
+---
+
+## The workflow
+
+The [AI SDLC](https://github.com/deepmodel-ai/ai-sdlc) structures development around five phases with explicit developer control points. AI executes within each phase and stops. The developer drives every transition forward.
+
+![AI SDLC Phase Arc](https://raw.githubusercontent.com/deepmodel-ai/ai-sdlc/main/assets/phase-arc.drawio.svg)
+
+| Phase | What happens | dmx command |
+|---|---|---|
+| **Specify** | AI drafts a structured spec, surfaces ambiguity, asks Q&A. Developer answers. | `/dmx/create-ticket` |
+| **Plan** | AI generates a phased task list from the answered spec. Developer reviews. | `/dmx/plan` |
+| **Build** | AI implements one phase, stops, reports. Developer reviews and commits. Repeats. | `/dmx/implement-next-phase` |
+| **Validate** | Automated quality gate checks spec, security, coverage. AI drafts the PR body. | `/dmx/validate` · `/dmx/create-pr` |
+| **Ship** | Developer merges. AI tags the release and publishes. Developer confirms. | `/dmx/create-release` |
+
+> The model does not merge. It does not advance the workflow. It does not decide when the work is done.
+
+---
+
+## Quick start
+
+Add to your IDE's MCP config and restart:
+
+**Cursor** — `~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "dmx": {
+      "command": "uvx",
+      "args": ["--from", "deepmodel-dmx", "dmx", "serve"]
+    }
+  }
+}
+```
+
+**Claude Code** — `~/.claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dmx": {
+      "command": "uvx",
+      "args": ["--from", "deepmodel-dmx", "dmx", "serve"]
+    }
+  }
+}
+```
+
+**Antigravity** — `~/.gemini/config/mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dmx": {
+      "command": "uvx",
+      "args": ["--from", "deepmodel-dmx", "dmx", "serve"]
+    }
+  }
+}
+```
+
+**GitHub Copilot** — `.vscode/settings.json` (workspace) or user settings
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "dmx": {
+        "command": "uvx",
+        "args": ["--from", "deepmodel-dmx", "dmx", "serve"]
+      }
+    }
+  }
+}
+```
+
+Then run `/dmx-init` in your IDE to write always-apply rules and scaffold the `.dmx/` memory bank.
+
+---
+
+## `/dmx-init` walkthrough
+
+`/dmx-init` is the one-time project setup skill. It:
+
+1. Detects your workflow mode (feature branches vs. trunk) and ticketing system
+2. Auto-detects your GitHub remote and tech stack
+3. Writes `.dmx/config.md` with project context
+4. Scaffolds the `.dmx/` memory bank (architecture, decisions, style guide, etc.)
+5. Calls `detect_invoking_ide` and `setup_ide_rules` to write IDE-specific rule files
+6. Writes the always-apply persona rule so every future chat starts with the right context
+
+Safe to re-run — updates config without overwriting memory bank files that already have content.
+
+---
+
+## Skill catalog
+
+All `/dmx-*` commands are MCP prompts served live — no file writes, no installation beyond the MCP config.
+
+### Workflow
+
+| Skill | What it does |
+|---|---|
+| `/dmx/init` | One-time project setup: rules, memory bank, IDE config |
+| `/dmx/create-ticket` | Idea → ticket → branch → spec in one command |
+| `/dmx/derive-ticket` | Uncommitted changes → ticket → branch → derived spec |
+| `/dmx/plan` | Answered spec → phased `tasks.md` |
+| `/dmx/implement-next-phase` | Execute the next phase in `tasks.md`, stop |
+| `/dmx/implement-next-task` | Execute the next single task, stop |
+| `/dmx/validate` | Pre-PR quality gate: ticket, code, security |
+| `/dmx/create-branch` | Create a properly named branch, scaffold spec |
+| `/dmx/commit` | Conventional commit from staged diff |
+| `/dmx/create-pr` | Open PR with correct title + description |
+| `/dmx/draft-pr-description` | Generate PR body without opening the PR |
+| `/dmx/close-ticket` | Post-merge: close ticket, delete branch, archive |
+
+### Release
+
+| Skill | What it does |
+|---|---|
+| `/dmx/hotfix` | Create hotfix branch from master |
+| `/dmx/draft-release-note` | Generate release notes from merged PRs |
+| `/dmx/release-merge` | Open staging → master release gate PR |
+| `/dmx/create-release` | Tag and publish GitHub release |
+
+### Utilities
+
+| Skill | What it does |
+|---|---|
+| `/dmx/status` | Snapshot of in-progress tickets and open PRs |
+| `/dmx/sync-branch` | Rebase/merge base branch onto current branch |
+| `/dmx/update-memory` | Sync ticket learnings into memory bank |
+| `/dmx/review` | Code review: clarity, correctness, maintainability |
+| `/dmx/test` | Write tests that enable change |
+| `/dmx/docs` | Write clear, human-first documentation |
+| `/dmx/secure` | Security analysis — thinks like an attacker |
+
+---
+
+## CLI
+
+```
+dmx serve               # stdio transport (default, for IDE MCP config)
+dmx serve --http        # SSE transport on :8080 (team server / Docker)
+dmx serve --http --port 9000
+dmx serve --watch       # hot-reload on file change (requires watchfiles extra)
+dmx list-skills         # print all loaded skills
+dmx version
+```
+
+**Environment variables**
+
+| Variable | Purpose | Default |
+|---|---|---|
+| `PORT` | HTTP port | `8080` |
+| `DMX_SKILLS_DIR` | Override bundled skills directory | bundled |
+| `DMX_RULES_DIR` | Override bundled rules directory | bundled |
+| `DMX_IDE` | Force IDE detection (`cursor`, `claude`, `copilot`, `antigravity`, `agents`) | auto-detect |
+| `MCP_API_KEY` | Bearer token for HTTP auth | — |
+| `REQUIRE_API_KEY` | Enable HTTP bearer auth (`true`/`false`) | `false` |
+
+---
+
+## Requirements
+
+- Python 3.11+
+- `uv` (recommended) or any package manager that supports `uvx`
+
+---
+
+## License
+
+[AGPL-3.0](LICENSE) — free for open-source use. Commercial licensing available from [Deepmodel](https://deepmodel.ai).

deepmodel_dmx-0.1.0.dist-info/RECORD

@@ -0,0 +1,40 @@
+dmx/__init__.py,sha256=FKvXiNPIb80EWvfb4tDXc7EF0Miz4_oSDT8ir09hNTY,589
+dmx/_workflow_version.py,sha256=malbsQczStdMzjvVKYkOKic9SYuM6M_CUtzcrA3NFOQ,390
+dmx/catalog.py,sha256=j_LCH5joJjmt-qSE9d1c9Y7GW-JfuUJCZ1cNmoYIKx4,8832
+dmx/cli.py,sha256=QcLTVOByBkBmCPL_oiM0_JJVunsMoPafJUYMoM2xNec,5891
+dmx/exceptions.py,sha256=J6V73mXVLC9_OIogZBhL4DfPGPGSXInHBbPAsspABBI,1293
+dmx/http_auth.py,sha256=dxZhNGC4i76O_iA7w1Ru6lGvCCyxJsn9HD-cAmsjENo,1644
+dmx/server.py,sha256=9_Mfj7qVa2vNnHy6kWru6HB1m7XgzMdt65m4Bxh_g9w,8752
+dmx/tools.py,sha256=w3oR4oQdnkUfqN4N4cGSiuiGpQS5Om5QHaUS0Jo78Nc,9061
+dmx/ide/__init__.py,sha256=XIKMwOowWRpgAnrilOyI48s8dyIVgA5Z6-fADvM9fuw,291
+dmx/ide/detect.py,sha256=IjkXUBPQHlMwUi2FJtDZUQJTopRUCAgcNln-megwW78,3376
+dmx/ide/emitters.py,sha256=t66e9aj5pc6zIHGuVXt2plPnsShVtWe8OvKG9wls3Og,8508
+dmx/rules/system-prompt.md,sha256=MSojHRNpPcdqau3LKrA6BFEvXRk2PqCx-heogzZNaLg,5819
+dmx/skills/specialist/dmx-docs.md,sha256=TcbH6uDIVlEM_LImYmI_PZAJuQGL4Z-XNBxCMFRy_Tc,4935
+dmx/skills/specialist/dmx-review.md,sha256=6gSg9YFIinbCHzPsOQS3cezLPTwhV93MJhxvSgf1-5U,3496
+dmx/skills/specialist/dmx-secure.md,sha256=UQpp-ZZ2ogBOsnSRD9X9cXoBKI9spQueLotlxyAYrgY,4055
+dmx/skills/specialist/dmx-test.md,sha256=jZF52vzMHLgHkI3onJSiTrOmD005rkJTxnc5MZ5kbco,4104
+dmx/skills/utility/dmx-commit.md,sha256=9_RntB1eXTyiHFM5HjNAKKY5z9rlQ3NhQo7yfpB1vqc,6067
+dmx/skills/utility/dmx-create-branch.md,sha256=g9umv8jXxL5gF6tOpMtWSJAeK1uzns_SHbb6bPp8m1I,6926
+dmx/skills/utility/dmx-draft-pr-description.md,sha256=1_AoJv1TVxdQlwh56lVSuyy_LDfZFv5-F_1A4B_xfwM,6714
+dmx/skills/utility/dmx-status.md,sha256=U64WfRb1bigzMVroPx4FoKYEro8Q2G7vLdjbxZdvjB4,3315
+dmx/skills/utility/dmx-sync-branch.md,sha256=C0_nIIdKloDMeqQZf01fr75ZZXqlFd63s8xcUN90dZE,2582
+dmx/skills/utility/dmx-update-memory.md,sha256=DirSebAuRO3q7kUGrwOig6XlBv3oW6gK7TCxjBUfQcc,4089
+dmx/skills/workflow/0-init/dmx-init.md,sha256=PMeHwI2z7y67i_8PnsOXbQwK_3A-oj0bu_e-EnTynWc,11207
+dmx/skills/workflow/1-triage/dmx-create-ticket.md,sha256=z6h-haRgG0Bd0YmpThORQhUgMLlCjYadRazJef2epSk,9118
+dmx/skills/workflow/1-triage/dmx-derive-ticket.md,sha256=DjD9SDqtW0TFwoTTW-YIgh7V9BzqgCkOqOGZoJ-NVGs,8383
+dmx/skills/workflow/1-triage/dmx-hotfix.md,sha256=e0DHSiwhVBwd71O4Rzg6eRhnXA9xNZUAkw7JFz19DYI,4184
+dmx/skills/workflow/2-plan/dmx-plan.md,sha256=95Tr_iv2TTgJ4CdWcYbHsf2Z1-STeWXowMCi7Qvfafw,4875
+dmx/skills/workflow/3-build/dmx-implement-next-phase.md,sha256=Dl0uiMrCvbk-uH6u1KH6SOQS3zeKZfrzLZJcF-hohtQ,3585
+dmx/skills/workflow/3-build/dmx-implement-next-task.md,sha256=eqo8cV8gLSAPyulURBBM7erAHH3_gane2Tf3vJ4GTkE,3125
+dmx/skills/workflow/4-validate/dmx-validate.md,sha256=4yeTbO2SRAD5Q4koHC0d8JlnVmkh5Rhe1vTPvkVIAFc,6088
+dmx/skills/workflow/5-ship/dmx-close-ticket.md,sha256=E5vKt6Bun4hopg1dnGi1o7oO0iasuD7bY22XAUryEsc,6536
+dmx/skills/workflow/5-ship/dmx-create-pr.md,sha256=ClWDcgq7rVNLX_DqH0t2h4SqUXCgMxbdZcmx0ESJ9fM,4885
+dmx/skills/workflow/6-release/dmx-create-release.md,sha256=ufLqxoKmWObeic73ufzpeRfToTDkhKB6LxzJpLe7_kI,4021
+dmx/skills/workflow/6-release/dmx-draft-release-note.md,sha256=QGiEEaerOnG9bTpmPWr2QY29gdUqPfJMjr4AdlSDUtY,6102
+dmx/skills/workflow/6-release/dmx-release-merge.md,sha256=qGhrkBsL0j8Ig_qKoomWlMLwRB563Rur15Q7p2ZI4aM,5152
+deepmodel_dmx-0.1.0.dist-info/METADATA,sha256=Updtkyo7OfAsdgrZvxPnvQ6-wULNr5uLIJ8yjWzVMhk,7594
+deepmodel_dmx-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+deepmodel_dmx-0.1.0.dist-info/entry_points.txt,sha256=zC3IDbfwwSPWurk6bKz1oF8sAvGZ0U8JohQ8NZIDYqs,37
+deepmodel_dmx-0.1.0.dist-info/licenses/LICENSE,sha256=g_rT-ZAvrkFf4v_I3nAwt_RygoWN4M2nZ08l7405lvQ,1809
+deepmodel_dmx-0.1.0.dist-info/RECORD,,

deepmodel_dmx-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

deepmodel_dmx-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dmx = dmx.cli:main

deepmodel_dmx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,38 @@
+                                                                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can modify it, that
+you know you can do these rights, and that you have the freedom to use,
+share, and change the software.
+
+  Specifically, the GNU Affero General Public License is designed to
+ensure that anyone running a modified version of the software over a
+network can receive the source code for that version.
+
+  For the full license text, see: https://www.gnu.org/licenses/agpl-3.0.txt
+
+  Copyright (C) 2024 Deepmodel Inc.
+  All Rights Reserved under AGPL-3.0.
+
+  Additional permissions: Deepmodel Inc. retains the right to release
+  the software under different license terms (dual licensing). See
+  CLA.md for contributor terms.

dmx/__init__.py

@@ -0,0 +1,24 @@
+"""dmx — AI SDLC MCP server."""
+
+from __future__ import annotations
+
+from dmx.catalog import RuleDefinition, SkillArgument, SkillDefinition
+from dmx.exceptions import DmxError, EmitterError, IdeDetectionError, RuleLoadError, SkillLoadError
+from dmx.ide.emitters import IdeRuleFile
+from dmx.server import create_app
+
+__all__ = [
+    # Exceptions
+    "DmxError",
+    "EmitterError",
+    "IdeDetectionError",
+    "RuleLoadError",
+    "SkillLoadError",
+    # Data classes
+    "IdeRuleFile",
+    "RuleDefinition",
+    "SkillArgument",
+    "SkillDefinition",
+    # Factory
+    "create_app",
+]

dmx/_workflow_version.py

@@ -0,0 +1,10 @@
+"""Workflow version — independent of the package version.
+
+Bump this constant when skills or rules change in a way that requires
+developers to re-run ``/dmx/init`` to get current behaviour.
+
+Do NOT bump for: bug fixes, new IDE emitters, CLI changes, dependency updates.
+DO bump for: new or removed skills, system-prompt rewrites, rule restructuring.
+"""
+
+WORKFLOW_VERSION = "workflow-v1"

dmx/catalog.py

@@ -0,0 +1,260 @@
+"""Skill and rule catalog: load, parse, and template substitution."""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path  # noqa: TCH003 — used at runtime in rglob/stat calls
+from typing import Any, cast
+
+import frontmatter
+
+from dmx.exceptions import RuleLoadError, SkillLoadError
+
+__all__ = [
+    "ARG_NAME_RE",
+    "SLUG_RE",
+    "SkillArgument",
+    "SkillDefinition",
+    "RuleDefinition",
+    "load_skills",
+    "load_rules",
+    "substitute_args",
+]
+
+logger = logging.getLogger(__name__)
+
+SLUG_RE = re.compile(r"^[a-z0-9_-]+$")
+# Argument names must be valid Python identifiers (lowercase, underscores only).
+# Hyphens are intentionally excluded: argument names are template placeholders
+# and Python parameter names — hyphens are not valid in either context.
+ARG_NAME_RE = re.compile(r"^[a-z][a-z0-9_]*$")
+MAX_SKILL_BYTES = 256 * 1024  # 256 KiB
+
+
+@dataclass(frozen=True)
+class SkillArgument:
+    """A single argument accepted by a skill.
+
+    Attributes:
+        name: Argument name used in ``{{name}}`` template placeholders.
+        description: Human-readable description shown in IDE command palette.
+        required: Whether the argument must be provided at invocation time.
+    """
+
+    name: str
+    description: str = ""
+    required: bool = False
+
+
+@dataclass(frozen=True)
+class SkillDefinition:
+    """A fully parsed skill loaded from a Markdown file.
+
+    Attributes:
+        name: Slug from frontmatter ``name`` field; falls back to filename stem.
+        title: Display name shown in IDE command palette.
+        description: Short description shown in IDE command palette.
+        arguments: Tuple of accepted arguments.
+        body: Raw Markdown body with ``{{arg}}`` placeholders.
+    """
+
+    name: str
+    title: str
+    description: str
+    arguments: tuple[SkillArgument, ...] = field(default_factory=tuple)
+    body: str = ""
+
+
+@dataclass(frozen=True)
+class RuleDefinition:
+    """A fully parsed rule loaded from a Markdown file.
+
+    Attributes:
+        name: Slug from frontmatter ``name`` field; falls back to filename stem.
+        title: Display name.
+        description: Short description shown in IDE rule picker.
+        always_apply: Whether the rule is always injected into context.
+        globs: Optional file-pattern filter (Cursor ``.mdc`` / Claude paths).
+        ides: Target IDEs; empty tuple means all targets.
+        body: Raw Markdown rule body.
+    """
+
+    name: str
+    title: str
+    description: str = ""
+    always_apply: bool = True
+    globs: str | None = None
+    ides: tuple[str, ...] = field(default_factory=tuple)
+    body: str = ""
+
+
+def load_skills(directory: Path) -> tuple[SkillDefinition, ...]:
+    """Load all skill files from *directory* recursively.
+
+    Files that cannot be parsed are skipped with a warning; the rest are
+    returned. Files larger than ``MAX_SKILL_BYTES`` are also skipped.
+
+    Args:
+        directory: Root directory to scan with ``rglob("*.md")``.
+
+    Returns:
+        Tuple of parsed :class:`SkillDefinition` objects, sorted by name.
+    """
+    skills: list[SkillDefinition] = []
+    for path in directory.rglob("*.md"):
+        try:
+            skill = _parse_skill(path)
+        except SkillLoadError as exc:
+            logger.warning("skipping skill — %s", exc)
+            continue
+        if skill is not None:
+            skills.append(skill)
+    return tuple(sorted(skills, key=lambda s: s.name))
+
+
+def load_rules(directory: Path) -> tuple[RuleDefinition, ...]:
+    """Load all rule files from *directory* recursively.
+
+    Files that cannot be parsed are skipped with a warning.
+
+    Args:
+        directory: Root directory to scan with ``rglob("*.md")``.
+
+    Returns:
+        Tuple of parsed :class:`RuleDefinition` objects, sorted by name.
+    """
+    rules: list[RuleDefinition] = []
+    for path in directory.rglob("*.md"):
+        try:
+            rule = _parse_rule(path)
+        except RuleLoadError as exc:
+            logger.warning("skipping rule — %s", exc)
+            continue
+        if rule is not None:
+            rules.append(rule)
+    return tuple(sorted(rules, key=lambda r: r.name))
+
+
+def substitute_args(template: str, args: dict[str, str | None]) -> str:
+    """Substitute ``{{name}}`` placeholders in *template* with *args* values.
+
+    Unknown placeholders and those whose value is ``None`` resolve to an
+    empty string.
+
+    Args:
+        template: Markdown template containing ``{{name}}`` placeholders.
+        args: Mapping of argument name to value.
+
+    Returns:
+        Template with all placeholders resolved.
+    """
+
+    def _replace(match: re.Match[str]) -> str:
+        key = match.group(1).strip()
+        value = args.get(key)
+        return value if value is not None else ""
+
+    return re.sub(r"\{\{([^}]+)\}\}", _replace, template)
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _valid_arg_name(skill_name: str, arg_name: object) -> bool:
+    """Return True if *arg_name* is a valid skill argument name.
+
+    Argument names must be lowercase Python identifiers (letters, digits,
+    underscores; must start with a letter). Hyphens are rejected: they are
+    not valid Python identifiers and cannot be used as template placeholders
+    or function parameter names without conversion gymnastics.
+    """
+    if not isinstance(arg_name, str) or not ARG_NAME_RE.match(arg_name):
+        logger.warning(
+            "skill %r: argument name %r is invalid (must match %s) — skipping argument",
+            skill_name,
+            arg_name,
+            ARG_NAME_RE.pattern,
+        )
+        return False
+    return True
+
+
+def _parse_skill(path: Path) -> SkillDefinition | None:
+    """Parse a single skill file; return None and log a warning on failure."""
+    try:
+        if path.stat().st_size > MAX_SKILL_BYTES:
+            logger.warning("skill file exceeds size limit, skipping: %s", path)
+            return None
+
+        post = frontmatter.load(str(path))
+        name = str(post.metadata.get("name", path.stem))
+
+        if not SLUG_RE.match(name):
+            logger.warning("invalid skill name %r, skipping: %s", name, path)
+            return None
+
+        raw_args_value = post.metadata.get("arguments", [])
+        if not isinstance(raw_args_value, list):
+            logger.warning(
+                "skill %r: 'arguments' must be a list, got %s — ignoring arguments",
+                name,
+                type(raw_args_value).__name__,
+            )
+            raw_args_value = []
+        raw_args: list[dict[str, Any]] = cast("list[dict[str, Any]]", raw_args_value)
+        arguments = tuple(
+            SkillArgument(
+                name=str(arg["name"]),
+                description=str(arg.get("description", "")),
+                required=bool(arg.get("required", False)),
+            )
+            for arg in raw_args
+            if isinstance(arg, dict) and "name" in arg and _valid_arg_name(name, arg["name"])
+        )
+
+        return SkillDefinition(
+            name=name,
+            title=str(post.metadata.get("title", name)),
+            description=str(post.metadata.get("description", "")),
+            arguments=arguments,
+            body=post.content,
+        )
+    except Exception as exc:  # noqa: BLE001
+        raise SkillLoadError(f"failed to load skill at {path}: {exc}", path=str(path)) from exc
+
+
+def _parse_rule(path: Path) -> RuleDefinition | None:
+    """Parse a single rule file; return None and log a warning on failure."""
+    try:
+        post = frontmatter.load(str(path))
+        name = str(post.metadata.get("name", path.stem))
+
+        if not SLUG_RE.match(name):
+            logger.warning("invalid rule name %r, skipping: %s", name, path)
+            return None
+
+        raw_ides_value = post.metadata.get("ides", [])
+        # Normalize: YAML scalar string → list; e.g. `ides: cursor` → ["cursor"]
+        if isinstance(raw_ides_value, str):
+            raw_ides_value = [raw_ides_value]
+        raw_ides: list[str] = cast("list[str]", raw_ides_value or [])
+        ides = tuple(raw_ides)
+
+        globs_raw = post.metadata.get("globs")
+        globs: str | None = str(globs_raw) if globs_raw is not None else None
+
+        return RuleDefinition(
+            name=name,
+            title=str(post.metadata.get("title", name)),
+            description=str(post.metadata.get("description", "")),
+            always_apply=bool(post.metadata.get("alwaysApply", True)),
+            globs=globs,
+            ides=ides,
+            body=post.content,
+        )
+    except Exception as exc:  # noqa: BLE001
+        raise RuleLoadError(f"failed to load rule at {path}: {exc}", path=str(path)) from exc