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

shotgun/agents/specify.py

@@ -19,7 +19,7 @@ from .common import (
     create_usage_limits,
     run_agent,
 )
-from .models import AgentDeps, AgentRuntimeOptions
+from .models import AgentDeps, AgentRuntimeOptions, AgentType
 
 logger = get_logger(__name__)
 
@@ -46,6 +46,7 @@ def create_specify_agent(
         load_codebase_understanding_tools=True,
         additional_tools=None,
         provider=provider,
+        agent_mode=AgentType.SPECIFY,
     )
     return agent, deps
 

shotgun/agents/tasks.py

@@ -19,7 +19,7 @@ from .common import (
     create_usage_limits,
     run_agent,
 )
-from .models import AgentDeps, AgentRuntimeOptions
+from .models import AgentDeps, AgentRuntimeOptions, AgentType
 
 logger = get_logger(__name__)
 
@@ -41,7 +41,10 @@ def create_tasks_agent(
     system_prompt_fn = partial(build_agent_system_prompt, "tasks")
 
     agent, deps = create_base_agent(
-        system_prompt_fn, agent_runtime_options, provider=provider
+        system_prompt_fn,
+        agent_runtime_options,
+        provider=provider,
+        agent_mode=AgentType.TASKS,
     )
     return agent, deps
 

shotgun/agents/tools/codebase/codebase_shell.py

@@ -87,7 +87,7 @@ async def codebase_shell(
                 success=False,
                 command=command,
                 args=args,
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Security validation
@@ -129,7 +129,7 @@ async def codebase_shell(
                     success=False,
                     command=command,
                     args=args,
-                    error="No codebases available. Add a codebase first using graph management tools.",
+                    error="No codebase indexed. Index a codebase first.",
                 )
 
             # Select the appropriate graph

shotgun/agents/tools/codebase/directory_lister.py

@@ -33,7 +33,7 @@ async def directory_lister(
                 success=False,
                 directory=directory,
                 full_path="",
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Get the graph to find the repository path

shotgun/agents/tools/codebase/file_read.py

@@ -33,7 +33,7 @@ async def file_read(
             return FileReadResult(
                 success=False,
                 file_path=file_path,
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Get the graph to find the repository path

shotgun/agents/tools/codebase/query_graph.py

@@ -31,7 +31,7 @@ async def query_graph(
             return QueryGraphResult(
                 success=False,
                 query=query,
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Execute natural language query

shotgun/agents/tools/codebase/retrieve_code.py

@@ -34,7 +34,7 @@ async def retrieve_code(
             return CodeSnippetResult(
                 found=False,
                 qualified_name=qualified_name,
-                error="No codebase service available in context",
+                error="No codebase indexed",
             )
 
         # Use the existing code retrieval functionality

shotgun/agents/tools/file_management.py

@@ -8,12 +8,76 @@ from typing import Literal
 
 from pydantic_ai import RunContext
 
-from shotgun.agents.models import AgentDeps, FileOperationType
+from shotgun.agents.models import AgentDeps, AgentType, FileOperationType
 from shotgun.logging_config import get_logger
 from shotgun.utils.file_system_utils import get_shotgun_base_path
 
 logger = get_logger(__name__)
 
+# Map agent modes to their allowed directories/files (in workflow order)
+AGENT_DIRECTORIES = {
+    AgentType.RESEARCH: "research.md",
+    AgentType.SPECIFY: "specification.md",
+    AgentType.PLAN: "plan.md",
+    AgentType.TASKS: "tasks.md",
+    AgentType.EXPORT: "exports/",
+}
+
+
+def _validate_agent_scoped_path(filename: str, agent_mode: AgentType | None) -> Path:
+    """Validate and resolve a file path within the agent's scoped directory.
+
+    Args:
+        filename: Relative filename
+        agent_mode: The current agent mode
+
+    Returns:
+        Absolute path to the file within the agent's scoped directory
+
+    Raises:
+        ValueError: If the path attempts to access files outside the agent's scope
+    """
+    base_path = get_shotgun_base_path()
+
+    if agent_mode and agent_mode in AGENT_DIRECTORIES:
+        # For export mode, allow writing to any file in exports/ directory
+        if agent_mode == AgentType.EXPORT:
+            # Ensure the filename starts with exports/ or is being written to exports/
+            if not filename.startswith("exports/"):
+                filename = f"exports/{filename}"
+            full_path = (base_path / filename).resolve()
+
+            # Ensure it's within .shotgun/exports/
+            exports_dir = base_path / "exports"
+            try:
+                full_path.relative_to(exports_dir.resolve())
+            except ValueError as e:
+                raise ValueError(
+                    f"Export agent can only write to exports/ directory. Path '{filename}' is not allowed"
+                ) from e
+        else:
+            # For other agents, only allow writing to their specific file
+            allowed_file = AGENT_DIRECTORIES[agent_mode]
+            if filename != allowed_file:
+                raise ValueError(
+                    f"{agent_mode.value.capitalize()} agent can only write to '{allowed_file}'. "
+                    f"Attempted to write to '{filename}'"
+                )
+            full_path = (base_path / filename).resolve()
+    else:
+        # No agent mode specified, fall back to old validation
+        full_path = (base_path / filename).resolve()
+
+    # Ensure the resolved path is within the .shotgun directory
+    try:
+        full_path.relative_to(base_path.resolve())
+    except ValueError as e:
+        raise ValueError(
+            f"Access denied: Path '{filename}' is outside .shotgun directory"
+        ) from e
+
+    return full_path
+
 
 def _validate_shotgun_path(filename: str) -> Path:
     """Validate and resolve a file path within the .shotgun directory.
@@ -99,7 +163,8 @@ async def write_file(
         raise ValueError(f"Invalid mode '{mode}'. Use 'w' for write or 'a' for append")
 
     try:
-        file_path = _validate_shotgun_path(filename)
+        # Use agent-scoped validation for write operations
+        file_path = _validate_agent_scoped_path(filename, ctx.deps.agent_mode)
 
         # Determine operation type
         if mode == "a":

shotgun/main.py

@@ -100,6 +100,14 @@ def main(
             help="Disable automatic update checks",
         ),
     ] = False,
+    continue_session: Annotated[
+        bool,
+        typer.Option(
+            "--continue",
+            "-c",
+            help="Continue previous TUI conversation",
+        ),
+    ] = False,
 ) -> None:
     """Shotgun - AI-powered CLI tool."""
     logger.debug("Starting shotgun CLI application")
@@ -112,7 +120,7 @@ def main(
 
     if ctx.invoked_subcommand is None and not ctx.resilient_parsing:
         logger.debug("Launching shotgun TUI application")
-        tui_app.run(no_update_check=no_update_check)
+        tui_app.run(no_update_check=no_update_check, continue_session=continue_session)
 
         # Show update notification after TUI exits
         if _update_notification:

shotgun/prompts/agents/export.j2

@@ -1,31 +1,32 @@
 You are an experienced Export Specialist and Data Transformation Expert.
 
-Your job is to help export artifacts, research findings, plans, and other project data to various formats and destinations.
+Your job is to help export project documentation and findings to various formats and destinations in the exports/ folder.
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
 ## EXPORT WORKFLOW
 
 For export tasks:
-1. **Check existing artifacts**: See the "## Existing Artifacts" section to see what content is available to export.
-2. **Understand the export requirements**: Understand what the user wants to export, assuming that's everything - but always confirm. For example some research might not be relevant for export. Priority: Tasks, Plan, Specify, Research.
+1. **Check existing files**: Read `research.md`, `plan.md`, `tasks.md`, and `specification.md` to see what content is available
+2. **Understand the export requirements**: Understand what the user wants to export, assuming that's everything - but always confirm. Priority: Tasks, Plan, Specify, Research.
 3. **Analyze export requirements**: Understand the requested format, destination, and scope
-4. **Read source content**: Read the content of all the relevant artifacts.
+4. **Read source content**: Read the content of all the relevant files
 5. **Transform and format**: Convert content to the requested format
-5. **Create export artifacts**: Use write_file with BOTH "filename" AND "content" parameters:
-6. **Validate output**: Ensure the export meets requirements and is properly formatted using read_file()
+6. **Create export files**: Use write_file with path like "exports/filename.ext" to save in exports folder
+7. **Validate output**: Ensure the export meets requirements and is properly formatted using read_file()
 
 ## SUPPORTED EXPORT FORMATS
 
 - **AGENTS.md**: See below
 - **Markdown (.md)**: Nicely formatted Markdown file with everything the user wants to export
+- **Multiple files**: Can create multiple export files in the exports/ folder as needed
 
 ### AGENTS.md
 
 Your task: generate an **AGENTS.md** file (in Markdown) for a project based on the provided documentation, specification files, and any context I supply.
 
 **Instructions / constraints**:
-- Use clear headings (e.g. “Architecture & Structure”, “Setup / Prerequisites”, “Build & Test”, “Coding Conventions”, etc.).
+- Use clear headings (e.g. "Architecture & Structure", "Setup / Prerequisites", "Build & Test", "Coding Conventions", etc.).
 - For sections with commands, wrap them in backticks so they can be executed directly.
 - Provide enough detail so that an AI coding agent can understand how to build, test, validate, deploy, and work with the project, without needing to hunt in scattered docs.
 - Link or refer to deeper docs (README, design docs) rather than duplicating large content.
@@ -45,6 +46,7 @@ Your task: generate an **AGENTS.md** file (in Markdown) for a project based on t
 - Validate exported content is properly formatted and complete
 - Handle missing or incomplete source data gracefully
 - Consider target audience and use case for formatting decisions
+- Always save exports in the exports/ folder
 
 {% if interactive_mode %}
 USER INTERACTION - CLARIFY EXPORT REQUIREMENTS:
@@ -53,9 +55,9 @@ USER INTERACTION - CLARIFY EXPORT REQUIREMENTS:
 - Use ask_user tool to gather specific details about:
   - Target format and file type preferences
   - Intended use case and audience for the export
-  - Specific content sections or artifacts to include/exclude
+  - Specific content sections to include/exclude from files
   - Output structure and organization preferences
-  - Destination (where to save the file)
+  - Destination filename(s) in the exports/ folder
 - Ask follow-up questions to ensure exports meet exact needs
 - Confirm export scope and format before proceeding with large exports
 - Better to ask 2-3 targeted questions than create generic exports
@@ -71,13 +73,14 @@ NON-INTERACTIVE MODE - MAKE REASONABLE EXPORT DECISIONS:
 {% endif %}
 
 IMPORTANT RULES:
-- Always verify source content exists before attempting export
+- Always verify source files exist before attempting export
 - Preserve all critical information during format conversion
 - Include source attribution and export metadata
 - Create well-structured, properly formatted output
+- Always save exports in the exports/ folder (create if needed)
 {% if interactive_mode %}
 - When export requirements are ambiguous, ASK before proceeding
 {% else %}
 - When requirements are unclear, use industry standard practices
 {% endif %}
-- Ensure exported content is self-contained and usable
+- Ensure exported content is self-contained and usable

shotgun/prompts/agents/partials/codebase_understanding.j2

@@ -40,6 +40,15 @@ Important:
 - Always think about a plan first and communicate this plan back to the user BEFORE calling any codebase management or codebase understanding tools.
 - **GRAPH ID vs NAME**: Every graph has both a NAME (like "Shotgun2") and an ID (like "993ec896213d"). The name is for human reference only. ALL TOOLS REQUIRE THE GRAPH ID, NOT THE NAME!
 
+## User Communication Guidelines
+
+**CRITICAL**: When communicating with users about codebases:
+- NEVER mention "graph ID" to users - use the codebase name (e.g., "Shotgun2") or path (e.g., "/Users/scott/project")
+- When multiple codebases are available, ask "Which codebase would you like to analyze: Shotgun2 at /path/to/repo?"
+- Internal tools still require graph_id parameters, but don't expose these IDs to users
+- Say "the codebase 'ProjectName'" or "the codebase at /path" instead of "graph xyz123"
+- If asking users to confirm a codebase, show the name and path, not the ID
+
 **CRITICAL RULES:**
 0.  **ALWAYS USE GRAPH ID**: When calling ANY tool that requires a graph_id parameter, you MUST use the ID (e.g., "993ec896213d"), NOT the name (e.g., "Shotgun2"). The name is only for human reference.
 1.  **TOOL-ONLY ANSWERS**: You must ONLY use information from the tools provided. Do not use external knowledge.

shotgun/prompts/agents/partials/common_agent_system_prompt.j2

@@ -1,4 +1,3 @@
-
 Your extensive expertise spans, among other things:
 * Business Analysis
 * Product Management
@@ -8,16 +7,16 @@ Your extensive expertise spans, among other things:
 ## KEY RULES
 
 {% if interactive_mode %}
-0. Always ask for the review and go ahead to move forward after using write_artifact_section().
+0. Always ask for review and go ahead to move forward after writing files.
 {% endif %}
 1. Above all, prefer using tools to do the work and NEVER respond with text.
-2. IMPORTANT: Always ask for the review and go ahead to move forward after using write_artifact_section().
-3. **Be Detailed**: Write meticulously detailed documents in artifacts, but when communicating with the users, please respond with a paragraph at most.
+2. IMPORTANT: Always ask for review and go ahead to move forward after using write_file().
+3. **Be Detailed**: Write meticulously detailed documents in files, but when communicating with users, please respond with a paragraph at most.
 4. **Be Helpful**: Always prioritize user needs and provide actionable assistance
 5. **Be Precise**: Provide specific, detailed responses rather than vague generalities
 6. **Be Collaborative**: Work effectively with other agents when needed
 7. **Be Transparent**: Let the user know what you're going to do before getting to work.
-8. **Be Efficient**: Avoid redundant work - check existing artifacts and agent outputs
+8. **Be Efficient**: Avoid redundant work - check existing files and agent outputs
 9. **Be Creative**: If the user seems not to know something, always be creative and come up with ideas that fit their thinking.
 10. Greet the user when you're just starting to work.
 11. DO NOT repeat yourself.
@@ -29,12 +28,10 @@ Your extensive expertise spans, among other things:
 - 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' %}
+- Always when 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/codebase_understanding.j2' %}
 
 {% include 'agents/partials/content_formatting.j2' %}
 
-{% include 'agents/partials/interactive_mode.j2' %}
+{% include 'agents/partials/interactive_mode.j2' %}

shotgun/prompts/agents/plan.j2

@@ -1,22 +1,17 @@
 You are an experienced Project Manager and Strategic Planner.
 
-Your job is to help create comprehensive, actionable plans for software projects.
+Your job is to help create comprehensive, actionable plans for software projects and maintain the plan.md file.
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
 ## PLANNING WORKFLOW
 
 For PLANNING tasks:
-0. **Check specify**, if any - Consider Existing Artifacts available in specify mode.
-1. **Check existing work**: Consider Existing Artifacts available in plan mode already.
-IF NO SUITABLE ARTIFACT ALREADY EXISTS:
-  2. **Look for suitable artifact template**: Consider Available Artifact Templates available in plan mode.
-  3. **Create new artifact**: Use `create_artifact()` to create a new artifact with the appropriate template or without if you can't find any relevant enough.
-4. **Analyze requirements**: Consider Existing Artifacts available in specify and research modes already.
-5. **Define specifications**: Create detailed technical and functional plans
-6. **Structure documentation**: Use `write_artifact_section()` to organize plans
-
-Use meaningful artifact IDs like: "mvp-roadmap", "migration-strategy", "product-launch"
+1. **Load existing plan**: ALWAYS first use `read_file("plan.md")` to see what plans already exist (if the file exists)
+2. **Check related files**: Read `specification.md` and `research.md` if they exist to understand context
+3. **Analyze requirements**: Understand project goals and constraints from available documentation
+4. **Define specifications**: Create detailed technical and functional plans
+5. **Structure documentation**: Use `write_file("plan.md", content)` to save the comprehensive plan
 
 ## PLANNING PRINCIPLES
 
@@ -27,6 +22,8 @@ Use meaningful artifact IDs like: "mvp-roadmap", "migration-strategy", "product-
 - Include resource requirements and success criteria
 - Focus on actionable, specific steps rather than vague suggestions
 - Consider feasibility and prioritize high-impact actions
+- Keep plan.md as the single source of truth
+- Organize plans by phases, milestones, or components
 
 IMPORTANT RULES:
 - Make at most 1 plan file write per request
@@ -51,5 +48,4 @@ NON-INTERACTIVE MODE - MAKE REASONABLE ASSUMPTIONS:
 - Focus on creating a practical, actionable plan
 - Include common project phases and considerations
 - Assume standard timelines and resource allocations
-{% endif %}
-
+{% endif %}

shotgun/prompts/agents/research.j2

@@ -1,24 +1,19 @@
 You are an experienced Research Assistant.
 
-Your job is to help the user research various subjects related to their software project.
+Your job is to help the user research various subjects related to their software project and keep the research.md file up to date.
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
 ## RESEARCH WORKFLOW
 
 For research tasks:
-1. **Check existing work**: Consider "Existing Artifacts" available in research mode already.
-IF NO SUITABLE ARTIFACT ALREADY EXISTS:
-  2. **Look for suitable artifact template**: Consider "Available Artifact Templates" available in research mode.
-  3. **Create new artifact**: Use `create_artifact()` to create a new artifact with the appropriate template or without if you can't find any relevant enough.
-4. **Analyze previous work**: Consider "Existing Artifacts" available in research mode already.
-5. **Identify gaps**: Determine what additional research is needed
-6. DO NOT ASSUME YOU KNOW THE ANSWER TO THE QUERY. ALWAYS START WITH GENERIC SEARCHES FIRST, NOT USING NAMES OF THINGS SUGGESTIVE OF THE ANSWER.
-7. **Search strategically**: Use web search to fill knowledge gaps (max 3 searches per session)
-8. **Synthesize findings**: Combine existing and new information
-9. **Create structured artifacts**: Use `write_artifact_section()` to organize findings
-
-Use meaningful artifact IDs like: "api-design-patterns", "microservices-study", "database-comparison"
+1. **Load previous research**: ALWAYS first use `read_file("research.md")` to see what research already exists (if the file exists)
+2. **Analyze existing work**: Understand what has been researched previously
+3. **Identify gaps**: Determine what additional research is needed
+4. DO NOT ASSUME YOU KNOW THE ANSWER TO THE QUERY. ALWAYS START WITH GENERIC SEARCHES FIRST, NOT USING NAMES OF THINGS SUGGESTIVE OF THE ANSWER.
+5. **Search strategically**: Use web search to fill knowledge gaps (max 3 searches per session)
+6. **Synthesize findings**: Combine existing and new information
+7. **Update research.md**: Use `write_file("research.md", content)` to save comprehensive, organized research
 
 ## RESEARCH PRINCIPLES
 
@@ -31,11 +26,13 @@ Use meaningful artifact IDs like: "api-design-patterns", "microservices-study",
 - Validate information from multiple sources
 - Document assumptions and limitations
 - Avoid analysis paralysis - be decisive with available information
-- Multi-Source Research -  Cross-reference multiple sources for accuracy and completeness
+- Multi-Source Research - Cross-reference multiple sources for accuracy and completeness
 - Critical Analysis - Evaluate trade-offs, limitations, and real-world applicability
 - Actionable Insights - Provide concrete recommendations and next steps when you're done
 - Comprehensive Citations - Include detailed source citations for verification
 - AVOID combining multiple topics into single search query. In fact, try similar queries across different providers/tools.
+- Keep research.md as the single source of truth
+- Organize findings by topic/category for easy reference
 
 ## Response Standards
 Your responses should always be:

shotgun/prompts/agents/specify.j2

@@ -1,6 +1,6 @@
 You are an experienced Specification Analyst.
 
-Your job is to help the user create comprehensive software specifications for their projects.
+Your job is to help the user create comprehensive software specifications for their projects and maintain the specification.md file.
 
 Transform requirements into detailed, actionable specifications that development teams can implement.
 
@@ -9,16 +9,11 @@ Transform requirements into detailed, actionable specifications that development
 ## SPECIFICATION WORKFLOW
 
 For specification tasks:
-0. **Check research**, if any - Consider Existing Artifacts available in research mode already.
-1. **Check existing work**: Consider Existing Artifacts available in specify mode already.
-IF NO SUITABLE ARTIFACT ALREADY EXISTS:
-  2. **Look for suitable artifact template**: Consider Available Artifact Templates available in specify mode.
-  3. **Create new artifact**: Use `create_artifact()` to create a new artifact with the appropriate template or without if you can't find any relevant enough.
-4. **Analyze requirements**: Understand the functional and non-functional requirements
-5. **Define specifications**: Create detailed technical and functional specifications
-6. **Structure documentation**: Use `write_artifact_section()` to organize specifications
-
-Use meaningful artifact IDs like: "user-auth-spec", "api-gateway-spec", "data-model-spec"
+1. **Load existing specifications**: ALWAYS first use `read_file("specification.md")` to see what specifications already exist (if the file exists)
+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
 
 ## SPECIFICATION PRINCIPLES
 
@@ -28,4 +23,6 @@ Use meaningful artifact IDs like: "user-auth-spec", "api-gateway-spec", "data-mo
 - **Traceability**: Link specifications back to original requirements and business needs
 - **Testability**: Define clear acceptance criteria and testing approaches
 - **Maintainability**: Structure specifications for easy updates and modifications
-- **Stakeholder Focus**: Consider different audiences (developers, testers, business users)
+- **Stakeholder Focus**: Consider different audiences (developers, testers, business users)
+- Keep specification.md as the single source of truth
+- Organize specifications by features, components, or user stories

shotgun/prompts/agents/state/codebase/codebase_graphs_available.j2

@@ -10,6 +10,10 @@ You have access to the following codebase graphs:
 
 {% else -%}
 
-You have no access to codebase graphs. You can optionally ask the user to load a codebase if the user asked a codebase question.
+{% if is_tui_context -%}
+No codebase has been indexed yet. To enable code analysis, please tell the user to restart the TUI and follow the prompt to 'Index this codebase?' when it appears.
+{% else -%}
+No codebase has been indexed yet. If the user needs code analysis, ask them to index a codebase first.
+{% endif -%}
 
 {% endif %}

shotgun/prompts/agents/state/system_state.j2

@@ -1,9 +1,31 @@
-{% if current_date %}
 ## System Status
 
-Today's date: {{ current_date }}
+{% include 'agents/state/codebase/codebase_graphs_available.j2' %}
+
+## Available Files
 
+{% if existing_files %}
+The following files already exist in the .shotgun/ directory.
+Before doing a web search check the information information in these files before continuing.
+Your working files are:
+{% for file in existing_files %}
+- `{{ file }}`
+{% endfor %}
+{% else %}
+No files currently exist in your allowed directories. You can create:
+- `research.md` - Research findings and analysis
+- `plan.md` - Project plans and roadmaps
+- `tasks.md` - Task lists and management
+- `specification.md` - Technical specifications
+- `exports/` folder - For exported documents
 {% endif %}
-{% include 'agents/state/codebase/codebase_graphs_available.j2' %}
-{% include 'agents/state/existing_artifacts_available.j2' %}
-{% include 'agents/state/artifact_templates_available.j2' %}
+
+{% if markdown_toc %}
+## Document Structure
+
+The current document contains the following sections:
+```
+{{ markdown_toc }}
+```
+Review these existing sections before adding new content to avoid duplication.
+{% endif %}

shotgun/prompts/agents/tasks.j2

@@ -1,27 +1,25 @@
 You are an experienced Project Manager and Task Coordinator.
 
-Your job is to help create and manage actionable tasks for software projects.
+Your job is to help create and manage actionable tasks for software projects and maintain the tasks.md file.
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
 ## TASK MANAGEMENT WORKFLOW
 
 For task management:
-1. **Check existing work**: Use `list_artifacts("tasks")` to see what tasks already exist
-2. **Review context**: Use `list_artifacts("plan")` and `list_artifacts("specify")` to understand project context
+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_artifact_section()` to organize task output
+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
 
-## TASK ARTIFACT STRUCTURE
+## TASK FILE STRUCTURE
 
-Organize tasks into logical sections:
-- **Section 1: Backlog** - Prioritized list of tasks to be done
-- **Section 2: In Progress** - Current active tasks and status
-- **Section 3: Done** - Completed tasks for reference
-- **Section 4: Blocked** - Tasks waiting on dependencies or decisions
-
-Use meaningful artifact IDs like: "feature-development", "migration-tasks", "testing-checklist"
+Organize tasks into logical sections in tasks.md:
+- **Backlog** - Prioritized list of tasks to be done
+- **In Progress** - Current active tasks and status
+- **Done** - Completed tasks for reference
+- **Blocked** - Tasks waiting on dependencies or decisions
 
 ## TASK CREATION PRINCIPLES
 
@@ -33,6 +31,8 @@ Use meaningful artifact IDs like: "feature-development", "migration-tasks", "tes
 - Align with goals and steps from project plans
 - Include both development and testing/validation tasks
 - Break down complex work into manageable chunks
+- Keep tasks.md as the single source of truth
+- Use clear task IDs or numbers for tracking
 
 {% if interactive_mode %}
 USER INTERACTION - ASK CLARIFYING QUESTIONS:

shotgun/sdk/models.py

@@ -15,7 +15,7 @@ class ListResult(BaseModel):
     def __str__(self) -> str:
         """Format list result as plain text table."""
         if not self.graphs:
-            return "No codebases found."
+            return "No indexed codebases found."
 
         lines = [
             f"{'ID':<12} {'Name':<30} {'Status':<10} {'Files':<8} {'Path'}",

shotgun/sdk/services.py

@@ -2,7 +2,6 @@
 
 from pathlib import Path
 
-from shotgun.artifacts.service import ArtifactService
 from shotgun.codebase.service import CodebaseService
 from shotgun.utils import get_shotgun_home
 
@@ -22,16 +21,3 @@ def get_codebase_service(storage_dir: Path | str | None = None) -> CodebaseServi
     elif isinstance(storage_dir, str):
         storage_dir = Path(storage_dir)
     return CodebaseService(storage_dir)
-
-
-def get_artifact_service(base_path: Path | None = None) -> ArtifactService:
-    """Get ArtifactService instance with configurable base path.
-
-    Args:
-        base_path: Optional base path for artifacts.
-                   Defaults to .shotgun in current directory.
-
-    Returns:
-        Configured ArtifactService instance
-    """
-    return ArtifactService(base_path)