@pennyfarthing/core 11.4.0 → 12.0.0

package/pennyfarthing-dist/src/pf/prime/loader.py

@@ -0,0 +1,322 @@
+"""
+Context loading functions for prime.
+
+Provides functions to load various context sources:
+- Agent definitions
+- Behavior guides
+- Sprint context
+- Session files
+- Sidecars (patterns, gotchas, decisions)
+- Domain documentation
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pf.common.config import get_dist_root, get_project_root
+
+
+def load_agent_definition(agent_name: str, project_root: Path | None = None) -> str | None:
+    """Load agent definition markdown.
+
+    Args:
+        agent_name: Name of the agent (e.g., "dev", "tea", "sm")
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Agent definition content, or None if not found
+    """
+    root = project_root or get_project_root()
+    agent_file = root / ".pennyfarthing" / "agents" / f"{agent_name}.md"
+
+    if agent_file.exists():
+        return agent_file.read_text()
+
+    # Fallback: pennyfarthing-dist via get_dist_root (npm context)
+    dist_root = get_dist_root(project_root=root)
+    if dist_root:
+        agent_file = dist_root / "agents" / f"{agent_name}.md"
+        if agent_file.exists():
+            return agent_file.read_text()
+
+    return None
+
+
+def load_behavior_guide(project_root: Path | None = None) -> str | None:
+    """Load shared agent behavior guide.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Behavior guide content, or None if not found
+    """
+    root = project_root or get_project_root()
+    guide_file = root / ".pennyfarthing" / "guides" / "agent-behavior.md"
+
+    if guide_file.exists():
+        return guide_file.read_text()
+
+    # Fallback: pennyfarthing-dist via get_dist_root (npm context)
+    dist_root = get_dist_root(project_root=root)
+    if dist_root:
+        guide_file = dist_root / "guides" / "agent-behavior.md"
+        if guide_file.exists():
+            return guide_file.read_text()
+
+    return None
+
+
+def load_sprint_context(project_root: Path | None = None) -> str | None:
+    """Load sprint summary context.
+
+    Returns brief sprint info: name, goal, and progress.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Formatted sprint summary, or None if no sprint data
+    """
+    # Import here to avoid circular imports
+    from pf.sprint.loader import load_sprint
+    from pf.sprint.status import get_sprint_status
+
+    root = project_root or get_project_root()
+    sprint_file = root / "sprint" / "current-sprint.yaml"
+
+    if not sprint_file.exists():
+        return None
+
+    sprint = load_sprint(root)
+    if not sprint:
+        return None
+
+    lines = []
+
+    # Sprint summary: "Sprint N: Goal"
+    sprint_info = sprint.get("sprint", {})
+    sprint_num = sprint_info.get("number")
+    sprint_goal = sprint_info.get("goal", "")
+
+    if sprint_num:
+        lines.append(f"Sprint {sprint_num}: {sprint_goal}")
+
+    # Progress: "X/Y points"
+    status = get_sprint_status()
+    if status:
+        completed = status.get("completed_points", 0)
+        total = status.get("total_points", 0)
+        lines.append(f"Progress: {completed}/{total} points")
+
+    return "\n".join(lines) if lines else None
+
+
+def _find_session_file(project_root: Path) -> Path | None:
+    """Find the active session file.
+
+    Args:
+        project_root: Project root path
+
+    Returns:
+        Path to session file, or None if not found
+    """
+    session_dir = project_root / ".session"
+    if not session_dir.is_dir():
+        return None
+
+    # Find *-session.md files
+    session_files = list(session_dir.glob("*-session.md"))
+    if not session_files:
+        return None
+
+    # Return the most recently modified one
+    return max(session_files, key=lambda f: f.stat().st_mtime)
+
+
+def _extract_session_parts(content: str) -> tuple[str, str]:
+    """Extract header and last assessment from session markdown.
+
+    Args:
+        content: Full session file content
+
+    Returns:
+        Tuple of (header, last_assessment) strings
+    """
+    lines = content.split("\n")
+
+    # Header: everything before first ## heading
+    header_lines = []
+    for line in lines:
+        if line.startswith("## "):
+            break
+        header_lines.append(line)
+
+    # Find the last assessment section
+    assessment_start = None
+    for i, line in enumerate(lines):
+        if re.match(r"^## .*Assessment", line):
+            assessment_start = i
+
+    assessment_lines = []
+    if assessment_start is not None:
+        # Extract from assessment header to next ## or end
+        for line in lines[assessment_start:]:
+            # Stop at next ## heading (but not the assessment header itself)
+            if line.startswith("## ") and lines.index(line) > assessment_start:
+                break
+            assessment_lines.append(line)
+
+    return "\n".join(header_lines).strip(), "\n".join(assessment_lines).strip()
+
+
+def load_session_context(project_root: Path | None = None) -> tuple[str, str, str] | None:
+    """Load active session context.
+
+    Extracts header metadata and the most recent assessment section
+    from the active session file.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Tuple of (filename, header, last_assessment), or None if no session
+    """
+    root = project_root or get_project_root()
+    session_file = _find_session_file(root)
+
+    if not session_file:
+        return None
+
+    content = session_file.read_text()
+    header, assessment = _extract_session_parts(content)
+
+    return session_file.name, header, assessment
+
+
+def load_sidecars(agent_name: str, project_root: Path | None = None) -> dict[str, str]:
+    """Load agent sidecar files (patterns, gotchas, decisions).
+
+    Sidecars are loaded in order of usefulness:
+    1. patterns.md - Most actionable
+    2. gotchas.md - Common pitfalls
+    3. decisions.md - Historical context
+
+    Args:
+        agent_name: Name of the agent
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Dict mapping filename to content (only includes existing files)
+    """
+    root = project_root or get_project_root()
+    sidecar_dir = root / ".pennyfarthing" / "sidecars" / agent_name
+
+    if not sidecar_dir.is_dir():
+        return {}
+
+    sidecars = {}
+    # Load in priority order
+    for filename in ["patterns.md", "gotchas.md", "decisions.md"]:
+        sidecar_file = sidecar_dir / filename
+        if sidecar_file.exists():
+            sidecars[filename] = sidecar_file.read_text()
+
+    return sidecars
+
+
+def load_domain_docs(project_root: Path | None = None) -> list[tuple[str, str]]:
+    """Load domain documentation files.
+
+    These are CLAUDE-*.md files in .claude/project/ that provide
+    domain-specific context.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        List of (filename, content) tuples
+    """
+    root = project_root or get_project_root()
+    project_dir = root / ".claude" / "project"
+
+    if not project_dir.is_dir():
+        return []
+
+    docs = []
+    for doc_file in sorted(project_dir.glob("CLAUDE-*.md")):
+        docs.append((doc_file.name, doc_file.read_text()))
+
+    return docs
+
+
+def load_repos_topology(project_root: Path | None = None) -> str | None:
+    """Load repos.yaml topology as formatted context for agents.
+
+    Reads .pennyfarthing/repos.yaml and formats the topology fields
+    (owns, never_edit, symlinks, ui_layer, components_path) as a
+    readable manifest for agent spatial awareness.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Formatted topology context string, or None if unavailable
+    """
+    import yaml
+
+    root = project_root or get_project_root()
+    repos_file = root / ".pennyfarthing" / "repos.yaml"
+
+    if not repos_file.exists():
+        return None
+
+    try:
+        data = yaml.safe_load(repos_file.read_text())
+    except Exception:
+        return None
+
+    if not isinstance(data, dict) or "repos" not in data:
+        return None
+
+    repos = data["repos"]
+    if not repos:
+        return None
+
+    lines: list[str] = []
+    for name, config in repos.items():
+        lines.append(f"## {name}")
+        if config.get("path"):
+            lines.append(f"Path: {config['path']}")
+        if config.get("type"):
+            lines.append(f"Type: {config['type']}")
+        if config.get("description"):
+            lines.append(f"Description: {config['description']}")
+
+        owns = config.get("owns", [])
+        if owns:
+            lines.append(f"Owns: {', '.join(owns)}")
+
+        never_edit = config.get("never_edit", [])
+        if never_edit:
+            lines.append(f"Never Edit: {', '.join(never_edit)}")
+
+        symlinks = config.get("symlinks", {})
+        if symlinks:
+            lines.append("Symlinks:")
+            for src, dest in symlinks.items():
+                lines.append(f"  {src} → {dest}")
+
+        ui_layer = config.get("ui_layer")
+        if ui_layer:
+            lines.append(f"UI Layer: {ui_layer}")
+
+        components_path = config.get("components_path")
+        if components_path:
+            lines.append(f"Components: {components_path}")
+
+        lines.append("")
+
+    return "\n".join(lines).strip() if lines else None

package/pennyfarthing-dist/src/pf/prime/persona.py

@@ -0,0 +1,305 @@
+"""
+Persona loading for Prime v2.
+
+Loads agent personas from theme YAML files for character-driven agents.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from pf.common.config import get_project_root, load_yaml_config
+from pf.common.themes import (
+    get_current_theme as _get_current_theme,
+)
+from pf.common.themes import (
+    resolve_theme_path,
+)
+from pf.prime.models import CrewMember, Persona
+
+# Standard agent roles for crew manifest
+AGENT_ROLES = [
+    "sm", "tea", "dev", "reviewer", "architect",
+    "pm", "tech-writer", "ux-designer", "devops", "orchestrator",
+    "ba",
+]
+
+
+def get_current_theme(project_root: Path | None = None) -> str | None:
+    """Get the currently configured theme.
+
+    Delegates to common.themes canonical implementation.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Theme name, or None if not configured
+    """
+    return _get_current_theme(project_root)
+
+
+def get_theme_path(theme: str, project_root: Path) -> Path | None:
+    """Get the path to a theme YAML file.
+
+    Delegates to common.themes canonical discovery algorithm.
+
+    Args:
+        theme: Theme name
+        project_root: Project root path
+
+    Returns:
+        Path to theme file, or None if not found
+    """
+    return resolve_theme_path(theme, project_root)
+
+
+def load_theme(theme: str, project_root: Path | None = None) -> dict[str, Any] | None:
+    """Load a theme YAML file.
+
+    Args:
+        theme: Theme name
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Theme data dict, or None if not found
+    """
+    root = project_root or get_project_root()
+    theme_path = get_theme_path(theme, root)
+
+    if not theme_path:
+        return None
+
+    try:
+        return yaml.safe_load(theme_path.read_text())
+    except Exception:
+        return None
+
+
+def load_persona(agent_name: str, project_root: Path | None = None) -> tuple[Persona | None, str | None]:
+    """Load persona for an agent from the current theme.
+
+    Args:
+        agent_name: Agent name (sm, tea, dev, etc.)
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Tuple of (Persona, theme_name) or (None, None) if not found
+    """
+    root = project_root or get_project_root()
+    theme = get_current_theme(root)
+
+    if not theme:
+        return None, None
+
+    theme_data = load_theme(theme, root)
+    if not theme_data or "agents" not in theme_data:
+        return None, None
+
+    agent_data = theme_data["agents"].get(agent_name)
+    if not agent_data:
+        return None, None
+
+    # Extract helper info if present
+    helper = agent_data.get("helper", {})
+
+    persona = Persona(
+        character=agent_data.get("character", "Unknown"),
+        style=agent_data.get("style", ""),
+        role=agent_data.get("role", ""),
+        quote=agent_data.get("quote"),
+        trait=agent_data.get("trait"),
+        quirk=agent_data.get("quirk"),
+        motto=agent_data.get("motto"),
+        helper_name=helper.get("name") if helper else None,
+        helper_style=helper.get("style") if helper else None,
+    )
+
+    return persona, theme
+
+
+def get_crew_manifest(project_root: Path | None = None) -> list[CrewMember]:
+    """Get all agent characters from the current theme.
+
+    Used for handoff reference so agents know other characters.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        List of CrewMember objects for all 11 standard roles
+    """
+    root = project_root or get_project_root()
+    theme = get_current_theme(root)
+
+    if not theme:
+        return []
+
+    theme_data = load_theme(theme, root)
+    if not theme_data or "agents" not in theme_data:
+        return []
+
+    crew = []
+    for role in AGENT_ROLES:
+        agent_data = theme_data["agents"].get(role)
+        if agent_data and "character" in agent_data:
+            crew.append(CrewMember(role=role, character=agent_data["character"]))
+
+    return crew
+
+
+def get_user_title(project_root: Path | None = None) -> str | None:
+    """Get the user title from the current theme.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        User title (e.g., "Bossmang"), or None if not set
+    """
+    root = project_root or get_project_root()
+    theme = get_current_theme(root)
+
+    if not theme:
+        return None
+
+    theme_data = load_theme(theme, root)
+    if not theme_data or "theme" not in theme_data:
+        return None
+
+    return theme_data["theme"].get("user_title")
+
+
+def format_persona_output(
+    persona: Persona,
+    theme: str,
+    agent_name: str,
+    crew: list[CrewMember] | None = None,
+    user_title: str | None = None,
+) -> str:
+    """Format persona as XML output for Claude.
+
+    Matches the format from agent-session.sh:
+    <persona agent="dev" theme="the-expanse">
+    Character: Naomi Nagata
+    Style: ...
+    </persona>
+
+    Args:
+        persona: Persona to format
+        theme: Theme name
+        agent_name: Agent name
+        crew: Optional crew manifest for handoff reference
+        user_title: Optional user title
+
+    Returns:
+        Formatted persona XML string
+    """
+    lines = [
+        f'<persona agent="{agent_name}" theme="{theme}">',
+        f"Character: {persona.character}",
+        f"Style: {persona.style}",
+        f"Role: {persona.role}",
+    ]
+
+    if persona.trait:
+        lines.append(f"Trait: {persona.trait}")
+    if persona.quirk:
+        lines.append(f"Quirk: {persona.quirk}")
+    if persona.motto:
+        lines.append(f"Motto: {persona.motto}")
+    if persona.quote:
+        lines.append(f"Quote: {persona.quote}")
+    if persona.helper_name:
+        helper_line = f"Helper: {persona.helper_name}"
+        if persona.helper_style:
+            helper_line += f" - {persona.helper_style}"
+        lines.append(helper_line)
+        lines.append(f"When spawning subagents, refer to them as your {persona.helper_name}.")
+
+    lines.append("</persona>")
+
+    # Add user title if set
+    if user_title:
+        lines.append("")
+        lines.append(f"<user-title>Address the user as: {user_title}</user-title>")
+
+    # Add crew manifest for handoff reference
+    if crew:
+        lines.append("")
+        lines.append(f'<crew theme="{theme}">')
+        lines.append("When handing off to other agents, address them by character name:")
+        for member in crew:
+            lines.append(f"  {member.role:12} {member.character}")
+        lines.append("</crew>")
+
+    return "\n".join(lines)
+
+
+def is_character_voice_enabled(project_root: Path | None = None) -> bool:
+    """Check if character voice is enabled in preferences.
+
+    Reads from .pennyfarthing/config.local.yaml preferences section.
+    Defaults to True if no preference is set.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        True if character voice is enabled
+    """
+    root = project_root or get_project_root()
+
+    config_path = root / ".pennyfarthing" / "config.local.yaml"
+    config = load_yaml_config(config_path)
+    if config:
+        prefs = config.get("preferences", {})
+        if prefs and "character_voice" in prefs:
+            return prefs["character_voice"] is not False
+
+    # Default to enabled
+    return True
+
+
+def format_persona_compressed(
+    persona: Persona,
+    theme: str,
+    agent_name: str,
+) -> str:
+    """Format persona as compressed XML for reduced token usage.
+
+    Compressed format (~100 tokens vs ~300 for full):
+    <persona agent="dev" character="Rosie the Riveter">
+      <voice>Can-do wartime spirit, practical, determined</voice>
+      <catchphrase>"We Can Do It!"</catchphrase>
+      <style>Direct, encouraging, efficiency-focused</style>
+    </persona>
+
+    Args:
+        persona: Persona to format
+        theme: Theme name
+        agent_name: Agent name
+
+    Returns:
+        Compressed persona XML string (~100 tokens)
+    """
+    lines = [f'<persona agent="{agent_name}" character="{persona.character}">']
+
+    # Voice from style (primary behavioral descriptor)
+    if persona.style:
+        lines.append(f"  <voice>{persona.style}</voice>")
+
+    # Catchphrase from quote
+    if persona.quote:
+        lines.append(f"  <catchphrase>{persona.quote}</catchphrase>")
+
+    # Style from role (short descriptor)
+    if persona.role:
+        lines.append(f"  <style>{persona.role}</style>")
+
+    lines.append("</persona>")
+
+    return "\n".join(lines)