shotgun-sh 0.2.11.dev5__py3-none-any.whl → 0.2.17.dev1__py3-none-any.whl

shotgun/tui/screens/chat/chat_screen.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import logging
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import cast
@@ -11,6 +12,7 @@ from pydantic_ai.messages import (
     ModelRequest,
     ModelResponse,
     TextPart,
+    ToolCallPart,
     ToolReturnPart,
     UserPromptPart,
 )
@@ -47,6 +49,7 @@ from shotgun.codebase.core.manager import (
     CodebaseGraphManager,
 )
 from shotgun.codebase.models import IndexProgress, ProgressPhase
+from shotgun.exceptions import ContextSizeLimitExceeded
 from shotgun.posthog_telemetry import track_event
 from shotgun.sdk.codebase import CodebaseSDK
 from shotgun.sdk.exceptions import CodebaseNotFoundError, InvalidPathError
@@ -101,7 +104,6 @@ class ChatScreen(Screen[None]):
     history: PromptHistory = PromptHistory()
     messages = reactive(list[ModelMessage | HintMessage]())
     indexing_job: reactive[CodebaseIndexSelection | None] = reactive(None)
-    partial_message: reactive[ModelMessage | None] = reactive(None)
 
     # Q&A mode state (for structured output clarifying questions)
     qa_mode = reactive(False)
@@ -112,6 +114,10 @@ class ChatScreen(Screen[None]):
     # Working state - keep reactive for Textual watchers
     working = reactive(False)
 
+    # Throttle context indicator updates (in seconds)
+    _last_context_update: float = 0.0
+    _context_update_throttle: float = 5.0  # 5 seconds
+
     def __init__(
         self,
         agent_manager: AgentManager,
@@ -572,8 +578,6 @@ class ChatScreen(Screen[None]):
 
     @on(PartialResponseMessage)
     def handle_partial_response(self, event: PartialResponseMessage) -> None:
-        self.partial_message = event.message
-
         # Filter event.messages to exclude ModelRequest with only ToolReturnPart
         # These are intermediate tool results that would render as empty (UserQuestionWidget
         # filters out ToolReturnPart in format_prompt_parts), causing user messages to disappear
@@ -597,16 +601,33 @@ class ChatScreen(Screen[None]):
         )
 
         # Use widget coordinator to set partial response
-        self.widget_coordinator.set_partial_response(
-            self.partial_message, new_message_list
+        self.widget_coordinator.set_partial_response(event.message, new_message_list)
+
+        # Skip context updates for file write operations (they don't add to input context)
+        has_file_write = any(
+            isinstance(msg, ModelResponse)
+            and any(
+                isinstance(part, ToolCallPart)
+                and part.tool_name in ("write_file", "append_file")
+                for part in msg.parts
+            )
+            for msg in event.messages
         )
 
-        # Update context indicator with full message history including streaming messages
-        # Combine existing agent history with new streaming messages for accurate token count
-        combined_agent_history = self.agent_manager.message_history + event.messages
-        self.update_context_indicator_with_messages(
-            combined_agent_history, new_message_list
-        )
+        if has_file_write:
+            return  # Skip context update for file writes
+
+        # Throttle context indicator updates to improve performance during streaming
+        # Only update at most once per 5 seconds to avoid excessive token calculations
+        current_time = time.time()
+        if current_time - self._last_context_update >= self._context_update_throttle:
+            self._last_context_update = current_time
+            # Update context indicator with full message history including streaming messages
+            # Combine existing agent history with new streaming messages for accurate token count
+            combined_agent_history = self.agent_manager.message_history + event.messages
+            self.update_context_indicator_with_messages(
+                combined_agent_history, new_message_list
+            )
 
     def _clear_partial_response(self) -> None:
         # Use widget coordinator to clear partial response
@@ -666,32 +687,42 @@ class ChatScreen(Screen[None]):
         self.update_context_indicator()
 
         # If there are file operations, add a message showing the modified files
+        # Skip if hint was already added by agent_manager (e.g., in QA mode)
         if event.file_operations:
-            chat_history = self.query_one(ChatHistory)
-            if chat_history.vertical_tail:
-                tracker = FileOperationTracker(operations=event.file_operations)
-                display_path = tracker.get_display_path()
-
-                if display_path:
-                    # Create a simple markdown message with the file path
-                    # The terminal emulator will make this clickable automatically
-                    path_obj = Path(display_path)
-
-                    if len(event.file_operations) == 1:
-                        message = f"📝 Modified: `{display_path}`"
-                    else:
-                        num_files = len({op.file_path for op in event.file_operations})
-                        if path_obj.is_dir():
-                            message = (
-                                f"📁 Modified {num_files} files in: `{display_path}`"
-                            )
+            # Check if file operation hint already exists in recent messages
+            file_hint_exists = any(
+                isinstance(msg, HintMessage)
+                and (
+                    msg.message.startswith("📝 Modified:")
+                    or msg.message.startswith("📁 Modified")
+                )
+                for msg in event.messages[-5:]  # Check last 5 messages
+            )
+
+            if not file_hint_exists:
+                chat_history = self.query_one(ChatHistory)
+                if chat_history.vertical_tail:
+                    tracker = FileOperationTracker(operations=event.file_operations)
+                    display_path = tracker.get_display_path()
+
+                    if display_path:
+                        # Create a simple markdown message with the file path
+                        # The terminal emulator will make this clickable automatically
+                        path_obj = Path(display_path)
+
+                        if len(event.file_operations) == 1:
+                            message = f"📝 Modified: `{display_path}`"
                         else:
-                            # Common path is a file, show parent directory
-                            message = (
-                                f"📁 Modified {num_files} files in: `{path_obj.parent}`"
+                            num_files = len(
+                                {op.file_path for op in event.file_operations}
                             )
+                            if path_obj.is_dir():
+                                message = f"📁 Modified {num_files} files in: `{display_path}`"
+                            else:
+                                # Common path is a file, show parent directory
+                                message = f"📁 Modified {num_files} files in: `{path_obj.parent}`"
 
-                    self.mount_hint(message)
+                        self.mount_hint(message)
 
                     # Check and display any marketing messages
                     from shotgun.tui.app import ShotgunApp
@@ -1117,6 +1148,27 @@ class ChatScreen(Screen[None]):
         except asyncio.CancelledError:
             # Handle cancellation gracefully - DO NOT re-raise
             self.mount_hint("⚠️ Operation cancelled by user")
+        except ContextSizeLimitExceeded as e:
+            # User-friendly error with actionable options
+            hint = (
+                f"⚠️ **Context too large for {e.model_name}**\n\n"
+                f"Your conversation history exceeds this model's limit ({e.max_tokens:,} tokens).\n\n"
+                f"**Choose an action:**\n\n"
+                f"1. Switch to a larger model (`Ctrl+P` → Change Model)\n"
+                f"2. Switch to a larger model, compact (`/compact`), then switch back to {e.model_name}\n"
+                f"3. Clear conversation (`/clear`)\n"
+            )
+
+            self.mount_hint(hint)
+
+            # Log for debugging (won't send to Sentry due to ErrorNotPickedUpBySentry)
+            logger.info(
+                "Context size limit exceeded",
+                extra={
+                    "max_tokens": e.max_tokens,
+                    "model_name": e.model_name,
+                },
+            )
         except Exception as e:
             # Log with full stack trace to shotgun.log
             logger.exception(

shotgun/tui/screens/chat_screen/history/chat_history.py

@@ -47,7 +47,6 @@ class ChatHistory(Widget):
         super().__init__()
         self.items: Sequence[ModelMessage | HintMessage] = []
         self.vertical_tail: VerticalTail | None = None
-        self.partial_response = None
         self._rendered_count = 0  # Track how many messages have been mounted
 
     def compose(self) -> ComposeResult:
@@ -63,7 +62,7 @@ class ChatHistory(Widget):
                     yield HintMessageWidget(item)
                 elif isinstance(item, ModelResponse):
                     yield AgentResponseWidget(item)
-            yield PartialResponseWidget(self.partial_response).data_bind(
+            yield PartialResponseWidget(None).data_bind(
                 item=ChatHistory.partial_response
             )
 

shotgun/tui/widgets/widget_coordinator.py

@@ -166,8 +166,9 @@ class WidgetCoordinator:
 
         try:
             chat_history = self.screen.query_one(ChatHistory)
-            if message:
-                chat_history.partial_response = message
+            # Set the reactive attribute to trigger the PartialResponseWidget update
+            chat_history.partial_response = message
+            # Also update the full message list
             chat_history.update_messages(messages)
         except Exception as e:
             logger.exception(f"Failed to set partial response: {e}")

shotgun_sh-0.2.17.dev1.dist-info/METADATA

@@ -0,0 +1,465 @@
+Metadata-Version: 2.4
+Name: shotgun-sh
+Version: 0.2.17.dev1
+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
+Project-URL: Issues, https://github.com/shotgun-sh/shotgun-alpha/issues
+Project-URL: Discord, https://discord.gg/5RmY6J2N7s
+Author-email: "Proofs.io" <hello@proofs.io>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,cli,llm,planning,productivity,pydantic-ai,research,task-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=24.0.0
+Requires-Dist: anthropic>=0.39.0
+Requires-Dist: dependency-injector>=4.41.0
+Requires-Dist: genai-prices>=0.0.27
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: kuzu>=0.7.0
+Requires-Dist: logfire>=2.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: posthog>=3.0.0
+Requires-Dist: pydantic-ai>=0.0.14
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentencepiece>=0.2.0
+Requires-Dist: sentry-sdk[pure-eval]>=2.0.0
+Requires-Dist: tenacity>=8.0.0
+Requires-Dist: textual-dev>=1.7.0
+Requires-Dist: textual-serve>=0.1.0
+Requires-Dist: textual>=6.1.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: tree-sitter-go>=0.23.0
+Requires-Dist: tree-sitter-javascript>=0.23.0
+Requires-Dist: tree-sitter-python>=0.23.0
+Requires-Dist: tree-sitter-rust>=0.23.0
+Requires-Dist: tree-sitter-typescript>=0.23.0
+Requires-Dist: tree-sitter>=0.21.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: watchdog>=4.0.0
+Provides-Extra: dev
+Requires-Dist: commitizen>=3.13.0; extra == 'dev'
+Requires-Dist: lefthook>=1.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+<img width="400" height="150" alt="Shotgun logo transparent background" src="https://github.com/user-attachments/assets/08f9ccd5-f2e8-4bf4-9cb2-2f0de866a76a" />  
+
+### Spec-Driven Development
+
+
+**Write codebase-aware specs for AI coding agents (Codex, Cursor, Claude Code) so they don't derail.**
+<p align="center">
+  <a href="https://github.com/shotgun-sh/shotgun">
+    <img src="https://img.shields.io/badge/python-3.11+-blue?style=flat&logo=python&logoColor=white" />
+  </a>
+  <a href="https://www.producthunt.com/products/shotgun-cli/launches/shotgun-cli">
+    <img src="https://img.shields.io/badge/Product%20Hunt-%237%20Product%20of%20the%20Day-FF6154?style=flat&logo=producthunt&logoColor=white" />
+  </a>
+  <a href="https://github.com/shotgun-sh/shotgun?tab=contributing-ov-file">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat" />
+  </a>
+  <a href="https://github.com/shotgun-sh/shotgun?tab=MIT-1-ov-file">
+    <img src="https://img.shields.io/badge/license-MIT-blue?style=flat" />
+  </a>
+  <a href="https://discord.com/invite/5RmY6J2N7s">
+    <img src="https://img.shields.io/badge/discord-150+%20online-5865F2?style=flat&logo=discord&logoColor=white" />
+  </a>
+</p>
+
+[![Website](https://img.shields.io/badge/-shotgun.sh-5865F2?style=social&logo=safari&logoColor=5865F2)](https://shotgun.sh)      [![Follow @ShotgunCLI](https://img.shields.io/badge/Follow%20@ShotgunCLI-1DA1F2?style=social&logo=x&logoColor=000000)](https://x.com/ShotgunCLI)    [![YouTube](https://img.shields.io/badge/-@shotgunCLI-FF0000?style=social&logo=youtube&logoColor=red)](https://www.youtube.com/@shotgunCLI)
+
+</div>
+
+---
+
+<table>
+<tr>
+<td>
+  
+**Shotgun is a CLI tool** that generates codebase-aware specs for AI coding agents like Cursor, Claude Code, and Lovable. **It reads your entire repository**, researches how new features should fit your architecture, and produces technical specifications that keep AI agents on track—so they build what you actually want instead of derailing halfway through. **Bring your own key (BYOK) or use a Shotgun subscription — $10 for $10 in usage.**
+
+It includes research on existing patterns, implementation plans that respect your architecture, and task breakdowns ready to export as **AGENTS.md** files. Each spec is complete enough that your AI agent can work longer and further without losing context or creating conflicts.
+
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/9c7ca014-1ed3-4935-b310-9147b275fdc7" alt="Shotgun Demo" />
+</p>
+
+</td>
+</tr>
+</table>
+
+---
+
+# 📦 Installation
+
+### 1. Install uv
+
+Shotgun runs via `uvx` or `uv tool install`. First, install `uv` for your platform:
+
+<table>
+<tr>
+<th>Platform</th>
+<th>Installation Command</th>
+</tr>
+<tr>
+<td><strong>macOS</strong> (Homebrew)</td>
+<td>
+
+```bash
+brew install uv
+```
+</td>
+</tr>
+<tr>
+<td><strong>macOS/Linux</strong> (curl)</td>
+<td>
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+</td>
+</tr>
+<tr>
+<td><strong>Windows</strong> (PowerShell)</td>
+<td>
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"       
+```
+</td>
+</tr>
+</table>
+
+_💡 Restart your terminal after installation_
+
+### 2. Run Shotgun
+
+<table>
+<tr>
+<th>🚀 Try It Out (Ephemeral)</th>
+<th>⚡ Regular Use (Permanent)</th>
+</tr>
+<tr>
+<td>
+  
+**Best for:** Testing Shotgun first
+
+```bash
+uvx shotgun-sh@latest    
+```
+
+No installation needed, runs immediately
+
+</td>
+<td>
+
+**Best for:** Daily use
+
+```bash
+uv tool install shotgun-sh       
+```
+
+Then run anywhere: ``` shotgun ```
+
+</td>
+</tr>
+</table>
+
+_**Why uv?** It's 10-100x faster than pip and handles binary wheels reliably—no cmake/build tool errors._
+
+### 3. Get Started
+
+When you launch Shotgun, it will guide you through:
+
+| Step | What Happens |
+|------|--------------|
+| **1. Codebase Indexing** | Builds a searchable graph of your entire repository |
+| **2. LLM Setup** | Configure OpenAI, Anthropic, or Gemini |
+| **3. First Research** | Start generating codebase-aware specs |
+
+_**💡 Pro tip:** Run Shotgun in your IDE's terminal for the best experience._
+
+> [!WARNING]
+> **Upgrading from alpha?** Uninstall the old version first:
+> ```bash
+> npm uninstall -g @proofs-io/shotgun @proofs-io/shotgun-server
+> ```
+
+---
+
+# 🎥 Demo
+
+<p align="center">
+  <a href="https://youtu.be/nR6iKbJ8l_I">
+    <img src="https://github.com/user-attachments/assets/37eae206-0d6f-4499-b980-2f33a5aed65d" alt="Watch the Shotgun demo" width="720" height="405">
+  </a>
+</p>
+
+_Click the image above to watch the full demo on YouTube_
+
+---
+
+# 🎯 Usage
+
+Shotgun's Terminal UI guides you through **5 specialized modes** — from research to export. Each mode has a dedicated AI agent optimized for that phase.
+
+### Launch Shotgun in your project directory:
+
+| Already Installed | First Time / Try It Out |
+|-------------------|------------------------|
+| `shotgun` | `uvx shotgun-sh@latest` |
+
+_The TUI opens automatically. **Press `Shift+Tab` to switch modes** or `Ctrl+P` for the command palette._
+
+### The 5-Phase Workflow
+
+<table>
+<tr>
+<td align="center"><b>🔬 Research</b><br/>Explore & understand</td>
+<td align="center">→</td>
+<td align="center"><b>📝 Specify</b><br/>Define requirements</td>
+<td align="center">→</td>
+<td align="center"><b>📋 Plan</b><br/>Create roadmap</td>
+<td align="center">→</td>
+<td align="center"><b>✅ Tasks</b><br/>Break into steps</td>
+<td align="center">→</td>
+<td align="center"><b>📤 Export</b><br/>Format for AI</td>
+</tr>
+</table>
+
+_Each phase builds on the previous one, creating a complete specification ready for AI coding agents._
+
+### Mode Reference
+
+| Mode | What It Does | Example Prompt | Output |
+|:-----|:-------------|:---------------|:-------|
+| **🔬&nbsp;Research** | Searches codebase + web, identifies patterns | `How do we handle authentication in this codebase?` | `research.md` |
+| **📝&nbsp;Specify** | Creates technical specs aware of architecture | `Add OAuth2 authentication with refresh token support` | `specification.md` |
+| **📋&nbsp;Plan** | Generates implementation roadmap | `Create an implementation plan for the payment system` | `plan.md` |
+| **✅&nbsp;Tasks** | Breaks plans into actionable items | `Break down the user dashboard plan into tasks` | `tasks.md` |
+| **📤&nbsp;Export** | Formats for AI coding agents | `Export everything to AGENTS.md` | `AGENTS.md` |
+
+_**Mode switching:** `Shift+Tab` cycles through modes_
+
+_**Visual status:** See current mode and progress at bottom_
+
+### ⌨️ Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Shift+Tab` | Switch modes |
+| `Ctrl+P` | Open command palette |
+| `Ctrl+C` | Cancel operation |
+| `Escape` | Exit Q&A / stop agent |
+| `Ctrl+U` | View usage stats |
+
+### Tips for Better Results
+
+| Do This | Not This |
+|---------|----------|
+| ✅ `Research how we handle auth` | ❌ Jump straight to building |
+| ✅ `Shotgun please ask me questions first` | ❌ Assume Shotgun knows your needs |
+| ✅ `I'm working on payments, need refunds` | ❌ `Add refunds` (no context) |
+| ✅ Follow Research → Specify → Plan → Tasks | ❌ Skip phases |
+
+**Result:** Your AI coding agent gets complete context—what exists, why, and what to build.
+
+ **Note:** CLI available in [docs/CLI.md](docs/CLI.md), but TUI is recommended.
+
+---
+
+# ✨ Features
+
+### What Makes Shotgun Different
+
+<table>
+<tr>
+<th width="25%">Feature</th>
+<th width="35%">Shotgun</th>
+<th width="40%">Other Tools</th>
+</tr>
+
+<tr>
+<td><strong>Codebase Understanding</strong></td>
+<td>
+Reads your <strong>entire repository</strong> before generating specs. Finds existing patterns, dependencies, and architecture.
+</td>
+<td>
+Require manual context or search each time. No persistent understanding of your codebase structure.
+</td>
+</tr>
+
+<tr>
+<td><strong>Research Phase</strong></td>
+<td>
+Starts with research—discovers what you already have AND what exists externally before writing anything.
+</td>
+<td>
+Start at specification. Build first, discover problems later.
+</td>
+</tr>
+
+<tr>
+<td><strong>Dedicated Agents Per Mode</strong></td>
+<td>
+Each mode (research, spec, plan, tasks, export) uses a <strong>separate specialized agent</strong> with prompts tailored specifically for that phase. 100% user-controllable via mode switching.
+</td>
+<td>
+Single-agent or one-size-fits-all prompts.
+</td>
+</tr>
+
+<tr>
+<td><strong>Structured Workflow</strong></td>
+<td>
+5-phase journey with checkpoints: Research → Spec → Plan → Tasks → Export
+</td>
+<td>
+No structure. Just "prompt and hope."
+</td>
+</tr>
+
+<tr>
+<td><strong>Export Formats</strong></td>
+<td>
+<code>AGENTS.md</code> files ready for Cursor, Claude Code, Windsurf, Lovable—your choice of tool.
+</td>
+<td>
+Locked into specific IDE or coding agent.
+</td>
+</tr>
+
+</table>
+
+### Case Study - Real Example:
+
+We had to implement payments. Cursor, Claude Code, and Copilot all suggested building a custom payment proxy — 3-4 weeks of development. 
+
+⭐ Shotgun's research found [LiteLLM Proxy](https://docs.litellm.ai/docs/simple_proxy) instead—**30 minutes to discover, 5 days to deploy, first customer in 14 hours.**
+
+****80% less dev time. Near-zero technical debt.****
+
+### **[📖 Read the full case study](docs/CASE_STUDY.md)**
+
+---
+
+# Use Cases
+
+- **🚀 Onboarding** - New developer? Shotgun maps your entire architecture and generates docs that actually match the code
+- **🔧 Refactoring** - Understand all dependencies before touching anything. Keep your refactor from becoming a rewrite
+- **🌱 Greenfield Projects** - Research existing solutions globally before writing line one
+- **➕ Adding Features** - Know exactly where your feature fits. Prevent duplicate functionality
+- **📦 Migration** - Map the old, plan the new, track the delta. Break migration into safe stages
+
+**📚 Want to see a detailed example?** Check out our [Case Study](docs/CASE_STUDY.md) showing Shotgun in action on a real-world project.
+
+---
+
+# FAQ
+
+**Q: Does Shotgun collect any stats or data?**
+
+A: We only gather minimal, anonymous events (e.g., install, server start, tool call). We don't collect the content itself—only that an event occurred. We use Sentry for error reporting to improve stability.
+
+**Q: Local LLMs?**
+
+A: Planned. We'll publish compatibility notes and local provider integrations.
+
+**Q: What LLM providers are supported?**
+
+A: Currently OpenAI, Anthropic (Claude), and Google Gemini. Local LLM support is on the roadmap.
+
+**Q: Can I use Shotgun offline?**
+
+A: You need an internet connection for LLM API calls, but your codebase stays local.
+
+**Q: How does the code graph work?**
+
+A: Shotgun indexes your codebase using tree-sitter for accurate parsing and creates a searchable graph of your code structure, dependencies, and relationships.
+
+---
+# Contributing
+
+Shotgun is open-source and we welcome contributions. Whether you're fixing bugs, proposing features, improving docs, or spreading the word—we'd love to have you as part of the community.
+
+### Ways to contribute:
+
+- **Bug Report:** Found an issue? [Create a bug report](https://github.com/shotgun-sh/shotgun/issues/new?template=bug_report.md)
+- **Feature Request:** Have an idea to make Shotgun better? [Submit a feature request](https://github.com/shotgun-sh/shotgun/issues/new?template=feature_request.md)
+- **Documentation:** See something missing in the docs? [Request documentation](https://github.com/shotgun-sh/shotgun/issues/new?template=documentation.md)
+
+**Not sure where to start?** Join our Discord and we'll help you get started!
+
+<div align="left">
+  <a href="https://discord.com/invite/5RmY6J2N7s">
+    <img src="https://img.shields.io/badge/Join%20our%20community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join Discord" />
+  </a>
+</div>
+
+### Development Resources
+
+- **[Contributing Guide](docs/CONTRIBUTING.md)** - Setup, workflow, and guidelines
+- **[Git Hooks](docs/GIT_HOOKS.md)** - Lefthook, trufflehog, and security scanning
+- **[CI/CD](docs/CI_CD.md)** - GitHub Actions and automated testing
+- **[Observability](docs/OBSERVABILITY.md)** - Telemetry, Logfire, and monitoring
+- **[Docker](docs/DOCKER.md)** - Container setup and deployment
+
+---
+
+<div align="center">
+
+## 🚀 Ready to Stop AI Agents from Derailing?
+
+**Research → Specify → Plan → Tasks → Export** — Five phases that give AI agents the full picture.
+
+```bash
+uvx shotgun-sh@latest
+```
+
+
+### ⭐ Star us on GitHub
+
+
+<a href="https://github.com/shotgun-sh/shotgun">
+  <img src="https://img.shields.io/badge/⭐%20Star%20on%20GitHub-181717?style=for-the-badge&logo=github&logoColor=white" alt="Star Shotgun Repo" />
+</a>
+
+### Star History
+
+<a href="https://www.star-history.com/#shotgun-sh/shotgun&type=date&legend=bottom-right">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=shotgun-sh/shotgun&type=date&theme=dark&legend=bottom-right" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=shotgun-sh/shotgun&type=date&legend=bottom-right" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=shotgun-sh/shotgun&type=date&legend=bottom-right" />
+ </picture>
+</a>
+
+</div>
+
+---
+
+**License:** MIT | **Python:** 3.11+ | **Homepage:** [shotgun.sh](https://shotgun.sh/)
+
+---
+
+## Uninstall
+
+```bash
+uv tool uninstall shotgun-sh
+```