rai-cli 2.0.0a1__py3-none-any.whl

rai_cli/skills/scaffold.py

@@ -0,0 +1,185 @@
+"""Skill scaffolding for creating new skills.
+
+Generates new skill directories with properly structured SKILL.md files
+following the RaiSE skill template.
+"""
+
+from __future__ import annotations
+
+from textwrap import dedent
+
+from pydantic import BaseModel, Field
+
+from rai_cli.skills.locator import get_default_skill_dir
+
+# Mapping from domain prefix to lifecycle
+DOMAIN_TO_LIFECYCLE = {
+    "session": "session",
+    "epic": "epic",
+    "story": "story",
+    "discover": "discovery",
+    "skill": "meta",
+    "research": "utility",
+    "debug": "utility",
+    "framework": "meta",
+}
+
+
+class ScaffoldResult(BaseModel):
+    """Result of scaffolding a skill."""
+
+    created: bool = Field(description="Whether the skill was created")
+    path: str | None = Field(default=None, description="Path to created skill")
+    error: str | None = Field(default=None, description="Error message if failed")
+
+
+def _infer_lifecycle(name: str) -> str:
+    """Infer lifecycle from skill name domain."""
+    parts = name.split("-")
+    if parts:
+        domain = parts[0]
+        return DOMAIN_TO_LIFECYCLE.get(domain, "utility")
+    return "utility"
+
+
+def _generate_skill_content(
+    name: str,
+    lifecycle: str,
+    prerequisites: str | None,
+    next_skill: str | None,
+) -> str:
+    """Generate SKILL.md content from template."""
+    # Extract title from name (e.g., story-validate -> Story Validate)
+    title = " ".join(word.capitalize() for word in name.split("-"))
+
+    # Build prerequisites and next strings
+    prereq_str = prerequisites or ""
+    next_str = next_skill or ""
+
+    # Determine frequency based on lifecycle
+    frequency_map = {
+        "session": "per-session",
+        "epic": "per-epic",
+        "story": "per-story",
+        "discovery": "per-project",
+        "utility": "on-demand",
+        "meta": "on-demand",
+    }
+    frequency = frequency_map.get(lifecycle, "on-demand")
+
+    content = dedent(f"""\
+        ---
+        name: {name}
+        description: >
+          [TODO: Add description of what this skill does]
+
+        license: MIT
+
+        metadata:
+          raise.work_cycle: {lifecycle}
+          raise.frequency: {frequency}
+          raise.fase: ""
+          raise.prerequisites: "{prereq_str}"
+          raise.next: "{next_str}"
+          raise.gate: ""
+          raise.adaptable: "true"
+          raise.version: "1.0.0"
+        ---
+
+        # {title}
+
+        ## Purpose
+
+        [TODO: Describe the purpose of this skill]
+
+        ## Context
+
+        **When to use:**
+        - [TODO: Add trigger conditions]
+
+        **When to skip:**
+        - [TODO: Add skip conditions]
+
+        **Inputs required:**
+        - [TODO: Add required inputs]
+
+        **Output:**
+        - [TODO: Add expected outputs]
+
+        ## Steps
+
+        ### Step 1: [TODO: Step Name]
+
+        [TODO: Describe what to do in this step]
+
+        ```bash
+        # Example command
+        ```
+
+        **Verification:** [TODO: How to verify this step succeeded]
+
+        ## Output
+
+        | Item | Destination |
+        |------|-------------|
+        | [TODO] | [TODO] |
+
+        ## Notes
+
+        [TODO: Add any additional notes]
+
+        ## References
+
+        - Previous: `/{prereq_str if prereq_str else "[none]"}`
+        - Next: `/{next_str if next_str else "[none]"}`
+    """)
+
+    return content
+
+
+def scaffold_skill(
+    name: str,
+    lifecycle: str | None = None,
+    after: str | None = None,
+    before: str | None = None,
+) -> ScaffoldResult:
+    """Scaffold a new skill with proper structure.
+
+    Args:
+        name: Skill name (e.g., 'story-validate').
+        lifecycle: Lifecycle category. If not specified, inferred from name.
+        after: Skill that should come before this one (prerequisites).
+        before: Skill that should come after this one (next).
+
+    Returns:
+        ScaffoldResult with creation status and path or error.
+    """
+    # Get or create skill directory
+    skill_dir = get_default_skill_dir()
+    if not skill_dir.exists():
+        skill_dir.mkdir(parents=True)
+
+    # Check if skill already exists
+    skill_path = skill_dir / name
+    if skill_path.exists():
+        return ScaffoldResult(
+            created=False,
+            error=f"Skill '{name}' already exists at {skill_path}",
+        )
+
+    # Infer lifecycle if not specified
+    if lifecycle is None:
+        lifecycle = _infer_lifecycle(name)
+
+    # Generate content
+    content = _generate_skill_content(name, lifecycle, after, before)
+
+    # Create skill directory and file
+    skill_path.mkdir(parents=True, exist_ok=True)
+    skill_file = skill_path / "SKILL.md"
+    skill_file.write_text(content)
+
+    return ScaffoldResult(
+        created=True,
+        path=str(skill_file),
+    )

rai_cli/skills/schema.py

@@ -0,0 +1,130 @@
+"""Pydantic models for SKILL.md frontmatter and structure.
+
+These models define the schema for RaiSE skills, enabling:
+- Parsing of SKILL.md YAML frontmatter
+- Validation of skill structure
+- Type-safe access to skill metadata
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SkillMetadata(BaseModel):
+    """Metadata for a RaiSE skill.
+
+    Maps from YAML frontmatter with 'raise.' prefix to clean attributes.
+    """
+
+    work_cycle: str = Field(
+        description="Lifecycle: session, epic, story, discovery, utility, meta"
+    )
+    version: str = Field(description="Semantic version of the skill")
+    frequency: str | None = Field(
+        default=None, description="How often invoked: per-session, per-epic, etc."
+    )
+    fase: str | None = Field(default=None, description="Phase number or 'meta'")
+    prerequisites: str | None = Field(
+        default=None, description="Skills that must run before this one"
+    )
+    next: str | None = Field(
+        default=None, description="Skill that typically follows this one"
+    )
+    gate: str | None = Field(default=None, description="Validation gate for this skill")
+    adaptable: bool = Field(
+        default=True, description="Whether skill can be adapted by mastery level"
+    )
+
+    @classmethod
+    def from_raw(cls, raw: dict[str, Any]) -> SkillMetadata:
+        """Parse metadata from raw YAML dict with 'raise.' prefix.
+
+        Args:
+            raw: Dictionary with keys like 'raise.work_cycle', 'raise.version', etc.
+
+        Returns:
+            SkillMetadata instance with cleaned attributes.
+        """
+        # Strip 'raise.' prefix and convert to clean dict
+        cleaned: dict[str, Any] = {}
+        for key, value in raw.items():
+            if key.startswith("raise."):
+                clean_key = key[6:]  # Remove 'raise.' prefix
+                # Handle boolean conversion
+                if clean_key == "adaptable":
+                    if isinstance(value, str):
+                        value = value.lower() == "true"
+                cleaned[clean_key] = value
+
+        return cls(**cleaned)
+
+
+class SkillHookCommand(BaseModel):
+    """A single hook command in a skill."""
+
+    type: str = Field(description="Hook type: 'command'")
+    command: str = Field(description="Shell command to execute")
+
+
+class SkillHook(BaseModel):
+    """A hook configuration with nested commands."""
+
+    hooks: list[SkillHookCommand] = Field(
+        default_factory=lambda: [], description="List of hook commands"
+    )
+
+
+class SkillFrontmatter(BaseModel):
+    """YAML frontmatter for a SKILL.md file.
+
+    This is the structured data at the top of each skill file,
+    containing name, description, metadata, and hooks.
+    """
+
+    name: str = Field(description="Skill name in {domain}-{action} format")
+    description: str = Field(description="Brief description of the skill")
+    license: str | None = Field(default=None, description="License (typically MIT)")
+    metadata: SkillMetadata | None = Field(
+        default=None, description="RaiSE-specific metadata"
+    )
+    hooks: dict[str, list[SkillHook]] | None = Field(
+        default=None, description="Claude Code hooks (e.g., Stop)"
+    )
+
+
+class Skill(BaseModel):
+    """A complete RaiSE skill with frontmatter and markdown body.
+
+    Represents a parsed SKILL.md file with all its components.
+    """
+
+    frontmatter: SkillFrontmatter = Field(description="Parsed YAML frontmatter")
+    body: str = Field(description="Markdown content after frontmatter")
+    path: str = Field(description="Path to the SKILL.md file")
+
+    @property
+    def name(self) -> str:
+        """Shortcut to skill name."""
+        return self.frontmatter.name
+
+    @property
+    def version(self) -> str | None:
+        """Skill version from metadata, or None if no metadata."""
+        if self.frontmatter.metadata:
+            return self.frontmatter.metadata.version
+        return None
+
+    @property
+    def lifecycle(self) -> str | None:
+        """Skill lifecycle from metadata work_cycle."""
+        if self.frontmatter.metadata:
+            return self.frontmatter.metadata.work_cycle
+        return None
+
+    @property
+    def description(self) -> str:
+        """Shortcut to skill description."""
+        return self.frontmatter.description

rai_cli/skills/validator.py

@@ -0,0 +1,172 @@
+"""Validator for SKILL.md files.
+
+Validates skill structure against RaiSE schema including:
+- Required fields (name, description, metadata)
+- Required sections (Purpose, Context, Steps, Output)
+- Naming conventions ({domain}-{action})
+- Hook paths (warns if script not found)
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from rai_cli.skills.parser import ParseError, parse_skill
+from rai_cli.skills.schema import Skill
+
+
+class ValidationSeverity(Enum):
+    """Severity level for validation issues."""
+
+    ERROR = "error"
+    WARNING = "warning"
+
+
+class ValidationResult(BaseModel):
+    """Result of validating a skill file."""
+
+    path: str = Field(description="Path to the validated file")
+    errors: list[str] = Field(
+        default_factory=lambda: [], description="Validation errors"
+    )
+    warnings: list[str] = Field(
+        default_factory=lambda: [], description="Validation warnings"
+    )
+
+    @property
+    def is_valid(self) -> bool:
+        """Skill is valid if there are no errors (warnings OK)."""
+        return len(self.errors) == 0
+
+    @property
+    def error_count(self) -> int:
+        """Number of errors."""
+        return len(self.errors)
+
+    @property
+    def warning_count(self) -> int:
+        """Number of warnings."""
+        return len(self.warnings)
+
+
+# Required sections in skill body (case-insensitive match)
+REQUIRED_SECTIONS = ["Purpose", "Context", "Steps", "Output"]
+
+# Pattern for {domain}-{action} naming convention
+NAMING_PATTERN = re.compile(r"^[a-z]+-[a-z]+(-[a-z]+)*$")
+
+
+def _validate_required_fields(skill: Skill, errors: list[str]) -> None:
+    """Check required frontmatter fields."""
+    if not skill.frontmatter.name:
+        errors.append("Missing required field: name")
+
+    if not skill.frontmatter.description:
+        errors.append("Missing required field: description")
+
+    if not skill.frontmatter.metadata:
+        errors.append("Missing required field: metadata")
+
+
+def _validate_required_sections(skill: Skill, errors: list[str]) -> None:
+    """Check required sections in body."""
+    body_lower = skill.body.lower()
+
+    for section in REQUIRED_SECTIONS:
+        # Look for ## Section (case-insensitive)
+        pattern = f"## {section.lower()}"
+        if pattern not in body_lower:
+            errors.append(f"Missing required section: {section}")
+
+
+def _validate_naming_convention(skill: Skill, warnings: list[str]) -> None:
+    """Check naming follows {domain}-{action} pattern."""
+    name = skill.frontmatter.name
+    if name and not NAMING_PATTERN.match(name):
+        warnings.append(
+            f"Name '{name}' doesn't follow {{domain}}-{{action}} pattern (e.g., session-start)"
+        )
+
+
+def _validate_hook_paths(skill: Skill, warnings: list[str]) -> None:
+    """Check that hook script paths exist (warning only)."""
+    if not skill.frontmatter.hooks:
+        return
+
+    for hook_name, hook_list in skill.frontmatter.hooks.items():
+        for hook in hook_list:
+            for cmd in hook.hooks:
+                # Extract script path from command
+                # Handles: "RAISE_SKILL_NAME=x \"$CLAUDE_PROJECT_DIR\"/.raise/scripts/script.sh"
+                # Also handles: "/absolute/path/script.sh"
+                command = cmd.command
+
+                # Skip variable-based paths (we can't resolve them)
+                if "$" in command:
+                    continue
+
+                # Check if command looks like a path
+                if command.startswith("/"):
+                    path = Path(command.split()[0])  # Get first word (the path)
+                    if not path.exists():
+                        warnings.append(f"Hook '{hook_name}' script not found: {path}")
+
+
+def validate_skill(skill: Skill) -> ValidationResult:
+    """Validate a parsed Skill object.
+
+    Args:
+        skill: Parsed Skill object.
+
+    Returns:
+        ValidationResult with errors and warnings.
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    _validate_required_fields(skill, errors)
+    _validate_required_sections(skill, errors)
+    _validate_naming_convention(skill, warnings)
+    _validate_hook_paths(skill, warnings)
+
+    return ValidationResult(
+        path=skill.path,
+        errors=errors,
+        warnings=warnings,
+    )
+
+
+def validate_skill_file(path: str | Path) -> ValidationResult:
+    """Validate a SKILL.md file.
+
+    Args:
+        path: Path to the SKILL.md file.
+
+    Returns:
+        ValidationResult with errors and warnings.
+    """
+    path = Path(path)
+    str_path = str(path)
+
+    # Check file exists
+    if not path.exists():
+        return ValidationResult(
+            path=str_path,
+            errors=[f"File not found: {path}"],
+        )
+
+    # Try to parse
+    try:
+        skill = parse_skill(path)
+    except ParseError as e:
+        return ValidationResult(
+            path=str_path,
+            errors=[f"Parse error: {e}"],
+        )
+
+    # Validate the parsed skill
+    return validate_skill(skill)

rai_cli/skills_base/__init__.py

@@ -0,0 +1,59 @@
+"""Base skills package for distribution.
+
+This package contains the RaiSE skills that ship with rai-cli.
+On `rai init`, skill files are copied to the project's
+`.claude/skills/` directory (Claude Code) or equivalent IDE location.
+
+All skills use the `rai-` namespace prefix to prevent collision
+with user-created or third-party skills.
+
+Contents:
+    Session lifecycle:  rai-session-start, rai-session-close
+    Story lifecycle:    rai-story-start, rai-story-plan, rai-story-design,
+                        rai-story-implement, rai-story-review, rai-story-close
+    Epic lifecycle:     rai-epic-start, rai-epic-plan, rai-epic-design, rai-epic-close
+    Discovery:          rai-discover-start, rai-discover-scan,
+                        rai-discover-validate, rai-discover-document
+    Onboarding:         rai-project-create, rai-project-onboard
+    Tools:              rai-research, rai-debug
+
+Usage:
+    from importlib.resources import files
+
+    base_skills = files("rai_cli.skills_base")
+    session_start = base_skills / "rai-session-start" / "SKILL.md"
+    content = session_start.read_text()
+"""
+
+from __future__ import annotations
+
+__version__ = "2.1.0"
+
+DISTRIBUTABLE_SKILLS: list[str] = [
+    # Session lifecycle
+    "rai-session-start",
+    "rai-session-close",
+    # Story lifecycle
+    "rai-story-start",
+    "rai-story-plan",
+    "rai-story-design",
+    "rai-story-implement",
+    "rai-story-review",
+    "rai-story-close",
+    # Epic lifecycle
+    "rai-epic-start",
+    "rai-epic-plan",
+    "rai-epic-design",
+    "rai-epic-close",
+    # Discovery
+    "rai-discover-start",
+    "rai-discover-scan",
+    "rai-discover-validate",
+    "rai-discover-document",
+    # Onboarding
+    "rai-project-create",
+    "rai-project-onboard",
+    # Tools
+    "rai-research",
+    "rai-debug",
+]