raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills/scaffold.py

@@ -0,0 +1,212 @@
+"""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 raise_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]
+
+        ## Mastery Levels (ShuHaRi)
+
+        - **Shu**: [TODO: Beginner behavior]
+        - **Ha**: [TODO: Intermediate behavior]
+        - **Ri**: [TODO: Expert behavior]
+
+        ## Context
+
+        **When to use:** [TODO: Add trigger conditions]
+
+        **When to skip:** [TODO: Add skip conditions]
+
+        **Inputs:** [TODO: Add required inputs]
+
+        ## 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] |
+
+        ## Quality Checklist
+
+        - [ ] [TODO: Add verification items]
+
+        ## 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,
+    skill_set: str | None = None,
+    from_builtin: bool = False,
+) -> ScaffoldResult:
+    """Scaffold a new skill with proper structure.
+
+    When ``skill_set`` is provided, creates the skill in
+    ``.raise/skills/{skill_set}/{name}/`` instead of the default
+    IDE skill directory. When ``from_builtin`` is also True, copies
+    the existing deployed skill as a starting point. (S340.2)
+
+    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).
+        skill_set: Skill set name (e.g., 'my-team'). Creates in .raise/skills/{set}/.
+        from_builtin: Copy from deployed .claude/skills/{name}/ as starting point.
+
+    Returns:
+        ScaffoldResult with creation status and path or error.
+    """
+    from pathlib import Path
+
+    # Determine target directory
+    if skill_set is not None:
+        skill_dir = Path.cwd() / ".raise" / "skills" / skill_set
+    else:
+        skill_dir = get_default_skill_dir()
+    if not skill_dir.exists():
+        skill_dir.mkdir(parents=True)
+
+    # Check if skill already exists in target
+    skill_path = skill_dir / name
+    if skill_path.exists():
+        return ScaffoldResult(
+            created=False,
+            error=f"Skill '{name}' already exists at {skill_path}",
+        )
+
+    # "Customize builtin" mode: copy from deployed skill
+    if from_builtin and skill_set is not None:
+        deployed = get_default_skill_dir() / name / "SKILL.md"
+        if deployed.exists():
+            skill_path.mkdir(parents=True, exist_ok=True)
+            skill_file = skill_path / "SKILL.md"
+            skill_file.write_text(deployed.read_text(encoding="utf-8"), encoding="utf-8")
+            return ScaffoldResult(created=True, path=str(skill_file))
+        return ScaffoldResult(
+            created=False,
+            error=f"Builtin '{name}' not found at {deployed}",
+        )
+
+    # 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, encoding="utf-8")
+
+    return ScaffoldResult(
+        created=True,
+        path=str(skill_file),
+    )

raise_cli/skills/schema.py

@@ -0,0 +1,132 @@
+"""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"
+    )
+    output_type: str | None = Field(
+        default=None, description="Artifact type this skill produces (e.g., story-design)"
+    )
+
+    @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" and 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

raise_cli/skills/skillsets.py

@@ -0,0 +1,195 @@
+"""Skill set management — create, list, and diff skill sets.
+
+Skill sets live in ``.raise/skills/{name}/`` and contain skill directories
+with SKILL.md files. They overlay builtins when deployed with
+``rai init --skill-set``. (S340.4, RAISE-344)
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.resources import files
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from raise_cli.config.paths import get_raise_dir
+from raise_cli.onboarding.skill_manifest import compute_content_hash
+from raise_cli.onboarding.skills import copy_skill_tree
+
+logger = logging.getLogger(__name__)
+
+
+class CreateResult(BaseModel):
+    """Result of skill set creation."""
+
+    created: bool
+    name: str
+    path: str | None = None
+    skill_count: int = 0
+    error: str | None = None
+
+
+class SkillSetInfo(BaseModel):
+    """Info about an existing skill set."""
+
+    name: str
+    path: str
+    skill_count: int = 0
+
+
+class SkillSetDiff(BaseModel):
+    """Diff of a skill set against builtins."""
+
+    name: str
+    added: list[str] = Field(default_factory=list)
+    modified: list[str] = Field(default_factory=list)
+    unchanged: list[str] = Field(default_factory=list)
+
+
+def _skills_dir(project_root: Path) -> Path:
+    """Get the .raise/skills/ directory."""
+    return get_raise_dir(project_root) / "skills"
+
+
+def _count_skills(set_dir: Path) -> int:
+    """Count skill directories containing SKILL.md."""
+    if not set_dir.is_dir():
+        return 0
+    return sum(
+        1 for d in set_dir.iterdir()
+        if d.is_dir() and (d / "SKILL.md").exists()
+    )
+
+
+def create_skill_set(
+    name: str,
+    project_root: Path,
+    *,
+    empty: bool = False,
+) -> CreateResult:
+    """Create a new skill set directory, optionally from builtins.
+
+    Args:
+        name: Skill set name (e.g., "my-team").
+        project_root: Project root directory.
+        empty: If True, create empty directory. Otherwise copy all builtins.
+
+    Returns:
+        CreateResult with creation status.
+    """
+    from raise_cli.onboarding.skills import SkillScaffoldResult
+    from raise_cli.skills_base import DISTRIBUTABLE_SKILLS
+
+    set_dir = _skills_dir(project_root) / name
+
+    if set_dir.exists():
+        return CreateResult(
+            created=False,
+            name=name,
+            error=f"Skill set '{name}' already exists at {set_dir}",
+        )
+
+    set_dir.mkdir(parents=True)
+
+    if empty:
+        return CreateResult(created=True, name=name, path=str(set_dir), skill_count=0)
+
+    # Copy builtins
+    base = files("raise_cli.skills_base")
+    result = SkillScaffoldResult()
+    for skill_name in DISTRIBUTABLE_SKILLS:
+        source = base / skill_name
+        dest = set_dir / skill_name
+        copy_skill_tree(source, dest, result, overwrite=True)
+
+    return CreateResult(
+        created=True,
+        name=name,
+        path=str(set_dir),
+        skill_count=len(DISTRIBUTABLE_SKILLS),
+    )
+
+
+def list_skill_sets(project_root: Path) -> list[SkillSetInfo]:
+    """List all skill sets in .raise/skills/.
+
+    Args:
+        project_root: Project root directory.
+
+    Returns:
+        List of SkillSetInfo, sorted by name.
+    """
+    skills_root = _skills_dir(project_root)
+    if not skills_root.is_dir():
+        return []
+
+    sets: list[SkillSetInfo] = []
+    for item in sorted(skills_root.iterdir()):
+        if not item.is_dir():
+            continue
+        sets.append(SkillSetInfo(
+            name=item.name,
+            path=str(item),
+            skill_count=_count_skills(item),
+        ))
+
+    return sets
+
+
+def diff_skill_set(
+    name: str,
+    project_root: Path,
+) -> SkillSetDiff | None:
+    """Compare a skill set against builtins.
+
+    Args:
+        name: Skill set name.
+        project_root: Project root directory.
+
+    Returns:
+        SkillSetDiff with added/modified/unchanged, or None if set doesn't exist.
+    """
+    from raise_cli.skills_base import DISTRIBUTABLE_SKILLS
+
+    set_dir = _skills_dir(project_root) / name
+    if not set_dir.is_dir():
+        return None
+
+    base = files("raise_cli.skills_base")
+    builtin_names = set(DISTRIBUTABLE_SKILLS)
+
+    added: list[str] = []
+    modified: list[str] = []
+    unchanged: list[str] = []
+
+    # Check each skill in the set
+    for skill_dir in sorted(set_dir.iterdir()):
+        if not skill_dir.is_dir():
+            continue
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.exists():
+            continue
+
+        skill_name = skill_dir.name
+
+        if skill_name not in builtin_names:
+            added.append(skill_name)
+            continue
+
+        # Compare against builtin
+        set_hash = compute_content_hash(skill_md.read_text(encoding="utf-8"))
+        builtin_content = (base / skill_name / "SKILL.md").read_text(encoding="utf-8")
+        builtin_hash = compute_content_hash(builtin_content)
+
+        if set_hash == builtin_hash:
+            unchanged.append(skill_name)
+        else:
+            modified.append(skill_name)
+
+    return SkillSetDiff(
+        name=name,
+        added=added,
+        modified=modified,
+        unchanged=unchanged,
+    )