@pennyfarthing/core 10.0.2 → 10.0.3

package/pennyfarthing_scripts/prime/loader.py

@@ -0,0 +1,239 @@
+"""
+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 typing import Any
+
+from pennyfarthing_scripts.common.config import 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 not agent_file.exists():
+        return None
+
+    return agent_file.read_text()
+
+
+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 not guide_file.exists():
+        return None
+
+    return guide_file.read_text()
+
+
+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 pennyfarthing_scripts.sprint.loader import load_sprint, get_sprint_info
+    from pennyfarthing_scripts.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 i, line in enumerate(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

package/pennyfarthing_scripts/prime/models.py

@@ -0,0 +1,206 @@
+"""
+Data models for Prime v2.
+
+Provides structured types for workflow state, persona, and session data.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class WorkflowState(Enum):
+    """Workflow states detected by prime."""
+
+    FINISH_STATE = "FINISH_STATE"
+    IN_PROGRESS_STATE = "IN_PROGRESS_STATE"
+    NEW_WORK_STATE = "NEW_WORK_STATE"
+    EMPTY_BACKLOG_STATE = "EMPTY_BACKLOG_STATE"
+
+
+@dataclass
+class WorkflowStatus:
+    """Result of workflow state detection.
+
+    Attributes:
+        state: Current workflow state
+        story_id: Active story ID if in progress/finish
+        phase: Current workflow phase (setup, red, green, review, finish)
+        phase_owner: Agent that owns the current phase
+        workflow: Workflow name (tdd, trivial, bdd, etc.)
+        backlog_count: Number of stories in backlog (for NEW_WORK_STATE)
+        session_file: Path to active session file if exists
+    """
+
+    state: WorkflowState
+    story_id: str | None = None
+    phase: str | None = None
+    phase_owner: str | None = None
+    workflow: str | None = None
+    backlog_count: int = 0
+    session_file: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "state": self.state.value,
+            "story_id": self.story_id,
+            "phase": self.phase,
+            "phase_owner": self.phase_owner,
+            "workflow": self.workflow,
+            "backlog_count": self.backlog_count,
+            "session_file": self.session_file,
+        }
+
+
+@dataclass
+class Persona:
+    """Agent persona from theme configuration.
+
+    Attributes:
+        character: Character name (e.g., "Camina Drummer")
+        style: Communication style description
+        role: Role description
+        quote: Optional signature quote
+        trait: Optional personality trait
+        quirk: Optional personality quirk
+        motto: Optional character motto
+        helper_name: Optional helper/assistant name
+        helper_style: Optional helper communication style
+    """
+
+    character: str
+    style: str
+    role: str
+    quote: str | None = None
+    trait: str | None = None
+    quirk: str | None = None
+    motto: str | None = None
+    helper_name: str | None = None
+    helper_style: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "character": self.character,
+            "style": self.style,
+            "role": self.role,
+        }
+        if self.quote:
+            result["quote"] = self.quote
+        if self.trait:
+            result["trait"] = self.trait
+        if self.quirk:
+            result["quirk"] = self.quirk
+        if self.motto:
+            result["motto"] = self.motto
+        if self.helper_name:
+            result["helper_name"] = self.helper_name
+        if self.helper_style:
+            result["helper_style"] = self.helper_style
+        return result
+
+
+@dataclass
+class CrewMember:
+    """A crew member in the theme manifest.
+
+    Attributes:
+        role: Agent role (sm, tea, dev, etc.)
+        character: Character name
+    """
+
+    role: str
+    character: str
+
+
+@dataclass
+class SessionInfo:
+    """Session registration information.
+
+    Attributes:
+        session_id: Unique session identifier
+        agent_name: Name of the registered agent
+        file_path: Path to the session file
+    """
+
+    session_id: str
+    agent_name: str
+    file_path: str
+
+
+@dataclass
+class PrimeComponent:
+    """A loaded context component with metadata.
+
+    Attributes:
+        name: Component identifier (e.g., "agent_definition", "persona")
+        tokens: Estimated token count
+        source: Relative path to source file, if applicable
+    """
+
+    name: str
+    tokens: int
+    source: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        d: dict[str, Any] = {"name": self.name, "tokens": self.tokens}
+        if self.source:
+            d["source"] = self.source
+        return d
+
+
+@dataclass
+class PrimeResult:
+    """Complete result from prime() for JSON output.
+
+    Attributes:
+        agent_name: Requested agent name
+        workflow_status: Current workflow state
+        persona: Loaded persona (if enabled)
+        theme: Active theme name
+        redirect_to: Agent to redirect to (if wrong agent activated)
+        redirect_reason: Reason for redirect
+        session_id: Session ID (if registered)
+        crew: List of crew members for handoff reference
+        tier: Context tier used (FULL, REFRESH, HANDOFF, MINIMAL)
+        token_counts: Per-component token estimates
+        total_tokens: Sum of all component token counts
+        context: Assembled context text for system prompt injection
+        components: Per-component metadata with source paths
+    """
+
+    agent_name: str
+    workflow_status: WorkflowStatus | None = None
+    persona: Persona | None = None
+    theme: str | None = None
+    redirect_to: str | None = None
+    redirect_reason: str | None = None
+    session_id: str | None = None
+    crew: list[CrewMember] = field(default_factory=list)
+    tier: str | None = None
+    token_counts: dict[str, int] = field(default_factory=dict)
+    total_tokens: int = 0
+    context: str | None = None
+    components: list[PrimeComponent] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "agent_name": self.agent_name,
+            "workflow_status": self.workflow_status.to_dict() if self.workflow_status else None,
+            "persona": self.persona.to_dict() if self.persona else None,
+            "theme": self.theme,
+            "redirect_to": self.redirect_to,
+            "redirect_reason": self.redirect_reason,
+            "session_id": self.session_id,
+            "crew": [{"role": c.role, "character": c.character} for c in self.crew],
+            "tier": self.tier,
+            "token_counts": self.token_counts,
+            "total_tokens": self.total_tokens,
+            "context": self.context,
+            "components": [c.to_dict() for c in self.components],
+        }