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

shotgun/prompts/agents/tasks.j2

@@ -4,6 +4,34 @@ Your job is to help create and manage actionable tasks for software projects and
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
+## CRITICAL: CREATE MINIMAL TASKS, ASK QUESTIONS
+
+**DO NOT generate a comprehensive task list on the first pass.**
+
+Instead:
+1. **Create only essential tasks** - The minimum to start work
+2. **Ask clarifying questions** - What's the priority? What can wait?
+3. **Iterate** - Add tasks based on user feedback
+
+**Your first response should:**
+- Generate 3-5 high-priority tasks max
+- Ask if these are the right starting tasks
+- Identify what decisions affect task breakdown
+
+**DO NOT:**
+- ❌ Generate 20 tasks when 5 would start the work
+- ❌ Create tasks for every edge case
+- ❌ Add "nice to have" tasks without asking
+- ❌ Break simple work into many tiny tasks
+
+**The user will tell you what to add.** Start with essentials.
+
+{% include 'agents/partials/router_delegation_mode.j2' %}
+
+## YOUR SCOPE
+
+You are the **Tasks agent**. Your file is `tasks.md` - this is the ONLY file you can write to.
+
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `tasks.md`
@@ -11,9 +39,9 @@ Your job is to help create and manage actionable tasks for software projects and
 - This is your persistent memory store - ALWAYS load it first
 - Compress content regularly to stay within context limits
 - Keep your file updated as you work - it's your memory across sessions
-- Archive completed tasks to a compressed section at the bottom
+- Keep completed tasks marked with `[X]` for reference
 - Consolidate similar or duplicate tasks when compressing
-- Maintain structure: Active Tasks → Backlog → Archived (compressed)
+- Maintain structure: Stages with numbered tasks (Stage 1, Stage 2, etc.)
 
 ## AI AGENT PIPELINE AWARENESS
 
@@ -40,9 +68,10 @@ Example task format:
 For task management:
 1. **Load existing tasks**: ALWAYS first use `read_file("tasks.md")` to see what tasks already exist (if the file exists)
 2. **Review context**: Read `plan.md` and `specification.md` if they exist to understand project context
-3. **Analyze requirements**: Understand the current situation and user's task requirements
-4. **Create structured tasks**: Use `write_file("tasks.md", content)` to save organized tasks
-5. **Build incrementally**: Update and refine tasks based on new information
+3. **Verify paths exist**: Check the "Available Files" list in your System Status to see what files exist in `.shotgun/`. If a path doesn't exist, tasks must CREATE it, not modify files within it.
+4. **Analyze requirements**: Understand the current situation and user's task requirements
+5. **Create structured tasks**: Use `write_file("tasks.md", content)` to save organized tasks
+6. **Build incrementally**: Update and refine tasks based on new information
 
 ## TASK FORMAT
 
@@ -53,33 +82,36 @@ For task management:
 
 ## TASK FILE STRUCTURE
 
-Start tasks.md with these instructions:
+**CRITICAL**: Start tasks.md with instructions for AI coding agents, then organize tasks by stages. Do NOT include "In Progress", "Done", or "Blocked" sections - the checkboxes handle completion tracking.
+
 ```markdown
 # Task Management
 
-## Instructions
-- Mark tasks as complete by replacing `[ ]` with `[X]`
-- Tasks without an `[X]` are not finished yet
-```
+## Instructions for AI Coding Agents
 
-Then organize tasks into logical sections:
-```markdown
-## Backlog
-- [ ] Task description with clear action
-- [ ] Another specific task to complete
+When working on these tasks:
+1. Focus on ONE stage at a time, completing all tasks in that stage before moving to the next
+2. Mark each task complete by replacing `[ ]` with `[X]` as you finish it
+3. Do NOT modify any other content in this file unless explicitly instructed by the user
+4. Tasks without an `[X]` are not finished yet
 
-## In Progress
-- [ ] Currently working on this task
-- [ ] Task being actively developed
+---
 
-## Done
-- [X] Completed task for reference
-- [X] Another finished task
+### Stage 1: [Stage Name]
+- [ ] Task description with clear action
+- [ ] Another specific task to complete
 
-## Blocked
-- [ ] Task waiting on dependency (blocked by: reason)
+### Stage 2: [Stage Name]
+- [ ] Task in the next stage
+- [ ] Another task in this stage
 ```
 
+**IMPORTANT**:
+- Group related tasks under numbered stages (Stage 1, Stage 2, etc.)
+- Do NOT create separate "In Progress", "Done", or "Blocked" sections
+- The `[ ]` / `[X]` checkboxes are the ONLY mechanism for tracking completion
+- Each stage should be completable independently before moving to the next
+
 ## TASK CREATION PRINCIPLES
 
 - **ALWAYS use checkbox format `[ ]` for every task**
@@ -129,6 +161,14 @@ INTEGRATION WITH RESEARCH & PLAN:
 - Create validation/testing tasks for success criteria from plan
 - Break down high-level plan steps into granular, executable tasks
 
+PATH VERIFICATION (CRITICAL):
+- Before generating tasks that reference specific file paths in `.shotgun/`, check the "Available Files" list in your System Status
+- If specification.md references files under `.shotgun/contracts/` that don't appear in "Available Files", DO NOT generate tasks for those files
+  - The Specification agent is responsible for creating contract files, not downstream coding agents
+  - Tasks should reference files that EXIST or will be created in the project codebase (src/, tests/, etc.), not in `.shotgun/`
+- Only generate tasks for `.shotgun/` files if they appear in the "Available Files" list and the task is about modifying them
+- Do NOT generate tasks referencing `.shotgun/contracts/*` files unless those files already exist
+
 IMPORTANT RULES:
 - Make at most 1 tasks file write per request
 - Always base tasks on available research and plan when relevant

shotgun/prompts/history/chunk_summarization.j2

@@ -0,0 +1,34 @@
+You are summarizing chunk {{ chunk_index }} of {{ total_chunks }} from a conversation that is too large to summarize at once.
+
+Focus on preserving:
+1. ALL file paths, function names, variable names, URLs, and identifiers VERBATIM
+2. Key decisions and their rationale
+3. Tool call results (summarize large outputs, keep critical data)
+4. Important errors or issues encountered
+5. User requests and how they were addressed
+
+<CHUNK_CONTENT>
+{{ chunk_content }}
+</CHUNK_CONTENT>
+
+<OUTPUT_FORMAT>
+## Topics Covered
+Brief bullet points of main topics discussed in this chunk.
+
+## Entities & References
+- Files: [list all file paths mentioned, verbatim]
+- Functions/Classes: [list all function/method/class names, verbatim]
+- Variables/Keys: [configuration keys, env vars, etc., verbatim]
+- Links/IDs: [any URLs, ticket IDs, etc., verbatim]
+
+## Actions & Results
+Summarized tool calls and their outcomes. Preserve important data verbatim.
+
+## Important Decisions
+Key decisions made and their rationale.
+
+## Status at Chunk End
+Current active task or objective at the end of this chunk (if any), or "N/A" if this chunk completes without active work.
+</OUTPUT_FORMAT>
+
+Be concise but preserve all critical information. This summary will be combined with others to create a complete conversation summary.

shotgun/prompts/history/combine_summaries.j2

@@ -0,0 +1,53 @@
+You are combining {{ num_summaries }} conversation chunk summaries into a unified summary.
+
+<CHUNK_SUMMARIES>
+{% for summary in chunk_summaries %}
+--- Chunk {{ loop.index }} of {{ num_summaries }} ---
+{{ summary }}
+
+{% endfor %}
+</CHUNK_SUMMARIES>
+
+Instructions:
+1. Merge overlapping information - don't repeat the same facts
+2. Preserve ALL entity references (files, functions, variables) from ALL chunks
+3. Maintain chronological timeline of actions
+4. Identify patterns and evolution across chunks
+5. The current status should reflect the LAST chunk's end state
+
+<OUTPUT_FORMAT>
+# Context
+
+Short summary of the discussion, grouped by topics or tasks if any.
+Present it as clear bullet points. Be brief but do not lose information that might be important for the current state, task or objectives.
+
+# Key elements, learnings and entities
+
+Present the important elements of context, learnings and entities from the discussion. Be very detailed.
+
+Present it as clear bullet points. Be brief but do not lose information that might be important for the current state, task or objectives.
+
+If the agent obtained information via tools, preserve it verbatim if it was short, summarize it if it was long focusing on preserving all of the most important facts and information.
+
+If there are any links mentioned, IDs, filenames, etc. - preserve them verbatim.
+
+# Timeline
+
+For important tasks and content, provide
+- User: asked to handle a complex task X: <summary of the task>
+- Assistant: we handle it by doing A, B, C...
+- Tools used and output summary
+
+...
+- User: asked to handle a complex task Y: <summary of the task>
+- Assistant: we handle it by doing A, B, C...
+- Tools used and output summary
+
+Do not hesitate to merge original messages, remove noise. We want to be as concise and brief as possible.
+
+# Current status, task and objectives
+
+Based on the conversation, include here the current status, task and objectives.
+
+CRITICAL: This is not about summarizing or compacting. We are talking about the status, task and objectives currently active in the conversation to keep as much context as possible regarding the last messages.
+</OUTPUT_FORMAT>

shotgun/sdk/codebase.py

@@ -93,6 +93,19 @@ class CodebaseSDK:
         if indexed_from_cwd is None:
             indexed_from_cwd = str(Path.cwd().resolve())
 
+        # Track codebase indexing started event
+        source = detect_source()
+        logger.debug(
+            "Tracking codebase_index_started event: source=%s",
+            source,
+        )
+        track_event(
+            "codebase_index_started",
+            {
+                "source": source,
+            },
+        )
+
         graph = await self.service.create_graph(
             resolved_path,
             name,
@@ -101,9 +114,7 @@ class CodebaseSDK:
         )
         file_count = sum(graph.language_stats.values()) if graph.language_stats else 0
 
-        # Track codebase indexing event
-        # Detect if called from TUI by checking the call stack
-        source = detect_source()
+        # Track codebase indexing completion event (reuse source from start event)
 
         logger.debug(
             "Tracking codebase_indexed event: file_count=%d, node_count=%d, relationship_count=%d, source=%s",

shotgun/settings.py

@@ -108,6 +108,11 @@ class LoggingSettings(BaseSettings):
         default=True,
         description="Enable file logging output",
     )
+    max_log_files: int = Field(
+        default=10,
+        description="Maximum number of log files to keep (older files are deleted)",
+        ge=1,
+    )
 
     model_config = SettingsConfigDict(
         env_prefix="SHOTGUN_",

shotgun/shotgun_web/__init__.py

@@ -1,14 +1,48 @@
-"""Shotgun Web API client for subscription and authentication."""
+"""Shotgun Web API client for subscription, authentication, and shared specs."""
 
 from .client import ShotgunWebClient, check_token_status, create_unification_token
+from .exceptions import (
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    PayloadTooLargeError,
+    RateLimitExceededError,
+    ShotgunWebError,
+    UnauthorizedError,
+)
 from .models import (
+    # Specs models
+    ErrorDetail,
+    ErrorResponse,
+    FileListResponse,
+    FileMetadata,
+    FileUploadRequest,
+    FileUploadResponse,
+    PermissionCheckResponse,
+    PublicSpecResponse,
+    SpecCreateRequest,
+    SpecCreateResponse,
+    SpecFileResponse,
+    SpecListResponse,
+    SpecResponse,
+    SpecUpdateRequest,
+    SpecVersionCreateRequest,
+    SpecVersionResponse,
+    SpecVersionState,
+    # Token models
     TokenCreateRequest,
     TokenCreateResponse,
     TokenStatus,
     TokenStatusResponse,
+    VersionCloseResponse,
+    VersionCreateResponse,
+    VersionListResponse,
+    WorkspaceRole,
 )
+from .specs_client import SpecsClient
 
 __all__ = [
+    # Existing exports
     "ShotgunWebClient",
     "create_unification_token",
     "check_token_status",
@@ -16,4 +50,36 @@ __all__ = [
     "TokenCreateResponse",
     "TokenStatus",
     "TokenStatusResponse",
+    # Specs client
+    "SpecsClient",
+    # Exceptions
+    "ShotgunWebError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ConflictError",
+    "PayloadTooLargeError",
+    "RateLimitExceededError",
+    # Specs models
+    "ErrorDetail",
+    "ErrorResponse",
+    "FileListResponse",
+    "FileMetadata",
+    "FileUploadRequest",
+    "FileUploadResponse",
+    "PermissionCheckResponse",
+    "PublicSpecResponse",
+    "SpecCreateRequest",
+    "SpecCreateResponse",
+    "SpecFileResponse",
+    "SpecListResponse",
+    "SpecResponse",
+    "SpecUpdateRequest",
+    "SpecVersionCreateRequest",
+    "SpecVersionResponse",
+    "SpecVersionState",
+    "VersionCloseResponse",
+    "VersionCreateResponse",
+    "VersionListResponse",
+    "WorkspaceRole",
 ]

shotgun/shotgun_web/client.py

@@ -5,11 +5,13 @@ import httpx
 from shotgun.logging_config import get_logger
 
 from .constants import (
+    ME_PATH,
     SHOTGUN_WEB_BASE_URL,
     UNIFICATION_TOKEN_CREATE_PATH,
     UNIFICATION_TOKEN_STATUS_PATH,
 )
 from .models import (
+    MeResponse,
     TokenCreateRequest,
     TokenCreateResponse,
     TokenStatusResponse,
@@ -66,7 +68,7 @@ class ShotgunWebClient:
             return result
 
         except httpx.HTTPError as e:
-            logger.error("Failed to create unification token: %s", e)
+            logger.error("Failed to create unification token at %s: %s", url, e)
             raise
 
     def check_token_status(self, token: str) -> TokenStatusResponse:
@@ -106,6 +108,45 @@ class ShotgunWebClient:
             logger.error("Failed to check token status: %s", e)
             raise
 
+    def get_me(self, jwt: str) -> MeResponse:
+        """Get current user info including workspace.
+
+        Args:
+            jwt: Supabase JWT for authentication
+
+        Returns:
+            User info including workspace details
+
+        Raises:
+            httpx.HTTPStatusError: If authentication fails (401) or other HTTP errors
+            httpx.HTTPError: For other request failures
+        """
+        url = f"{self.base_url}{ME_PATH}"
+
+        logger.debug("Fetching user info from /api/me")
+
+        try:
+            response = httpx.get(
+                url,
+                headers={"Authorization": f"Bearer {jwt}"},
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+
+            data = response.json()
+            result = MeResponse.model_validate(data)
+
+            logger.info("Successfully fetched user info for %s", result.email)
+            return result
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 401:
+                logger.error("Authentication failed for /api/me")
+            raise
+        except httpx.HTTPError as e:
+            logger.error("Failed to fetch user info: %s", e)
+            raise
+
 
 # Convenience functions for standalone use
 def create_unification_token(shotgun_instance_id: str) -> TokenCreateResponse:

shotgun/shotgun_web/constants.py

@@ -6,16 +6,62 @@ from shotgun.api_endpoints import SHOTGUN_WEB_BASE_URL
 # API endpoints
 UNIFICATION_TOKEN_CREATE_PATH = "/api/unification/token/create"  # noqa: S105
 UNIFICATION_TOKEN_STATUS_PATH = "/api/unification/token/{token}/status"  # noqa: S105
+ME_PATH = "/api/me"
 
 # Polling configuration
 DEFAULT_POLL_INTERVAL_SECONDS = 3
 DEFAULT_TOKEN_TIMEOUT_SECONDS = 1800  # 30 minutes
 
+# Workspaces API endpoint
+WORKSPACES_PATH = "/api/workspaces"
+
+# Specs API endpoints
+PERMISSIONS_PATH = "/api/workspaces/{workspace_id}/specs/permissions"
+SPECS_BASE_PATH = "/api/workspaces/{workspace_id}/specs"
+SPECS_DETAIL_PATH = "/api/workspaces/{workspace_id}/specs/{spec_id}"
+VERSIONS_PATH = "/api/workspaces/{workspace_id}/specs/{spec_id}/versions"
+VERSION_DETAIL_PATH = (
+    "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}"
+)
+VERSION_CLOSE_PATH = (
+    "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}/close"
+)
+VERSION_SET_LATEST_PATH = (
+    "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}/set-latest"
+)
+FILES_PATH = (
+    "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}/files"
+)
+FILE_DETAIL_PATH = "/api/workspaces/{workspace_id}/specs/{spec_id}/versions/{version_id}/files/{file_id}"
+PUBLIC_SPEC_PATH = "/api/public/specs/{spec_id}"
+PUBLIC_SPEC_FILES_PATH = "/api/public/specs/{spec_id}/files"
+PUBLIC_FILE_PATH = "/api/public/specs/{spec_id}/files/{file_id}"
+
+# CLI convenience endpoint (version lookup by ID only)
+VERSION_BY_ID_PATH = "/api/versions/{version_id}"
+
 # Re-export for backward compatibility
 __all__ = [
     "SHOTGUN_WEB_BASE_URL",
     "UNIFICATION_TOKEN_CREATE_PATH",
     "UNIFICATION_TOKEN_STATUS_PATH",
+    "ME_PATH",
     "DEFAULT_POLL_INTERVAL_SECONDS",
     "DEFAULT_TOKEN_TIMEOUT_SECONDS",
+    # Workspaces endpoint
+    "WORKSPACES_PATH",
+    # Specs endpoints
+    "PERMISSIONS_PATH",
+    "SPECS_BASE_PATH",
+    "SPECS_DETAIL_PATH",
+    "VERSIONS_PATH",
+    "VERSION_DETAIL_PATH",
+    "VERSION_CLOSE_PATH",
+    "VERSION_SET_LATEST_PATH",
+    "FILES_PATH",
+    "FILE_DETAIL_PATH",
+    "PUBLIC_SPEC_PATH",
+    "PUBLIC_SPEC_FILES_PATH",
+    "PUBLIC_FILE_PATH",
+    "VERSION_BY_ID_PATH",
 ]

shotgun/shotgun_web/exceptions.py

@@ -0,0 +1,29 @@
+"""Typed exceptions for Shotgun Web API operations."""
+
+
+class ShotgunWebError(Exception):
+    """Base exception for Shotgun Web API operations."""
+
+
+class UnauthorizedError(ShotgunWebError):
+    """401 - Missing or invalid authentication token."""
+
+
+class ForbiddenError(ShotgunWebError):
+    """403 - Insufficient permissions for the requested operation."""
+
+
+class NotFoundError(ShotgunWebError):
+    """404 - Resource not found."""
+
+
+class ConflictError(ShotgunWebError):
+    """409 - Name conflict or duplicate path."""
+
+
+class PayloadTooLargeError(ShotgunWebError):
+    """413 - File exceeds maximum size limit."""
+
+
+class RateLimitExceededError(ShotgunWebError):
+    """429 - Rate limit exceeded."""