shotgun-sh 0.1.0.dev20__py3-none-any.whl → 0.1.0.dev23__py3-none-any.whl

shotgun/artifacts/templates/specify/product_spec.yaml

@@ -1,301 +0,0 @@
-name: Product Specification Template
-purpose: Use this to template to build a product specification for the user's product.
-prompt: |
-  First, suggest creating a product.overview section. Then, once the user reviews, move on to the next sections.
-  Include a technology architecture blueprint that defines boundaries, responsibilities, and quality goals for the product. The system enables end users to perform core workflows reliably and securely while supporting iterative evolution.
-  Prioritize features by user value × business value to maximize the ROI.
-  Facilitate ideation & discovery: Divergent thinking before convergence
-  Fill blanks creatively if the user lacks detail: Momentum over paralysis
-  Your focus needs to be on creating clear, actionable product artifacts that development teams can use.
-  If user provides detailed description with problem, solution, target users, acknowledge and get to work OR ask for more details if critical details are truly missing.
-  Try to suggest next steps for the user in their product definition journey.
-sections:
-    product.overview:
-        instructions: |
-            # A good product.overview:
-            •	Inspires action
-            •	Focuses on a real pain for real users
-            •	Aligns the team on desired outcomes
-            * Is complete and comprehensive
-
-            # Questions to ask yourself:
-            •	What would success headlines say 12 months after launch?
-            •	What user behavior or workflow do we want to eliminate or unlock?
-            * Is there anything else, specific to the product, that we should include?
-
-            # Includes:
-              Product Vision: [One punchy sentence that inspires; problem + aspirational outcome]
-              Problem Statement:
-                Who hurts? [Persona or segment]
-                Pain intensity? [Metric / qualitative quote]
-                Existing workaround? [Current solution]
-                [additional relevant information]
-
-            # Goals & Success Metrics:
-
-            | Goal | KPI | Target |
-            |------|-----|--------|
-            | Reduce payroll processing time | Avg. run time | < 5 min |
-            | Increase retention | NPS | > 60 |
-            [more like that]
-    product.user_personas:
-        instructions: |
-            # How to write a good product.user_personas section
-
-            Capture the motivations, frustrations, and context of your target users.
-
-              •	Makes the user feel real to the team
-              •	Communicates job context and emotional stakes
-              •	Informs tradeoffs during prioritization
-
-            # Questions to ask yourself:
-              •	What would frustrate this person about our current plan?
-              •	What would success feel like in their words?
-
-            Each persona should have their own Emoji you'll use throughout the product specification.
-
-            # Includes:
-              Name / Archetype: [Short, memorable]
-              Role & Demographics: [Job, age, environment]
-              Goals:
-                - [Primary job‑to‑be‑done]
-                - [Secondary]
-              Frustrations / Pain Points:
-                - [Top pain]
-                - [Tech constraints]
-              Success Definition: “[Quote in their words]”
-        depends_on:
-            - "product.overview"
-    product.user_stories:
-        instructions: |
-            Create a concise set of INVEST-compliant user stories, each with clear acceptance criteria using the **Given / When / Then** pattern.
-
-            # Voice & Style
-            Professional, direct, and unambiguous. Avoid marketing fluff and technical implementation details.
-
-            # How to write a good product.user_stories section
-
-            •	Is short, clear, and framed around user benefit
-            •	Has testable, concrete acceptance criteria
-            •	Maps to a real persona and real-world situation
-            * Comprehensively cover the whole system
-            * They cover all personas already defined in the product.personas section (do not create new personas here)
-
-            # Questions to ask yourself:
-            •	Could the team design/build this without ambiguity?
-            •	Is this too big? Can it be split?
-
-            # Key Principles to Apply
-            - **User story format:** "As a \<role>, I want \<goal> so that \<benefit>."
-            - **INVEST:** Independent, Negotiable, Valuable, Estimable, Small, Testable.
-            - **3 Cs:**
-              - **Card:** Concise statement
-              - **Conversation:** Brief elaboration if needed
-              - **Confirmation:** Acceptance criteria clearly defined
-            - **Do’s:** User-centric, outcome-oriented, sprint-sized, measurable value.
-            - **Don’ts:** No UI specifics, vague benefits, or bundled epics.
-            - ALWAYS include at least one acceptance criteria for each user story.
-            - ALWAYS assign the story a JIRA-like ID that we can later refer to easily. Format prefix should come from the product name or EPIC.
-
-            Write key parts of user stories in **bold**.
-
-            # Context Sensitivity
-            - **Startup Context:** Allow lighter processes and faster iteration.
-            - **Enterprise Context:** Include 1–2 "Enabler" stories for compliance, performance, and note dependencies explicitly.
-
-
-            # (Optional) Enabler / Technical Stories
-
-            - As a developer…, I want… so that…
-        depends_on:
-            - "product.user_personas"
-
-    product.user_journeys:
-        instructions: |
-            # How to write a good product.user_journeys section
-
-            Visually maps the end-to-end experience from the user's perspective, highlighting actions, thoughts, and feelings.
-              •	Tells a Story: It should have a clear beginning, middle, and end, following a specific user and scenario.	•	Reveals Pain & Opportunity: Clearly identifies moments of frustration (pain points) and moments of delight.	•	Holistic View: Captures touchpoints both inside and outside the product (e.g., receiving an email notification).	•	Uses Mermaid: Creates a clean, easy-to-read visual diagram of the journey.
-            Questions to ask yourself:
-              •	What happens before the user opens our app and after they close it?	•	Where is the emotional low point of this journey? How can we fix it?	•	What is the "happy path," and what are the most common deviations?
-
-            # Includes:
-            * A Mermaid diagram for each key persona or critical task.
-            * Title: A clear, descriptive title for the journey (e.g., "Journey of a New User Onboarding").
-            * Sections: Logical phases of the journey (e.g., Awareness, Consideration, Purchase, Onboarding, Regular Use).
-            * Tasks: Specific actions the user takes, assigned to a persona.
-            * Sentiment Score: A rating (e.g., 1-5) to show the user's emotional state at each step.
-            * Include a description of the journey in the section content. Make important things in **bold**.
-
-            # Diagram example
-
-            IMPORTANT: DO NOT use semicolons in the content.
-
-            ```mermaid
-            journey
-                title My working day
-                section Go to work
-                  Make tea: 5: Me
-                  Go upstairs: 3: Me
-                  Do work: 1: Me, Cat
-                section Go home
-                  Go downstairs: 5: Me
-                  Sit down: 5: Me
-            ```
-
-        depends_on:
-            - "product.user_stories"
-
-    product.features:
-        instructions: |
-            # How to write a good product.features section
-
-            Detailed specification of product capabilities. Tied directly to user needs and business outcomes.
-
-            •	Explains why the feature matters (not just what it does)
-            •	Specifies functional and non-functional behavior
-            •	Clarifies edge cases and constraints
-
-            # Questions to ask yourself:
-            •	What would make a developer or designer fail to implement this right?
-            •	What are the failure modes or critical risks?
-
-            # Includes:
-              Feature: **[Name]**
-              Objective: **[Problem it solves]**
-              User Benefit: **[Why user cares]**
-              Detailed Requirements:
-                - **[Functional spec]**
-                - **[Performance spec]**
-              Non‑Functional:
-                - Security: **[e.g., SOC 2 compliance]**
-                - Localization: **[e.g., EN/ES at launch]**
-        depends_on:
-            - "product.user_stories"
-
-    product.roadmap:
-        instructions: |
-            # How to write a good product.roadmap section?
-
-            Defines the sequence of what gets built when — and why.
-
-            •	Shows clear strategic themes
-            •	Communicates tradeoffs and intent
-            •	Helps stakeholders set expectations
-
-            # Questions to ask yourself:
-            •	What themes are we prioritizing this quarter and why?
-            •	What’s realistic to deliver given team velocity?
-
-            # Includes:
-              Quarter
-              Theme
-              Initiatives
-              Mermaid Gantt diagram
-
-            # Diagram example (syntax)
-
-            ```mermaid
-            gantt
-                dateFormat  YYYY-MM-DD
-                title       Adding GANTT diagram functionality to mermaid
-                excludes    weekends
-                %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)
-
-                section A section
-                Completed task            :done,    des1, 2014-01-06,2014-01-08
-                Active task               :active,  des2, 2014-01-09, 3d
-                Future task               :         des3, after des2, 5d
-                Future task2              :         des4, after des3, 5d
-
-                section Critical tasks
-                Completed task in the critical line :crit, done, 2014-01-06,24h
-                Implement parser and jison          :crit, done, after des1, 2d
-                Create tests for parser             :crit, active, 3d
-                Future task in critical line        :crit, 5d
-                Create tests for renderer           :2d
-                Add to mermaid                      :until isadded
-                Functionality added                 :milestone, isadded, 2014-01-25, 0d
-
-                section Documentation
-                Describe gantt syntax               :active, a1, after des1, 3d
-                Add gantt diagram to demo page      :after a1  , 20h
-                Add another diagram to demo page    :doc1, after a1  , 48h
-
-                section Last section
-                Describe gantt syntax               :after doc1, 3d
-                Add gantt diagram to demo page      :20h
-                Add another diagram to demo page    :48h
-            ```
-
-    architecture.overview:
-        instructions: |
-            # A good architecture_overview:
-              •	Establishes scope, purpose, high‑level constraints
-              •	Gives a north‑star vision for future evolution
-
-            # Ask yourself:
-              •	What external systems/actors touch us?
-              •	Which constraints shape every other decision (regulations, runtime, budget)?
-
-            # Includes:
-              •	System Purpose – 1‑sentence mission
-              •	Context Diagram – Mermaid
-              •	Key Constraints – Regs, legacy ties, SLAs
-
-        depends_on:
-            - "product.features"
-
-    architecture.key_components:
-        instructions: |
-            This section should include all key components and their relationships.
-
-            Include diagrams on how they interact and dependencies.
-
-        depends_on:
-            - "architecture.overview"
-            
-    architecture.quality_attributes:
-        instructions: |
-            # Example of a good architecture_quality_attributes section
-
-            Attribute	Metric	Target	Design Strategies
-            Performance	P99 latency	< 200 ms	Async queue, in‑memory cache
-            Scalability	Sustained RPS	5 k	Stateless services + HPA
-            Security	OWASP Top 10	0 critical vulns	CSP, parameterized SQL
-
-            Use measurable targets and map to architectural mechanisms.
-
-        depends_on:
-            - "architecture.key_components"
-
-    architecture.cross_cutting_concerns:
-      instructions: |
-          Capture reusable patterns/services (e.g., centralized logging stack, OAuth provider, feature flags).
-          State ownership and SLOs so ops knows who to page.
-
-      depends_on:
-          - "architecture.key_components"
-          - "architecture.quality_attributes"
-
-    architecture.tech_stack_requirements:
-        instructions: |
-            Next up, we will engage tech research agent to find the best tech stack for the project.
-            Outline key elements of the stack so they can focus on finding the best option for each element in terms of programming language, frameworks, libraries, databases, etc.
-        depends_on:
-            - "architecture.cross_cutting_concerns"
-            - "architecture.quality_attributes"
-            - "architecture.key_components"
-
-    architecture.tech_stack_decisions:
-        instructions: |
-            # Example of a good architecture_tech_stack_decisions section
-
-            Include a summary of the tech stack decisions and why they were made.
-
-        depends_on:
-            - "architecture.tech_stack_requirements"
-            - "architecture.cross_cutting_concerns"
-            - "architecture.quality_attributes"
-            - "architecture.key_components"
-            - "architecture.overview"

shotgun/artifacts/utils.py

@@ -1,76 +0,0 @@
-"""Utilities for artifact system."""
-
-from .models import AgentMode
-
-# Error message templates
-INVALID_AGENT_MODE_MSG = (
-    "Invalid agent mode '{mode}'. Valid modes: research, plan, tasks, specify"
-)
-VALIDATION_ERROR_MSG = "Validation error: {error}"
-
-# Valid modes list for error messages
-VALID_AGENT_MODES = ["research", "plan", "tasks", "specify"]
-
-
-def parse_agent_mode_string(mode_str: str) -> AgentMode:
-    """Parse agent mode string to AgentMode enum.
-
-    Args:
-        mode_str: String representation of agent mode
-
-    Returns:
-        AgentMode enum value
-
-    Raises:
-        ValueError: If mode_str is not a valid agent mode
-    """
-    try:
-        return AgentMode(mode_str.lower())
-    except ValueError as e:
-        if "not a valid enumeration member" in str(e):
-            raise ValueError(INVALID_AGENT_MODE_MSG.format(mode=mode_str)) from e
-        raise ValueError(VALIDATION_ERROR_MSG.format(error=str(e))) from e
-
-
-def generate_artifact_name(artifact_id: str) -> str:
-    """Generate human-readable name from artifact ID.
-
-    Args:
-        artifact_id: Artifact identifier (slug format)
-
-    Returns:
-        Human-readable name
-    """
-    return artifact_id.replace("-", " ").title()
-
-
-def format_agent_error_message(agent_mode: str, error: Exception) -> str:
-    """Format error message for agent tools.
-
-    Args:
-        agent_mode: Agent mode string that caused the error
-        error: The exception that occurred
-
-    Returns:
-        Formatted error message
-    """
-    if "not a valid enumeration member" in str(error):
-        return INVALID_AGENT_MODE_MSG.format(mode=agent_mode)
-    else:
-        return VALIDATION_ERROR_MSG.format(error=str(error))
-
-
-def handle_agent_mode_parsing(agent_mode: str) -> tuple[AgentMode | None, str | None]:
-    """Handle agent mode parsing with error handling.
-
-    Args:
-        agent_mode: Agent mode string to parse
-
-    Returns:
-        Tuple of (parsed_mode, error_message). If parsing succeeds,
-        error_message is None. If parsing fails, parsed_mode is None.
-    """
-    try:
-        return parse_agent_mode_string(agent_mode), None
-    except ValueError as e:
-        return None, str(e)

shotgun/prompts/agents/partials/artifact_system.j2

@@ -1,32 +0,0 @@
-## ARTIFACT SYSTEM
-
-You have access to a structured artifact system for organizing your work. Use artifacts instead of flat files for better organization.
-
-### Available Artifact Tools:
-- `list_artifacts(agent_mode)`: List existing artifacts for an agent mode ("research", "plan", "tasks", "specify")
-- `read_artifact(artifact_id, agent_mode)`: Read all sections of an artifact
-- `read_artifact_section(artifact_id, agent_mode, section_number)`: Read specific section
-- `write_artifact_section(artifact_id, agent_mode, section_number, section_slug, section_title, content)`: Create/update section
-
-### Artifact Structure:
-- **Artifact ID**: Meaningful slug (e.g., "api-design-patterns", "mvp-roadmap")
-- **Sections**: Numbered sections with descriptive slugs and titles
-- **Organization**: `.shotgun/{agent_mode}/{artifact_id}/{section_number}-{section_slug}.md`
-
-### Best Practices:
-- Use meaningful artifact IDs that describe the work
-- Organize content into logical sections (overview, analysis, recommendations, etc.)
-- Use descriptive section titles and slugs
-- Build upon existing work rather than starting from scratch
-
-
-## ARTIFACT TEMPLATES
-
-Use artifact templates to help you create new artifacts.
-
-MOST IMPORTANT: WHEN YOU CREATE AN ARTIFACT FROM A TEMPLATE, ALWAYS RESPECT AND FOLLOW THE "INSTRUCTIONS" AND "PROMPT" CONTAINED IN THE TEMPLATE TO THE LETTER.
-
-Use `create_artifact(artifact_id, agent_mode, name, template_id)` to create a new artifact with a template.
-
-Template ID example: "research/market_research"
-

shotgun/prompts/agents/state/artifact_templates_available.j2

@@ -1,20 +0,0 @@
-{% if available_templates %}
-
-## Available Artifact Templates (up to date, no need to check again)
-
-### Below if the current output of list_artifact_templates()
-
-You have access to these pre-built templates for creating structured artifacts:
-
-{% for mode, templates in available_templates.items() %}
-### {{ mode.title() }} Templates
-{% for template in templates %}
-- **{{ template.name }}** (`{{ template.template_id }}`)
-  Purpose: {{ template.purpose[:150] }}{% if template.purpose|length > 150 %}...{% endif %}
-{% endfor %}
-
-{% endfor %}
-Use `list_artifact_templates("mode")` to get detailed template information for a specific mode, or `list_artifact_templates()` for all templates.
-Use `create_artifact(artifact_id, agent_mode, name, template_id)` to create a new artifact with any of these templates.
-
-{% endif %}

shotgun/prompts/agents/state/existing_artifacts_available.j2

@@ -1,25 +0,0 @@
-{% if existing_artifacts %}
-
-## Existing Artifacts (All Modes)
-
-### Below if the current output of list_artifacts()
-
-Work already completed across all agent modes:
-
-{% for mode, artifacts in existing_artifacts.items() %}
-### {{ mode.title() }} Artifacts
-{% for artifact in artifacts %}
-- **{{ artifact.artifact_id }}** ({{ artifact.section_count }} sections)
-  Updated: {{ artifact.updated_at.strftime('%B %d, %Y') }}
-{% endfor %}
-
-{% endfor %}
-Use `read_artifact(artifact_id)` to access full content, `list_artifacts()` for detailed view, or `list_artifacts("mode")` for specific mode.
-
-{% else %}
-
-## Existing Artifacts
-
-No artifacts have been created yet. Use `create_artifact()` with available templates to start new work.
-
-{% endif %}

shotgun/sdk/artifact_models.py

@@ -1,186 +0,0 @@
-"""Result models for SDK artifact operations."""
-
-from pydantic import BaseModel
-
-from shotgun.artifacts.models import AgentMode, Artifact, ArtifactSummary
-
-
-class ArtifactListResult(BaseModel):
-    """Result for artifact list command."""
-
-    artifacts: list[ArtifactSummary]
-    agent_mode: AgentMode | None = None
-
-    def __str__(self) -> str:
-        """Format list result as plain text table."""
-        if not self.artifacts:
-            mode_text = f" for {self.agent_mode.value}" if self.agent_mode else ""
-            return f"No artifacts found{mode_text}."
-
-        lines = [
-            f"{'Agent':<10} {'ID':<25} {'Name':<30} {'Sections':<8} {'Updated'}",
-            "-" * 85,
-        ]
-
-        for artifact in self.artifacts:
-            lines.append(
-                f"{artifact.agent_mode.value:<10} "
-                f"{artifact.artifact_id[:25]:<25} "
-                f"{artifact.name[:30]:<30} "
-                f"{artifact.section_count:<8} "
-                f"{artifact.updated_at.strftime('%Y-%m-%d')}"
-            )
-
-        return "\n".join(lines)
-
-
-class ArtifactCreateResult(BaseModel):
-    """Result for artifact create command."""
-
-    artifact_id: str
-    agent_mode: AgentMode
-    name: str
-    created: bool = True
-
-    def __str__(self) -> str:
-        """Format create result as success message."""
-        return f"Created artifact '{self.artifact_id}' in {self.agent_mode.value} mode"
-
-
-class ArtifactDeleteResult(BaseModel):
-    """Result for artifact delete command."""
-
-    artifact_id: str
-    agent_mode: AgentMode
-    deleted: bool = True
-    cancelled: bool = False
-
-    def __str__(self) -> str:
-        """Format delete result message."""
-        if self.cancelled:
-            return "Deletion cancelled."
-        elif self.deleted:
-            return f"Deleted artifact '{self.artifact_id}' from {self.agent_mode.value} mode"
-        else:
-            return f"Failed to delete artifact '{self.artifact_id}'"
-
-
-class ArtifactInfoResult(BaseModel):
-    """Result for artifact info command."""
-
-    artifact: Artifact
-
-    def __str__(self) -> str:
-        """Format detailed artifact information."""
-        artifact = self.artifact
-        lines = [
-            f"Artifact ID: {artifact.artifact_id}",
-            f"Name: {artifact.name}",
-            f"Agent Mode: {artifact.agent_mode.value}",
-            f"Created: {artifact.get_created_at()}",
-            f"Updated: {artifact.get_updated_at()}",
-            f"Sections: {artifact.get_section_count()}",
-            f"Total Content Length: {artifact.get_total_content_length()} characters",
-        ]
-
-        if artifact.sections:
-            lines.append("\nSections:")
-            for section in artifact.get_ordered_sections():
-                content_preview = (
-                    section.content[:50] + "..."
-                    if len(section.content) > 50
-                    else section.content
-                ).replace("\n", " ")
-                lines.append(f"  {section.number:03d}. {section.title}")
-                if content_preview:
-                    lines.append(f"       {content_preview}")
-
-        return "\n".join(lines)
-
-
-class SectionCreateResult(BaseModel):
-    """Result for section create command."""
-
-    artifact_id: str
-    agent_mode: AgentMode
-    section_number: int
-    section_title: str
-    created: bool = True
-
-    def __str__(self) -> str:
-        """Format section create result."""
-        return (
-            f"Created section {self.section_number} '{self.section_title}' "
-            f"in artifact '{self.artifact_id}'"
-        )
-
-
-class SectionUpdateResult(BaseModel):
-    """Result for section update command."""
-
-    artifact_id: str
-    agent_mode: AgentMode
-    section_number: int
-    updated_fields: list[str]
-
-    def __str__(self) -> str:
-        """Format section update result."""
-        fields_text = ", ".join(self.updated_fields)
-        return (
-            f"Updated section {self.section_number} in artifact '{self.artifact_id}' "
-            f"(fields: {fields_text})"
-        )
-
-
-class SectionDeleteResult(BaseModel):
-    """Result for section delete command."""
-
-    artifact_id: str
-    agent_mode: AgentMode
-    section_number: int
-    deleted: bool = True
-
-    def __str__(self) -> str:
-        """Format section delete result."""
-        if self.deleted:
-            return f"Deleted section {self.section_number} from artifact '{self.artifact_id}'"
-        else:
-            return f"Failed to delete section {self.section_number}"
-
-
-class SectionContentResult(BaseModel):
-    """Result for section content read command."""
-
-    artifact_id: str
-    agent_mode: AgentMode
-    section_number: int
-    content: str
-
-    def __str__(self) -> str:
-        """Format section content."""
-        return self.content
-
-
-class ArtifactErrorResult(BaseModel):
-    """Result for error cases in artifact operations."""
-
-    error_message: str
-    artifact_id: str | None = None
-    agent_mode: AgentMode | None = None
-    section_number: int | None = None
-    details: str | None = None
-
-    def __str__(self) -> str:
-        """Format error message."""
-        parts = [f"Error: {self.error_message}"]
-
-        if self.artifact_id:
-            parts.append(f"Artifact: {self.artifact_id}")
-        if self.agent_mode:
-            parts.append(f"Mode: {self.agent_mode.value}")
-        if self.section_number:
-            parts.append(f"Section: {self.section_number}")
-        if self.details:
-            parts.append(f"Details: {self.details}")
-
-        return " | ".join(parts)