shotgun-sh 0.1.0.dev26__py3-none-any.whl → 0.1.0.dev27__py3-none-any.whl

shotgun/agents/agent_manager.py

@@ -41,6 +41,7 @@ from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 
 from .export import create_export_agent
 from .history.compaction import apply_persistent_compaction
+from .messages import AgentSystemPrompt
 from .models import AgentDeps, AgentRuntimeOptions
 from .plan import create_plan_agent
 from .research import create_research_agent
@@ -278,15 +279,51 @@ class AgentManager(Widget):
 
         deps.agent_mode = self._current_agent_type
 
+        # Filter out system prompts from other agent types
+        from pydantic_ai.messages import ModelRequestPart
+
+        filtered_history: list[ModelMessage] = []
+        for message in message_history:
+            # Keep all non-ModelRequest messages as-is
+            if not isinstance(message, ModelRequest):
+                filtered_history.append(message)
+                continue
+
+            # Filter out AgentSystemPrompts from other agent types
+            filtered_parts: list[ModelRequestPart] = []
+            for part in message.parts:
+                # Keep non-AgentSystemPrompt parts
+                if not isinstance(part, AgentSystemPrompt):
+                    filtered_parts.append(part)
+                    continue
+
+                # Only keep system prompts from the same agent type
+                if part.agent_mode == deps.agent_mode:
+                    filtered_parts.append(part)
+
+            # Only add the message if it has parts remaining
+            if filtered_parts:
+                filtered_history.append(ModelRequest(parts=filtered_parts))
+
+        message_history = filtered_history
+
         # Add a system status message so the agent knows whats going on
         message_history = await add_system_status_message(deps, message_history)
 
-        # Check if the message history already has a system prompt
-        has_system_prompt = any(
-            hasattr(msg, "parts")
-            and any(isinstance(part, SystemPromptPart) for part in msg.parts)
-            for msg in message_history
-        )
+        # Check if the message history already has a system prompt from the same agent type
+        has_system_prompt = False
+        for message in message_history:
+            if not isinstance(message, ModelRequest):
+                continue
+
+            for part in message.parts:
+                if not isinstance(part, AgentSystemPrompt):
+                    continue
+
+                # Check if it's from the same agent type
+                if part.agent_mode == deps.agent_mode:
+                    has_system_prompt = True
+                    break
 
         # Always ensure we have a system prompt for the agent
         # (compaction may remove it from persistent history, but agent needs it)
@@ -472,8 +509,6 @@ class AgentManager(Widget):
         Returns:
             List of messages without system prompt parts
         """
-        from pydantic_ai.messages import SystemPromptPart
-
         filtered_messages: list[ModelMessage | HintMessage] = []
         for msg in messages:
             if isinstance(msg, HintMessage):

shotgun/agents/common.py

@@ -16,7 +16,6 @@ from pydantic_ai.agent import AgentRunResult
 from pydantic_ai.messages import (
     ModelMessage,
     ModelRequest,
-    SystemPromptPart,
 )
 
 from shotgun.agents.config import ProviderType, get_config_manager, get_provider_model
@@ -29,6 +28,7 @@ from shotgun.utils.file_system_utils import get_shotgun_base_path
 
 from .history import token_limit_compactor
 from .history.compaction import apply_persistent_compaction
+from .messages import AgentSystemPrompt, SystemStatusPrompt
 from .models import AgentDeps, AgentRuntimeOptions, PipelineConfigEntry
 from .tools import (
     append_file,
@@ -85,7 +85,7 @@ async def add_system_status_message(
     message_history.append(
         ModelRequest(
             parts=[
-                SystemPromptPart(content=system_state),
+                SystemStatusPrompt(content=system_state),
             ]
         )
     )
@@ -315,10 +315,9 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
         # Only show # and ## headings from prior files, max 500 chars each
         prior_toc = _extract_file_toc_content(file_path, max_depth=2, max_chars=500)
         if prior_toc:
-            # Add section header
-            file_label = prior_file.replace(".md", "").replace("_", " ").title()
+            # Add section with XML tags
             toc_sections.append(
-                f"=== Prior Context: {file_label} (summary) ===\n{prior_toc}"
+                f'<TABLE_OF_CONTENTS file_name="{prior_file}">\n{prior_toc}\n</TABLE_OF_CONTENTS>'
             )
 
     # Extract TOC from own file (full detail)
@@ -326,10 +325,10 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
         own_path = base_path / config.own_file
         own_toc = _extract_file_toc_content(own_path, max_depth=None, max_chars=2000)
         if own_toc:
-            file_label = config.own_file.replace(".md", "").replace("_", " ").title()
-            # Put own file TOC at the beginning
+            # Put own file TOC at the beginning with XML tags
             toc_sections.insert(
-                0, f"=== Your Current Document: {file_label} ===\n{own_toc}"
+                0,
+                f'<TABLE_OF_CONTENTS file_name="{config.own_file}">\n{own_toc}\n</TABLE_OF_CONTENTS>',
             )
 
     # Combine all sections
@@ -484,7 +483,9 @@ async def add_system_prompt_message(
 
     # Create system message and prepend to message history
     system_message = ModelRequest(
-        parts=[SystemPromptPart(content=system_prompt_content)]
+        parts=[
+            AgentSystemPrompt(content=system_prompt_content, agent_mode=deps.agent_mode)
+        ]
     )
     message_history.insert(0, system_message)
     logger.debug("✅ System prompt prepended as first message")

shotgun/agents/history/history_processors.py

@@ -6,12 +6,12 @@ from pydantic_ai.messages import (
     ModelMessage,
     ModelRequest,
     ModelResponse,
-    SystemPromptPart,
     TextPart,
     UserPromptPart,
 )
 
 from shotgun.agents.config.models import shotgun_model_request
+from shotgun.agents.messages import AgentSystemPrompt, SystemStatusPrompt
 from shotgun.agents.models import AgentDeps
 from shotgun.logging_config import get_logger
 from shotgun.prompts import PromptLoader
@@ -20,8 +20,9 @@ from .constants import SUMMARY_MARKER, TOKEN_LIMIT_RATIO
 from .context_extraction import extract_context_from_messages
 from .history_building import ensure_ends_with_model_request
 from .message_utils import (
+    get_agent_system_prompt,
     get_first_user_request,
-    get_system_prompt,
+    get_latest_system_status,
 )
 from .token_estimation import (
     calculate_max_summarization_tokens as _calculate_max_summarization_tokens,
@@ -274,31 +275,39 @@ async def token_limit_compactor(
         new_summary_part = create_marked_summary_part(summary_response)
 
         # Extract essential context from messages before the last summary (if any)
-        system_prompt = ""
+        agent_prompt = ""
+        system_status = ""
         first_user_prompt = ""
         if last_summary_index > 0:
-            # Get system and first user from original conversation
-            system_prompt = get_system_prompt(messages[:last_summary_index]) or ""
+            # Get agent system prompt and first user from original conversation
+            agent_prompt = get_agent_system_prompt(messages[:last_summary_index]) or ""
             first_user_prompt = (
                 get_first_user_request(messages[:last_summary_index]) or ""
             )
 
+        # Get the latest system status from all messages
+        system_status = get_latest_system_status(messages) or ""
+
         # Create the updated summary message
         updated_summary_message = ModelResponse(parts=[new_summary_part])
 
         # Build final compacted history with CLEAN structure
         compacted_messages: list[ModelMessage] = []
 
-        # Only add system/user context if it exists and is meaningful
-        if system_prompt or first_user_prompt:
-            compacted_messages.append(
-                ModelRequest(
-                    parts=[
-                        SystemPromptPart(content=system_prompt),
-                        UserPromptPart(content=first_user_prompt),
-                    ]
-                )
-            )
+        # Build parts for the initial request
+        from pydantic_ai.messages import ModelRequestPart
+
+        parts: list[ModelRequestPart] = []
+        if agent_prompt:
+            parts.append(AgentSystemPrompt(content=agent_prompt))
+        if system_status:
+            parts.append(SystemStatusPrompt(content=system_status))
+        if first_user_prompt:
+            parts.append(UserPromptPart(content=first_user_prompt))
+
+        # Only add if we have at least one part
+        if parts:
+            compacted_messages.append(ModelRequest(parts=parts))
 
         # Add the summary
         compacted_messages.append(updated_summary_message)
@@ -390,19 +399,26 @@ async def _full_compaction(
     marked_summary_part = create_marked_summary_part(summary_response)
 
     # Build compacted history structure
-    system_prompt = get_system_prompt(messages) or ""
+    agent_prompt = get_agent_system_prompt(messages) or ""
+    system_status = get_latest_system_status(messages) or ""
     user_prompt = get_first_user_request(messages) or ""
 
+    # Build parts for the initial request
+    from pydantic_ai.messages import ModelRequestPart
+
+    parts: list[ModelRequestPart] = []
+    if agent_prompt:
+        parts.append(AgentSystemPrompt(content=agent_prompt))
+    if system_status:
+        parts.append(SystemStatusPrompt(content=system_status))
+    if user_prompt:
+        parts.append(UserPromptPart(content=user_prompt))
+
     # Create base structure
-    compacted_messages: list[ModelMessage] = [
-        ModelRequest(
-            parts=[
-                SystemPromptPart(content=system_prompt),
-                UserPromptPart(content=user_prompt),
-            ]
-        ),
-        ModelResponse(parts=[marked_summary_part]),
-    ]
+    compacted_messages: list[ModelMessage] = []
+    if parts:
+        compacted_messages.append(ModelRequest(parts=parts))
+    compacted_messages.append(ModelResponse(parts=[marked_summary_part]))
 
     # Ensure history ends with ModelRequest for PydanticAI compatibility
     compacted_messages = ensure_ends_with_model_request(compacted_messages, messages)

shotgun/agents/history/message_utils.py

@@ -7,6 +7,8 @@ from pydantic_ai.messages import (
     UserPromptPart,
 )
 
+from shotgun.agents.messages import AgentSystemPrompt, SystemStatusPrompt
+
 
 def get_first_user_request(messages: list[ModelMessage]) -> str | None:
     """Extract first user request content from messages."""
@@ -37,10 +39,46 @@ def get_user_content_from_request(request: ModelRequest) -> str | None:
 
 
 def get_system_prompt(messages: list[ModelMessage]) -> str | None:
-    """Extract system prompt from messages."""
+    """Extract system prompt from messages (any SystemPromptPart)."""
     for msg in messages:
         if isinstance(msg, ModelRequest):
             for part in msg.parts:
                 if isinstance(part, SystemPromptPart):
                     return part.content
     return None
+
+
+def get_agent_system_prompt(messages: list[ModelMessage]) -> str | None:
+    """Extract the main agent system prompt from messages.
+
+    Prioritizes AgentSystemPrompt but falls back to generic SystemPromptPart
+    if no AgentSystemPrompt is found.
+    """
+    # First try to find AgentSystemPrompt
+    for msg in messages:
+        if isinstance(msg, ModelRequest):
+            for part in msg.parts:
+                if isinstance(part, AgentSystemPrompt):
+                    return part.content
+
+    # Fall back to any SystemPromptPart (excluding SystemStatusPrompt)
+    for msg in messages:
+        if isinstance(msg, ModelRequest):
+            for part in msg.parts:
+                if isinstance(part, SystemPromptPart) and not isinstance(
+                    part, SystemStatusPrompt
+                ):
+                    return part.content
+
+    return None
+
+
+def get_latest_system_status(messages: list[ModelMessage]) -> str | None:
+    """Extract the most recent system status prompt from messages."""
+    # Iterate in reverse to find the most recent status
+    for msg in reversed(messages):
+        if isinstance(msg, ModelRequest):
+            for part in msg.parts:
+                if isinstance(part, SystemStatusPrompt):
+                    return part.content
+    return None

shotgun/agents/messages.py

@@ -0,0 +1,35 @@
+"""Custom message types for Shotgun agents.
+
+This module defines specialized SystemPromptPart subclasses to distinguish
+between different types of system prompts in the agent pipeline.
+"""
+
+from dataclasses import dataclass, field
+
+from pydantic_ai.messages import SystemPromptPart
+
+from shotgun.agents.models import AgentType
+
+
+@dataclass
+class AgentSystemPrompt(SystemPromptPart):
+    """System prompt containing the main agent instructions.
+
+    This is the primary system prompt that defines the agent's role,
+    capabilities, and behavior. It should be preserved during compaction.
+    """
+
+    prompt_type: str = "agent"
+    agent_mode: AgentType | None = field(default=None)
+
+
+@dataclass
+class SystemStatusPrompt(SystemPromptPart):
+    """System prompt containing current system status information.
+
+    This includes table of contents, available files, and other contextual
+    information about the current state. Only the most recent status should
+    be preserved during compaction.
+    """
+
+    prompt_type: str = "status"

shotgun/agents/tools/file_management.py

@@ -20,7 +20,15 @@ AGENT_DIRECTORIES = {
     AgentType.SPECIFY: "specification.md",
     AgentType.PLAN: "plan.md",
     AgentType.TASKS: "tasks.md",
-    AgentType.EXPORT: "exports/",
+    AgentType.EXPORT: "*",  # Export agent can write anywhere except protected files
+}
+
+# Files protected from export agent modifications
+PROTECTED_AGENT_FILES = {
+    "research.md",
+    "specification.md",
+    "plan.md",
+    "tasks.md",
 }
 
 
@@ -40,21 +48,17 @@ def _validate_agent_scoped_path(filename: str, agent_mode: AgentType | None) ->
     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
+        # For export mode, allow writing to any file except protected agent files
         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:
+            # Check if trying to write to a protected file
+            if filename in PROTECTED_AGENT_FILES:
                 raise ValueError(
-                    f"Export agent can only write to exports/ directory. Path '{filename}' is not allowed"
-                ) from e
+                    f"Export agent cannot write to protected file '{filename}'. "
+                    f"Protected files are: {', '.join(sorted(PROTECTED_AGENT_FILES))}"
+                )
+
+            # Allow writing anywhere else in .shotgun directory
+            full_path = (base_path / filename).resolve()
         else:
             # For other agents, only allow writing to their specific file
             allowed_file = AGENT_DIRECTORIES[agent_mode]

shotgun/prompts/agents/export.j2

@@ -1,166 +1,301 @@
-You are an experienced Export Specialist and Data Transformation Expert.
+You are an experienced Export Specialist and Agents.md/CLAUDE.md Documentation Expert.
 
-Your job is to help export project documentation and findings to various formats and destinations in the exports/ folder.
+Your primary job is to generate Agents.md or CLAUDE.md files following the https://agents.md/ standard format that provides project setup and development guidance for AI coding agents (NOT a comprehensive combination of all pipeline files).
+
+**CRITICAL CLARIFICATION**:
+- CLAUDE.md is development documentation FOR Claude Code to read about the PROJECT
+- CLAUDE.md is NOT a guide about HOW TO USE or INTERACT WITH Claude
+- Do NOT create prompt templates, interaction guides, or ```prompt blocks
+- The content is IDENTICAL for Agents.md and CLAUDE.md - only filename differs
 
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
 ## MEMORY MANAGEMENT PROTOCOL
 
-- You can ONLY write to the `exports/` directory
-- SHOULD READ all files: `research.md`, `specification.md`, `plan.md`, `tasks.md`
-- Create new export files, don't modify source files
-- Name exports descriptively with timestamps: `exports/AGENTS_[timestamp].md`
+- You can write to ANY file EXCEPT protected files
+- PROTECTED FILES (DO NOT MODIFY): `research.md`, `specification.md`, `plan.md`, `tasks.md`
+- SHOULD READ all pipeline files: `research.md`, `specification.md`, `plan.md`, `tasks.md`
+- PRIMARY OUTPUT:
+  - For Claude Code: Create `CLAUDE.md` (at root, NOT in any folder)
+  - For other AI agents: Create `Agents.md` (at root, NOT in any folder)
+  - **IMPORTANT**: Save these files directly, not in exports/ or any subdirectory
+- OPTIONAL: Additional specialized exports can go in exports/ folder if needed
 - Each export is a standalone deliverable for AI agents
 
 ## AI AGENT PIPELINE AWARENESS
 
-**CRITICAL**: Your exports will be consumed by AI coding agents (Claude Code, Cursor, Windsurf, etc.)
-- The AGENTS.md file is THE primary deliverable for AI agents
-- Consolidate all relevant information into a single, actionable document
-- Include all necessary context without requiring access to source files
-- Structure exports for immediate AI agent consumption
-- Prioritize tasks and implementation steps from tasks.md
-- Include specifications and API details from specification.md
-- Add relevant research findings that affect implementation
-- Format as executable instructions, not educational content
+**CRITICAL**: Your export file will be consumed by AI coding agents (Claude Code, Cursor, Windsurf, etc.)
+
+**IMPORTANT - WHAT NOT TO DO**:
+- DO NOT create a comprehensive combination of all pipeline files
+- DO NOT copy-paste entire sections from research.md, plan.md, tasks.md, specification.md
+- DO NOT create detailed task lists with inputs/outputs
+- DO NOT make a huge document that merges everything together
+
+**WHAT TO DO INSTEAD**:
+- Claude Code: Save as `CLAUDE.md` at root (just `write_file('CLAUDE.md', content)`)
+- Other AI agents: Save as `Agents.md` at root (just `write_file('Agents.md', content)`)
+- **DO NOT save in exports/ folder** - save directly at root
+- Both files use THE SAME FORMAT - only the filename differs
+- The file provides PROJECT SETUP and DEVELOPMENT GUIDANCE
+- **CRITICAL**: CLAUDE.md is development documentation FOR Claude Code to use, NOT a guide ABOUT how to use Claude
+- **DO NOT** create prompt templates or "how to interact with Claude" guides
+- **DO NOT** use ```prompt blocks or interaction examples
+- Focus on: environment setup, code style, testing commands, build/deployment
+- Extract only KEY SETUP INFORMATION from pipeline files
+- Create a concise guide for working with the codebase
+- Think of it like a technical README for AI agents
 
 ## EXPORT WORKFLOW
 
-For AGENTS.md exports:
-1. **MANDATORY: Read ALL pipeline files**:
-   - `tasks.md` - Extract actionable tasks with inputs/outputs
-   - `specification.md` - Get primary objective and constraints
-   - `plan.md` - Convert stages to success criteria
-   - `research.md` - Extract codebase context and open questions
-2. **Map content to template sections**:
-   - Primary Objective: From specification.md's main goal
-   - Tasks: From tasks.md, formatted as action items
-   - Research Needed: Unresolved questions from research.md
-   - Codebase Context: Technical findings from research.md
-   - Success Criteria: Plan.md stages as measurable outcomes
-   - Important Notes: Critical constraints from all files
-   - References: Documentation links from research.md
-3. **Transform content**: Convert to action-oriented language for AI agents
-4. **Create export**: Save as `exports/AGENTS.md` or `exports/AGENTS_[timestamp].md`
-5. **Validate**: Ensure every section has actionable content
-
-For other export tasks:
-1. **Check existing files**: Read relevant source files
-2. **Understand requirements**: Determine format and scope
-3. **Read source content**: Load all necessary information
-4. **Transform and format**: Convert to requested format
-5. **Create export files**: Save in exports/ folder
-6. **Validate output**: Verify proper formatting
+**CRITICAL - READ FILES FIRST**:
+Before writing ANY export, you MUST:
+1. **READ ALL PIPELINE FILES** - This is MANDATORY, not optional:
+   - `read_file('research.md')` - Read FIRST to understand what was researched
+   - `read_file('specification.md')` - Read to understand project requirements
+   - `read_file('plan.md')` - Read to understand development approach
+   - `read_file('tasks.md')` - Read to understand implementation details
+2. **UNDERSTAND THE PROJECT** - After reading, you must understand:
+   - What the actual project is about (NOT generic assumptions)
+   - The specific technologies being used
+   - The actual development requirements
+3. **VALIDATE RELEVANCE** - Your export MUST be about the ACTUAL project described in the files
+   - DO NOT write generic guides (like "Claude Integration Guide")
+   - DO NOT assume what the project is without reading files
+   - Content MUST be based on what you read in the pipeline files
+
+**CRITICAL FILE LOCATION RULE**:
+- Agents.md and CLAUDE.md must be saved at ROOT level
+- Use `write_file('CLAUDE.md', content)` or `write_file('Agents.md', content)`
+- DO NOT use `write_file('exports/CLAUDE.md', ...)` or any folder path
+- These are the ONLY files that go at root - everything else can go in exports/
+
+**FILE NAMING EXAMPLES**:
+
+<GOOD_FILENAME_EXAMPLES>
+1. `write_file('CLAUDE.md', content)` - YES! For Claude Code export
+2. `write_file('Agents.md', content)` - YES! For other AI agents
+3. `write_file('exports/detailed_report.md', content)` - YES! Additional exports go in exports/
+</GOOD_FILENAME_EXAMPLES>
+
+<BAD_FILENAME_EXAMPLES>
+1. `write_file('exports/CLAUDE.md', content)` - NO! CLAUDE.md must be at root
+2. `write_file('exports/ai_agent_cli_claude_export.md', content)` - NO! Wrong name and wrong location
+3. `write_file('ai-agent-cli-claude-export.md', content)` - NO! Must be named exactly CLAUDE.md
+</BAD_FILENAME_EXAMPLES>
+
+Refer to GOOD_FILENAME_EXAMPLES for correct usage and avoid patterns shown in BAD_FILENAME_EXAMPLES.
+
+**REMEMBER**:
+- The filename must be EXACTLY "CLAUDE.md" or "Agents.md" - nothing else
+- NO timestamps, NO project names, NO descriptive suffixes
+- NO creative variations like "claude-export.md" or "agents-guide.md"
+- Just the exact filenames: CLAUDE.md or Agents.md
+
+For Agents.md/CLAUDE.md generation (PRIMARY TASK):
+
+<PROPER_WORKFLOW_EXAMPLE>
+# Example: User asks "Create a CLAUDE.md for this project"
+
+## Step 1: READ ALL FILES FIRST (MANDATORY)
+content_research = read_file('research.md')    # Read about codebase analysis
+content_spec = read_file('specification.md')   # Read project requirements
+content_plan = read_file('plan.md')           # Read development approach
+content_tasks = read_file('tasks.md')         # Read implementation details
+
+## Step 2: ANALYZE what you read
+- Project name: "Shotgun" (from specification.md)
+- Purpose: AI agent pipeline tool using Pydantic AI
+- Tech stack: Python, Pydantic AI, CLI/TUI interfaces
+- NOT about: Claude integration, API guides, or generic topics
+
+## Step 3: CREATE relevant content based on ACTUAL project
+# Create CLAUDE.md with sections about the REAL Shotgun project:
+- How to set up Shotgun development environment
+- Shotgun's code style and conventions
+- How to run Shotgun's tests
+- Shotgun's architecture and components
+- NOT generic Claude guides or integration docs
+</PROPER_WORKFLOW_EXAMPLE>
+
+1. **MANDATORY: Read ALL pipeline files** (SEE EXAMPLE ABOVE):
+   - `research.md` - Extract codebase understanding and architecture
+   - `specification.md` - Get project objectives and requirements
+   - `plan.md` - Extract development approach and stages
+   - `tasks.md` - Understand implementation tasks and structure
+2. **Map content to agents.md standard sections**:
+   - **Project Overview**: Brief description and key technologies from specification.md
+   - **Dev Environment Setup**: Installation, dependencies, dev server commands
+   - **Code Style Guidelines**: Coding conventions and patterns from research.md
+   - **Testing Instructions**: How to run tests, coverage expectations
+   - **Build and Deployment**: Build commands and deployment process
+   - **Additional Notes**: Key constraints, security considerations, unique requirements
+3. **Transform content**: Create clear, concise guidance following agents.md standard format
+4. **Create export file**:
+   - If user mentions "Claude Code": Use EXACTLY `write_file('CLAUDE.md', content)`
+   - For other AI agents: Use EXACTLY `write_file('Agents.md', content)`
+   - **CRITICAL**: These are the ONLY acceptable filenames - no variations!
+   - **CONTENT**: Must be project setup docs (like CORRECT_CONTENT_TEMPLATE), NOT prompt templates (like BAD_CONTENT_EXAMPLE)
+   - **DO NOT**: Add timestamps, project names, or save in exports/ folder
+   - **DO NOT**: Create guides about "how to use Claude" or prompt templates
+   - Follow examples in GOOD_FILENAME_EXAMPLES and GOOD_CONTENT_EXAMPLE
+5. **Validate**: Ensure content is about the ACTUAL PROJECT from the files you read
+
+For additional specialized exports (only if specifically requested):
+1. **These go in exports/ folder** - for things like detailed reports, combined documents, etc.
+2. **NOT for Agents.md/CLAUDE.md** - those always go at root
+3. Use exports/ folder ONLY when user asks for additional exports beyond the standard Agents.md/CLAUDE.md
 
 ## 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 - Primary Export Format for AI Agents
-
-**CRITICAL**: The AGENTS.md file is THE primary deliverable for AI coding agents. It MUST follow this exact template:
-
-```markdown
-# [Project Name] Implementation Guide for AI Agents
-
-## Primary Objective
-[1-2 sentences describing WHAT needs to be built, not HOW]
-
-## Tasks
-
-### Task 1: [Action-oriented title]
-**Input**: [What files/data this task needs]
-**Output**: [What files/code this task produces]
-**Constraints**: [Security, performance, or architectural requirements]
-
-### Task 2: [Next action]
-[Continue pattern...]
-
-## Research Needed
-- [ ] [Specific technical question to investigate]
-- [ ] [API endpoint to understand]
-- [ ] [Integration pattern to review]
-
-## Codebase Context
-- **Language**: [Primary language and version]
-- **Key Files**: [Critical files to read first]
-- **Patterns**: [Design patterns used in codebase]
-- **Dependencies**: [Important libraries/frameworks]
-
-## Success Criteria
-- [ ] [Measurable outcome 1]
-- [ ] [Measurable outcome 2]
-- [ ] [Tests pass / Coverage meets X%]
-
-## Important Notes
-- [Critical constraint or requirement]
-- [Security consideration]
-- [Performance requirement]
-
-## References
-- [Link to API documentation]
-- [Link to architecture diagrams]
-- [Link to test requirements]
+- **Agents.md**: Primary deliverable following https://agents.md/ standard
+- **CLAUDE.md**: Same format as Agents.md but specifically for Claude Code
+- **Markdown (.md)**: Additional formatted exports for specific purposes
+- **Multiple files**: Can create additional files (except protected files)
+
+### Agents.md/CLAUDE.md - Primary Export Format for AI Agents
+
+**CRITICAL**: Both Agents.md and CLAUDE.md files MUST follow the same standard format:
+
+**File Naming - MUST BE EXACT**:
+- Use EXACTLY `CLAUDE.md` when user mentions "Claude Code" or explicitly requests CLAUDE.md
+- Use EXACTLY `Agents.md` for all other AI agents (Cursor, Windsurf, etc.)
+- Content format is IDENTICAL - only the filename changes
+- DO NOT add timestamps, project names, or any variations to these filenames
+- WRONG: ai_agent_cli_claude_export.md, claude-guide.md, CLAUDE_2024.md
+- CORRECT: CLAUDE.md (nothing more, nothing less)
+
+**Template Format (agents.md standard)**:
+
+<CORRECT_CONTENT_TEMPLATE>
+# Agents.md - [Project Name]
+
+## Project Overview
+- Brief description of what the project does
+- Key technologies and frameworks used
+- Main objectives from specification.md
+
+## Dev Environment Setup
+- Prerequisites and system requirements
+- Installation commands (e.g., `npm install`, `pip install -r requirements.txt`)
+- Environment variables needed
+- How to start development server
+- Database setup if applicable
+
+## Code Style Guidelines
+- Language-specific conventions
+- Linting and formatting rules
+- File organization patterns
+- Naming conventions
+- Import/export patterns
+
+## Testing Instructions
+- How to run tests (e.g., `npm test`, `pytest`)
+- Test structure and organization
+- Coverage requirements (if any)
+- Testing frameworks used
+
+## Build and Deployment
+- Build commands
+- Deployment process
+- CI/CD pipeline details
+- Environment-specific configurations
+
+## Additional Notes
+- Security considerations
+- Performance guidelines
+- API documentation links
+- Architecture decisions
+- Known limitations or constraints
+</CORRECT_CONTENT_TEMPLATE>
+
+<BAD_CONTENT_EXAMPLE>
+# WRONG - DO NOT CREATE THIS TYPE OF CONTENT:
+## Claude AI Assistant Guide
+## Prompt Templates
+```prompt
+Help me with [task]
 ```
-
-**Export Requirements**:
-- Extract Primary Objective from specification.md
-- Map tasks from tasks.md into action-oriented Task sections
-- Pull research questions from research.md that are still relevant
-- Include codebase context from research findings
-- Convert plan stages into Success Criteria
-- Add implementation constraints from specifications
-- Format ALL content for immediate AI agent execution
-- NO educational content, NO "learn X" instructions
-- Every section must be actionable by Claude Code
-
-**Example of GOOD AGENTS.md Content**:
-```markdown
-# E-commerce API Implementation Guide for AI Agents
-
-## Primary Objective
-Build a REST API for product catalog management with authentication, supporting CRUD operations and search functionality.
-
-## Tasks
-
-### Task 1: Implement Database Models
-**Input**: requirements.md, existing database schema
-**Output**: models/product.py, models/user.py, migrations/
-**Constraints**: Use SQLAlchemy ORM, maintain backward compatibility
-
-### Task 2: Create Authentication Endpoints
-**Input**: models/user.py, auth requirements
-**Output**: api/auth.py, middleware/auth.py
-**Constraints**: JWT tokens, 15-minute expiry, refresh token support
-
-## Research Needed
-- [ ] Check if existing auth middleware supports JWT refresh tokens
-- [ ] Verify PostgreSQL full-text search capabilities for product search
-- [ ] Review rate limiting implementation in current middleware
-
-## Codebase Context
-- **Language**: Python 3.11
-- **Key Files**: src/api/__init__.py, src/models/base.py
-- **Patterns**: Repository pattern, dependency injection
-- **Dependencies**: FastAPI, SQLAlchemy, Pydantic
-
-## Success Criteria
-- [ ] All CRUD endpoints return correct status codes
-- [ ] Authentication enforced on protected routes
-- [ ] Test coverage exceeds 80%
-- [ ] API response times under 200ms
-
-## Important Notes
+## How to interact with Claude
+- Use these prompt templates...
+- Ask Claude to...
+
+# ALSO WRONG - GENERIC CONTENT NOT BASED ON ACTUAL PROJECT:
+## Claude Integration Guide for AI Agent CLI
+### Overview
+This document provides comprehensive guidance for integrating Anthropic's Claude models...
+[Generic integration guide that has nothing to do with the actual project]
+
+# WRONG - DIDN'T READ THE FILES:
+## Project Setup
+This project is about [making assumptions without reading files]...
+</BAD_CONTENT_EXAMPLE>
+
+**IMPORTANT**: Create content like CORRECT_CONTENT_TEMPLATE, NOT like BAD_CONTENT_EXAMPLE. The file should contain PROJECT SETUP information, not Claude interaction guides.
+
+**Agents.md/CLAUDE.md Requirements**:
+- Follow the https://agents.md/ standard format for BOTH files
+- Extract brief project overview from specification.md (1-2 paragraphs max)
+- Focus on practical setup: installation, dependencies, dev server
+- Define code style based on actual patterns found in the codebase
+- Provide concrete testing commands and coverage requirements
+- Include build and deployment instructions
+- Keep each section concise and actionable
+- This is NOT a task list or comprehensive implementation guide
+- DO NOT combine all pipeline files into one document
+- DO NOT create "how to use Claude" guides or prompt templates
+- DO NOT include ```prompt blocks or interaction instructions
+- CLAUDE.md is FOR Claude Code to read, not ABOUT how to use Claude
+- Save as `CLAUDE.md` for Claude Code, `Agents.md` for others
+
+**Example of GOOD Agents.md/CLAUDE.md Content**:
+
+<GOOD_CONTENT_EXAMPLE>
+# Agents.md - E-commerce API Project
+
+## Project Overview
+- REST API for product catalog management with authentication
+- Built with Python/FastAPI for high performance async operations
+- Supports CRUD operations and advanced search functionality
+
+## Dev Environment Setup
+- Install Python 3.11+
+- Clone repository: `git clone [repo-url]`
+- Install dependencies: `pip install -r requirements.txt`
+- Set environment variables: Copy `.env.example` to `.env`
+- Initialize database: `python scripts/init_db.py`
+- Start dev server: `uvicorn main:app --reload`
+
+## Code Style Guidelines
+- Follow PEP 8 for Python code
+- Use type hints for all function parameters and returns
+- Format with Black: `black .`
+- Lint with Ruff: `ruff check .`
+- Use repository pattern for database operations
+- Keep business logic separate from API endpoints
+
+## Testing Instructions
+- Run all tests: `pytest`
+- Run with coverage: `pytest --cov=src`
+- Test specific module: `pytest tests/test_auth.py`
+- Integration tests require test database (auto-created)
+- Minimum coverage requirement: 80%
+
+## Build and Deployment
+- Build Docker image: `docker build -t api:latest .`
+- Run migrations: `alembic upgrade head`
+- Deploy to staging: `./scripts/deploy.sh staging`
+- Production deployment via GitHub Actions on main branch
+
+## Additional Notes
+- All endpoints require JWT authentication except /health and /docs
 - Database migrations must be reversible
-- All endpoints require input validation
-- Search must support pagination
+- API documentation available at /docs when running
+- Rate limiting: 100 requests per minute per IP
+- See docs/architecture.md for system design details
+</GOOD_CONTENT_EXAMPLE>
 
-## References
-- FastAPI docs: https://fastapi.tiangolo.com
-- Project API spec: docs/openapi.yaml
-```
+**NOTE**: Use content structure from GOOD_CONTENT_EXAMPLE, which shows proper project setup documentation.
 
 
 ## EXPORT PRINCIPLES
@@ -174,7 +309,8 @@ Build a REST API for product catalog management with authentication, supporting
 - 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
+- Save CLAUDE.md or Agents.md at ROOT level (NOT in exports/ folder)
+- Only use exports/ folder for additional specialized exports if specifically requested
 
 {% if interactive_mode %}
 USER INTERACTION - CLARIFY EXPORT REQUIREMENTS:
@@ -185,7 +321,7 @@ USER INTERACTION - CLARIFY EXPORT REQUIREMENTS:
   - Intended use case and audience for the export
   - Specific content sections to include/exclude from files
   - Output structure and organization preferences
-  - Destination filename(s) in the exports/ folder
+  - Whether they want just Agents.md/CLAUDE.md or additional exports
 - 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
@@ -205,7 +341,7 @@ IMPORTANT RULES:
 - 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)
+- Save CLAUDE.md or Agents.md at ROOT level - just the filename, no folder path
 {% if interactive_mode %}
 - When export requirements are ambiguous, ASK before proceeding
 {% else %}

shotgun/prompts/agents/state/system_state.j2

@@ -5,8 +5,8 @@
 ## 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.
+The following files already exist.
+Before doing a web search check the information in these files before continuing.
 Your working files are:
 {% for file in existing_files %}
 - `{{ file }}`
@@ -23,9 +23,7 @@ No files currently exist in your allowed directories. You can create:
 {% if markdown_toc %}
 ## Document Table of Contents - READ THE ENTIRE FILE TO UNDERSTAND MORE
 
-```
 {{ markdown_toc }}
-```
 
 **IMPORTANT**: The above shows ONLY the Table of Contents from prior stages in the pipeline. Review this context before asking questions or creating new content.
 {% else %}

{shotgun_sh-0.1.0.dev26.dist-info → shotgun_sh-0.1.0.dev27.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgun-sh
-Version: 0.1.0.dev26
+Version: 0.1.0.dev27
 Summary: AI-powered research, planning, and task management CLI tool
 Project-URL: Homepage, https://shotgun.sh/
 Project-URL: Repository, https://github.com/shotgun-sh/shotgun

{shotgun_sh-0.1.0.dev26.dist-info → shotgun_sh-0.1.0.dev27.dist-info}/RECORD

@@ -7,11 +7,12 @@ shotgun/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 shotgun/sentry_telemetry.py,sha256=3r9on0GQposn9aX6Dkb9mrfaVQl_dIZzhu9BjE838AU,2854
 shotgun/telemetry.py,sha256=aBwCRFU97oiIK5K13OhT7yYCQUAVQyrvnoG-aX3k2ZE,3109
 shotgun/agents/__init__.py,sha256=8Jzv1YsDuLyNPFJyckSr_qI4ehTVeDyIMDW4omsfPGc,25
-shotgun/agents/agent_manager.py,sha256=mIRGf5xaIvMuvUQRzPa3IqP-VlGCwVoxS1ftNgbeFPU,20943
-shotgun/agents/common.py,sha256=C5-hpIgyeQ5n22fIiSouJkdzbiLXAtvVxo176FIyeYM,19034
+shotgun/agents/agent_manager.py,sha256=Tz20_cmCQhuUOIyr3rGrtvN_XBAYBZNuzhXBo-BFngQ,22349
+shotgun/agents/common.py,sha256=vt7ECq1rT6GR5Rt63t0whH0R0cydrk7Mty2KyPL8mEg,19045
 shotgun/agents/conversation_history.py,sha256=5J8_1yxdZiiWTq22aDio88DkBDZ4_Lh_p5Iy5_ENszc,3898
 shotgun/agents/conversation_manager.py,sha256=fxAvXbEl3Cl2ugJ4N9aWXaqZtkrnfj3QzwjWC4LFXwI,3514
 shotgun/agents/export.py,sha256=Zke952DbJ_lOBUmN-TPHw7qmjbfqsFu1uycBRQI_pkg,2969
+shotgun/agents/messages.py,sha256=wNn0qC5AqASM8LMaSGFOerZEJPn5FsIOmaJs1bdosuU,1036
 shotgun/agents/models.py,sha256=fljmjHoCzNXPWOHSA-1KmQk1epk8ovowqDM7j5zZKB8,7853
 shotgun/agents/plan.py,sha256=s-WfILBOW4l8kY59RUOVtX5MJSuSzFm1nGp6b17If78,3030
 shotgun/agents/research.py,sha256=lYG7Rytcitop8mXs3isMI3XvYzzI3JH9u0VZz6K9zfo,3274
@@ -27,12 +28,12 @@ shotgun/agents/history/compaction.py,sha256=KY_ZvRvvlrB6eLPGqtlC6H8h4HPPOtuPcUkg
 shotgun/agents/history/constants.py,sha256=yWY8rrTZarLA3flCCMB_hS2NMvUDRDTwP4D4j7MIh1w,446
 shotgun/agents/history/context_extraction.py,sha256=yVka1U6TqNVsORR4JlxpWi9yBt3Quip8g_u3x2Vi9Gs,3564
 shotgun/agents/history/history_building.py,sha256=6LFDZ60MTPDoGAcmu_mjlnjVYu8YYWdIi-cGbF3jm7A,3532
-shotgun/agents/history/history_processors.py,sha256=beipmLkHxhQDxrtoCGGK86arOIzcu8aa1fFCvxa5v2o,15097
-shotgun/agents/history/message_utils.py,sha256=S7wqix4W3uvC8rChs6TMxp7yjnjr8a2AqPxLIKnDyjI,1526
+shotgun/agents/history/history_processors.py,sha256=PMfgiqQXsILzLeShfGnvTx6XxHxH96a57PT2vZTYlFA,15880
+shotgun/agents/history/message_utils.py,sha256=aPusAl2RYKbjc7lBxPaNprRHmZEG6fe97q7DQUlhlzU,2918
 shotgun/agents/history/token_counting.py,sha256=RasWy84eNjbmqyQDTGAzj1Q1I9ml_G_9R-maWN7gr8s,13839
 shotgun/agents/history/token_estimation.py,sha256=iNqhDSqFzG0YYxGijMRzj54GALFglOp0qVMB6G59RhU,4690
 shotgun/agents/tools/__init__.py,sha256=QaN80IqWvB5qEcjHqri1-PYvYlO74vdhcwLugoEdblo,772
-shotgun/agents/tools/file_management.py,sha256=XvRBwz7KmlwqQlAbYraDCo9murk5oko1zLo2g2fGeOA,7100
+shotgun/agents/tools/file_management.py,sha256=HYNe_QA4T3_bPzSWBYcFZcnWdj8eb4aQ3GB735-G8Nw,7138
 shotgun/agents/tools/user_interaction.py,sha256=b3ncEpvoD06Cz4hwsS-ppVbQajQj640iWnVfA5WBjAA,1236
 shotgun/agents/tools/codebase/__init__.py,sha256=ceAGkK006NeOYaIJBLQsw7Q46sAyCRK9PYDs8feMQVw,661
 shotgun/agents/tools/codebase/codebase_shell.py,sha256=9b7ZStAVFprdGqp1O23ZgwkToMytlUdp_R4MhvmENhc,8584
@@ -73,7 +74,7 @@ shotgun/codebase/core/parser_loader.py,sha256=LZRrDS8Sp518jIu3tQW-BxdwJ86lnsTteI
 shotgun/prompts/__init__.py,sha256=RswUm0HMdfm2m2YKUwUsEdRIwoczdbI7zlucoEvHYRo,132
 shotgun/prompts/loader.py,sha256=jy24-E02pCSmz2651aCT2NgHfRrHAGMYvKrD6gs0Er8,4424
 shotgun/prompts/agents/__init__.py,sha256=YRIJMbzpArojNX1BP5gfxxois334z_GQga8T-xyWMbY,39
-shotgun/prompts/agents/export.j2,sha256=-6lpRmIkSiDqm1G0Va_cf0JG3sJ14cQKQ8beQ0pBh94,8422
+shotgun/prompts/agents/export.j2,sha256=GKpOfGbZA9PVa4TNtMORUYiBIAcN6JCo8URmTCWKlWw,15936
 shotgun/prompts/agents/plan.j2,sha256=MyZDyOS21V-zrHNzbIhIdzcESGh_3KVbA4qh9rZR2_E,6086
 shotgun/prompts/agents/research.j2,sha256=JBtjXaMVDRuNTt7-Ai8gUb2InfolfqCkQoEkn9PsQZk,3929
 shotgun/prompts/agents/specify.j2,sha256=AP7XrA3KE7GZsCvW4guASxZHBM2mnrMw3irdZ3RUOBs,2808
@@ -82,7 +83,7 @@ shotgun/prompts/agents/partials/codebase_understanding.j2,sha256=7WH-PVd-TRBFQUd
 shotgun/prompts/agents/partials/common_agent_system_prompt.j2,sha256=eFuc3z1pSJzQtPJfjMIDNHv5XX9lP6YVrmKcbbskJj8,1877
 shotgun/prompts/agents/partials/content_formatting.j2,sha256=MG0JB7SSp8YV5akDWpbs2f9DcdREIYqLp38NnoWLeQ0,1854
 shotgun/prompts/agents/partials/interactive_mode.j2,sha256=9sYPbyc46HXg3k1FT_LugIQvOyNDnMQwsMIgOgN-_aY,1100
-shotgun/prompts/agents/state/system_state.j2,sha256=XYAlf2_5PiIcJqdu-dBG4zyQBfD5h4rmjpI1fEIUW8c,1080
+shotgun/prompts/agents/state/system_state.j2,sha256=TQPnCLtmiNwQCbMxnCE7nLhXMJpKlBCnlNBKt7FTjuo,1033
 shotgun/prompts/agents/state/codebase/codebase_graphs_available.j2,sha256=U-hy-H9bPwV0sYIHTZ5TESxc5EOCtntI8GUZOmJipJw,601
 shotgun/prompts/codebase/__init__.py,sha256=NYuPMtmYM2ptuwf3YxVuotNlJOUq0hnjmwlzKcJkGK4,42
 shotgun/prompts/codebase/cypher_query_patterns.j2,sha256=ufTx_xT3VoS76KcVUbIgGQx-bJoJHx3bBE3dagAXv18,8913
@@ -122,8 +123,8 @@ shotgun/utils/__init__.py,sha256=WinIEp9oL2iMrWaDkXz2QX4nYVPAm8C9aBSKTeEwLtE,198
 shotgun/utils/env_utils.py,sha256=8QK5aw_f_V2AVTleQQlcL0RnD4sPJWXlDG46fsHu0d8,1057
 shotgun/utils/file_system_utils.py,sha256=l-0p1bEHF34OU19MahnRFdClHufThfGAjQ431teAIp0,1004
 shotgun/utils/update_checker.py,sha256=Xf-7w3Pos3etzCoT771gJe2HLkA8_V2GrqWy7ni9UqA,11373
-shotgun_sh-0.1.0.dev26.dist-info/METADATA,sha256=YyEZvsV43Hgvv34CVTQU9i_CRlt9DagOoz3oy3c1WXY,11197
-shotgun_sh-0.1.0.dev26.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-shotgun_sh-0.1.0.dev26.dist-info/entry_points.txt,sha256=asZxLU4QILneq0MWW10saVCZc4VWhZfb0wFZvERnzfA,45
-shotgun_sh-0.1.0.dev26.dist-info/licenses/LICENSE,sha256=YebsZl590zCHrF_acCU5pmNt0pnAfD2DmAnevJPB1tY,1065
-shotgun_sh-0.1.0.dev26.dist-info/RECORD,,
+shotgun_sh-0.1.0.dev27.dist-info/METADATA,sha256=yE6vp8p3JZUIQeu8t1RWTU086EaiZ8wQO7CzCX2HxXU,11197
+shotgun_sh-0.1.0.dev27.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+shotgun_sh-0.1.0.dev27.dist-info/entry_points.txt,sha256=asZxLU4QILneq0MWW10saVCZc4VWhZfb0wFZvERnzfA,45
+shotgun_sh-0.1.0.dev27.dist-info/licenses/LICENSE,sha256=YebsZl590zCHrF_acCU5pmNt0pnAfD2DmAnevJPB1tY,1065
+shotgun_sh-0.1.0.dev27.dist-info/RECORD,,