@mc1global/opencode-jarvis 0.12.0 → 0.13.1

package/src/application/orchestration/scrum_master_service.py

@@ -0,0 +1,993 @@
+"""
+Scrum Master Service - Automated Agent Orchestration.
+
+Provides governance and coordination for multi-agent software development:
+- Auto-assign work to available agents
+- Process review handoffs
+- Generate standup/status reports
+- Capture learning to context-memory for continuous improvement
+
+Type Hints: Required (mypy compliant)
+Docstring: Google format
+"""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+from enum import Enum
+
+from src.infrastructure.kanban.sqlite_repository import (
+    KanbanRepository,
+    CardDTO,
+    SprintDTO,
+)
+from src.application.kanban.kanban_service import KanbanService, ServiceResult
+from src.application.kanban.token_metrics_service import (
+    TokenMetricsService,
+    TokenReport,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# DATA CLASSES
+# =============================================================================
+
+
+@dataclass
+class AgentCapability:
+    """Defines an agent's capabilities and constraints."""
+
+    name: str
+    capabilities: List[str] = field(default_factory=list)
+    max_wip: int = 1
+    preferred_complexity: List[str] = field(
+        default_factory=lambda: ["simple", "medium", "complex"]
+    )
+    model: str = "default"
+
+
+@dataclass
+class AssignmentResult:
+    """Result of work assignment."""
+
+    success: bool
+    agent: Optional[str] = None
+    card_id: Optional[str] = None
+    error: Optional[str] = None
+    learning: Optional[str] = None
+
+
+@dataclass
+class ReviewHandoffResult:
+    """Result of review processing."""
+
+    card_id: str
+    action: str  # "approved", "rejected", "escalated"
+    from_status: str
+    to_status: str
+    feedback: Optional[str] = None
+    iteration: int = 0
+    learning: Optional[str] = None
+
+
+@dataclass
+class StandupReport:
+    """Daily standup report."""
+
+    workspace: str
+    generated_at: str
+    sprint: Optional[Dict[str, Any]] = None
+    cards_in_progress: List[Dict[str, Any]] = field(default_factory=list)
+    cards_in_review: List[Dict[str, Any]] = field(default_factory=list)
+    cards_blocked: List[Dict[str, Any]] = field(default_factory=list)
+    cards_done_today: List[Dict[str, Any]] = field(default_factory=list)
+    available_agents: List[str] = field(default_factory=list)
+    recommendations: List[str] = field(default_factory=list)
+    token_metrics: Optional[Dict[str, Any]] = None  # Token usage summary
+
+
+@dataclass
+class LearningEntry:
+    """Learning captured from orchestration actions."""
+
+    category: str  # "assignment", "review", "blocking", "velocity"
+    context: str
+    insight: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+
+
+# =============================================================================
+# AGENT REGISTRY
+# =============================================================================
+
+
+class AgentRegistry:
+    """
+    Registry of available agents and their capabilities.
+
+    Used to match cards to appropriate agents based on:
+    - Agent capabilities
+    - Current WIP (Work In Progress)
+    - Card complexity/type
+
+    Configuration Sources (in priority order):
+    1. Workspace config: data/workspaces/{workspace}/config/agents.yaml
+    2. Default config: config/agents.default.yaml
+    3. Hardcoded fallback: DEFAULT_AGENTS (for backward compatibility)
+
+    Usage:
+        # Use external config (recommended)
+        registry = AgentRegistry.from_config(workspace="my-workspace")
+
+        # Use hardcoded defaults (backward compatible)
+        registry = AgentRegistry()
+
+        # Use custom agents
+        registry = AgentRegistry(custom_agents={"my-agent": AgentCapability(...)})
+    """
+
+    # Hardcoded fallback for backward compatibility
+    # These are used ONLY when no config file exists
+    DEFAULT_AGENTS = {
+        "script-developer": AgentCapability(
+            name="script-developer",
+            capabilities=["code_implementation", "bug_fix", "refactoring", "testing"],
+            max_wip=1,
+            preferred_complexity=["simple", "medium"],
+            model="claude-sonnet",
+        ),
+        "solution-architect": AgentCapability(
+            name="solution-architect",
+            capabilities=[
+                "architecture_design",
+                "refactoring",
+                "complex_implementation",
+            ],
+            max_wip=1,
+            preferred_complexity=["complex"],
+            model="claude-sonnet",
+        ),
+        "data-engineer": AgentCapability(
+            name="data-engineer",
+            capabilities=["data_migration", "schema_design", "database"],
+            max_wip=1,
+            preferred_complexity=["medium", "complex"],
+            model="claude-sonnet",
+        ),
+        "code-reviewer": AgentCapability(
+            name="code-reviewer",
+            capabilities=["code_review", "quality_assurance"],
+            max_wip=3,  # Can review multiple cards
+            preferred_complexity=["simple", "medium", "complex"],
+            model="claude-sonnet",
+        ),
+        "product-owner": AgentCapability(
+            name="product-owner",
+            capabilities=["requirements", "grooming", "acceptance_criteria"],
+            max_wip=5,
+            preferred_complexity=["simple", "medium", "complex"],
+            model="claude-sonnet",
+        ),
+    }
+
+    def __init__(self, custom_agents: Optional[Dict[str, AgentCapability]] = None):
+        """
+        Initialize registry with default + custom agents.
+
+        Note: Prefer using AgentRegistry.from_config() for external configuration.
+
+        Args:
+            custom_agents: Optional dictionary of custom AgentCapability objects
+        """
+        self.agents = self.DEFAULT_AGENTS.copy()
+        if custom_agents:
+            self.agents.update(custom_agents)
+        self._config_source = "hardcoded"
+
+    @classmethod
+    def from_config(
+        cls,
+        workspace: Optional[str] = None,
+        fallback_to_defaults: bool = True,
+    ) -> "AgentRegistry":
+        """
+        Create registry from external YAML configuration.
+
+        Loads agents from:
+        1. config/agents.default.yaml (framework defaults)
+        2. data/workspaces/{workspace}/config/agents.yaml (workspace overrides)
+
+        Args:
+            workspace: Workspace name for workspace-specific config
+            fallback_to_defaults: If True, use hardcoded defaults when no config exists
+
+        Returns:
+            AgentRegistry instance populated from configuration
+
+        Raises:
+            ConfigLoadError: If config loading fails and fallback_to_defaults is False
+        """
+        try:
+            from src.infrastructure.orchestration import ConfigLoader, ConfigLoadError
+
+            loader = ConfigLoader()
+
+            # Check if any config exists
+            if not loader.config_exists() and not loader.config_exists(workspace):
+                if fallback_to_defaults:
+                    logger.info("No agent config found, using hardcoded defaults")
+                    return cls()
+                raise ConfigLoadError("No agent configuration found")
+
+            # Load and convert to AgentCapability objects
+            config_schemas = loader.get_agents(workspace)
+            agents = {}
+            for schema in config_schemas:
+                agents[schema.name] = AgentCapability(
+                    name=schema.name,
+                    capabilities=schema.capabilities,
+                    max_wip=schema.max_wip,
+                    preferred_complexity=schema.preferred_complexity,
+                    model=schema.model,
+                )
+
+            registry = cls(custom_agents=agents)
+            # Replace default agents with config agents
+            registry.agents = agents
+            registry._config_source = (
+                f"config:workspace={workspace}" if workspace else "config:default"
+            )
+
+            logger.info(f"Loaded {len(agents)} agents from {registry._config_source}")
+            return registry
+
+        except ImportError:
+            logger.warning("ConfigLoader not available, using hardcoded defaults")
+            return cls()
+
+        except Exception as e:
+            if fallback_to_defaults:
+                logger.warning(f"Failed to load config ({e}), using hardcoded defaults")
+                return cls()
+            raise
+
+    def get_agent(self, name: str) -> Optional[AgentCapability]:
+        """Get agent by name."""
+        return self.agents.get(name)
+
+    def list_agents(self) -> List[str]:
+        """List all registered agent names."""
+        return list(self.agents.keys())
+
+    def get_agents_for_capability(self, capability: str) -> List[AgentCapability]:
+        """Get agents that have a specific capability."""
+        return [
+            agent for agent in self.agents.values() if capability in agent.capabilities
+        ]
+
+    def get_config_source(self) -> str:
+        """Get the source of the current configuration."""
+        return self._config_source
+
+
+# =============================================================================
+# SCRUM MASTER SERVICE
+# =============================================================================
+
+
+class ScrumMasterService:
+    """
+    Scrum Master Service - Orchestrates agent workflow.
+
+    Responsibilities:
+    1. Auto-assign work to available agents
+    2. Process review handoffs
+    3. Generate standup/status reports
+    4. Capture learning for continuous improvement
+    """
+
+    def __init__(self, workspace: str, agent_registry: Optional[AgentRegistry] = None):
+        """
+        Initialize Scrum Master Service.
+
+        Args:
+            workspace: Workspace identifier
+            agent_registry: Optional custom agent registry
+        """
+        self.workspace = workspace
+        self.registry = agent_registry or AgentRegistry()
+        self._repo: Optional[KanbanRepository] = None
+        self._kanban_svc: Optional[KanbanService] = None
+        self._token_svc: Optional[TokenMetricsService] = None
+        self._learnings: List[LearningEntry] = []
+
+    def _get_repo(self) -> KanbanRepository:
+        """Get or create repository connection."""
+        if not self._repo:
+            self._repo = KanbanRepository(self.workspace)
+            self._repo.connect()
+        return self._repo
+
+    def _get_kanban_service(self) -> KanbanService:
+        """Get or create Kanban service."""
+        if not self._kanban_svc:
+            self._kanban_svc = KanbanService(self.workspace)
+        return self._kanban_svc
+
+    def _get_token_service(self) -> TokenMetricsService:
+        """Get or create Token Metrics service."""
+        if not self._token_svc:
+            self._token_svc = TokenMetricsService(self.workspace)
+        return self._token_svc
+
+    def close(self) -> None:
+        """Close connections."""
+        if self._repo:
+            self._repo.close()
+            self._repo = None
+        if self._kanban_svc:
+            self._kanban_svc.close()
+            self._kanban_svc = None
+        if self._token_svc:
+            self._token_svc.close()
+            self._token_svc = None
+
+    def __enter__(self) -> "ScrumMasterService":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    # =========================================================================
+    # AUTO-ASSIGN WORK
+    # =========================================================================
+
+    def get_available_agents(self) -> List[str]:
+        """
+        Get list of agents that are available for work.
+
+        An agent is available if they have fewer cards in DOING
+        than their max_wip limit.
+
+        Returns:
+            List of available agent names
+        """
+        repo = self._get_repo()
+        available = []
+
+        for agent_name, agent_config in self.registry.agents.items():
+            # Count cards in DOING for this agent
+            doing_cards = repo.list_cards(status="doing", agent=agent_name)
+
+            if len(doing_cards) < agent_config.max_wip:
+                available.append(agent_name)
+
+        return available
+
+    def get_agents_wip_status(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Get WIP status for all agents.
+
+        Returns:
+            Dict mapping agent name to WIP info
+        """
+        repo = self._get_repo()
+        status = {}
+
+        for agent_name, agent_config in self.registry.agents.items():
+            doing_cards = repo.list_cards(status="doing", agent=agent_name)
+            status[agent_name] = {
+                "current_wip": len(doing_cards),
+                "max_wip": agent_config.max_wip,
+                "available": len(doing_cards) < agent_config.max_wip,
+                "cards": [c.id for c in doing_cards],
+            }
+
+        return status
+
+    def auto_assign_work(
+        self, target_agents: Optional[List[str]] = None, dry_run: bool = False
+    ) -> List[AssignmentResult]:
+        """
+        Automatically assign READY cards to available agents.
+
+        Algorithm:
+        1. Get available agents (WIP < max_wip)
+        2. For each available agent, get next READY card by priority
+        3. Start the card with the agent
+        4. Capture learning about the assignment
+
+        Args:
+            target_agents: Optional list of specific agents to assign to
+            dry_run: If True, only report what would be done
+
+        Returns:
+            List of assignment results
+        """
+        repo = self._get_repo()
+        kanban_svc = self._get_kanban_service()
+        results = []
+
+        # Get available agents
+        available = self.get_available_agents()
+        if target_agents:
+            available = [a for a in available if a in target_agents]
+
+        if not available:
+            return [
+                AssignmentResult(
+                    success=False, error="no_available_agents:all agents at WIP limit"
+                )
+            ]
+
+        for agent_name in available:
+            # Get next ready card
+            next_card = repo.get_next_ready_card(agent_name)
+
+            if not next_card:
+                results.append(
+                    AssignmentResult(
+                        success=False,
+                        agent=agent_name,
+                        error="no_ready_cards:backlog empty or all cards assigned",
+                    )
+                )
+                continue
+
+            if dry_run:
+                results.append(
+                    AssignmentResult(
+                        success=True,
+                        agent=agent_name,
+                        card_id=next_card.id,
+                        learning=f"[DRY RUN] Would assign {next_card.id} to {agent_name}",
+                    )
+                )
+                continue
+
+            # Start the card
+            result = kanban_svc.start_card(next_card.id, agent_name)
+
+            if result.success:
+                learning = self._capture_assignment_learning(agent_name, next_card)
+                results.append(
+                    AssignmentResult(
+                        success=True,
+                        agent=agent_name,
+                        card_id=next_card.id,
+                        learning=learning.insight,
+                    )
+                )
+            else:
+                results.append(
+                    AssignmentResult(
+                        success=False,
+                        agent=agent_name,
+                        card_id=next_card.id,
+                        error=result.error,
+                    )
+                )
+
+        return results
+
+    def _capture_assignment_learning(self, agent: str, card: CardDTO) -> LearningEntry:
+        """Capture learning from assignment for future reference."""
+        learning = LearningEntry(
+            category="assignment",
+            context=f"card:{card.id}:agent:{agent}:priority:{card.priority}",
+            insight=f"Assigned {card.id} ({card.priority} priority, {card.story_points or '?'}pts) to {agent}",
+            metadata={
+                "card_id": card.id,
+                "agent": agent,
+                "priority": card.priority,
+                "story_points": card.story_points,
+                "epic_id": card.epic_id,
+                "sprint_id": card.sprint_id,
+            },
+        )
+        self._learnings.append(learning)
+        return learning
+
+    # =========================================================================
+    # PROCESS REVIEWS
+    # =========================================================================
+
+    def get_pending_reviews(self) -> List[CardDTO]:
+        """Get all cards pending review."""
+        repo = self._get_repo()
+        return repo.list_cards(status="review")
+
+    def process_reviews(
+        self, auto_approve_tested: bool = False, dry_run: bool = False
+    ) -> List[ReviewHandoffResult]:
+        """
+        Process review handoffs.
+
+        This method helps manage the review cycle:
+        1. Lists cards in REVIEW status
+        2. For auto_approve_tested: moves TESTED to DONE
+        3. Captures learning about review patterns
+
+        Note: Actual review approval/rejection must be done by reviewers.
+        This method facilitates the handoff, not the review itself.
+
+        Args:
+            auto_approve_tested: If True, auto-move TESTED cards to DONE
+            dry_run: If True, only report what would be done
+
+        Returns:
+            List of handoff results
+        """
+        repo = self._get_repo()
+        kanban_svc = self._get_kanban_service()
+        results = []
+
+        # Process TESTED → DONE if enabled
+        if auto_approve_tested:
+            tested_cards = repo.list_cards(status="tested")
+            for card in tested_cards:
+                if dry_run:
+                    results.append(
+                        ReviewHandoffResult(
+                            card_id=card.id,
+                            action="approved",
+                            from_status="tested",
+                            to_status="done",
+                            learning=f"[DRY RUN] Would move {card.id} to done",
+                        )
+                    )
+                else:
+                    result = kanban_svc.move_card(card.id, "done")
+                    if result.success:
+                        learning = self._capture_review_learning(card, "approved")
+                        results.append(
+                            ReviewHandoffResult(
+                                card_id=card.id,
+                                action="approved",
+                                from_status="tested",
+                                to_status="done",
+                                learning=learning.insight,
+                            )
+                        )
+
+        # Report on cards in REVIEW waiting for reviewer
+        review_cards = repo.list_cards(status="review")
+        for card in review_cards:
+            results.append(
+                ReviewHandoffResult(
+                    card_id=card.id,
+                    action="pending_review",
+                    from_status="review",
+                    to_status="review",
+                    iteration=card.review_iterations,
+                    feedback=f"Awaiting review (iteration {card.review_iterations + 1}/{card.max_review_iterations})",
+                )
+            )
+
+        return results
+
+    def assign_reviewer(
+        self, card_id: str, reviewer: Optional[str] = None
+    ) -> ServiceResult:
+        """
+        Assign a reviewer to a card in REVIEW status.
+
+        If no reviewer specified, picks one that is:
+        1. Different from the implementer (self-review prevention)
+        2. Has review capability
+        3. Has capacity (WIP < max_wip)
+
+        Args:
+            card_id: Card to assign reviewer
+            reviewer: Optional specific reviewer
+
+        Returns:
+            ServiceResult with assignment details
+        """
+        repo = self._get_repo()
+        card = repo.get_card(card_id)
+
+        if not card:
+            return ServiceResult(success=False, error="card_not_found")
+
+        if card.status != "review":
+            return ServiceResult(
+                success=False, error=f"card_not_in_review:status={card.status}"
+            )
+
+        # If reviewer not specified, find one
+        if not reviewer:
+            # Get agents with review capability
+            review_agents = self.registry.get_agents_for_capability("code_review")
+
+            for agent in review_agents:
+                # Skip implementer (self-review prevention)
+                if agent.name == card.assigned_agent:
+                    continue
+
+                # Check availability
+                doing_cards = repo.list_cards(status="review", agent=agent.name)
+                # Note: for reviewers, we count review cards not doing cards
+                if len(doing_cards) < agent.max_wip:
+                    reviewer = agent.name
+                    break
+
+            if not reviewer:
+                return ServiceResult(
+                    success=False,
+                    error="no_available_reviewer:all reviewers busy or same as implementer",
+                )
+
+        # Validate reviewer is not implementer
+        if reviewer.lower() == (card.assigned_agent or "").lower():
+            return ServiceResult(
+                success=False,
+                error="self_review_not_allowed:reviewer cannot be implementer",
+            )
+
+        # Log the assignment (we don't have a reviewer field in card, so use activity)
+        repo.log_activity(
+            card_id,
+            "scrum-master",
+            "reviewer_assigned",
+            f"Assigned {reviewer} as reviewer",
+        )
+
+        learning = LearningEntry(
+            category="review",
+            context=f"card:{card_id}:reviewer:{reviewer}",
+            insight=f"Assigned {reviewer} to review {card_id} (implemented by {card.assigned_agent})",
+            metadata={
+                "card_id": card_id,
+                "reviewer": reviewer,
+                "implementer": card.assigned_agent,
+            },
+        )
+        self._learnings.append(learning)
+
+        return ServiceResult(
+            success=True,
+            data={
+                "card_id": card_id,
+                "reviewer": reviewer,
+                "implementer": card.assigned_agent,
+            },
+        )
+
+    def _capture_review_learning(self, card: CardDTO, action: str) -> LearningEntry:
+        """Capture learning from review action."""
+        learning = LearningEntry(
+            category="review",
+            context=f"card:{card.id}:action:{action}:iterations:{card.review_iterations}",
+            insight=f"Card {card.id} {action} after {card.review_iterations} review iterations",
+            metadata={
+                "card_id": card.id,
+                "action": action,
+                "iterations": card.review_iterations,
+                "agent": card.assigned_agent,
+            },
+        )
+        self._learnings.append(learning)
+        return learning
+
+    # =========================================================================
+    # STANDUP / STATUS
+    # =========================================================================
+
+    def generate_standup(self) -> StandupReport:
+        """
+        Generate daily standup report.
+
+        Includes:
+        - Active sprint info
+        - Cards in progress (per agent)
+        - Cards in review
+        - Blocked cards
+        - Recently completed cards
+        - Available agents
+        - Recommendations
+
+        Returns:
+            StandupReport with current status
+        """
+        repo = self._get_repo()
+
+        # Get active sprint
+        sprints = repo.list_sprints("active")
+        active_sprint = sprints[0] if sprints else None
+
+        sprint_info = None
+        if active_sprint:
+            sprint_info = {
+                "id": active_sprint.id,
+                "name": active_sprint.name,
+                "goal": active_sprint.goal,
+            }
+
+        # Get cards by status
+        doing_cards = repo.list_cards(status="doing")
+        review_cards = repo.list_cards(status="review")
+        blocked_cards = repo.list_cards(status="blocked")
+        done_cards = repo.list_cards(status="done")
+        ready_cards = repo.list_cards(status="ready")
+
+        # Format card info
+        def format_card(c: CardDTO) -> Dict[str, Any]:
+            return {
+                "id": c.id,
+                "title": c.title[:50],
+                "priority": c.priority,
+                "agent": c.assigned_agent,
+                "points": c.story_points,
+            }
+
+        # Get available agents
+        available = self.get_available_agents()
+
+        # Generate recommendations
+        recommendations = []
+
+        if blocked_cards:
+            recommendations.append(
+                f"URGENT: {len(blocked_cards)} cards blocked - need attention"
+            )
+
+        if review_cards:
+            recommendations.append(f"{len(review_cards)} cards awaiting review")
+
+        if ready_cards and available:
+            recommendations.append(
+                f"{len(ready_cards)} cards ready, {len(available)} agents available - can assign work"
+            )
+
+        if not ready_cards and doing_cards:
+            recommendations.append("Backlog empty - need to groom more cards")
+
+        # Check for stale reviews (multiple iterations)
+        for card in review_cards:
+            if card.review_iterations >= 2:
+                recommendations.append(
+                    f"Card {card.id} on review iteration {card.review_iterations} - may need escalation"
+                )
+
+        # Get token metrics summary
+        token_metrics = None
+        try:
+            token_svc = self._get_token_service()
+            summary = token_svc.get_workspace_summary()
+            token_metrics = {
+                "total_tokens": summary.total_tokens,
+                "total_cost_usd": summary.total_cost_usd,
+                "records_count": summary.records_count,
+            }
+            # Add token-related recommendations
+            if summary.total_cost_usd > 1.0:
+                recommendations.append(
+                    f"Token cost: ${summary.total_cost_usd:.2f} - monitor spending"
+                )
+        except Exception:
+            pass  # Token metrics are optional
+
+        return StandupReport(
+            workspace=self.workspace,
+            generated_at=datetime.now().isoformat(),
+            sprint=sprint_info,
+            cards_in_progress=[format_card(c) for c in doing_cards],
+            cards_in_review=[format_card(c) for c in review_cards],
+            cards_blocked=[format_card(c) for c in blocked_cards],
+            cards_done_today=[format_card(c) for c in done_cards[:5]],  # Last 5
+            available_agents=available,
+            recommendations=recommendations,
+            token_metrics=token_metrics,
+        )
+
+    # =========================================================================
+    # LEARNING CAPTURE
+    # =========================================================================
+
+    def get_learnings(self) -> List[LearningEntry]:
+        """Get all learnings captured this session."""
+        return self._learnings.copy()
+
+    def export_learnings_for_context_memory(self) -> List[Dict[str, Any]]:
+        """
+        Export learnings in format suitable for context-memory.
+
+        Returns:
+            List of dicts ready for context-memory note creation
+        """
+        exports = []
+        for learning in self._learnings:
+            exports.append(
+                {
+                    "category": f"scrum-master:{learning.category}",
+                    "content": learning.insight,
+                    "metadata": {
+                        **learning.metadata,
+                        "context": learning.context,
+                        "timestamp": learning.timestamp,
+                        "workspace": self.workspace,
+                    },
+                }
+            )
+        return exports
+
+    def save_learnings_to_context_memory(self) -> int:
+        """
+        Save all learnings to context-memory.
+
+        Uses context_memory CLI to persist learnings for future agent reference.
+
+        Returns:
+            Number of learnings saved
+        """
+        import subprocess
+
+        learnings = self.export_learnings_for_context_memory()
+        saved = 0
+
+        for learning in learnings:
+            try:
+                # Format metadata as key=value pairs
+                metadata_str = " ".join(
+                    f"--meta {k}={v}"
+                    for k, v in learning["metadata"].items()
+                    if isinstance(v, (str, int, float))
+                )
+
+                cmd = (
+                    f"python scripts/context_memory_cli.py note add "
+                    f'-c "{learning["category"]}" '
+                    f'-t "{learning["content"][:200]}" '
+                    f"-w {self.workspace} "
+                    f"{metadata_str}"
+                )
+
+                result = subprocess.run(
+                    cmd, shell=True, capture_output=True, text=True, timeout=10
+                )
+
+                if result.returncode == 0:
+                    saved += 1
+                else:
+                    logger.warning(f"Failed to save learning: {result.stderr}")
+
+            except Exception as e:
+                logger.warning(f"Error saving learning: {e}")
+
+        return saved
+
+    # =========================================================================
+    # TOKEN METRICS
+    # =========================================================================
+
+    def record_token_usage(
+        self,
+        agent: str,
+        operation: str,
+        input_tokens: int,
+        output_tokens: int,
+        card_id: Optional[str] = None,
+        sprint_id: Optional[str] = None,
+        model: str = "claude-sonnet",
+        session_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Record token usage for an agent operation.
+
+        Convenience method that delegates to TokenMetricsService.
+
+        Args:
+            agent: Agent that consumed tokens
+            operation: Type of operation
+            input_tokens: Number of input tokens
+            output_tokens: Number of output tokens
+            card_id: Optional card ID
+            sprint_id: Optional sprint ID
+            model: LLM model used
+            session_id: Session identifier
+
+        Returns:
+            Dict with usage_id, total_tokens, cost_usd
+        """
+        token_svc = self._get_token_service()
+        result = token_svc.record_usage(
+            agent=agent,
+            operation=operation,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            card_id=card_id,
+            sprint_id=sprint_id,
+            model=model,
+            session_id=session_id,
+        )
+
+        if result.success:
+            return result.data
+        return {"error": result.error}
+
+    def get_token_summary(self) -> Dict[str, Any]:
+        """
+        Get token usage summary for workspace.
+
+        Returns:
+            Dict with total_tokens, total_cost_usd, by_agent, by_operation
+        """
+        token_svc = self._get_token_service()
+        report = token_svc.get_workspace_summary()
+
+        return {
+            "workspace": self.workspace,
+            "total_tokens": report.total_tokens,
+            "total_cost_usd": report.total_cost_usd,
+            "records_count": report.records_count,
+            "details": report.details,
+            "recommendations": report.recommendations,
+        }
+
+    def get_agent_token_report(self, agent: Optional[str] = None) -> TokenReport:
+        """
+        Get token usage report by agent.
+
+        Args:
+            agent: Optional specific agent
+
+        Returns:
+            TokenReport with agent metrics
+        """
+        token_svc = self._get_token_service()
+        return token_svc.get_agent_report(agent)
+
+    def get_sprint_token_report(self, sprint_id: Optional[str] = None) -> TokenReport:
+        """
+        Get token usage report by sprint.
+
+        Args:
+            sprint_id: Optional specific sprint
+
+        Returns:
+            TokenReport with sprint metrics
+        """
+        token_svc = self._get_token_service()
+        return token_svc.get_sprint_report(sprint_id)
+
+    # =========================================================================
+    # SPRINT LIFECYCLE
+    # =========================================================================
+
+    def get_sprint_status(self) -> Dict[str, Any]:
+        """Get current sprint status with metrics."""
+        repo = self._get_repo()
+
+        sprints = repo.list_sprints("active")
+        if not sprints:
+            return {"error": "no_active_sprint"}
+
+        sprint = sprints[0]
+        stats = repo.get_board_stats(sprint.id)
+
+        # Calculate progress
+        total = sum(stats.values())
+        done = stats.get("done", 0)
+        in_progress = (
+            stats.get("doing", 0) + stats.get("review", 0) + stats.get("tested", 0)
+        )
+
+        return {
+            "sprint_id": sprint.id,
+            "name": sprint.name,
+            "goal": sprint.goal,
+            "status": sprint.status,
+            "cards": {
+                "total": total,
+                "done": done,
+                "in_progress": in_progress,
+                "remaining": total - done - in_progress,
+            },
+            "progress_pct": (done / total * 100) if total > 0 else 0,
+            "board_stats": stats,
+        }