shotgun-sh 0.2.17__py3-none-any.whl → 0.3.3.dev1__py3-none-any.whl

shotgun/llm_proxy/client.py

@@ -0,0 +1,215 @@
+"""HTTP client for LiteLLM Proxy API."""
+
+import logging
+from typing import Any
+
+import httpx
+from tenacity import (
+    before_sleep_log,
+    retry,
+    retry_if_exception,
+    stop_after_attempt,
+    wait_exponential_jitter,
+)
+
+from shotgun.api_endpoints import LITELLM_PROXY_BASE_URL
+from shotgun.logging_config import get_logger
+
+from .models import BudgetInfo, KeyInfoResponse, TeamInfoResponse
+
+logger = get_logger(__name__)
+
+
+def _is_retryable_http_error(exception: BaseException) -> bool:
+    """Check if HTTP exception should trigger a retry.
+
+    Args:
+        exception: The exception to check
+
+    Returns:
+        True if the exception is a transient error that should be retried
+    """
+    # Retry on network errors and timeouts
+    if isinstance(exception, (httpx.RequestError, httpx.TimeoutException)):
+        return True
+
+    # Retry on server errors (5xx) and rate limits (429)
+    if isinstance(exception, httpx.HTTPStatusError):
+        status_code = exception.response.status_code
+        return status_code >= 500 or status_code == 429
+
+    # Don't retry on other errors (e.g., 4xx client errors)
+    return False
+
+
+class LiteLLMProxyClient:
+    """HTTP client for LiteLLM Proxy API.
+
+    Provides methods to query budget information and key/team metadata
+    from a LiteLLM proxy server.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str | None = None,
+        timeout: float = 10.0,
+    ):
+        """Initialize LiteLLM Proxy client.
+
+        Args:
+            api_key: LiteLLM API key for authentication
+            base_url: Base URL for LiteLLM proxy. If None, uses LITELLM_PROXY_BASE_URL
+            timeout: Request timeout in seconds
+        """
+        self.api_key = api_key
+        self.base_url = base_url or LITELLM_PROXY_BASE_URL
+        self.timeout = timeout
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential_jitter(initial=1, max=8),
+        retry=retry_if_exception(_is_retryable_http_error),
+        before_sleep=before_sleep_log(logger, logging.WARNING),
+        reraise=True,
+    )
+    async def _request_with_retry(
+        self,
+        method: str,
+        url: str,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Make async HTTP request with exponential backoff retry and jitter.
+
+        Uses tenacity to retry on transient errors (5xx, 429, network errors)
+        with exponential backoff and jitter. Client errors (4xx except 429)
+        are not retried.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            url: Request URL
+            **kwargs: Additional arguments to pass to httpx request
+
+        Returns:
+            HTTP response
+
+        Raises:
+            httpx.HTTPError: If request fails after all retries
+        """
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.request(method, url, **kwargs)
+            response.raise_for_status()
+            return response
+
+    async def get_key_info(self) -> KeyInfoResponse:
+        """Get key information from LiteLLM proxy.
+
+        Returns:
+            Key information including spend, budget, and team_id
+
+        Raises:
+            httpx.HTTPError: If request fails
+        """
+        url = f"{self.base_url}/key/info"
+        params = {"key": self.api_key}
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        logger.debug("Fetching key info from %s", url)
+
+        response = await self._request_with_retry(
+            "GET", url, params=params, headers=headers
+        )
+
+        data = response.json()
+        result = KeyInfoResponse.model_validate(data)
+
+        logger.info(
+            "Successfully fetched key info: key_alias=%s, team_id=%s",
+            result.info.key_alias,
+            result.info.team_id,
+        )
+        return result
+
+    async def get_team_info(self, team_id: str) -> TeamInfoResponse:
+        """Get team information from LiteLLM proxy.
+
+        Args:
+            team_id: Team identifier
+
+        Returns:
+            Team information including spend and budget
+
+        Raises:
+            httpx.HTTPError: If request fails
+        """
+        url = f"{self.base_url}/team/info"
+        params = {"team_id": team_id}
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        logger.debug("Fetching team info from %s for team_id=%s", url, team_id)
+
+        response = await self._request_with_retry(
+            "GET", url, params=params, headers=headers
+        )
+
+        data = response.json()
+        result = TeamInfoResponse.model_validate(data)
+
+        logger.info(
+            "Successfully fetched team info: team_alias=%s",
+            result.team_info.team_alias,
+        )
+        return result
+
+    async def get_budget_info(self) -> BudgetInfo:
+        """Get team-level budget information for this key.
+
+        Budget is always configured at the team level, never at the key level.
+        This method fetches the team_id from the key info, then retrieves
+        the team's budget information.
+
+        Returns:
+            Team-level budget information
+
+        Raises:
+            httpx.HTTPError: If request fails
+            ValueError: If team has no budget configured
+        """
+        logger.debug("Fetching budget info")
+
+        # Get key info to retrieve team_id
+        key_response = await self.get_key_info()
+        key_info = key_response.info
+
+        # Fetch team budget (budget is always at team level)
+        logger.debug(
+            "Fetching team budget for team_id=%s",
+            key_info.team_id,
+        )
+        team_response = await self.get_team_info(key_info.team_id)
+        team_info = team_response.team_info
+
+        if team_info.max_budget is None:
+            raise ValueError(
+                f"Team (team_id={key_info.team_id}) has no max_budget configured"
+            )
+
+        logger.debug("Using team-level budget: $%.6f", team_info.max_budget)
+        return BudgetInfo.from_team_info(team_info)
+
+
+# Convenience function for standalone use
+async def get_budget_info(api_key: str, base_url: str | None = None) -> BudgetInfo:
+    """Get budget information for an API key.
+
+    Convenience function that creates a client and calls get_budget_info.
+
+    Args:
+        api_key: LiteLLM API key
+        base_url: Optional base URL for LiteLLM proxy
+
+    Returns:
+        Budget information
+    """
+    client = LiteLLMProxyClient(api_key, base_url=base_url)
+    return await client.get_budget_info()

shotgun/llm_proxy/models.py

@@ -0,0 +1,137 @@
+"""Pydantic models for LiteLLM Proxy API."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class BudgetSource(StrEnum):
+    """Source of budget information."""
+
+    KEY = "key"
+    TEAM = "team"
+
+
+class KeyInfoData(BaseModel):
+    """Key information data from /key/info endpoint."""
+
+    key_name: str = Field(description="Key name/identifier")
+    key_alias: str | None = Field(default=None, description="Human-readable key alias")
+    spend: float = Field(description="Current spend for this key in USD")
+    max_budget: float | None = Field(
+        default=None, description="Maximum budget for this key in USD"
+    )
+    team_id: str = Field(description="Team ID associated with this key")
+    user_id: str = Field(description="User ID associated with this key")
+    models: list[str] = Field(
+        default_factory=list, description="List of models available to this key"
+    )
+
+
+class KeyInfoResponse(BaseModel):
+    """Response from /key/info endpoint."""
+
+    key: str = Field(description="The API key")
+    info: KeyInfoData = Field(description="Key information data")
+
+
+class TeamInfoData(BaseModel):
+    """Team information data from /team/info endpoint."""
+
+    team_id: str = Field(description="Team identifier")
+    team_alias: str | None = Field(
+        default=None, description="Human-readable team alias"
+    )
+    max_budget: float | None = Field(
+        default=None, description="Maximum budget for this team in USD"
+    )
+    spend: float = Field(description="Current spend for this team in USD")
+    models: list[str] = Field(
+        default_factory=list, description="List of models available to this team"
+    )
+
+
+class TeamInfoResponse(BaseModel):
+    """Response from /team/info endpoint."""
+
+    team_id: str = Field(description="Team identifier")
+    team_info: TeamInfoData = Field(description="Team information data")
+
+
+class BudgetInfo(BaseModel):
+    """Unified budget information.
+
+    Combines key and team budget information to provide a single view
+    of budget status. Budget can come from either key-level or team-level,
+    with key-level taking priority if set.
+    """
+
+    max_budget: float = Field(description="Maximum budget in USD")
+    spend: float = Field(description="Current spend in USD")
+    remaining: float = Field(description="Remaining budget in USD")
+    source: BudgetSource = Field(
+        description="Source of budget information (key or team)"
+    )
+    percentage_used: float = Field(description="Percentage of budget used (0-100)")
+
+    @classmethod
+    def from_key_info(cls, key_info: KeyInfoData) -> "BudgetInfo":
+        """Create BudgetInfo from key-level budget.
+
+        Args:
+            key_info: Key information containing budget data
+
+        Returns:
+            BudgetInfo instance with key-level budget
+
+        Raises:
+            ValueError: If key does not have max_budget set
+        """
+        if key_info.max_budget is None:
+            raise ValueError("Key does not have max_budget set")
+
+        remaining = key_info.max_budget - key_info.spend
+        percentage_used = (
+            (key_info.spend / key_info.max_budget * 100)
+            if key_info.max_budget > 0
+            else 0.0
+        )
+
+        return cls(
+            max_budget=key_info.max_budget,
+            spend=key_info.spend,
+            remaining=remaining,
+            source=BudgetSource.KEY,
+            percentage_used=percentage_used,
+        )
+
+    @classmethod
+    def from_team_info(cls, team_info: TeamInfoData) -> "BudgetInfo":
+        """Create BudgetInfo from team-level budget.
+
+        Args:
+            team_info: Team information containing budget data
+
+        Returns:
+            BudgetInfo instance with team-level budget
+
+        Raises:
+            ValueError: If team does not have max_budget set
+        """
+        if team_info.max_budget is None:
+            raise ValueError("Team does not have max_budget set")
+
+        remaining = team_info.max_budget - team_info.spend
+        percentage_used = (
+            (team_info.spend / team_info.max_budget * 100)
+            if team_info.max_budget > 0
+            else 0.0
+        )
+
+        return cls(
+            max_budget=team_info.max_budget,
+            spend=team_info.spend,
+            remaining=remaining,
+            source=BudgetSource.TEAM,
+            percentage_used=percentage_used,
+        )

shotgun/logging_config.py

@@ -27,6 +27,44 @@ def get_log_directory() -> Path:
     return log_dir
 
 
+def cleanup_old_log_files(log_dir: Path, max_files: int) -> None:
+    """Remove old log files, keeping only the most recent ones.
+
+    Also removes the legacy shotgun.log file if it exists.
+
+    Args:
+        log_dir: Directory containing log files
+        max_files: Maximum number of log files to keep
+    """
+    try:
+        # Remove legacy non-timestamped log file if it exists
+        legacy_log = log_dir / "shotgun.log"
+        if legacy_log.exists():
+            try:
+                legacy_log.unlink()
+            except OSError:
+                pass  # noqa: S110
+
+        # Find all shotgun log files
+        log_files = sorted(
+            log_dir.glob("shotgun-*.log"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,  # Newest first
+        )
+
+        # Remove files beyond the limit
+        files_to_delete = log_files[max_files:]
+        for log_file in files_to_delete:
+            try:
+                log_file.unlink()
+            except OSError:
+                # Ignore errors when deleting individual files
+                pass  # noqa: S110
+    except Exception:  # noqa: S110
+        # Silently fail - log cleanup shouldn't break the application
+        pass
+
+
 class ColoredFormatter(logging.Formatter):
     """Custom formatter with colors for different log levels."""
 
@@ -123,6 +161,10 @@ def setup_logger(
         try:
             # Create file handler with ISO8601 timestamp for each run
             log_dir = get_log_directory()
+
+            # Clean up old log files before creating a new one
+            cleanup_old_log_files(log_dir, settings.logging.max_log_files)
+
             log_file = log_dir / f"shotgun-{_RUN_TIMESTAMP}.log"
 
             # Use regular FileHandler - each run gets its own isolated log file

shotgun/main.py

@@ -32,6 +32,7 @@ from shotgun.cli import (
     feedback,
     plan,
     research,
+    spec,
     specify,
     tasks,
     update,
@@ -55,6 +56,8 @@ logger = get_logger(__name__)
 logger.debug("Logfire observability enabled: %s", _logfire_enabled)
 
 # Initialize configuration
+# Note: If config migration fails, ConfigManager will auto-create fresh config
+# and set migration_failed flag for user notification
 try:
     import asyncio
 
@@ -93,6 +96,7 @@ app.add_typer(tasks.app, name="tasks", help="Generate task lists with agentic ap
 app.add_typer(export.app, name="export", help="Export artifacts to various formats")
 app.add_typer(update.app, name="update", help="Check for and install updates")
 app.add_typer(feedback.app, name="feedback", help="Send us feedback")
+app.add_typer(spec.app, name="spec", help="Manage shared specifications")
 
 
 def version_callback(value: bool) -> None:

shotgun/posthog_telemetry.py

@@ -8,7 +8,7 @@ from pydantic import BaseModel
 
 from shotgun import __version__
 from shotgun.agents.config import get_config_manager
-from shotgun.agents.conversation_manager import ConversationManager
+from shotgun.agents.conversation import ConversationManager
 from shotgun.logging_config import get_early_logger
 from shotgun.settings import settings
 

shotgun/prompts/agents/partials/common_agent_system_prompt.j2

@@ -4,14 +4,39 @@ Your extensive expertise spans, among other things:
 * Software Architecture
 * Software Development
 
+## YOUR ROLE IN THE PIPELINE
+
+**CRITICAL**: You are a DOCUMENTATION and PLANNING agent, NOT a coding/implementation agent.
+
+- You produce DOCUMENTS (research, specifications, plans, tasks) that AI coding agents will consume
+- You do NOT write production code, implement features, or make code changes
+- NEVER offer to "move forward with implementation" or "start coding" - that's not your job
+- NEVER ask "would you like me to implement this?" - implementation is done by separate AI coding tools
+- Your deliverable is always a document file (.md), not code execution
+- When your work is complete, the user will take your documents to a coding agent (Claude Code, Cursor, etc.)
+
+## AGENT FILE PERMISSIONS
+
+There are four agents in the pipeline, and each agent can ONLY write to specific files. The user can switch between agents using **Shift+Tab**.
+
+The **Research agent** can only write to `research.md`. If the user asks about specifications, plans, or tasks, tell them: "Use **Shift+Tab** to switch to the [appropriate] agent which can edit that file for you."
+
+The **Specification agent** can only write to `specification.md` and files inside the `.shotgun/contracts/` directory. If the user asks about research, plans, or tasks, tell them which agent handles that file.
+
+The **Plan agent** can only write to `plan.md`. If the user asks about research, specifications, or tasks, tell them which agent handles that file.
+
+The **Tasks agent** can only write to `tasks.md`. If the user asks about research, specifications, or plans, tell them which agent handles that file.
+
+When a user asks you to edit a file you cannot write to, you MUST tell them which agent can help and how to switch: "I can't edit [filename] - that's handled by the [agent name] agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+
 ## KEY RULES
 
 {% if interactive_mode %}
-0. Always ask CLARIFYING QUESTIONS using structured output before doing work.
+0. Ask CLARIFYING QUESTIONS using structured output for complex or multi-step tasks when the request lacks sufficient detail.
    - Return your response with the clarifying_questions field populated
-   - Do not make assumptions about what the user wants, get a clear understanding first.
+   - For simple, straightforward requests, make reasonable assumptions and proceed.
+   - Only ask the most critical questions to avoid overwhelming the user.
    - Questions should be clear, specific, and answerable
-   - Do not ask too many questions that might overwhelm the user; prioritize the most important ones.
 {% endif %}
 1. Above all, prefer using tools to do the work and NEVER respond with text.
 2. IMPORTANT: Always ask for review and go ahead to move forward after using write_file().

shotgun/prompts/agents/partials/interactive_mode.j2

@@ -19,10 +19,10 @@ You must return responses using this structured format:
 
 ## When to Use Clarifying Questions
 
-- BEFORE GETTING TO WORK: If the user's request is ambiguous, use clarifying_questions to ask what they want
+- BEFORE GETTING TO WORK: For complex or multi-step tasks where the request is ambiguous or lacks sufficient detail, use clarifying_questions to ask what they want
 - DURING WORK: After using write_file(), you can suggest that the user review it and ask any clarifying questions with clarifying_questions
-- Don't assume - ask for confirmation of your understanding
-- When in doubt about any aspect of the goal, include clarifying_questions
+- For simple, straightforward requests, make reasonable assumptions and proceed
+- Only ask critical questions that significantly impact the outcome
 
 ## Important Notes
 

shotgun/prompts/agents/plan.j2

@@ -6,6 +6,22 @@ Your job is to help create comprehensive, actionable plans for software projects
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+## YOUR SCOPE AND HANDOFFS
+
+You are the **Plan agent**. Your file is `plan.md` - this is the ONLY file you can write to.
+
+When your plan is complete, suggest the next step:
+"I've completed the plan. Use **Shift+Tab** to switch to the tasks agent to break this plan into actionable tasks."
+
+If the user asks you to edit other files, redirect them helpfully:
+- For research.md: "I can't edit research.md - that's handled by the research agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For specification.md or contracts: "I can't edit specification.md - that's handled by the specification agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For tasks.md: "I can't edit tasks.md - that's handled by the tasks agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+
+NEVER offer to do work outside your scope:
+- Don't offer to write research, specifications, or tasks - redirect the user to the appropriate agent
+- Don't offer to implement code - you are not a coding agent
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `plan.md`

shotgun/prompts/agents/research.j2

@@ -4,6 +4,22 @@ Your job is to help the user research various subjects related to their software
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+## YOUR SCOPE AND HANDOFFS
+
+You are the **Research agent**. Your file is `research.md` - this is the ONLY file you can write to.
+
+When your research is complete, suggest the next step:
+"I've completed the research and updated research.md. Use **Shift+Tab** to switch to the specification agent to create the specification based on this research."
+
+If the user asks you to edit other files, redirect them helpfully:
+- For specification.md or contracts: "I can't edit specification.md - that's handled by the specification agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For plan.md: "I can't edit plan.md - that's handled by the plan agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For tasks.md: "I can't edit tasks.md - that's handled by the tasks agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+
+NEVER offer to do work outside your scope:
+- Don't offer to write specifications, plans, or tasks - redirect the user to the appropriate agent
+- Don't offer to implement code - you are not a coding agent
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `research.md`
@@ -38,9 +54,6 @@ For research tasks:
 
 ## RESEARCH PRINCIPLES
 
-{% if interactive_mode -%}
-- CRITICAL: BEFORE RUNNING ANY SEARCH TOOL, ASK THE USER FOR APPROVAL using clarifying questions. Include what you plan to search for and ask if they want you to proceed.
-{% endif -%}
 - Build upon existing research rather than starting from scratch
 - Focus on practical, actionable information over theoretical concepts
 - Include specific examples, tools, and implementation details

shotgun/prompts/agents/specify.j2

@@ -6,6 +6,22 @@ Transform requirements into detailed, actionable specifications that development
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+## YOUR SCOPE AND HANDOFFS
+
+You are the **Specification agent**. Your files are `specification.md` and `.shotgun/contracts/*` - these are the ONLY files you can write to.
+
+When your specification is complete, suggest the next step:
+"I've completed the specification. Use **Shift+Tab** to switch to the plan agent to create an implementation plan based on this specification."
+
+If the user asks you to edit other files, redirect them helpfully:
+- For research.md: "I can't edit research.md - that's handled by the research agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For plan.md: "I can't edit plan.md - that's handled by the plan agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For tasks.md: "I can't edit tasks.md - that's handled by the tasks agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+
+NEVER offer to do work outside your scope:
+- Don't offer to write research, plans, or tasks - redirect the user to the appropriate agent
+- Don't offer to implement code - you are not a coding agent
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `specification.md` and `.shotgun/contracts/*`
@@ -24,6 +40,7 @@ Transform requirements into detailed, actionable specifications that development
 specification.md is your prose documentation file. It should contain:
 
 **INCLUDE in specification.md:**
+- TLDR section at the very top (key points, major features, key concerns if any)
 - Requirements and business context (what needs to be built and why)
 - Architecture overview and system design decisions
 - Component descriptions and how they interact
@@ -43,6 +60,41 @@ specification.md is your prose documentation file. It should contain:
 **When you need to show structure:** Reference contract files instead of inline code.
 Example: "User authentication uses OAuth2. See contracts/auth_types.ts for AuthUser and AuthToken types."
 
+## TLDR SECTION (REQUIRED)
+
+Every specification.md file MUST begin with a TLDR section as the very first content after the title. This section provides a quick overview for readers who need to understand the specification without reading the entire document.
+
+**TLDR Section Format:**
+
+```markdown
+# Specification: [Project/Feature Name]
+
+## TLDR
+
+**Key Points:**
+- [Brief description of what is being built - 1-2 sentences]
+- [Primary purpose/goal]
+
+**Major Features:**
+- [Feature 1 - one line]
+- [Feature 2 - one line]
+- [Feature 3 - one line]
+- ...
+
+**Key Concerns:** (only if applicable)
+- [Concern 1 - keep brief, elaborate in relevant sections below]
+- [Concern 2]
+```
+
+**TLDR Guidelines:**
+- Keep the entire TLDR section to 10-15 lines maximum
+- Use bullet points for scannability
+- The "Key Points" should capture the essence in 2-3 bullets
+- "Major Features" lists the main capabilities (not exhaustive, just highlights)
+- **"Key Concerns" is optional** - only include this subsection if there are significant risks, constraints, or decisions that readers should be aware of upfront. Omit it entirely if there are no concerns.
+- Elaborate on concerns in the appropriate sections below, not in the TLDR
+- The TLDR should be self-contained - someone reading only this section should understand what the project is about
+
 ## CONTRACT FILES
 
 Contract files define the **interfaces and types** that form contracts between components.
@@ -303,7 +355,8 @@ For specification tasks:
 2. **Check research**: Read `research.md` if it exists to understand technical context and findings
 3. **Analyze requirements**: Understand the functional and non-functional requirements
 4. **Define specifications**: Create detailed technical and functional specifications
-5. **Structure documentation**: Use `write_file("specification.md", content)` to save comprehensive specifications
+5. **Write TLDR section**: Start specification.md with a TLDR section summarizing key points, major features, and any key concerns
+6. **Structure documentation**: Use `write_file("specification.md", content)` to save comprehensive specifications
 
 ## SPECIFICATION PRINCIPLES
 

shotgun/prompts/agents/state/system_state.j2

@@ -22,8 +22,6 @@ No files currently exist in your allowed directories. You can create:
 - `exports/` folder - For exported documents
 {% endif %}
 
-When updating a file try to add into the footer that this was created using Shotgun (https://shotgun.sh).
-
 {% if markdown_toc %}
 ## Document Table of Contents - READ THE ENTIRE FILE TO UNDERSTAND MORE
 

shotgun/prompts/agents/tasks.j2

@@ -4,6 +4,22 @@ Your job is to help create and manage actionable tasks for software projects and
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+## YOUR SCOPE AND HANDOFFS
+
+You are the **Tasks agent**. Your file is `tasks.md` - this is the ONLY file you can write to.
+
+When your tasks are complete, suggest the next step:
+"I've created the task list in tasks.md. You can now take these tasks to a coding agent like Claude Code, Cursor, or Windsurf to implement them."
+
+If the user asks you to edit other files, redirect them helpfully:
+- For research.md: "I can't edit research.md - that's handled by the research agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For specification.md or contracts: "I can't edit specification.md - that's handled by the specification agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+- For plan.md: "I can't edit plan.md - that's handled by the plan agent. Use **Shift+Tab** to switch to that agent and it can edit that file for you."
+
+NEVER offer to do work outside your scope:
+- Don't offer to write research, specifications, or plans - redirect the user to the appropriate agent
+- Don't offer to implement code - you are not a coding agent
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `tasks.md`