shotgun-sh 0.1.0.dev22__py3-none-any.whl → 0.1.0.dev24__py3-none-any.whl

shotgun/agents/tasks.py

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

shotgun/agents/tools/file_management.py

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

shotgun/codebase/core/ingestor.py

@@ -54,7 +54,7 @@ class Ingestor:
 
         # Node tables
         node_schemas = [
-            "CREATE NODE TABLE Project(name STRING PRIMARY KEY, repo_path STRING, graph_id STRING, created_at INT64, updated_at INT64, schema_version STRING, build_options STRING, node_count INT64, relationship_count INT64, stats_updated_at INT64, status STRING, current_operation_id STRING, last_operation STRING)",
+            "CREATE NODE TABLE Project(name STRING PRIMARY KEY, repo_path STRING, graph_id STRING, created_at INT64, updated_at INT64, schema_version STRING, build_options STRING, node_count INT64, relationship_count INT64, stats_updated_at INT64, status STRING, current_operation_id STRING, last_operation STRING, indexed_from_cwds STRING)",
             "CREATE NODE TABLE Package(qualified_name STRING PRIMARY KEY, name STRING, path STRING)",
             "CREATE NODE TABLE Folder(path STRING PRIMARY KEY, name STRING)",
             "CREATE NODE TABLE File(path STRING PRIMARY KEY, name STRING, extension STRING)",

shotgun/codebase/core/manager.py

@@ -252,6 +252,7 @@ class CodebaseGraphManager:
         name: str,
         languages: list[str] | None,
         exclude_patterns: list[str] | None,
+        indexed_from_cwd: str | None = None,
     ) -> None:
         """Initialize the graph database and create initial metadata.
 
@@ -294,7 +295,8 @@ class CodebaseGraphManager:
                 last_operation: $last_operation,
                 node_count: 0,
                 relationship_count: 0,
-                stats_updated_at: $stats_updated_at
+                stats_updated_at: $stats_updated_at,
+                indexed_from_cwds: $indexed_from_cwds
             })
             """,
             {
@@ -311,6 +313,9 @@ class CodebaseGraphManager:
                 "current_operation_id": None,
                 "last_operation": None,
                 "stats_updated_at": int(time.time()),
+                "indexed_from_cwds": json.dumps(
+                    [indexed_from_cwd] if indexed_from_cwd else []
+                ),
             },
         )
 
@@ -323,6 +328,7 @@ class CodebaseGraphManager:
         name: str | None = None,
         languages: list[str] | None = None,
         exclude_patterns: list[str] | None = None,
+        indexed_from_cwd: str | None = None,
     ) -> CodebaseGraph:
         """Build a new code knowledge graph.
 
@@ -397,7 +403,8 @@ class CodebaseGraphManager:
                 created_at: $created_at,
                 updated_at: $updated_at,
                 schema_version: $schema_version,
-                build_options: $build_options
+                build_options: $build_options,
+                indexed_from_cwds: $indexed_from_cwds
             })
             """,
             {
@@ -410,6 +417,9 @@ class CodebaseGraphManager:
                 "build_options": json.dumps(
                     {"languages": languages, "exclude_patterns": exclude_patterns}
                 ),
+                "indexed_from_cwds": json.dumps(
+                    [indexed_from_cwd] if indexed_from_cwd else []
+                ),
             },
         )
 
@@ -475,6 +485,7 @@ class CodebaseGraphManager:
             status=GraphStatus.READY,
             last_operation=None,
             current_operation_id=None,
+            indexed_from_cwds=[indexed_from_cwd] if indexed_from_cwd else [],
         )
 
         # Update status to READY
@@ -1145,6 +1156,15 @@ class CodebaseGraphManager:
                     logger.debug(f"Failed to parse last operation stats: {e}")
                     last_operation = None
 
+            # Parse indexed_from_cwds - handle backward compatibility
+            indexed_from_cwds_json = project.get("indexed_from_cwds", "[]")
+            try:
+                indexed_from_cwds = (
+                    json.loads(indexed_from_cwds_json) if indexed_from_cwds_json else []
+                )
+            except (json.JSONDecodeError, TypeError):
+                indexed_from_cwds = []
+
             return CodebaseGraph(
                 graph_id=graph_id,
                 repo_path=project.get("repo_path", ""),
@@ -1165,6 +1185,7 @@ class CodebaseGraphManager:
                 status=status,
                 last_operation=last_operation,
                 current_operation_id=project.get("current_operation_id"),
+                indexed_from_cwds=indexed_from_cwds,
             )
         except Exception as e:
             logger.error(
@@ -1190,6 +1211,83 @@ class CodebaseGraphManager:
 
         return sorted(graphs, key=lambda g: g.updated_at, reverse=True)
 
+    async def add_cwd_access(self, graph_id: str, cwd: str | None = None) -> None:
+        """Add a working directory to a graph's access list.
+
+        Args:
+            graph_id: Graph ID to update
+            cwd: Working directory to add. If None, uses current working directory.
+        """
+        from pathlib import Path
+
+        if cwd is None:
+            cwd = str(Path.cwd().resolve())
+        else:
+            cwd = str(Path(cwd).resolve())
+
+        # Get current graph
+        graph = await self.get_graph(graph_id)
+        if not graph:
+            raise ValueError(f"Graph {graph_id} not found")
+
+        # Get current list
+        current_cwds = graph.indexed_from_cwds.copy()
+
+        # Add new CWD if not already present
+        if cwd not in current_cwds:
+            current_cwds.append(cwd)
+
+            # Update in database
+            await self._execute_query(
+                graph_id,
+                """
+                MATCH (p:Project {graph_id: $graph_id})
+                SET p.indexed_from_cwds = $indexed_from_cwds
+                """,
+                {
+                    "graph_id": graph_id,
+                    "indexed_from_cwds": json.dumps(current_cwds),
+                },
+            )
+            logger.info(f"Added CWD access for {cwd} to graph {graph_id}")
+
+    async def remove_cwd_access(self, graph_id: str, cwd: str) -> None:
+        """Remove a working directory from a graph's access list.
+
+        Args:
+            graph_id: Graph ID to update
+            cwd: Working directory to remove
+        """
+        from pathlib import Path
+
+        cwd = str(Path(cwd).resolve())
+
+        # Get current graph
+        graph = await self.get_graph(graph_id)
+        if not graph:
+            raise ValueError(f"Graph {graph_id} not found")
+
+        # Get current list
+        current_cwds = graph.indexed_from_cwds.copy()
+
+        # Remove CWD if present
+        if cwd in current_cwds:
+            current_cwds.remove(cwd)
+
+            # Update in database
+            await self._execute_query(
+                graph_id,
+                """
+                MATCH (p:Project {graph_id: $graph_id})
+                SET p.indexed_from_cwds = $indexed_from_cwds
+                """,
+                {
+                    "graph_id": graph_id,
+                    "indexed_from_cwds": json.dumps(current_cwds),
+                },
+            )
+            logger.info(f"Removed CWD access for {cwd} from graph {graph_id}")
+
     async def delete_graph(self, graph_id: str) -> None:
         """Delete a graph.
 
@@ -1365,6 +1463,7 @@ class CodebaseGraphManager:
         name: str,
         languages: list[str] | None,
         exclude_patterns: list[str] | None,
+        indexed_from_cwd: str | None = None,
     ) -> CodebaseGraph:
         """Internal implementation of graph building (runs in background)."""
         operation_id = str(uuid.uuid4())
@@ -1388,7 +1487,7 @@ class CodebaseGraphManager:
 
             # Do the actual build work
             graph = await self._do_build_graph(
-                graph_id, repo_path, name, languages, exclude_patterns
+                graph_id, repo_path, name, languages, exclude_patterns, indexed_from_cwd
             )
 
             # Update operation stats
@@ -1436,6 +1535,7 @@ class CodebaseGraphManager:
         name: str,
         languages: list[str] | None,
         exclude_patterns: list[str] | None,
+        indexed_from_cwd: str | None = None,
     ) -> CodebaseGraph:
         """Execute the actual graph building logic (extracted from original build_graph)."""
         # The database and Project node already exist from _initialize_graph_metadata
@@ -1515,6 +1615,7 @@ class CodebaseGraphManager:
         name: str | None = None,
         languages: list[str] | None = None,
         exclude_patterns: list[str] | None = None,
+        indexed_from_cwd: str | None = None,
     ) -> str:
         """Start building a new code knowledge graph asynchronously.
 
@@ -1547,12 +1648,13 @@ class CodebaseGraphManager:
             name=name,
             languages=languages,
             exclude_patterns=exclude_patterns,
+            indexed_from_cwd=indexed_from_cwd,
         )
 
         # Start the build operation in background
         task = asyncio.create_task(
             self._build_graph_impl(
-                graph_id, repo_path, name, languages, exclude_patterns
+                graph_id, repo_path, name, languages, exclude_patterns, indexed_from_cwd
             )
         )
         self._operations[graph_id] = task

shotgun/codebase/models.py

@@ -73,6 +73,10 @@ class CodebaseGraph(BaseModel):
     current_operation_id: str | None = Field(
         None, description="ID of current in-progress operation"
     )
+    indexed_from_cwds: list[str] = Field(
+        default_factory=list,
+        description="List of working directories from which this graph is accessible. Empty list means globally accessible.",
+    )
 
 
 class QueryResult(BaseModel):

shotgun/codebase/service.py

@@ -36,17 +36,57 @@ class CodebaseService:
         """
         return await self.manager.list_graphs()
 
-    async def create_graph(self, repo_path: str | Path, name: str) -> CodebaseGraph:
+    async def list_graphs_for_directory(
+        self, directory: Path | str | None = None
+    ) -> list[CodebaseGraph]:
+        """List graphs that match a specific directory.
+
+        Args:
+            directory: Directory to filter by. If None, uses current working directory.
+
+        Returns:
+            List of CodebaseGraph objects accessible from the specified directory
+        """
+        from pathlib import Path
+
+        if directory is None:
+            directory = Path.cwd()
+        elif isinstance(directory, str):
+            directory = Path(directory)
+
+        # Resolve to absolute path for comparison
+        target_path = str(directory.resolve())
+
+        # Get all graphs and filter by those accessible from this directory
+        all_graphs = await self.manager.list_graphs()
+        filtered_graphs = []
+
+        for graph in all_graphs:
+            # If indexed_from_cwds is empty, it's globally accessible (backward compatibility)
+            if not graph.indexed_from_cwds:
+                filtered_graphs.append(graph)
+            # Otherwise, check if current directory is in the allowed list
+            elif target_path in graph.indexed_from_cwds:
+                filtered_graphs.append(graph)
+
+        return filtered_graphs
+
+    async def create_graph(
+        self, repo_path: str | Path, name: str, indexed_from_cwd: str | None = None
+    ) -> CodebaseGraph:
         """Create and index a new graph from a repository.
 
         Args:
             repo_path: Path to the repository to index
             name: Human-readable name for the graph
+            indexed_from_cwd: Working directory from which indexing was initiated
 
         Returns:
             The created CodebaseGraph
         """
-        return await self.manager.build_graph(str(repo_path), name)
+        return await self.manager.build_graph(
+            str(repo_path), name, indexed_from_cwd=indexed_from_cwd
+        )
 
     async def get_graph(self, graph_id: str) -> CodebaseGraph | None:
         """Get graph metadata by ID.
@@ -59,6 +99,24 @@ class CodebaseService:
         """
         return await self.manager.get_graph(graph_id)
 
+    async def add_cwd_access(self, graph_id: str, cwd: str | None = None) -> None:
+        """Add a working directory to a graph's access list.
+
+        Args:
+            graph_id: Graph ID to update
+            cwd: Working directory to add. If None, uses current working directory.
+        """
+        await self.manager.add_cwd_access(graph_id, cwd)
+
+    async def remove_cwd_access(self, graph_id: str, cwd: str) -> None:
+        """Remove a working directory from a graph's access list.
+
+        Args:
+            graph_id: Graph ID to update
+            cwd: Working directory to remove
+        """
+        await self.manager.remove_cwd_access(graph_id, cwd)
+
     async def delete_graph(self, graph_id: str) -> None:
         """Delete a graph and its data.
 

shotgun/main.py

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

shotgun/prompts/agents/export.j2

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

shotgun/prompts/agents/partials/common_agent_system_prompt.j2

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

shotgun/prompts/agents/plan.j2

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