raise-cli 2.2.1__py3-none-any.whl

raise_cli/agents/copilot_plugin.py

@@ -0,0 +1,124 @@
+"""CopilotPlugin — transforms RaiSE skills to GitHub Copilot agent format.
+
+GitHub Copilot uses:
+  - .github/agents/*.SKILL.md   (different frontmatter: tools, infer)
+  - .github/prompts/*.prompt.md (one per skill, for Copilot workflows)
+
+This plugin handles both transformations via AgentPlugin protocol hooks.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, cast
+
+from raise_cli.config.agents import AgentConfig
+
+logger = logging.getLogger(__name__)
+
+_COPILOT_TOOLS = ["execute", "read", "edit", "search"]
+_REMOVE_FIELDS = {"license", "compatibility"}
+
+
+class CopilotPlugin:
+    """Transform RaiSE skills and instructions for GitHub Copilot.
+
+    Copilot uses a different frontmatter schema for .github/agents/ files
+    and supports .github/prompts/*.prompt.md workflow files.
+    """
+
+    def transform_instructions(self, content: str, config: AgentConfig) -> str:
+        """Return instructions unchanged — Copilot reads standard markdown."""
+        return content
+
+    def transform_skill(
+        self, frontmatter: dict[str, Any], body: str, config: AgentConfig
+    ) -> tuple[dict[str, Any], str]:
+        """Transform skill frontmatter to Copilot agent format.
+
+        Adds Copilot-specific fields (tools, infer).
+        Removes fields unsupported by Copilot (license, compatibility).
+        """
+        fm = {k: v for k, v in frontmatter.items() if k not in _REMOVE_FIELDS}
+        fm["tools"] = list(_COPILOT_TOOLS)
+        fm["infer"] = True
+        return fm, body
+
+    def post_init(self, project_root: Path, config: AgentConfig) -> list[str]:
+        """Generate .prompt.md files from skills in .github/agents/.
+
+        Reads each SKILL.md in the skills_dir, extracts name and description
+        from frontmatter, and writes a .prompt.md to .github/prompts/.
+
+        Args:
+            project_root: Project root directory.
+            config: Copilot agent configuration.
+
+        Returns:
+            List of created .prompt.md file paths.
+        """
+        if config.skills_dir is None:
+            return []
+
+        agents_dir = project_root / config.skills_dir
+        if not agents_dir.exists():
+            return []
+
+        prompts_dir = project_root / ".github" / "prompts"
+        prompts_dir.mkdir(parents=True, exist_ok=True)
+
+        created: list[str] = []
+        for skill_dir in sorted(agents_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
+            frontmatter = _read_frontmatter(skill_md)
+            name = frontmatter.get("name", skill_name)
+            description = frontmatter.get("description", "")
+
+            prompt_content = _build_prompt_md(skill_name, name, str(description))
+            prompt_file = prompts_dir / f"{skill_name}.prompt.md"
+            prompt_file.write_text(prompt_content, encoding="utf-8")
+            created.append(str(prompt_file))
+            logger.debug("Created Copilot prompt: %s", prompt_file)
+
+        return created
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_frontmatter(skill_md: Path) -> dict[str, Any]:
+    """Parse YAML frontmatter from a SKILL.md file (best-effort)."""
+    try:
+        import yaml
+
+        content = skill_md.read_text(encoding="utf-8")
+        if not content.startswith("---"):
+            return {}
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            return {}
+        raw: Any = yaml.safe_load(parts[1])
+        if not isinstance(raw, dict):
+            return {}
+        return cast(dict[str, Any], raw)
+    except Exception:
+        return {}
+
+
+def _build_prompt_md(skill_name: str, name: str, description: str) -> str:
+    """Build .prompt.md content for a Copilot workflow prompt."""
+    return (
+        f"# {name}\n\n"
+        f"{description.strip()}\n\n"
+        f"---\n\n"
+        f"Run the `{skill_name}` skill from `.github/agents/{skill_name}/SKILL.md`.\n"
+    )

raise_cli/agents/cursor.yaml

@@ -0,0 +1,7 @@
+name: Cursor
+agent_type: cursor
+instructions_file: .cursor/rules/raise.mdc
+skills_dir: .cursor/skills
+detection_markers:
+  - .cursor/rules
+  - .cursor

raise_cli/agents/roo.yaml

@@ -0,0 +1,8 @@
+name: Roo Code
+agent_type: roo
+instructions_file: .roo/rules/raise.md
+skills_dir: .roo/skills
+detection_markers:
+  - .roo/rules
+  - .roo
+  - .rooignore

raise_cli/agents/windsurf.yaml

@@ -0,0 +1,8 @@
+name: Windsurf
+agent_type: windsurf
+instructions_file: .windsurf/rules/raise.md
+skills_dir: .windsurf/skills
+workflows_dir: .windsurf/workflows
+detection_markers:
+  - .windsurf/rules
+  - .windsurf

raise_cli/artifacts/__init__.py

@@ -0,0 +1,30 @@
+"""Typed skill artifacts: models, validation, and YAML storage."""
+
+from raise_cli.artifacts.models import ArtifactRefs, ArtifactType, SkillArtifact
+from raise_cli.artifacts.reader import read_all_artifacts, read_artifact
+from raise_cli.artifacts.renderer import render_artifact
+from raise_cli.artifacts.story_design import (
+    AcceptanceCriterion,
+    Complexity,
+    Decision,
+    IntegrationPoint,
+    StoryDesignArtifact,
+    StoryDesignContent,
+)
+from raise_cli.artifacts.writer import write_artifact
+
+__all__ = [
+    "AcceptanceCriterion",
+    "ArtifactRefs",
+    "ArtifactType",
+    "Complexity",
+    "Decision",
+    "IntegrationPoint",
+    "SkillArtifact",
+    "StoryDesignArtifact",
+    "StoryDesignContent",
+    "read_all_artifacts",
+    "read_artifact",
+    "render_artifact",
+    "write_artifact",
+]

raise_cli/artifacts/models.py

@@ -0,0 +1,43 @@
+"""Pydantic models for typed skill artifacts."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ArtifactType(StrEnum):
+    """Types of skill artifacts.
+
+    Each value corresponds to a skill's output type declared
+    in SKILL.md frontmatter as ``raise.output_type``.
+    """
+
+    STORY_DESIGN = "story-design"
+
+
+class ArtifactRefs(BaseModel):
+    """References from an artifact to external items."""
+
+    backlog_item: str | None = None
+    epic_scope: str | None = None
+    related_artifacts: list[str] = Field(default_factory=list)
+
+
+class SkillArtifact(BaseModel):
+    """Base artifact produced by a skill execution.
+
+    Subclasses replace ``content`` with a typed model for
+    specific artifact types (e.g., StoryDesignContent).
+    """
+
+    artifact_type: ArtifactType
+    version: int = Field(default=1, ge=1)
+    skill: str
+    created: datetime
+    story: str | None = None
+    epic: str | None = None
+    content: dict[str, Any] = Field(default_factory=dict)
+    refs: ArtifactRefs = Field(default_factory=ArtifactRefs)
+    metadata: dict[str, Any] = Field(default_factory=dict)

raise_cli/artifacts/reader.py

@@ -0,0 +1,55 @@
+"""YAML reader for skill artifacts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from raise_cli.artifacts.models import SkillArtifact
+
+# Lazy import to avoid circular dependency
+_artifact_registry: dict[str, type[SkillArtifact]] | None = None
+
+
+def _get_registry() -> dict[str, type[SkillArtifact]]:
+    """Build the artifact type registry on first access."""
+    global _artifact_registry  # noqa: PLW0603
+    if _artifact_registry is None:
+        from raise_cli.artifacts.story_design import StoryDesignArtifact
+
+        _artifact_registry = {
+            "story-design": StoryDesignArtifact,
+        }
+    return _artifact_registry
+
+
+def read_artifact(path: Path) -> SkillArtifact:
+    """Load and validate a single artifact from a YAML file.
+
+    Dispatches to the correct model subclass based on ``artifact_type``.
+    Falls back to ``SkillArtifact`` (base) for unknown types.
+
+    Raises:
+        pydantic.ValidationError: If the YAML doesn't match the schema.
+    """
+    data = yaml.safe_load(path.read_text())
+    artifact_type = data.get("artifact_type", "")
+    registry = _get_registry()
+    model_class = registry.get(artifact_type, SkillArtifact)
+    return model_class.model_validate(data)
+
+
+def read_all_artifacts(artifacts_dir: Path) -> list[SkillArtifact]:
+    """Load all artifacts from a directory.
+
+    Returns an empty list if the directory doesn't exist or is empty.
+    Raises ``ValidationError`` if any file fails validation.
+    """
+    if not artifacts_dir.is_dir():
+        return []
+
+    artifacts: list[SkillArtifact] = []
+    for yaml_file in sorted(artifacts_dir.glob("*.yaml")):
+        artifacts.append(read_artifact(yaml_file))
+    return artifacts

raise_cli/artifacts/renderer.py

@@ -0,0 +1,104 @@
+"""Render typed artifacts to human-readable Markdown."""
+
+import re
+from pathlib import Path
+
+from raise_cli.artifacts.models import SkillArtifact
+from raise_cli.artifacts.story_design import (
+    StoryDesignArtifact,
+    StoryDesignContent,
+)
+
+
+def _render_acceptance_criteria(content: StoryDesignContent) -> str:
+    """Render AC as a numbered list."""
+    lines: list[str] = []
+    for i, ac in enumerate(content.acceptance_criteria, 1):
+        lines.append(f"{i}. [{ac.id}] {ac.description}")
+    return "\n".join(lines)
+
+
+def _render_integration_points(content: StoryDesignContent) -> str:
+    """Render integration points as bullet list."""
+    if not content.integration_points:
+        return ""
+    lines: list[str] = []
+    for ip in content.integration_points:
+        files = ", ".join(f"`{f}`" for f in ip.files) if ip.files else ""  # pyright: ignore[reportUnknownArgumentType]
+        line = f"- `{ip.module}` — {ip.change_type}"
+        if files:
+            line += f": {files}"
+        lines.append(line)
+    return "\n".join(lines)
+
+
+def _render_decisions(content: StoryDesignContent) -> str:
+    """Render decisions with rationale and alternatives."""
+    if not content.decisions:
+        return ""
+    blocks: list[str] = []
+    for d in content.decisions:
+        block = f"### {d.id}: {d.choice}\n"
+        block += f"**Rationale:** {d.rationale}\n"
+        if d.alternatives_considered:
+            alts = ", ".join(d.alternatives_considered)  # pyright: ignore[reportUnknownArgumentType]
+            block += f"**Alternatives:** {alts}"
+        blocks.append(block)
+    return "\n\n".join(blocks)
+
+
+def _remove_empty_sections(md: str) -> str:
+    """Remove sections whose placeholder was empty."""
+    # Match ## heading followed by only whitespace until next ## or end
+    return re.sub(r"\n## [^\n]+\n\n\s*(?=\n##|\Z)", "", md)
+
+
+def _get_template(project_root: Path | None = None) -> str:
+    """Load the story-design template."""
+    if project_root:
+        template_path = (
+            project_root / ".raise" / "templates" / "artifacts" / "story-design.md"
+        )
+        if template_path.exists():
+            return template_path.read_text()
+
+    # Fallback: inline default
+    return (
+        "# {story} Design: {summary}\n\n"
+        "**Story:** {story} | **Epic:** {epic} | **Complexity:** {complexity}\n"
+        "**Skill:** {skill} | **Created:** {created}\n\n"
+        "## Summary\n\n{summary}\n\n"
+        "## Acceptance Criteria\n\n{acceptance_criteria}\n\n"
+        "## Integration Points\n\n{integration_points}\n\n"
+        "## Decisions\n\n{decisions}\n"
+    )
+
+
+def render_artifact(
+    artifact: SkillArtifact, project_root: Path | None = None
+) -> str:
+    """Render a typed artifact to Markdown.
+
+    Uses the template from ``.raise/templates/artifacts/`` if available,
+    falls back to a built-in default.
+    """
+    if not isinstance(artifact, StoryDesignArtifact):
+        # Fallback for non-story-design artifacts
+        return f"# Artifact: {artifact.artifact_type}\n\n{artifact.content}\n"
+
+    content = artifact.content
+    template = _get_template(project_root)
+
+    md = template.format(
+        story=artifact.story or "—",
+        epic=artifact.epic or "—",
+        summary=content.summary,
+        complexity=content.complexity.value,
+        skill=artifact.skill,
+        created=artifact.created.strftime("%Y-%m-%d"),
+        acceptance_criteria=_render_acceptance_criteria(content),
+        integration_points=_render_integration_points(content),
+        decisions=_render_decisions(content),
+    )
+
+    return _remove_empty_sections(md)

raise_cli/artifacts/story_design.py

@@ -0,0 +1,69 @@
+"""Story-design artifact schema and governance validators."""
+
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from raise_cli.artifacts.models import ArtifactType, SkillArtifact
+
+
+class Complexity(StrEnum):
+    """Story complexity assessment."""
+
+    SIMPLE = "simple"
+    MODERATE = "moderate"
+    COMPLEX = "complex"
+
+
+class AcceptanceCriterion(BaseModel):
+    """A single acceptance criterion."""
+
+    id: str
+    description: str
+    verifiable: bool = True
+
+
+class IntegrationPoint(BaseModel):
+    """A codebase integration point affected by the story."""
+
+    module: str
+    change_type: str
+    files: list[str] = Field(default_factory=list)
+
+
+class Decision(BaseModel):
+    """A design decision with rationale."""
+
+    id: str
+    choice: str
+    rationale: str
+    alternatives_considered: list[str] = Field(default_factory=list)
+
+
+class StoryDesignContent(BaseModel):
+    """Typed content for a story-design artifact.
+
+    Governance rules are encoded as validators.
+    """
+
+    summary: str
+    complexity: Complexity
+    acceptance_criteria: list[AcceptanceCriterion] = Field(min_length=1, max_length=10)
+    integration_points: list[IntegrationPoint] = Field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+    decisions: list[Decision] = Field(default_factory=list)  # pyright: ignore[reportUnknownVariableType]
+
+    @model_validator(mode="after")
+    def _validate_decisions_have_rationale(self) -> "StoryDesignContent":
+        for decision in self.decisions:
+            if not decision.rationale.strip():
+                msg = f"Decision {decision.id}: rationale must not be empty"
+                raise ValueError(msg)
+        return self
+
+
+class StoryDesignArtifact(SkillArtifact):
+    """A story-design artifact with typed content."""
+
+    artifact_type: Literal[ArtifactType.STORY_DESIGN] = ArtifactType.STORY_DESIGN  # pyright: ignore[reportIncompatibleVariableOverride]
+    content: StoryDesignContent  # pyright: ignore[reportIncompatibleVariableOverride,reportGeneralTypeIssues]

raise_cli/artifacts/writer.py

@@ -0,0 +1,45 @@
+"""YAML writer for skill artifacts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from raise_cli.artifacts.models import SkillArtifact
+
+
+def _artifact_filename(artifact: SkillArtifact) -> str:
+    """Derive filename from artifact story/epic and type.
+
+    Convention: ``{id}-{type_suffix}.yaml``
+    where type_suffix strips the first segment (e.g., ``story-design`` → ``design``).
+    """
+    # Use story if available, else epic
+    work_id = artifact.story or artifact.epic or "unknown"
+    work_id = work_id.lower()
+
+    # Strip prefix from artifact type: "story-design" → "design"
+    type_suffix = artifact.artifact_type.value.split("-", 1)[-1]
+
+    return f"{work_id}-{type_suffix}.yaml"
+
+
+def write_artifact(artifact: SkillArtifact, project_root: Path) -> Path:
+    """Serialize artifact to YAML in ``.raise/artifacts/``.
+
+    Creates the directory if it doesn't exist.
+
+    Returns:
+        Path to the written YAML file.
+    """
+    artifacts_dir = project_root / ".raise" / "artifacts"
+    artifacts_dir.mkdir(parents=True, exist_ok=True)
+
+    filename = _artifact_filename(artifact)
+    path = artifacts_dir / filename
+
+    data = artifact.model_dump(mode="json")
+    path.write_text(yaml.dump(data, default_flow_style=False, sort_keys=False))
+
+    return path

raise_cli/backlog/__init__.py

@@ -0,0 +1 @@
+"""Backlog sync and management utilities."""

raise_cli/backlog/sync.py

@@ -0,0 +1,115 @@
+"""Backlog sync: query remote adapter, format markdown, write atomically.
+
+Generates ``governance/backlog.md`` from a remote PM adapter (e.g., Jira).
+The filesystem adapter is detected and rejected (it IS the source of truth).
+
+Architecture: S347.6 (E347 Backlog Automation)
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from raise_cli.adapters.models import IssueSummary
+
+if TYPE_CHECKING:
+    from raise_cli.adapters.protocols import ProjectManagementAdapter
+
+
+class SyncResult(BaseModel):
+    """Result of a backlog sync operation."""
+
+    adapter_name: str = Field(..., description="Name of source adapter")
+    epic_count: int = Field(..., description="Number of epics synced")
+    timestamp: str = Field(..., description="ISO 8601 sync timestamp")
+    output_path: str = Field(..., description="Path to generated file")
+
+
+def sync_backlog(
+    adapter: ProjectManagementAdapter,
+    adapter_name: str,
+    project_filter: str | None,
+    output_path: Path,
+) -> SyncResult:
+    """Query adapter, format markdown, write atomically.
+
+    Raises:
+        ValueError: If adapter is a FilesystemPMAdapter (self-sync).
+        RuntimeError: If adapter query fails (file left untouched).
+    """
+    # Guard: filesystem adapter is source of truth
+    from raise_cli.adapters.filesystem import FilesystemPMAdapter
+
+    if isinstance(adapter, FilesystemPMAdapter):
+        raise ValueError("Filesystem adapter is source of truth — nothing to sync.")
+
+    # Build query
+    query = "issuetype = Epic ORDER BY key ASC"
+    if project_filter:
+        query = f'project = "{project_filter}" AND issuetype = Epic ORDER BY key ASC'
+
+    # Fetch from adapter — let exceptions propagate (file untouched)
+    try:
+        results = adapter.search(query, limit=200)
+    except Exception as exc:
+        raise RuntimeError(f"Adapter '{adapter_name}' failed: {exc}") from exc
+
+    # Format and write
+    timestamp = datetime.now(UTC).isoformat()
+    content = _format_markdown(results, adapter_name, timestamp)
+    _atomic_write(output_path, content)
+
+    return SyncResult(
+        adapter_name=adapter_name,
+        epic_count=len(results),
+        timestamp=timestamp,
+        output_path=str(output_path),
+    )
+
+
+def _escape_pipe(value: str) -> str:
+    """Escape pipe characters in markdown table cell values."""
+    return value.replace("|", "\\|")
+
+
+def _format_markdown(
+    epics: list[IssueSummary], adapter_name: str, timestamp: str
+) -> str:
+    """Generate markdown table from IssueSummary list."""
+    lines: list[str] = [
+        f"<!-- Generated by `rai backlog sync` at {timestamp} from adapter: {adapter_name} -->",
+        "<!-- Do not edit manually. Re-run `rai backlog sync` to refresh. -->",
+        "",
+        "# Backlog",
+        "",
+        "## Epics Overview",
+        "",
+        "| Key | Epic | Status | Type |",
+        "|-----|------|--------|------|",
+    ]
+    for epic in epics:
+        summary = _escape_pipe(epic.summary)
+        status = _escape_pipe(epic.status)
+        issue_type = _escape_pipe(epic.issue_type)
+        lines.append(f"| {epic.key} | {summary} | {status} | {issue_type} |")
+    lines.append("")  # trailing newline
+    return "\n".join(lines)
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    """Write content to path atomically via temp file + rename.
+
+    Uses ``str(path) + ".tmp"`` to preserve the original suffix
+    (e.g., ``backlog.md.tmp`` not ``backlog.tmp``).
+    Uses :func:`os.replace` instead of :meth:`Path.rename` for
+    cross-platform atomicity (``rename`` fails on Windows when target exists).
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = Path(str(path) + ".tmp")
+    tmp.write_text(content, encoding="utf-8")
+    os.replace(tmp, path)

raise_cli/cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI presentation layer."""
+
+from __future__ import annotations

raise_cli/cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""Commands."""
+
+from __future__ import annotations