Persist .plain/AGENTS.md via plain dev

Author: davegaeddert

AGENTS.md

@@ -69,6 +69,7 @@ Example workflow:
 ## Coding style
 
 - Don't include args and returns in docstrings if they are already type annotated.
+- CLI command docstrings should be concise, informative, no punctuation at the end.
 
 ## Verifying changes
 

plain-dev/plain/dev/core.py

@@ -136,6 +136,7 @@ def run(self) -> int:
         )
 
         self.symlink_plain_src()
+        self.generate_agents_md()
         self.modify_hosts_file()
 
         click.secho("→ Running preflight checks... ", dim=True, nl=False)
@@ -209,6 +210,28 @@ def symlink_plain_src(self) -> None:
         if plain_path.exists() and not symlink_path.exists():
             symlink_path.symlink_to(plain_path)
 
+    def generate_agents_md(self) -> None:
+        """Generate .plain/AGENTS.md from installed packages with AGENTS.md files."""
+        try:
+            result = subprocess.run(
+                [sys.executable, "-m", "plain", "agent", "md", "--save"],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0 and result.stderr:
+                click.secho(
+                    f"Warning: Failed to generate .plain/AGENTS.md: {result.stderr}",
+                    fg="yellow",
+                    err=True,
+                )
+        except Exception as e:
+            click.secho(
+                f"Warning: Failed to generate .plain/AGENTS.md: {e}",
+                fg="yellow",
+                err=True,
+            )
+
     def modify_hosts_file(self) -> None:
         """Modify the hosts file to map the custom domain to 127.0.0.1."""
         entry_identifier = "# Added by plain"

plain-observer/plain/observer/AGENTS.md

@@ -2,5 +2,4 @@
 
 - Send a request and record traces: `plain agent request /some/path --user 1 --header "Observer: persist"`
 - Find traces by request ID: `plain observer traces --request-id abc-123-def`
-- Diagnose trace: `plain observer diagnose [TRACE_ID]`
 - Output raw trace data: `plain observer trace [TRACE_ID] --json`

plain/plain/cli/agent/__init__.py

@@ -5,13 +5,10 @@
 from .request import request
 
 
-@click.group("agent", invoke_without_command=True)
-@click.pass_context
-def agent(ctx: click.Context) -> None:
+@click.group("agent")
+def agent() -> None:
     """Tools for coding agents"""
-    if ctx.invoked_subcommand is None:
-        # If no subcommand provided, show all AGENTS.md files
-        ctx.invoke(md, show_all=True, show_list=False, package="")
+    pass
 
 
 # Add commands to the group

plain/plain/cli/agent/md.py

@@ -6,6 +6,8 @@
 
 import click
 
+from plain.runtime import PLAIN_TEMP_PATH
+
 from ..output import iterate_markdown
 
 
@@ -20,11 +22,13 @@ def _get_packages_with_agents() -> dict[str, Path]:
         # Check core plain package (namespace package)
         plain_spec = importlib.util.find_spec("plain")
         if plain_spec and plain_spec.submodule_search_locations:
-            # For namespace packages, use the first search location
-            plain_path = Path(plain_spec.submodule_search_locations[0])
-            agents_path = plain_path / "AGENTS.md"
-            if agents_path.exists():
-                agents_files["plain"] = agents_path
+            # For namespace packages, check all search locations
+            for location in plain_spec.submodule_search_locations:
+                plain_path = Path(location)
+                agents_path = plain_path / "AGENTS.md"
+                if agents_path.exists():
+                    agents_files["plain"] = agents_path
+                    break  # Use the first one found
 
         # Check other plain.* subpackages
         if hasattr(plain, "__path__"):
@@ -49,44 +53,54 @@ def _get_packages_with_agents() -> dict[str, Path]:
 
 
 @click.command("md")
-@click.argument("package", default="", required=False)
-@click.option(
-    "--all",
-    "show_all",
-    is_flag=True,
-    help="Show AGENTS.md for all packages that have them",
-)
 @click.option(
-    "--list",
-    "show_list",
-    is_flag=True,
-    help="List packages with AGENTS.md files",
+    "--save",
+    default=None,
+    is_flag=False,
+    flag_value="PLAIN_TEMP_PATH",
+    help="Save combined AGENTS.md from all packages to file (default: .plain/AGENTS.md)",
 )
-def md(package: str, show_all: bool, show_list: bool) -> None:
-    """Show AGENTS.md for a package"""
+def md(save: str | None) -> None:
+    """AGENTS.md from installed Plain packages"""
 
     agents_files = _get_packages_with_agents()
 
-    if show_list:
-        for pkg in sorted(agents_files.keys()):
-            click.echo(f"- {pkg}")
-
+    if not agents_files:
         return
 
-    if show_all:
+    # Handle --save flag
+    if save:
+        # Use PLAIN_TEMP_PATH if flag was used without value
+        if save == "PLAIN_TEMP_PATH":
+            save_path = PLAIN_TEMP_PATH / "AGENTS.md"
+        else:
+            save_path = Path(save)
+
+        # Check if we need to regenerate
+        if save_path.exists():
+            output_mtime = save_path.stat().st_mtime
+            # Check if any source file is newer
+            needs_regen = any(
+                path.stat().st_mtime > output_mtime for path in agents_files.values()
+            )
+            if not needs_regen:
+                return
+
+        # Ensure parent directory exists
+        save_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Generate combined file
+        with save_path.open("w") as f:
+            for pkg_name in sorted(agents_files.keys()):
+                content = agents_files[pkg_name].read_text()
+                f.write(content)
+                if not content.endswith("\n"):
+                    f.write("\n")
+                f.write("\n")
+    else:
+        # Display to console
         for pkg in sorted(agents_files.keys()):
             agents_path = agents_files[pkg]
             for line in iterate_markdown(agents_path.read_text()):
                 click.echo(line, nl=False)
             print()
-
-        return
-
-    if not package:
-        raise click.UsageError(
-            "Package name or --all required. Use --list to see available packages."
-        )
-
-    agents_path = agents_files[package]
-    for line in iterate_markdown(agents_path.read_text()):
-        click.echo(line, nl=False)