shotgun-sh 0.1.0.dev12__py3-none-any.whl → 0.1.0.dev13__py3-none-any.whl

shotgun/artifacts/templates/specify/product_spec.yaml

@@ -0,0 +1,301 @@
+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

@@ -0,0 +1,76 @@
+"""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/cli/plan.py

@@ -7,7 +7,7 @@ import typer
 
 from shotgun.agents.config import ProviderType
 from shotgun.agents.models import AgentRuntimeOptions
-from shotgun.agents.plan import create_plan_agent, get_plan_history, run_plan_agent
+from shotgun.agents.plan import create_plan_agent, run_plan_agent
 from shotgun.logging_config import get_logger
 
 app = typer.Typer(name="plan", help="Generate structured plans", no_args_is_help=True)
@@ -65,9 +65,6 @@ def plan(
         logger.info("✅ Planning Complete!")
         logger.info("📋 Results:")
         logger.info("%s", result.output)
-        logger.info("📄 Plan saved to: .shotgun/plan.md")
-        logger.debug("📚 Current plan:")
-        logger.debug("%s", get_plan_history())
 
     except Exception as e:
         logger.error("❌ Error during planning: %s", str(e))

shotgun/cli/specify.py

@@ -0,0 +1,69 @@
+"""Specify command for shotgun CLI."""
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+from shotgun.agents.config import ProviderType
+from shotgun.agents.models import AgentRuntimeOptions
+from shotgun.agents.specify import (
+    create_specify_agent,
+    run_specify_agent,
+)
+from shotgun.logging_config import get_logger
+
+app = typer.Typer(
+    name="specify", help="Generate comprehensive specifications", no_args_is_help=True
+)
+logger = get_logger(__name__)
+
+
+@app.callback(invoke_without_command=True)
+def specify(
+    requirement: Annotated[
+        str, typer.Argument(help="Requirement or feature to specify")
+    ],
+    non_interactive: Annotated[
+        bool,
+        typer.Option(
+            "--non-interactive", "-n", help="Disable user interaction (for CI/CD)"
+        ),
+    ] = False,
+    provider: Annotated[
+        ProviderType | None,
+        typer.Option("--provider", "-p", help="AI provider to use (overrides default)"),
+    ] = None,
+) -> None:
+    """Generate comprehensive specifications for software features and systems.
+
+    This command creates detailed technical specifications including requirements,
+    architecture, implementation details, and acceptance criteria based on your
+    provided requirement or feature description.
+    """
+
+    logger.info("📝 Specification Requirement: %s", requirement)
+
+    try:
+        # Create agent dependencies
+        agent_runtime_options = AgentRuntimeOptions(
+            interactive_mode=not non_interactive
+        )
+
+        # Create the specify agent with deps and provider
+        agent, deps = create_specify_agent(agent_runtime_options, provider)
+
+        # Start specification process
+        logger.info("📋 Starting specification generation...")
+        result = asyncio.run(run_specify_agent(agent, requirement, deps))
+
+        # Display results
+        logger.info("✅ Specification Complete!")
+        logger.info("📋 Results:")
+        logger.info("%s", result.output)
+
+    except Exception as e:
+        logger.error("❌ Error during specification: %s", str(e))
+        import traceback
+
+        logger.debug("Full traceback:\n%s", traceback.format_exc())

shotgun/cli/tasks.py

@@ -9,7 +9,6 @@ from shotgun.agents.config import ProviderType
 from shotgun.agents.models import AgentRuntimeOptions
 from shotgun.agents.tasks import (
     create_tasks_agent,
-    get_tasks_history,
     run_tasks_agent,
 )
 from shotgun.logging_config import get_logger
@@ -71,9 +70,6 @@ def tasks(
         logger.info("✅ Task Creation Complete!")
         logger.info("📋 Results:")
         logger.info("%s", result.output)
-        logger.info("📄 Tasks saved to: .shotgun/tasks.md")
-        logger.debug("📚 Current tasks:")
-        logger.debug("%s", get_tasks_history())
 
     except Exception as e:
         logger.error("❌ Error during task creation: %s", str(e))

shotgun/logging_config.py

@@ -65,14 +65,20 @@ def setup_logger(
     """
     logger = logging.getLogger(name)
 
-    # Avoid adding duplicate handlers
-    if logger.handlers:
+    # Check if we already have a file handler
+    has_file_handler = any(
+        isinstance(h, logging.handlers.TimedRotatingFileHandler)
+        for h in logger.handlers
+    )
+
+    # If we already have a file handler, just return the logger
+    if has_file_handler:
         return logger
 
-    # Get log level from environment variable, default to ERROR
-    env_level = os.getenv("SHOTGUN_LOG_LEVEL", "ERROR").upper()
+    # Get log level from environment variable, default to INFO
+    env_level = os.getenv("SHOTGUN_LOG_LEVEL", "INFO").upper()
     if env_level not in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]:
-        env_level = "ERROR"
+        env_level = "INFO"
 
     logger.setLevel(getattr(logging, env_level))
 
@@ -163,8 +169,14 @@ def get_logger(name: str) -> logging.Logger:
     """
     logger = logging.getLogger(name)
 
-    # If logger doesn't have handlers, set it up
-    if not logger.handlers:
+    # Check if we have a file handler already
+    has_file_handler = any(
+        isinstance(h, logging.handlers.TimedRotatingFileHandler)
+        for h in logger.handlers
+    )
+
+    # If no file handler, set up the logger (will add file handler)
+    if not has_file_handler:
         return setup_logger(name)
 
     return logger
@@ -187,4 +199,8 @@ def set_global_log_level(level: str) -> None:
 
 def configure_root_logger() -> None:
     """Configure the root shotgun logger."""
+    # Always set up the root logger to ensure file handler is added
     setup_logger("shotgun")
+
+    # Also ensure main module gets configured
+    setup_logger("__main__")

shotgun/main.py

@@ -7,7 +7,7 @@ from dotenv import load_dotenv
 
 from shotgun import __version__
 from shotgun.agents.config import get_config_manager
-from shotgun.cli import codebase, config, plan, research, tasks, update
+from shotgun.cli import codebase, config, plan, research, specify, tasks, update
 from shotgun.logging_config import configure_root_logger, get_logger
 from shotgun.posthog_telemetry import setup_posthog_observability
 from shotgun.sentry_telemetry import setup_sentry_observability
@@ -18,9 +18,13 @@ from shotgun.utils.update_checker import check_for_updates_async
 # Load environment variables from .env file
 load_dotenv()
 
-# Initialize logging
+# Initialize telemetry FIRST (before logging setup to prevent handler conflicts)
+_logfire_enabled = setup_logfire_observability()
+
+# Initialize logging AFTER telemetry
 configure_root_logger()
 logger = get_logger(__name__)
+logger.debug("Logfire observability enabled: %s", _logfire_enabled)
 
 # Initialize configuration
 try:
@@ -29,10 +33,6 @@ try:
 except Exception as e:
     logger.debug("Configuration initialization warning: %s", e)
 
-# Initialize telemetry
-_logfire_enabled = setup_logfire_observability()
-logger.debug("Logfire observability enabled: %s", _logfire_enabled)
-
 # Initialize Sentry telemetry
 _sentry_enabled = setup_sentry_observability()
 logger.debug("Sentry observability enabled: %s", _sentry_enabled)
@@ -64,6 +64,7 @@ app.add_typer(
 )
 app.add_typer(research.app, name="research", help="Perform research with agentic loops")
 app.add_typer(plan.app, name="plan", help="Generate structured plans")
+app.add_typer(specify.app, name="specify", help="Generate comprehensive specifications")
 app.add_typer(tasks.app, name="tasks", help="Generate task lists with agentic approach")
 app.add_typer(update.app, name="update", help="Check for and install updates")
 

shotgun/prompts/agents/partials/artifact_system.j2

@@ -0,0 +1,32 @@
+## 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:
+- Always start by checking existing artifacts with `list_artifacts()`
+- 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.
+
+Use `list_artifact_templates(agent_mode)` to see what templates are available.
+
+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/partials/common_agent_system_prompt.j2

@@ -1,10 +1,36 @@
 
-{% include 'agents/partials/interactive_mode.j2' %}
-
 Your extensive expertise spans, among other things:
 * Business Analysis
 * Product Management
 * Software Architecture
 * Software Development
 
+## KEY RULES
+
+0. Above all, prefer using tools to do the work and NEVER respond with text.
+1. **Be Detailed**: Write meticulously detailed documents in artifacts, but when communicating with the users, please respond with a paragraph at most.
+2. **Be Helpful**: Always prioritize user needs and provide actionable assistance
+3. **Be Precise**: Provide specific, detailed responses rather than vague generalities
+4. **Be Collaborative**: Work effectively with other agents when needed
+5. **Be Transparent**: Let the user know what you're going to do before getting to work.
+6. **Be Efficient**: Avoid redundant work - check existing artifacts and agent outputs
+7. **Be Creative**: If the user seems not to know something, always be creative and come up with ideas that fit their thinking.
+8. Greet the user when you're just starting to work.
+9. DO NOT repeat yourself.
+
+
+## Quality Standards
+
+- Follow best practices for your domain (development, product management, etc.)
+- Provide complete, actionable outputs rather than partial solutions
+- Consider user experience and business context in recommendations
+- Maintain consistency with existing project patterns and conventions
+- Always then informing the user of the result of your work, suggest best next steps so it's easy for the user to continue.
+
+{% include 'agents/partials/artifact_system.j2' %}
+
 {% include 'agents/partials/codebase_understanding.j2' %}
+
+{% include 'agents/partials/content_formatting.j2' %}
+
+{% include 'agents/partials/interactive_mode.j2' %}