raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills/__init__.py

@@ -0,0 +1,44 @@
+"""Skills module for RaiSE skill management.
+
+Skills are AI-executed process guides that leverage the RaiSE toolkit.
+This module provides:
+- Schema models for SKILL.md parsing
+- Parser for extracting frontmatter and body
+- Locator for finding skills in the codebase
+- Validator for checking skill compliance
+- Naming utilities for ontology compliance
+- Scaffold for generating new skills
+"""
+
+from __future__ import annotations
+
+from raise_cli.skills.locator import (
+    SkillLocator,
+    get_default_skill_dir,
+    list_skills,
+)
+from raise_cli.skills.parser import ParseError, parse_frontmatter, parse_skill
+from raise_cli.skills.schema import (
+    Skill,
+    SkillFrontmatter,
+    SkillHook,
+    SkillHookCommand,
+    SkillMetadata,
+)
+
+__all__ = [
+    # Schema
+    "Skill",
+    "SkillFrontmatter",
+    "SkillHook",
+    "SkillHookCommand",
+    "SkillMetadata",
+    # Parser
+    "ParseError",
+    "parse_frontmatter",
+    "parse_skill",
+    # Locator
+    "SkillLocator",
+    "get_default_skill_dir",
+    "list_skills",
+]

raise_cli/skills/locator.py

@@ -0,0 +1,141 @@
+"""Skill locator for finding and loading skills.
+
+Discovers skills in the IDE skill directory (e.g. .claude/skills/
+for Claude Code, .agent/skills/ for Antigravity) and provides
+methods for loading and organizing them.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+
+from raise_cli.config.agents import AgentConfig, get_agent_config
+from raise_cli.skills.parser import parse_skill
+from raise_cli.skills.schema import Skill
+
+
+def get_default_skill_dir(
+    project_root: Path | None = None,
+    *,
+    agent_config: AgentConfig | None = None,
+) -> Path:
+    """Get the default skill directory path.
+
+    Args:
+        project_root: Project root directory. Defaults to current directory.
+        agent_config: Agent configuration. Defaults to Claude.
+
+    Returns:
+        Path to the agent's skill directory.
+    """
+    root = project_root or Path.cwd()
+    config = agent_config or get_agent_config()
+    skills_dir = config.skills_dir or ".claude/skills"
+    return root / skills_dir
+
+
+class SkillLocator:
+    """Locates and loads skills from a skill directory.
+
+    Typical usage:
+        locator = SkillLocator()
+        skills = locator.load_all_skills()
+        grouped = locator.group_by_lifecycle(skills)
+    """
+
+    def __init__(self, skill_dir: Path | None = None) -> None:
+        """Initialize the locator.
+
+        Args:
+            skill_dir: Path to skill directory. Defaults to .claude/skills/.
+        """
+        self.skill_dir = skill_dir or get_default_skill_dir()
+
+    def find_skill_dirs(self) -> list[Path]:
+        """Find all skill directories containing SKILL.md.
+
+        Returns:
+            List of paths to skill directories, sorted by name.
+        """
+        if not self.skill_dir.exists():
+            return []
+
+        dirs: list[Path] = []
+        for item in self.skill_dir.iterdir():
+            if item.is_dir() and (item / "SKILL.md").exists():
+                dirs.append(item)
+
+        return sorted(dirs, key=lambda p: p.name)
+
+    def load_skill(self, name: str) -> Skill | None:
+        """Load a skill by name.
+
+        Args:
+            name: Skill name (directory name).
+
+        Returns:
+            Parsed Skill object, or None if not found.
+        """
+        skill_path = self.skill_dir / name / "SKILL.md"
+        if not skill_path.exists():
+            return None
+
+        return parse_skill(skill_path)
+
+    def load_all_skills(self) -> list[Skill]:
+        """Load all skills from the skill directory.
+
+        Returns:
+            List of parsed Skill objects, sorted by name.
+        """
+        skills: list[Skill] = []
+        for skill_dir in self.find_skill_dirs():
+            skill_path = skill_dir / "SKILL.md"
+            try:
+                skill = parse_skill(skill_path)
+                skills.append(skill)
+            except Exception:
+                # Skip skills that fail to parse
+                continue
+
+        return skills
+
+    def group_by_lifecycle(self, skills: list[Skill]) -> dict[str, list[Skill]]:
+        """Group skills by their lifecycle.
+
+        Args:
+            skills: List of skills to group.
+
+        Returns:
+            Dictionary mapping lifecycle name to list of skills.
+        """
+        grouped: dict[str, list[Skill]] = defaultdict(list)
+        for skill in skills:
+            lifecycle = skill.lifecycle or "unknown"
+            grouped[lifecycle].append(skill)
+
+        return dict(grouped)
+
+
+def list_skills(
+    skill_dir: Path | None = None,
+    project_root: Path | None = None,
+    *,
+    agent_config: AgentConfig | None = None,
+) -> list[Skill]:
+    """Convenience function to list all skills.
+
+    Args:
+        skill_dir: Direct path to skill directory.
+        project_root: Project root (resolves via agent_config).
+        agent_config: Agent configuration. Defaults to Claude.
+
+    Returns:
+        List of parsed Skill objects.
+    """
+    if skill_dir is None and project_root is not None:
+        skill_dir = get_default_skill_dir(project_root, agent_config=agent_config)
+
+    locator = SkillLocator(skill_dir)
+    return locator.load_all_skills()

raise_cli/skills/name_checker.py

@@ -0,0 +1,199 @@
+"""Skill name checker for ontology compliance.
+
+Checks proposed skill names against:
+- {domain}-{action} naming pattern
+- Existing skill conflicts
+- CLI command conflicts (PAT-132)
+- Known lifecycle domains
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, Field
+
+from raise_cli.skills.locator import SkillLocator, get_default_skill_dir
+
+# Pattern for {domain}-{action} naming convention
+NAMING_PATTERN = re.compile(r"^[a-z]+-[a-z]+(-[a-z]+)*$")
+
+# RaiSE namespace prefix for distributed skills
+RAI_PREFIX = "rai-"
+
+# Known lifecycle domains
+KNOWN_LIFECYCLES = {
+    "session",
+    "epic",
+    "story",
+    "discover",
+    "skill",
+    "research",
+    "debug",
+    "framework",
+    "project",
+    "docs",
+}
+
+# CLI commands that conflict with skill names (PAT-132)
+# Format: {domain: [actions]} for {domain}-{action} pattern
+CLI_COMMANDS = {
+    "memory": ["build", "query", "emit-pattern", "emit-calibration"],
+    "skill": ["list", "validate", "scaffold", "check-name"],
+    "profile": ["show", "update"],
+    "session": ["start", "close"],
+    "discover": ["scan", "drift", "status"],
+    "init": [],  # init is a standalone command
+}
+
+
+class NameCheckResult(BaseModel):
+    """Result of checking a skill name."""
+
+    name: str = Field(description="The name that was checked")
+    valid_pattern: bool = Field(description="Whether name follows {domain}-{action}")
+    no_skill_conflict: bool = Field(
+        description="Whether no existing skill has this name"
+    )
+    no_cli_conflict: bool = Field(description="Whether no CLI command has this name")
+    known_lifecycle: bool = Field(description="Whether domain is a known lifecycle")
+    conflicting_skill: str | None = Field(
+        default=None, description="Name of conflicting skill if any"
+    )
+    conflicting_command: str | None = Field(
+        default=None, description="CLI command that conflicts if any"
+    )
+    suggestions: list[str] = Field(
+        default_factory=lambda: [], description="Positioning suggestions"
+    )
+
+    @property
+    def is_valid(self) -> bool:
+        """Name is valid if pattern OK, no skill conflict, and no CLI conflict."""
+        return self.valid_pattern and self.no_skill_conflict and self.no_cli_conflict
+
+
+def _check_pattern(name: str) -> bool:
+    """Check if name follows {domain}-{action} pattern."""
+    return bool(NAMING_PATTERN.match(name))
+
+
+def _check_skill_conflict(
+    name: str, existing_names: set[str]
+) -> tuple[bool, str | None]:
+    """Check for conflict with existing skills."""
+    if name in existing_names:
+        return False, name
+    return True, None
+
+
+def _check_cli_conflict(name: str) -> tuple[bool, str | None]:
+    """Check for conflict with CLI commands."""
+    parts = name.split("-")
+    if len(parts) < 2:
+        return True, None
+
+    domain = parts[0]
+    action = "-".join(parts[1:])  # Handle multi-part actions like "emit-pattern"
+
+    # Check if this matches a CLI command
+    if domain in CLI_COMMANDS:
+        cli_actions = CLI_COMMANDS[domain]
+        if action in cli_actions:
+            return False, f"{domain} {action}"
+        # Also check if domain alone is a command (like "init")
+        if not cli_actions and domain == name:
+            return False, domain
+
+    return True, None
+
+
+def _strip_rai_prefix(name: str) -> str:
+    """Strip rai- namespace prefix if present."""
+    if name.startswith(RAI_PREFIX):
+        return name[len(RAI_PREFIX) :]
+    return name
+
+
+def _check_lifecycle(name: str) -> bool:
+    """Check if domain is a known lifecycle."""
+    unprefixed = _strip_rai_prefix(name)
+    parts = unprefixed.split("-")
+    if parts:
+        domain = parts[0]
+        return domain in KNOWN_LIFECYCLES
+    return False
+
+
+def _get_suggestions(
+    name: str, existing_skills: list[str], known_lifecycle: bool
+) -> list[str]:
+    """Generate positioning suggestions."""
+    suggestions: list[str] = []
+
+    unprefixed = _strip_rai_prefix(name)
+    parts = unprefixed.split("-")
+    if len(parts) < 2:
+        return suggestions
+
+    domain = parts[0]
+
+    # Find related skills in same domain (check both prefixed and unprefixed)
+    related = sorted(
+        [s for s in existing_skills if _strip_rai_prefix(s).startswith(f"{domain}-")]
+    )
+
+    if related:
+        # Suggest positioning relative to existing skills
+        if known_lifecycle:
+            suggestions.append(f"Related {domain} skills: {', '.join(related)}")
+    elif known_lifecycle:
+        suggestions.append(f"First skill in '{domain}' lifecycle")
+
+    if not known_lifecycle:
+        suggestions.append(
+            f"Domain '{domain}' is not a standard lifecycle "
+            f"(known: {', '.join(sorted(KNOWN_LIFECYCLES))})"
+        )
+
+    return suggestions
+
+
+def check_name(name: str) -> NameCheckResult:
+    """Check a proposed skill name against ontology patterns.
+
+    Args:
+        name: Proposed skill name.
+
+    Returns:
+        NameCheckResult with validation results and suggestions.
+    """
+    # Check pattern
+    valid_pattern = _check_pattern(name)
+
+    # Get existing skills
+    skill_dir = get_default_skill_dir()
+    locator = SkillLocator(skill_dir)
+    existing_skills = locator.find_skill_dirs()
+    existing_names = {s.name for s in existing_skills}
+
+    # Check conflicts
+    no_skill_conflict, conflicting_skill = _check_skill_conflict(name, existing_names)
+    no_cli_conflict, conflicting_command = _check_cli_conflict(name)
+
+    # Check lifecycle
+    known_lifecycle = _check_lifecycle(name)
+
+    # Generate suggestions
+    suggestions = _get_suggestions(name, sorted(existing_names), known_lifecycle)
+
+    return NameCheckResult(
+        name=name,
+        valid_pattern=valid_pattern,
+        no_skill_conflict=no_skill_conflict,
+        no_cli_conflict=no_cli_conflict,
+        known_lifecycle=known_lifecycle,
+        conflicting_skill=conflicting_skill,
+        conflicting_command=conflicting_command,
+        suggestions=suggestions,
+    )

raise_cli/skills/parser.py

@@ -0,0 +1,145 @@
+"""Parser for SKILL.md files.
+
+Extracts YAML frontmatter and markdown body from skill files,
+converting them into structured Skill objects.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, cast
+
+import yaml
+
+from raise_cli.skills.schema import (
+    Skill,
+    SkillFrontmatter,
+    SkillHook,
+    SkillHookCommand,
+    SkillMetadata,
+)
+
+
+class ParseError(Exception):
+    """Error parsing a skill file."""
+
+    pass
+
+
+# Regex to match YAML frontmatter (--- at start, content, --- to close)
+# Handles empty frontmatter (---\n---) and content with or without trailing newline
+FRONTMATTER_PATTERN = re.compile(
+    r"^---[ \t]*\n(.*?)^---[ \t]*\n?",
+    re.DOTALL | re.MULTILINE,
+)
+
+
+def parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:
+    """Extract YAML frontmatter and body from markdown content.
+
+    Args:
+        content: Raw markdown content with YAML frontmatter.
+
+    Returns:
+        Tuple of (frontmatter dict, body string).
+
+    Raises:
+        ParseError: If frontmatter is missing, unclosed, or invalid YAML.
+    """
+    # Check if content starts with ---
+    if not content.startswith("---"):
+        raise ParseError("No YAML frontmatter found (must start with ---)")
+
+    # Find the closing ---
+    match = FRONTMATTER_PATTERN.match(content)
+    if not match:
+        # Check if there's an unclosed frontmatter
+        # Look for --- at start of a line (not just anywhere in content)
+        lines = content.split("\n")
+        closing_markers = sum(1 for line in lines[1:] if line.strip() == "---")
+        if closing_markers == 0:
+            raise ParseError("Unclosed frontmatter (missing closing ---)")
+        raise ParseError("No YAML frontmatter found")
+
+    yaml_content = match.group(1)
+    body = content[match.end() :]
+
+    # Parse YAML
+    frontmatter: dict[str, Any] = {}
+    try:
+        raw_yaml = yaml.safe_load(yaml_content)
+        if isinstance(raw_yaml, dict):
+            frontmatter = cast(dict[str, Any], raw_yaml)
+    except yaml.YAMLError as e:
+        raise ParseError(f"Invalid YAML in frontmatter: {e}") from e
+
+    return frontmatter, body
+
+
+def _parse_hooks(raw_hooks: dict[str, Any] | None) -> dict[str, list[SkillHook]] | None:
+    """Parse hooks from raw frontmatter dict."""
+    if not raw_hooks:
+        return None
+
+    result: dict[str, list[SkillHook]] = {}
+    for hook_name, hook_list in raw_hooks.items():
+        parsed_hooks: list[SkillHook] = []
+        for hook_entry in hook_list:
+            commands: list[SkillHookCommand] = []
+            for cmd in hook_entry.get("hooks", []):
+                commands.append(
+                    SkillHookCommand(
+                        type=cmd.get("type", "command"),
+                        command=cmd.get("command", ""),
+                    )
+                )
+            parsed_hooks.append(SkillHook(hooks=commands))
+        result[hook_name] = parsed_hooks
+
+    return result
+
+
+def _parse_frontmatter_to_model(raw: dict[str, Any]) -> SkillFrontmatter:
+    """Convert raw frontmatter dict to SkillFrontmatter model."""
+    metadata = None
+    if "metadata" in raw and raw["metadata"]:
+        metadata = SkillMetadata.from_raw(raw["metadata"])
+
+    hooks = _parse_hooks(raw.get("hooks"))
+
+    return SkillFrontmatter(
+        name=raw.get("name", ""),
+        description=raw.get("description", ""),
+        license=raw.get("license"),
+        metadata=metadata,
+        hooks=hooks,
+    )
+
+
+def parse_skill(path: str | Path) -> Skill:
+    """Parse a SKILL.md file into a Skill object.
+
+    Args:
+        path: Path to the SKILL.md file.
+
+    Returns:
+        Parsed Skill object.
+
+    Raises:
+        ParseError: If file not found or parsing fails.
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise ParseError(f"Skill file not found: {path}")
+
+    content = path.read_text(encoding="utf-8")
+    raw_frontmatter, body = parse_frontmatter(content)
+    frontmatter = _parse_frontmatter_to_model(raw_frontmatter)
+
+    return Skill(
+        frontmatter=frontmatter,
+        body=body,
+        path=str(path),
+    )