emdash-core 0.1.7__py3-none-any.whl

emdash_core/swarm/worktree_manager.py

@@ -0,0 +1,278 @@
+"""Git worktree management for parallel agent execution."""
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from git import Repo
+
+from ..utils.logger import log
+
+
+@dataclass
+class WorktreeInfo:
+    """Information about a created worktree."""
+    path: Path
+    branch: str
+    base_branch: str
+    task_slug: str
+    created_at: str
+    status: str  # pending, active, completed, failed
+
+
+class WorktreeError(Exception):
+    """Error during worktree operations."""
+    pass
+
+
+class WorktreeManager:
+    """Manages Git worktrees for parallel agent execution.
+
+    Creates isolated worktrees under .emdash-worktrees/{task-slug}/
+    with unique branches for each parallel task.
+
+    Example:
+        manager = WorktreeManager(repo_root=Path("."))
+
+        # Create worktree for a task
+        info = manager.create_worktree("add-user-auth", base_branch="main")
+        # -> .emdash-worktrees/add-user-auth/
+        # -> branch: emdash/task-add-user-auth
+
+        # Clean up when done
+        manager.remove_worktree("add-user-auth")
+    """
+
+    WORKTREE_DIR = ".emdash-worktrees"
+    BRANCH_PREFIX = "emdash/task-"
+
+    def __init__(self, repo_root: Path):
+        """Initialize worktree manager.
+
+        Args:
+            repo_root: Root of the main git repository
+        """
+        self.repo_root = repo_root.resolve()
+        self.repo = Repo(self.repo_root)
+        self.worktrees_base = self.repo_root / self.WORKTREE_DIR
+
+    def slugify(self, text: str) -> str:
+        """Convert text to URL-safe slug."""
+        text = text.lower().strip()
+        text = re.sub(r"[^\w\s-]", "", text)
+        text = re.sub(r"[-\s]+", "-", text)
+        return text[:50]
+
+    def _get_default_branch(self) -> str:
+        """Get the default branch name for this repo.
+
+        Tries HEAD, then common names (main, master), then first available branch.
+        """
+        # Try current HEAD branch
+        try:
+            if not self.repo.head.is_detached:
+                return self.repo.active_branch.name
+        except Exception:
+            pass
+
+        # Try common branch names
+        branch_names = [h.name for h in self.repo.heads]
+        for name in ["main", "master", "develop"]:
+            if name in branch_names:
+                return name
+
+        # Use first available branch
+        if branch_names:
+            return branch_names[0]
+
+        # Fallback to HEAD
+        return "HEAD"
+
+    def create_worktree(
+        self,
+        task_name: str,
+        base_branch: str | None = None,
+        force: bool = False,
+    ) -> WorktreeInfo:
+        """Create a new worktree for a task.
+
+        Args:
+            task_name: Human-readable task name or slug
+            base_branch: Branch to base the worktree on (auto-detected if None)
+            force: If True, remove existing worktree first
+
+        Returns:
+            WorktreeInfo with worktree details
+
+        Raises:
+            WorktreeError: If worktree creation fails
+        """
+        slug = self.slugify(task_name)
+        worktree_path = self.worktrees_base / slug
+        branch_name = f"{self.BRANCH_PREFIX}{slug}"
+
+        # Auto-detect base branch if not provided
+        if base_branch is None:
+            base_branch = self._get_default_branch()
+        log.debug(f"Using base branch: {base_branch}")
+
+        # Handle existing worktree
+        if worktree_path.exists():
+            if force:
+                self.remove_worktree(slug)
+            else:
+                raise WorktreeError(f"Worktree already exists: {worktree_path}")
+
+        # Ensure base directory exists
+        self.worktrees_base.mkdir(parents=True, exist_ok=True)
+
+        # Fetch latest if remote exists
+        try:
+            if self.repo.remotes:
+                self.repo.remotes.origin.fetch()
+        except Exception:
+            pass  # No remote or fetch failed, continue with local
+
+        # Delete branch if it exists (from previous run)
+        if branch_name in [h.name for h in self.repo.heads]:
+            self.repo.delete_head(branch_name, force=True)
+
+        # Create worktree with new branch using git command
+        cmd = [
+            "git", "worktree", "add",
+            "-b", branch_name,
+            str(worktree_path),
+            base_branch,
+        ]
+        result = subprocess.run(
+            cmd,
+            cwd=str(self.repo_root),
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            raise WorktreeError(f"Failed to create worktree: {result.stderr}")
+
+        log.info(f"Created worktree at {worktree_path} on branch {branch_name}")
+
+        return WorktreeInfo(
+            path=worktree_path,
+            branch=branch_name,
+            base_branch=base_branch,
+            task_slug=slug,
+            created_at=datetime.now().isoformat(),
+            status="pending",
+        )
+
+    def remove_worktree(self, slug_or_path: str | Path) -> bool:
+        """Remove a worktree and optionally its branch.
+
+        Args:
+            slug_or_path: Task slug or full worktree path
+
+        Returns:
+            True if removed successfully
+        """
+        if isinstance(slug_or_path, Path):
+            worktree_path = slug_or_path
+            slug = worktree_path.name
+        else:
+            slug = slug_or_path
+            worktree_path = self.worktrees_base / slug
+
+        branch_name = f"{self.BRANCH_PREFIX}{slug}"
+
+        # Remove worktree
+        if worktree_path.exists():
+            cmd = ["git", "worktree", "remove", str(worktree_path), "--force"]
+            subprocess.run(cmd, cwd=str(self.repo_root), capture_output=True)
+
+            # If git worktree remove fails, force delete
+            if worktree_path.exists():
+                shutil.rmtree(worktree_path)
+
+        # Prune worktree metadata
+        subprocess.run(
+            ["git", "worktree", "prune"],
+            cwd=str(self.repo_root),
+            capture_output=True,
+        )
+
+        # Delete the branch
+        try:
+            if branch_name in [h.name for h in self.repo.heads]:
+                self.repo.delete_head(branch_name, force=True)
+        except Exception:
+            pass  # Branch may not exist
+
+        log.info(f"Removed worktree {slug}")
+        return True
+
+    def list_worktrees(self) -> list[WorktreeInfo]:
+        """List all active emdash worktrees."""
+        result = subprocess.run(
+            ["git", "worktree", "list", "--porcelain"],
+            cwd=str(self.repo_root),
+            capture_output=True,
+            text=True,
+        )
+
+        worktrees = []
+        current: dict = {}
+
+        for line in result.stdout.strip().split("\n"):
+            if line.startswith("worktree "):
+                current["path"] = Path(line[9:])
+            elif line.startswith("branch refs/heads/"):
+                current["branch"] = line[18:]
+            elif line == "":
+                path = current.get("path")
+                if path and str(self.worktrees_base) in str(path):
+                    worktrees.append(WorktreeInfo(
+                        path=path,
+                        branch=current.get("branch", ""),
+                        base_branch="main",
+                        task_slug=path.name,
+                        created_at="",
+                        status="active",
+                    ))
+                current = {}
+
+        return worktrees
+
+    def cleanup_all(self) -> int:
+        """Remove all emdash worktrees.
+
+        Returns:
+            Number of worktrees removed
+        """
+        worktrees = self.list_worktrees()
+        for wt in worktrees:
+            self.remove_worktree(wt.task_slug)
+
+        # Also clean up the base directory
+        if self.worktrees_base.exists():
+            shutil.rmtree(self.worktrees_base)
+
+        return len(worktrees)
+
+    def get_worktree(self, slug: str) -> Optional[WorktreeInfo]:
+        """Get info for a specific worktree by slug."""
+        worktree_path = self.worktrees_base / slug
+        if not worktree_path.exists():
+            return None
+
+        branch_name = f"{self.BRANCH_PREFIX}{slug}"
+        return WorktreeInfo(
+            path=worktree_path,
+            branch=branch_name,
+            base_branch="main",
+            task_slug=slug,
+            created_at="",
+            status="active",
+        )

emdash_core/templates/__init__.py

@@ -0,0 +1,10 @@
+"""Template loading utilities for emdash."""
+
+from .loader import (
+    load_template,
+    load_template_for_agent,
+    get_template_path,
+    list_templates,
+)
+
+__all__ = ["load_template", "load_template_for_agent", "get_template_path", "list_templates"]

emdash_core/templates/defaults/agent-builder.md.template

@@ -0,0 +1,82 @@
+# Agent Builder Rules
+
+> How we create specialized AI agents for this codebase.
+
+## Purpose
+
+The agent-builder creates custom AGENTS.md profiles by analyzing the codebase, PRs, and review patterns to capture institutional knowledge.
+
+## What to Gather
+
+1. **Related PRs** - Find PRs related to the agent's purpose using keyword search
+2. **Review Patterns** - What reviewers consistently care about (from APPROVED reviews)
+3. **Anti-Patterns** - Things from REQUEST_CHANGES reviews that should be avoided
+4. **Domain Experts** - Authors and reviewers with most activity in the area
+5. **Code Communities** - Clustered areas of related code in the graph
+6. **Entry Points** - Key files and functions relevant to the purpose
+
+## AGENTS.md Format
+
+The output should be Claude Code CLAUDE.md compatible:
+
+```markdown
+# <agent-name>
+
+## Purpose
+Single paragraph defining what this agent does and specializes in.
+
+## Knowledge Context
+### Code Areas
+- Community descriptions from graph analysis
+
+### Key Files
+- List of relevant file paths
+
+## Hints
+1. Best practice from approved reviews
+2. Specific, actionable advice (not generic)
+...
+
+## Things to Avoid
+- (PR #N, @reviewer) Feedback from CHANGES_REQUESTED reviews
+...
+
+## Related PRs
+- **PR #N**: Title (by @author)
+...
+
+## Domain Experts
+- @username (N PRs in this area)
+...
+
+## MCP Tools
+Reference to mcp.json tools.
+```
+
+## Exploration Strategy
+
+1. Start with semantic search for the agent's purpose
+2. Use github_search_prs to find related PRs
+3. For top PRs, extract review comments with github_pr_details
+4. Find communities that contain the relevant code
+5. Identify top contributors from PR authors
+
+## Hint Quality Guidelines
+
+Good hints are:
+- Specific to this codebase (reference actual patterns)
+- Actionable (tell the agent what TO DO)
+- Derived from real review feedback
+- Concise (1-2 sentences each)
+
+Bad hints:
+- Generic advice ("write good tests")
+- Vague guidance ("follow best practices")
+- Not backed by PR evidence
+
+## Things to Avoid
+
+- Generic hints that apply to any project
+- Listing every file touched (focus on patterns)
+- Ignoring negative feedback (REQUEST_CHANGES are valuable)
+- Creating duplicate entries

emdash_core/templates/defaults/focus.md.template

@@ -0,0 +1,115 @@
+# Team Focus Analysis Template
+
+> How we summarize team activity and work-in-progress for stakeholders.
+
+## Purpose
+
+The Team Focus report gives engineering managers and leads a quick understanding of:
+- What the team is actively building
+- Where technical effort is concentrated
+- Who is working on what
+- Patterns and risks worth attention
+
+## Required Sections
+
+### 1. Executive Summary
+
+2-3 sentences capturing the main thrust of team activity. Should answer:
+- What is the primary focus area?
+- What secondary work is happening?
+- What's the overall picture?
+
+**Example:**
+> The team is focused on **AI-driven code generation improvements**, with primary efforts in prompt engineering and content handling. Secondary work involves test infrastructure modernization and bug fixes.
+
+### 2. Work Streams
+
+Group related work by theme. For each stream:
+- **Name the stream** with activity percentage
+- **List hot files** being modified
+- **Explain what's being built** using function/class names
+- **Why it matters** (business/technical impact)
+- **How it fits together** (show call flow if available)
+
+Use code blocks for call graphs:
+```
+FunctionA()
+  → calls FunctionB()
+  → returns to FunctionC()
+```
+
+### 3. PR Analysis
+
+A table showing recent PRs with technical context:
+
+| PR | Author | Code Changes | What It Does |
+|----|--------|--------------|--------------|
+| [PR #123](link) | [@author](link) | `file.ts` | Description of change |
+
+**Requirements:**
+- PRs MUST be linked: `[PR #123](https://github.com/owner/repo/pull/123)`
+- Authors MUST be linked: `[@username](https://github.com/username)`
+- Describe WHAT the code does, not just which files changed
+
+### 4. Key Contributors
+
+A table showing who is working on what:
+
+| Contributor | Commits | Technical Focus | Key PRs |
+|-------------|---------|-----------------|---------|
+| [@name](link) | N | Description of focus area | #PR1, #PR2 |
+
+**Requirements:**
+- Contributors MUST be linked to their GitHub profile
+- Describe their technical focus area, not just file paths
+
+### 5. Technical Insights
+
+Split into positive patterns and areas of attention:
+
+#### Positive Patterns
+- What's working well?
+- Good architectural decisions?
+- Effective patterns emerging?
+
+#### Areas of Attention
+- Risks or concerns?
+- Large changes with missing context?
+- Churn or instability patterns?
+
+#### Recommendations
+- Specific, actionable suggestions
+- Reference specific PRs or patterns
+
+## Link Formatting (REQUIRED)
+
+**All PRs and contributors must be clickable links:**
+
+- PRs: `[PR #123](https://github.com/owner/repo/pull/123)`
+- Contributors: `[@username](https://github.com/username)`
+
+The GitHub repository URL will be provided in the data. Use it to construct proper links.
+
+## Writing Style
+
+- Be specific: name functions, classes, and files
+- Explain WHAT is being built, not just WHERE files are changing
+- Use docstrings and code context to understand purpose
+- Write for an engineering manager audience
+- No vague statements like "improvements to X directory"
+- Use tables for structured data (PRs, contributors)
+- Use code blocks for call graphs and technical flows
+
+## What to Avoid
+
+- Generic descriptions ("working on the codebase")
+- Directory-only references without file specifics
+- Missing links for PRs and contributors
+- Unexplained technical terms
+- Skipping the insights section
+
+
+
+
+
+