Developer Productivity Agent.

# scripts/profile_codebase.py
import json, subprocess
from pathlib import Path
from collections import Counter

def profile() -> dict:
    profile = {"languages": [], "framework": None, "key_dirs": [], "top_imports": []}

    if Path("package.json").exists():
        pkg = json.loads(Path("package.json").read_text())
        profile["languages"].append("typescript")
        deps = list((pkg.get("dependencies") or {}).keys())
        if "next" in deps: profile["framework"] = "next.js"
        elif "react" in deps: profile["framework"] = "react"

    if Path("pyproject.toml").exists():
        profile["languages"].append("python")

    # Top 50 imported modules across the repo
    imports = Counter()
    for ext, regex in [("ts", r"^import .* from ['\"]"), ("py", r"^(import|from) ")]:
        for f in Path(".").rglob(f"*.{ext}"):
            if "node_modules" in f.parts or ".venv" in f.parts:
                continue
            for line in f.read_text(errors="ignore").splitlines()[:50]:
                if line.startswith(("import", "from")):
                    imports[line.split()[1].rstrip(',')] += 1
    profile["top_imports"] = [m for m, _ in imports.most_common(50)]

    profile["key_dirs"] = [
        p.name for p in Path(".").iterdir()
        if p.is_dir() and not p.name.startswith(".") and p.name not in ("node_modules", "dist")
    ]

    Path(".claude/context-cache.json").write_text(json.dumps(profile, indent=2))
    return profile

if __name__ == "__main__":
    print(json.dumps(profile(), indent=2))

# Wrong. Read everything, hope for the best
# for f in glob('**/*.ts'):
#     content = read_file(f)  # 1000 reads, context floods, agent gets lost

# Right. Grep first to locate, then Read only matched
def find_function_usages(name: str) -> list[dict]:
    """Grep + Glob first, Read only what matched."""
    # Step 1: Grep finds the pattern across the repo
    grep_result = run_tool("Grep", {
        "pattern": rf"\b{name}\b",
        "type": "ts",
        "output_mode": "files_with_matches",  # NOT 'content'. Too verbose
    })
    matched_files = grep_result["files"]  # e.g. 12 files, not 1000

    # Step 2: Glob filters further if needed
    if len(matched_files) > 30:
        # Too many. Narrow by path
        matched_files = [f for f in matched_files if "src/" in f]

    # Step 3: Read only the files that matched
    file_contents = {}
    for f in matched_files[:20]:  # cap at 20 to bound context
        file_contents[f] = run_tool("Read", {"file_path": f})

    return [{"file": f, "content": c} for f, c in file_contents.items()]

# Specialist subagent definitions
SPECIALISTS = {
    "reader": {
        "system": "You are a codebase reader. Use Grep+Glob to locate, "
                  "then Read only what matched. Never modify files.",
        "tools": ["Read", "Grep", "Glob"],
    },
    "reviewer": {
        "system": "You are an independent code reviewer. Fresh context, "
                  "no carry-over from the writer. Check against .claude/rules/.",
        "tools": ["Read", "Grep", "Bash(npm test, npm run lint, ruff check)"],
    },
    "docgen": {
        "system": "You generate docs from source. Use the code as ground truth.",
        "tools": ["Read", "Write(docs/**, *.md)", "Glob"],
    },
}

def spawn_specialist(role: str, task: str) -> dict:
    spec = SPECIALISTS[role]
    return client.messages.create(
        model="claude-sonnet-4.5",
        max_tokens=2048,
        system=spec["system"],
        tools=load_tools(spec["tools"]),
        messages=[{"role": "user", "content": task}],
    )

# Lead agent coordinates
def refactor_function(name: str, new_name: str):
    locations = spawn_specialist("reader", f"Find all usages of {name}")
    proposed_diff = generate_renames(locations, new_name)
    review = spawn_specialist("reviewer", f"Review this diff: {proposed_diff}")
    if review["verdict"] != "approve":
        return {"status": "review_failed", "issues": review["issues"]}
    return {"status": "ready_to_apply", "diff": proposed_diff, "review": review}

def review_diff_independently(diff: str, file_paths: list[str]) -> dict:
    """Spawn a fresh-context reviewer. NO carry-over from the writer."""
    REVIEWER_SYSTEM = """You are an independent code reviewer.

You have NO context from the agent that wrote this diff. You see only:
1. The diff itself
2. The current state of the affected files
3. The project rules in .claude/rules/

Check for:
- Style conformance (matches .claude/rules/)
- Test coverage (does the diff change behavior without test changes?)
- Type safety (any unsafe casts or 'any' added?)
- API breakage (did a public signature change?)

Return JSON: { verdict: 'approve'|'request_changes', issues: [{ file, line, severity, message }], summary }"""

    # CRITICAL: fresh messages array, fresh system, fresh tool list
    return client.messages.create(
        model="claude-sonnet-4.5",
        max_tokens=2048,
        system=REVIEWER_SYSTEM,
        tools=[READ_TOOL, GREP_TOOL, BASH_TEST_LINT_TOOL],  # no Edit/Write
        messages=[{
            "role": "user",
            "content": f"Diff to review:\n{diff}\n\nAffected files: {file_paths}",
        }],
    )

# .claude/scratchpad.md. Agent working memory across turns
SCRATCHPAD = Path(".claude/scratchpad.md")

def update_scratchpad(section: str, content: str):
    """Append-and-replace by section. Trims old entries past 20."""
    if not SCRATCHPAD.exists():
        SCRATCHPAD.write_text("# Agent scratchpad\n\n")
    text = SCRATCHPAD.read_text()
    # Replace existing section or append
    marker = f"## {section}"
    if marker in text:
        # Replace existing section
        before, _, rest = text.partition(marker)
        _, _, after = rest.partition("\n## ")
        new = before + marker + "\n" + content + "\n## " + after if "\n## " in rest else before + marker + "\n" + content
    else:
        new = text + "\n" + marker + "\n" + content
    SCRATCHPAD.write_text(new)

# Usage in the agent loop
update_scratchpad(
    "Rename Task: FooBar -> BazQux",
    "Files matched: 12. Already updated: 8. Remaining: src/old.ts, src/legacy.ts.",
)

# Per-extension MCP routing
MCP_BY_EXTENSION = {
    ".ts": ["tsc", "eslint", "prettier"],
    ".tsx": ["tsc", "eslint", "prettier"],
    ".py": ["pyright", "ruff", "black"],
    ".go": ["gopls", "gofmt"],
    ".rs": ["rust-analyzer", "rustfmt"],
}

def select_mcp_servers(file_paths: list[str]) -> list[str]:
    """Pick the minimum set of MCP servers needed for these files."""
    extensions = {Path(f).suffix for f in file_paths}
    servers = set()
    for ext in extensions:
        for server in MCP_BY_EXTENSION.get(ext, []):
            servers.add(server)
    return sorted(servers)

# In the lead agent before spawning the reviewer
def review_with_mcp(diff: str, files: list[str]):
    mcp_servers = select_mcp_servers(files)
    return spawn_specialist(
        "reviewer",
        f"Review diff: {diff}\nUse MCP servers: {mcp_servers}",
    )

from typing import Literal, TypedDict

class ApprovalRequest(TypedDict):
    delegation: str    # what the agent proposes (1 sentence)
    description: str   # the diff + summary of changes
    discernment: dict  # reviewer subagent's verdict + issues
    risk_level: Literal["low", "medium", "high"]

def request_approval(req: ApprovalRequest) -> Literal["approve", "reject"]:
    """4D gate. ALWAYS waits for human input. No auto-approve."""
    print("=" * 60)
    print(f"DELEGATION: {req['delegation']}")
    print(f"\nDESCRIPTION:\n{req['description']}")
    print(f"\nDISCERNMENT (review verdict): {req['discernment']['verdict']}")
    if req['discernment'].get('issues'):
        print(f"  Issues:")
        for issue in req['discernment']['issues']:
            print(f"  - {issue['severity']}: {issue['message']}")
    print(f"\nRISK LEVEL: {req['risk_level']}")
    print("=" * 60)
    print("DILIGENCE: Approve? [y/N]: ", end="")
    return "approve" if input().strip().lower() == "y" else "reject"

# Usage in the lead agent
def apply_refactor_safely(diff: str, files: list[str], reviewer_verdict: dict):
    decision = request_approval({
        "delegation": f"Apply rename refactor across {len(files)} files",
        "description": f"Diff:\n{diff}",
        "discernment": reviewer_verdict,
        "risk_level": "medium" if len(files) > 20 else "low",
    })
    if decision == "approve":
        run_tool("Edit", {"diff": diff})
    else:
        print("Refactor rejected by human; no files changed.")

# Wrong. Regex on prose output
# output = run("git log --oneline -10")
# commits = re.findall(r"^([a-f0-9]{7,}) (.+)$", output, re.M)
# # Breaks when commit message contains a colon or special chars

# Right. Structured output, parse JSON
import json, subprocess

def recent_commits(n: int = 10) -> list[dict]:
    """git log with structured output, no regex needed."""
    raw = subprocess.check_output(
        ["git", "log", f"-{n}",
         "--pretty=format:%H%x09%h%x09%s%x09%an%x09%aI"],
        text=True,
    )
    return [
        dict(zip(["sha", "short", "subject", "author", "date"], line.split("\t")))
        for line in raw.splitlines() if line
    ]

def lint_results(file: str) -> list[dict]:
    """eslint --format json gives a structured contract."""
    raw = subprocess.check_output(
        ["npx", "eslint", "--format", "json", file],
        text=True,
    )
    return json.loads(raw)  # array of { filePath, messages: [{ ruleId, severity, line, message }] }

def pr_diff_files() -> list[str]:
    """gh pr diff --name-only. One file per line, no parsing needed."""
    return subprocess.check_output(
        ["gh", "pr", "diff", "--name-only"],
        text=True,
    ).strip().split("\n")