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

shotgun/agents/agent_manager.py

@@ -37,6 +37,7 @@ from textual.widget import Widget
 
 from shotgun.agents.common import add_system_prompt_message, add_system_status_message
 from shotgun.agents.models import AgentType, FileOperation
+from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 
 from .export import create_export_agent
 from .history.compaction import apply_persistent_compaction
@@ -54,7 +55,7 @@ class MessageHistoryUpdated(Message):
 
     def __init__(
         self,
-        messages: list[ModelMessage],
+        messages: list[ModelMessage | HintMessage],
         agent_type: AgentType,
         file_operations: list[FileOperation] | None = None,
     ) -> None:
@@ -143,7 +144,7 @@ class AgentManager(Widget):
         self._current_agent_type: AgentType = initial_type
 
         # Maintain shared message history
-        self.ui_message_history: list[ModelMessage] = []
+        self.ui_message_history: list[ModelMessage | HintMessage] = []
         self.message_history: list[ModelMessage] = []
         self.recently_change_files: list[FileOperation] = []
         self._stream_state: _PartialStreamState | None = None
@@ -461,8 +462,8 @@ class AgentManager(Widget):
         )
 
     def _filter_system_prompts(
-        self, messages: list[ModelMessage]
-    ) -> list[ModelMessage]:
+        self, messages: list[ModelMessage | HintMessage]
+    ) -> list[ModelMessage | HintMessage]:
         """Filter out system prompts from messages for UI display.
 
         Args:
@@ -473,8 +474,12 @@ class AgentManager(Widget):
         """
         from pydantic_ai.messages import SystemPromptPart
 
-        filtered_messages: list[ModelMessage] = []
+        filtered_messages: list[ModelMessage | HintMessage] = []
         for msg in messages:
+            if isinstance(msg, HintMessage):
+                filtered_messages.append(msg)
+                continue
+
             parts: Sequence[ModelRequestPart] | Sequence[ModelResponsePart] | None = (
                 msg.parts if hasattr(msg, "parts") else None
             )
@@ -514,6 +519,7 @@ class AgentManager(Widget):
 
         return ConversationState(
             agent_messages=self.message_history.copy(),
+            ui_messages=self.ui_message_history.copy(),
             agent_type=self._current_agent_type.value,
         )
 
@@ -524,10 +530,16 @@ class AgentManager(Widget):
             state: ConversationState object to restore
         """
         # Restore message history for agents (includes system prompts)
-        self.message_history = state.agent_messages.copy()
+        non_hint_messages = [
+            msg for msg in state.agent_messages if not isinstance(msg, HintMessage)
+        ]
+        self.message_history = non_hint_messages
 
-        # Filter out system prompts for UI display
-        self.ui_message_history = self._filter_system_prompts(state.agent_messages)
+        # Filter out system prompts for UI display while keeping hints
+        ui_source = state.ui_messages or cast(
+            list[ModelMessage | HintMessage], state.agent_messages
+        )
+        self.ui_message_history = self._filter_system_prompts(ui_source)
 
         # Restore agent type
         self._current_agent_type = AgentType(state.agent_type)
@@ -535,6 +547,10 @@ class AgentManager(Widget):
         # Notify listeners about the restored messages
         self._post_messages_updated()
 
+    def add_hint_message(self, message: HintMessage) -> None:
+        self.ui_message_history.append(message)
+        self._post_messages_updated()
+
 
 # Re-export AgentType for backward compatibility
 __all__ = [

shotgun/agents/common.py

@@ -2,6 +2,7 @@
 
 import asyncio
 from collections.abc import Callable
+from pathlib import Path
 from typing import Any
 
 from pydantic_ai import (
@@ -28,7 +29,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 .models import AgentDeps, AgentRuntimeOptions
+from .models import AgentDeps, AgentRuntimeOptions, PipelineConfigEntry
 from .tools import (
     append_file,
     ask_user,
@@ -197,33 +198,24 @@ def create_base_agent(
     return agent, deps
 
 
-def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
-    """Extract table of contents from agent's markdown file.
+def _extract_file_toc_content(
+    file_path: Path, max_depth: int | None = None, max_chars: int = 500
+) -> str | None:
+    """Extract TOC from a single file with depth and character limits.
 
     Args:
-        agent_mode: The agent mode to extract TOC for
+        file_path: Path to the markdown file
+        max_depth: Maximum heading depth (1=#, 2=##, None=all)
+        max_chars: Maximum characters for the TOC
 
     Returns:
-        Formatted TOC string (up to 2000 chars) or None if not applicable
+        Formatted TOC string or None if file doesn't exist
     """
-    # Skip for EXPORT mode or no mode
-    if (
-        not agent_mode
-        or agent_mode == AgentType.EXPORT
-        or agent_mode not in AGENT_DIRECTORIES
-    ):
-        return None
-
-    base_path = get_shotgun_base_path()
-    md_file = AGENT_DIRECTORIES[agent_mode]
-    md_path = base_path / md_file
-
-    # Check if the markdown file exists
-    if not md_path.exists():
+    if not file_path.exists():
         return None
 
     try:
-        content = md_path.read_text(encoding="utf-8")
+        content = file_path.read_text(encoding="utf-8")
         lines = content.split("\n")
 
         # Extract headings
@@ -239,6 +231,10 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
                     else:
                         break
 
+                # Skip if exceeds max_depth
+                if max_depth and level > max_depth:
+                    continue
+
                 # Get the heading text (remove the # symbols and clean up)
                 heading_text = stripped[level:].strip()
                 if heading_text:
@@ -246,21 +242,110 @@ def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
                     indent = "  " * (level - 1)
                     toc_lines.append(f"{indent}{'#' * level} {heading_text}")
 
+                    # Check if we're approaching the character limit
+                    current_length = sum(len(line) + 1 for line in toc_lines)
+                    if current_length > max_chars:
+                        # Remove the last line and add ellipsis
+                        toc_lines.pop()
+                        if toc_lines:
+                            toc_lines.append("  ...")
+                        break
+
         if not toc_lines:
             return None
 
-        # Join and truncate to 2000 characters
-        toc = "\n".join(toc_lines)
-        if len(toc) > 2000:
-            toc = toc[:1997] + "..."
-
-        return toc
+        return "\n".join(toc_lines)
 
     except Exception as e:
-        logger.debug(f"Failed to extract TOC from {md_file}: {e}")
+        logger.debug(f"Failed to extract TOC from {file_path}: {e}")
         return None
 
 
+def extract_markdown_toc(agent_mode: AgentType | None) -> str | None:
+    """Extract TOCs from current and prior agents' files in the pipeline.
+
+    Shows full TOC of agent's own file and high-level summaries of prior agents'
+    files to maintain context awareness while keeping context window tight.
+
+    Args:
+        agent_mode: The agent mode to extract TOC for
+
+    Returns:
+        Formatted multi-file TOC string or None if not applicable
+    """
+    # Skip if no mode
+    if not agent_mode:
+        return None
+
+    # Define pipeline order and dependencies
+    pipeline_config: dict[AgentType, PipelineConfigEntry] = {
+        AgentType.RESEARCH: PipelineConfigEntry(
+            own_file="research.md",
+            prior_files=[],  # First in pipeline
+        ),
+        AgentType.SPECIFY: PipelineConfigEntry(
+            own_file="specification.md",
+            prior_files=["research.md"],
+        ),
+        AgentType.PLAN: PipelineConfigEntry(
+            own_file="plan.md",
+            prior_files=["research.md", "specification.md"],
+        ),
+        AgentType.TASKS: PipelineConfigEntry(
+            own_file="tasks.md",
+            prior_files=["research.md", "specification.md", "plan.md"],
+        ),
+        AgentType.EXPORT: PipelineConfigEntry(
+            own_file=None,  # Export uses directory
+            prior_files=["research.md", "specification.md", "plan.md", "tasks.md"],
+        ),
+    }
+
+    # Get configuration for current agent
+    if agent_mode not in pipeline_config:
+        return None
+
+    config = pipeline_config[agent_mode]
+    base_path = get_shotgun_base_path()
+    toc_sections: list[str] = []
+
+    # Extract TOCs from prior files (high-level only)
+    for prior_file in config.prior_files:
+        file_path = base_path / prior_file
+        # 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()
+            toc_sections.append(
+                f"=== Prior Context: {file_label} (summary) ===\n{prior_toc}"
+            )
+
+    # Extract TOC from own file (full detail)
+    if config.own_file:
+        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
+            toc_sections.insert(
+                0, f"=== Your Current Document: {file_label} ===\n{own_toc}"
+            )
+
+    # Combine all sections
+    if not toc_sections:
+        return None
+
+    combined_toc = "\n\n".join(toc_sections)
+
+    # Final truncation if needed (should rarely happen with our limits)
+    max_total = 3500  # Conservative total limit
+    if len(combined_toc) > max_total:
+        combined_toc = combined_toc[: max_total - 3] + "..."
+
+    return combined_toc
+
+
 def get_agent_existing_files(agent_mode: AgentType | None = None) -> list[str]:
     """Get list of existing files for the given agent mode.
 

shotgun/agents/conversation_history.py

@@ -1,7 +1,7 @@
 """Models and utilities for persisting TUI conversation history."""
 
 from datetime import datetime
-from typing import Any
+from typing import Any, cast
 
 from pydantic import BaseModel, ConfigDict, Field
 from pydantic_ai.messages import (
@@ -10,11 +10,16 @@ from pydantic_ai.messages import (
 )
 from pydantic_core import to_jsonable_python
 
+from shotgun.tui.screens.chat_screen.hint_message import HintMessage
+
+SerializedMessage = dict[str, Any]
+
 
 class ConversationState(BaseModel):
     """Represents the complete state of a conversation in memory."""
 
     agent_messages: list[ModelMessage]
+    ui_messages: list[ModelMessage | HintMessage] = Field(default_factory=list)
     agent_type: str  # Will store AgentType.value
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
@@ -24,9 +29,12 @@ class ConversationHistory(BaseModel):
     """Persistent conversation history for TUI sessions."""
 
     version: int = 1
-    agent_history: list[dict[str, Any]] = Field(
+    agent_history: list[SerializedMessage] = Field(
+        default_factory=list
+    )  # Stores serialized ModelMessage objects
+    ui_history: list[SerializedMessage] = Field(
         default_factory=list
-    )  # Will store serialized ModelMessage objects
+    )  # Stores serialized ModelMessage and HintMessage objects
     last_agent_model: str = "research"
     updated_at: datetime = Field(default_factory=datetime.now)
 
@@ -43,6 +51,25 @@ class ConversationHistory(BaseModel):
             messages, fallback=lambda x: str(x), exclude_none=True
         )
 
+    def set_ui_messages(self, messages: list[ModelMessage | HintMessage]) -> None:
+        """Set ui_history from a list of UI messages."""
+
+        def _serialize_message(
+            message: ModelMessage | HintMessage,
+        ) -> Any:
+            if isinstance(message, HintMessage):
+                data = message.model_dump()
+                data["message_type"] = "hint"
+                return data
+            payload = to_jsonable_python(
+                message, fallback=lambda x: str(x), exclude_none=True
+            )
+            if isinstance(payload, dict):
+                payload.setdefault("message_type", "model")
+            return payload
+
+        self.ui_history = [_serialize_message(msg) for msg in messages]
+
     def get_agent_messages(self) -> list[ModelMessage]:
         """Get agent_history as a list of ModelMessage objects.
 
@@ -54,3 +81,26 @@ class ConversationHistory(BaseModel):
 
         # Deserialize from JSON format back to ModelMessage objects
         return ModelMessagesTypeAdapter.validate_python(self.agent_history)
+
+    def get_ui_messages(self) -> list[ModelMessage | HintMessage]:
+        """Get ui_history as a list of Model or hint messages."""
+
+        if not self.ui_history:
+            # Fallback for older conversation files without UI history
+            return cast(list[ModelMessage | HintMessage], self.get_agent_messages())
+
+        messages: list[ModelMessage | HintMessage] = []
+        for item in self.ui_history:
+            message_type = item.get("message_type") if isinstance(item, dict) else None
+            if message_type == "hint":
+                messages.append(HintMessage.model_validate(item))
+                continue
+
+            # Backwards compatibility: data may not include the type marker
+            payload = item
+            if isinstance(payload, dict):
+                payload = {k: v for k, v in payload.items() if k != "message_type"}
+            deserialized = ModelMessagesTypeAdapter.validate_python([payload])
+            messages.append(deserialized[0])
+
+        return messages

shotgun/agents/models.py

@@ -27,6 +27,23 @@ class AgentType(StrEnum):
     EXPORT = "export"
 
 
+class PipelineConfigEntry(BaseModel):
+    """Configuration for each agent in the pipeline.
+
+    This model defines what files an agent can write to and what
+    files from prior agents it should read for context.
+    """
+
+    own_file: str | None = Field(
+        default=None,
+        description="The file this agent writes to (None for export agent)",
+    )
+    prior_files: list[str] = Field(
+        default_factory=list,
+        description="Files from prior agents in pipeline to read for context",
+    )
+
+
 class UserAnswer(BaseModel):
     """A answer from the user."""
 

shotgun/prompts/agents/export.j2

@@ -26,14 +26,31 @@ Your job is to help export project documentation and findings to various formats
 
 ## EXPORT WORKFLOW
 
-For export tasks:
-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 files
-5. **Transform and format**: Convert content to the requested format
-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()
+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
 
 ## SUPPORTED EXPORT FORMATS
 
@@ -41,18 +58,109 @@ For export tasks:
 - **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.).
-- 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.
-- If the project is a monorepo or modular, mention whether nested AGENTS.md may override parts.
-- Do **not** include large prose — focus on actionable instructions and bullet lists.
-- Assume the agent must obey programmatic checks listed in the file after generating code.
+### 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]
+```
+
+**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
+- Database migrations must be reversible
+- All endpoints require input validation
+- Search must support pagination
+
+## References
+- FastAPI docs: https://fastapi.tiangolo.com
+- Project API spec: docs/openapi.yaml
+```
 
 
 ## EXPORT PRINCIPLES

shotgun/prompts/agents/partials/common_agent_system_prompt.j2

@@ -7,7 +7,7 @@ Your extensive expertise spans, among other things:
 ## KEY RULES
 
 {% if interactive_mode %}
-0. Always ask for review and go ahead to move forward after writing files.
+0. Always ask CLARIFYING QUESTIONS if the user's request is ambiguous or lacks sufficient detail. Do not make assumptions about what the user wants.
 {% endif %}
 1. Above all, prefer using tools to do the work and NEVER respond with text.
 2. IMPORTANT: Always ask for review and go ahead to move forward after using write_file().

shotgun/prompts/agents/plan.j2

@@ -2,72 +2,143 @@ You are an experienced Project Manager and Strategic Planner.
 
 Your job is to help create comprehensive, actionable plans for software projects and maintain the plan.md file.
 
+⚠️ **CRITICAL RULE**: If you use ANY time references (Week, Day, Month, Hour, Quarter, Year), your plan is INVALID and will be rejected. Use ONLY Stage/Step numbering based on technical dependencies.
+
 {% include 'agents/partials/common_agent_system_prompt.j2' %}
 
 ## MEMORY MANAGEMENT PROTOCOL
 
 - You have exclusive write access to: `plan.md`
-- SHOULD READ `research.md` and `specification.md` for context but CANNOT write to them
+- MUST READ `research.md` and `specification.md` BEFORE asking questions or creating plans
+- Cannot write to research.md or specification.md - they are read-only context
 - This is your persistent memory store - ALWAYS load it first
 - Compress content regularly to stay within context limits
 - Keep your file updated as you work - it's your memory across sessions
-- When adding new plans, archive completed phases and compress old plans
+- When adding new plans, archive completed stages and compress old plans
 - Keep active plan at top, archived/completed plans compressed at bottom
 
 ## AI AGENT PIPELINE AWARENESS
 
 **CRITICAL**: Your output will be consumed by AI coding agents (Claude Code, Cursor, Windsurf, etc.)
-- These agents already know how to code - don't teach programming concepts
-- Create implementation roadmaps, not learning paths
-- Each step must reference specific files and functions to create/modify
-- Replace "learn X" with "implement Y in file Z"
-- Include concrete validation checkpoints (run tests, check endpoints)
-- Break down into atomic, executable steps
-- Reference specific code patterns from the research
-- Every plan step should be a direct instruction an AI agent can execute
+
+**NEVER INCLUDE:**
+- Weeks, days, hours, months, quarters, or ANY time measurements
+- Timeline overviews, Gantt charts, or project schedules
+- "Phase 1 (Week 1-2)" or "Day 1-2" style headers
+- Calendar-based planning or duration estimates
+- "8-10 weeks to complete" or similar time predictions
+
+**ALWAYS USE:**
+- "Stage 1", "Stage 2" or "Step 1", "Step 2" (NO time references)
+- Prerequisites and technical dependencies
+- High-level components and architecture
+- Success criteria without implementation details
+- Purpose-driven descriptions (WHY each stage exists)
+
+**REMEMBER:**
+- Plans should be HIGH-LEVEL architecture and approach
+- Leave specific file paths and function names to the task agent
+- Focus on WHAT to build, not HOW to code it
+- AI agents execute immediately based on dependencies, not schedules
 
 ## PLANNING WORKFLOW
 
 For PLANNING tasks:
 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
+2. **MANDATORY: Load context files**: You MUST read `specification.md` and `research.md` (if they exist) BEFORE doing anything else, including asking questions
+3. **Analyze requirements**: Understand project goals and constraints from the loaded documentation
+4. **Define specifications**: Create detailed technical and functional plans based on the context
+5. **REQUIRED: Write the plan**: You MUST use `write_file("plan.md", content)` to save the plan. NOT writing the plan means FAILURE.
+
+**CRITICAL RULES**:
+- You CANNOT ask questions until you have first attempted to read both `research.md` and `specification.md`
+- You MUST write your plan to `plan.md` - not writing the file means you have failed your task
+- ANY time reference (week, day, month) makes the plan INVALID
+
+## PLAN FORMAT EXAMPLE
+
+**CORRECT high-level plan format:**
+
+```markdown
+# API Implementation Plan
+
+## Stage 1: Database Layer
+### Purpose: Establish data persistence
+### Prerequisites: None
+### Key Components:
+- User and session models
+- Database schema and migrations
+### Success Criteria:
+- Data models support all required operations
+- Database can be reliably initialized
+
+## Stage 2: Business Logic
+### Purpose: Implement core functionality
+### Prerequisites: Database layer complete
+### Key Components:
+- Authentication service
+- Validation rules
+- Business logic layer
+### Success Criteria:
+- All business rules enforced
+- Services handle edge cases properly
+```
+
+**NEVER write plans like this:**
+- "Week 1-2: Setup database"
+- "Phase 1 (5 days): Foundation"
+- "Timeline: 8-10 weeks"
+- "Day 1: Initialize project"
 
 ## PLANNING PRINCIPLES
 
 - Build on existing research and previous plans
-- Create SMART goals (Specific, Measurable, Achievable, Relevant, Time-bound)
-- Break down complex objectives into manageable phases
-- Consider dependencies between tasks and potential risks
-- Include resource requirements and success criteria
-- Focus on actionable, specific steps rather than vague suggestions
-- Consider feasibility and prioritize high-impact actions
+- Create clear goals that are Specific, Measurable, Achievable, and Relevant
+- Break down complex objectives into sequential implementation stages
+- Consider dependencies between components and potential risks
+- Include technical requirements and success criteria
+- Focus on high-level architecture rather than implementation details
+- Consider feasibility and prioritize high-impact components
 - Keep plan.md as the single source of truth
-- Organize plans by phases, milestones, or components
+- Organize plans by implementation order, dependencies, or components
 
 IMPORTANT RULES:
 - Make at most 1 plan file write per request
 - Always base plans on available specifications and research when relevant
-- Create actionable, specific steps rather than vague suggestions
-- Consider feasibility and prioritize high-impact actions
+- **ABSOLUTELY NO TIME REFERENCES** (weeks, days, months, hours, quarters, years)
+- If you write "Week", "Day", "Month" or any time unit, the plan is INVALID
+- Structure ONLY by Stages/Steps with technical dependencies
+- Focus on high-level architecture, not specific file implementations
+- Leave detailed tasks for the task agent to create
 - Be concise but comprehensive
 
 {% if interactive_mode %}
 USER INTERACTION - REDUCE UNCERTAINTY:
 
-- ALWAYS ask clarifying questions when the goal is vague or ambiguous
-- Use ask_user tool frequently to gather specific details about:
-  - Budget considerations
-  - Risk tolerance and priorities
-- Ask follow-up questions to drill down into specifics
+- FIRST read `research.md` and `specification.md` before asking ANY questions
+- ONLY ask clarifying questions AFTER reading the context files
+- Questions should be about gaps not covered in research/specification
+- Use ask_user tool to gather specific details about:
+  - Information not found in the context files
+  - Clarifications on ambiguous specifications
+  - Priorities when multiple options exist
 - Better to ask 2-3 targeted questions than create a generic plan
 - Confirm major changes to existing plans before proceeding
 {% else %}
 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 %}
+- Include logical implementation steps and considerations
+- Structure by dependencies and execution order, not calendar time
+{% endif %}
+
+## FINAL VALIDATION BEFORE WRITING
+
+Before writing to plan.md, verify:
+✅ NO time references (week, day, month, hour, year, quarter)
+✅ Uses Stage/Step numbering only
+✅ Based on technical dependencies, not schedules
+✅ High-level architecture focus (details for task agent)
+✅ Follows the example format shown above
+
+If your plan contains ANY time reference, DELETE IT and rewrite using Stages.

shotgun/prompts/agents/state/system_state.j2

@@ -21,11 +21,13 @@ No files currently exist in your allowed directories. You can create:
 {% endif %}
 
 {% if markdown_toc %}
-## Document Structure
+## Document Table of Contents - READ THE ENTIRE FILE TO UNDERSTAND MORE
 
-The current document contains the following sections:
 ```
 {{ markdown_toc }}
 ```
-Review these existing sections before adding new content to avoid duplication.
+
+**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 %}
+Review the existing documents above before adding new content to avoid duplication.
 {% endif %}

shotgun/tui/screens/chat.py

@@ -43,6 +43,7 @@ from shotgun.sdk.codebase import CodebaseSDK
 from shotgun.sdk.exceptions import CodebaseNotFoundError, InvalidPathError
 from shotgun.sdk.services import get_codebase_service
 from shotgun.tui.commands import CommandHandler
+from shotgun.tui.screens.chat_screen.hint_message import HintMessage
 from shotgun.tui.screens.chat_screen.history import ChatHistory
 
 from ..components.prompt_input import PromptInput
@@ -322,7 +323,7 @@ class ChatScreen(Screen[None]):
     value = reactive("")
     mode = reactive(AgentType.RESEARCH)
     history: PromptHistory = PromptHistory()
-    messages = reactive(list[ModelMessage]())
+    messages = reactive(list[ModelMessage | HintMessage]())
     working = reactive(False)
     question: reactive[UserQuestion | None] = reactive(None)
     indexing_job: reactive[CodebaseIndexSelection | None] = reactive(None)
@@ -375,7 +376,7 @@ class ChatScreen(Screen[None]):
             dir.is_dir() and dir.name in ["__pycache__", ".git", ".shotgun"]
             for dir in cur_dir.iterdir()
         )
-        if is_empty:
+        if is_empty or self.continue_session:
             return
 
         # Check if the current directory has any accessible codebases
@@ -417,7 +418,7 @@ class ChatScreen(Screen[None]):
             spinner.set_classes("" if is_working else "hidden")
             spinner.display = is_working
 
-    def watch_messages(self, messages: list[ModelMessage]) -> None:
+    def watch_messages(self, messages: list[ModelMessage | HintMessage]) -> None:
         """Update the chat history when messages change."""
         if self.is_mounted:
             chat_history = self.query_one(ChatHistory)
@@ -479,14 +480,8 @@ class ChatScreen(Screen[None]):
                     yield Static("", id="indexing-job-display")
 
     def mount_hint(self, markdown: str) -> None:
-        chat_history = self.query_one(ChatHistory)
-        if not chat_history.vertical_tail:
-            return
-        chat_history.vertical_tail.mount(Markdown(markdown))
-        # Scroll to bottom after mounting hint
-        chat_history.vertical_tail.call_after_refresh(
-            chat_history.vertical_tail.scroll_end, animate=False
-        )
+        hint = HintMessage(message=markdown)
+        self.agent_manager.add_hint_message(hint)
 
     @on(PartialResponseMessage)
     def handle_partial_response(self, event: PartialResponseMessage) -> None:
@@ -543,9 +538,7 @@ class ChatScreen(Screen[None]):
                                 f"📁 Modified {num_files} files in: `{path_obj.parent}`"
                             )
 
-                    # Add this as a simple markdown widget
-                    file_info_widget = Markdown(message)
-                    chat_history.vertical_tail.mount(file_info_widget)
+                    self.mount_hint(message)
 
     @on(PromptInput.Submitted)
     async def handle_submit(self, message: PromptInput.Submitted) -> None:
@@ -730,6 +723,7 @@ class ChatScreen(Screen[None]):
             last_agent_model=state.agent_type,
         )
         conversation.set_agent_messages(state.agent_messages)
+        conversation.set_ui_messages(state.ui_messages)
 
         # Save to file
         self.conversation_manager.save(conversation)
@@ -742,10 +736,12 @@ class ChatScreen(Screen[None]):
 
         # Restore agent state
         agent_messages = conversation.get_agent_messages()
+        ui_messages = conversation.get_ui_messages()
 
         # Create ConversationState for restoration
         state = ConversationState(
             agent_messages=agent_messages,
+            ui_messages=ui_messages,
             agent_type=conversation.last_agent_model,
         )
 

shotgun/tui/screens/chat_screen/hint_message.py

@@ -0,0 +1,40 @@
+from typing import Literal
+
+from pydantic import BaseModel
+from textual.app import ComposeResult
+from textual.widget import Widget
+from textual.widgets import Markdown
+
+
+class HintMessage(BaseModel):
+    message: str
+    kind: Literal["hint"] = "hint"
+
+
+class HintMessageWidget(Widget):
+    """A message for the user generated by shotgun, not the agent.."""
+
+    DEFAULT_CSS = """
+        HintMessageWidget {
+          background: $secondary-background-darken-1;
+          height: auto;
+          margin: 1;
+          margin-left: 1;
+          padding: 1;
+
+          * > Markdown {
+              height: auto;
+              offset-x: -1;
+              padding: 0;
+              margin: 0;
+          }
+        }
+
+    """
+
+    def __init__(self, message: HintMessage) -> None:
+        super().__init__()
+        self.message = message
+
+    def compose(self) -> ComposeResult:
+        yield Markdown(markdown=f"{self.message.message}")

shotgun/tui/screens/chat_screen/history.py

@@ -19,6 +19,7 @@ from textual.widget import Widget
 from textual.widgets import Markdown
 
 from shotgun.tui.components.vertical_tail import VerticalTail
+from shotgun.tui.screens.chat_screen.hint_message import HintMessage, HintMessageWidget
 
 
 class PartialResponseWidget(Widget):  # TODO: doesn't work lol
@@ -75,16 +76,19 @@ class ChatHistory(Widget):
 
     def __init__(self) -> None:
         super().__init__()
-        self.items: list[ModelMessage] = []
+        self.items: list[ModelMessage | HintMessage] = []
         self.vertical_tail: VerticalTail | None = None
         self.partial_response = None
 
     def compose(self) -> ComposeResult:
         self.vertical_tail = VerticalTail()
+
         with self.vertical_tail:
             for item in self.items:
                 if isinstance(item, ModelRequest):
                     yield UserQuestionWidget(item)
+                elif isinstance(item, HintMessage):
+                    yield HintMessageWidget(item)
                 elif isinstance(item, ModelResponse):
                     yield AgentResponseWidget(item)
             yield PartialResponseWidget(self.partial_response).data_bind(
@@ -94,7 +98,7 @@ class ChatHistory(Widget):
     def watch_partial_response(self, _partial_response: ModelMessage | None) -> None:
         self.call_after_refresh(self.autoscroll)
 
-    def update_messages(self, messages: list[ModelMessage]) -> None:
+    def update_messages(self, messages: list[ModelMessage | HintMessage]) -> None:
         """Update the displayed messages without recomposing."""
         if not self.vertical_tail:
             return

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgun-sh
-Version: 0.1.0.dev25
+Version: 0.1.0.dev26
 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.dev25.dist-info → shotgun_sh-0.1.0.dev26.dist-info}/RECORD

@@ -7,12 +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=ApRzriE3mvAms5144rQ4Vjv1JWvRS89DruTtBvgVPdg,20235
-shotgun/agents/common.py,sha256=z4MOOHXpGWVpnxfGbOmfz-gYX9r8gjzcPPIOAJ9-2hc,15704
-shotgun/agents/conversation_history.py,sha256=vw7LMOCmpkidQGAidPIxPly2sh1k1K-5NF3iYkXOAAU,1815
+shotgun/agents/agent_manager.py,sha256=mIRGf5xaIvMuvUQRzPa3IqP-VlGCwVoxS1ftNgbeFPU,20943
+shotgun/agents/common.py,sha256=C5-hpIgyeQ5n22fIiSouJkdzbiLXAtvVxo176FIyeYM,19034
+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/models.py,sha256=MzQJFHZ7F_q2VEl48LDzuwroi0bvPR74g9qq5Zkqkq4,7339
+shotgun/agents/models.py,sha256=fljmjHoCzNXPWOHSA-1KmQk1epk8ovowqDM7j5zZKB8,7853
 shotgun/agents/plan.py,sha256=s-WfILBOW4l8kY59RUOVtX5MJSuSzFm1nGp6b17If78,3030
 shotgun/agents/research.py,sha256=lYG7Rytcitop8mXs3isMI3XvYzzI3JH9u0VZz6K9zfo,3274
 shotgun/agents/specify.py,sha256=7MoMxfIn34G27mw6wrp_F0i2O5rid476L3kHFONDCd0,3137
@@ -73,16 +73,16 @@ 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=qnb_V4QZycaOKDevb-9ZzAY10pEgBxbdk3kKyIRDex8,5466
-shotgun/prompts/agents/plan.j2,sha256=npu7x1p2O2O_ONI0nmkSvG7Kv6OC1dU8_IuqTOV1sHU,3420
+shotgun/prompts/agents/export.j2,sha256=-6lpRmIkSiDqm1G0Va_cf0JG3sJ14cQKQ8beQ0pBh94,8422
+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
 shotgun/prompts/agents/tasks.j2,sha256=Vm6nFSgYzdwRBySUzwMzWHhfYR12Cb_xKPqif7yMuhs,4909
 shotgun/prompts/agents/partials/codebase_understanding.j2,sha256=7WH-PVd-TRBFQUdOdKkwwn9hAUaJznFZMAGHhO7IGGU,5633
-shotgun/prompts/agents/partials/common_agent_system_prompt.j2,sha256=f5cpo2Ds7EceHvXYUHNs_1NoXv_K4BrWduXYcT2PL40,1803
+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=k7WICOLFCZ7yhH004AzqCBJ1U0MCF56ODSzdb7fe7Ck,905
+shotgun/prompts/agents/state/system_state.j2,sha256=XYAlf2_5PiIcJqdu-dBG4zyQBfD5h4rmjpI1fEIUW8c,1080
 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
@@ -107,22 +107,23 @@ shotgun/tui/components/prompt_input.py,sha256=Ss-htqraHZAPaehGE4x86ij0veMjc4Ugad
 shotgun/tui/components/spinner.py,sha256=ovTDeaJ6FD6chZx_Aepia6R3UkPOVJ77EKHfRmn39MY,2427
 shotgun/tui/components/splash.py,sha256=vppy9vEIEvywuUKRXn2y11HwXSRkQZHLYoVjhDVdJeU,1267
 shotgun/tui/components/vertical_tail.py,sha256=kkCH0WjAh54jDvRzIaOffRZXUKn_zHFZ_ichfUpgzaE,1071
-shotgun/tui/screens/chat.py,sha256=UlyFrd3OISB-M62R3fGBb-E9CoD6G4untbMVfDUSV3U,27820
+shotgun/tui/screens/chat.py,sha256=474e6W6r2QgQZvWwZoFds9Y7YmhjNukR_bXvwutHetM,27690
 shotgun/tui/screens/chat.tcss,sha256=2Yq3E23jxsySYsgZf4G1AYrYVcpX0UDW6kNNI0tDmtM,437
 shotgun/tui/screens/directory_setup.py,sha256=lIZ1J4A6g5Q2ZBX8epW7BhR96Dmdcg22CyiM5S-I5WU,3237
 shotgun/tui/screens/provider_config.py,sha256=A_tvDHF5KLP5PV60LjMJ_aoOdT3TjI6_g04UIUqGPqM,7126
 shotgun/tui/screens/splash.py,sha256=E2MsJihi3c9NY1L28o_MstDxGwrCnnV7zdq00MrGAsw,706
 shotgun/tui/screens/chat_screen/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 shotgun/tui/screens/chat_screen/command_providers.py,sha256=55JIH9T8QnyHRsMoXhOi87FiVM-d6o7OKpCe82uDP9I,7840
-shotgun/tui/screens/chat_screen/history.py,sha256=AP8wdXCxQ0uZeZE29WnLF6RCaZjcJzG97tjzqXFceoY,7711
+shotgun/tui/screens/chat_screen/hint_message.py,sha256=WOpbk8q7qt7eOHTyyHvh_IQIaublVDeJGaLpsxEk9FA,933
+shotgun/tui/screens/chat_screen/history.py,sha256=PKUqj3kYk0NqQyQRoM7fTn4lsivfTOlKqm_77cO5RG4,7930
 shotgun/tui/utils/__init__.py,sha256=cFjDfoXTRBq29wgP7TGRWUu1eFfiIG-LLOzjIGfadgI,150
 shotgun/tui/utils/mode_progress.py,sha256=lseRRo7kMWLkBzI3cU5vqJmS2ZcCjyRYf9Zwtvc-v58,10931
 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.dev25.dist-info/METADATA,sha256=GkDNaK-wokG1FYKaeQOLGZ2vVS0AehWd82rYBpjmbes,11197
-shotgun_sh-0.1.0.dev25.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-shotgun_sh-0.1.0.dev25.dist-info/entry_points.txt,sha256=asZxLU4QILneq0MWW10saVCZc4VWhZfb0wFZvERnzfA,45
-shotgun_sh-0.1.0.dev25.dist-info/licenses/LICENSE,sha256=YebsZl590zCHrF_acCU5pmNt0pnAfD2DmAnevJPB1tY,1065
-shotgun_sh-0.1.0.dev25.dist-info/RECORD,,
+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,,