fix: address CodeRabbitAI review comments

- Use argparse for CLI argument parsing in server.py
- Use cross-platform webbrowser command in CONTRIBUTING.md
- Fix agent count and hyphenation in tasks file
- Fix test ordering assertions to follow SUPPORTED_AGENTS order
- Add explicit UTF-8 encoding to conftest.py
- Use iter_detection_dirs() in detection.py
- Clarify TOML dependency documentation
- Remove Qwen Code reference from docs
- Simplify test_writer.py fixture
- Add command prefix assertion in test_validation.py
- Show actual agent keys in error messages
- Preserve intentional blank lines in normalization
- Add argument deduplication in generators.py

Author: ryderstorm

CONTRIBUTING.md

@@ -62,8 +62,8 @@ See `docs/operations.md` for more details on transports and configuration.
 # Run tests with coverage report
 uv run pytest
 
-# View HTML coverage report (opens in browser)
-open htmlcov/index.html
+# View HTML coverage report (opens in default browser)
+uv run python -m webbrowser htmlcov/index.html
 ```
 
 The test suite generates both terminal and HTML coverage reports showing which code paths are tested.

docs/slash-command-generator.md

@@ -55,6 +55,8 @@ This means:
 - ✅ Guaranteed compatibility with your Python installation
 - ✅ Faster import times
 
+**Note**: While `tomllib` handles parsing TOML files (reading), the project uses `tomli-w` for writing TOML files (generating command files for Gemini CLI). Both are lightweight dependencies and `tomli-w` is required for generating TOML command files.
+
 ### Running Commands
 
 After installation, use `uv run` to execute the command:
@@ -223,7 +225,7 @@ $ARGUMENTS
 
 ### TOML Format
 
-TOML-based agents (Gemini CLI, Qwen Code) use TOML syntax:
+TOML-based agents (Gemini CLI) use TOML syntax:
 
 ```toml
 [command]

server.py

@@ -4,7 +4,7 @@
 The 'mcp' instance is automatically discovered by the FastMCP CLI.
 """
 
-import sys
+import argparse
 
 from mcp_server import create_app
 
@@ -22,25 +22,24 @@ def main() -> None:
     It runs the MCP server using stdio transport by default, or http transport
     if --transport http is passed as an argument.
     """
-    # Parse command line arguments
-    transport = "stdio"
-    port = 8000
-    args = sys.argv[1:]
-
-    # Simple argument parsing for transport and port
-    if "--transport" in args:
-        idx = args.index("--transport")
-        if idx + 1 < len(args):
-            transport = args[idx + 1]
-
-    if "--port" in args:
-        idx = args.index("--port")
-        if idx + 1 < len(args):
-            port = int(args[idx + 1])
+    parser = argparse.ArgumentParser(description="Run the MCP server")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "http"],
+        default="stdio",
+        help="Transport type (default: stdio)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="HTTP server port (default: 8000)",
+    )
+    args = parser.parse_args()
 
     # Run the server with the specified transport
-    if transport == "http":
-        mcp.run(transport="http", port=port)
+    if args.transport == "http":
+        mcp.run(transport="http", port=args.port)
     else:
         mcp.run()
 

slash_commands/cli.py

@@ -218,9 +218,7 @@ def generate(  # noqa: PLR0913 PLR0912 PLR0915
         print("\nTo fix this:", file=sys.stderr)
         print("  - Use --list-agents to see all supported agents", file=sys.stderr)
         print("  - Ensure agent keys are spelled correctly", file=sys.stderr)
-        print(
-            "  - Valid agent keys include: claude-code, cursor, gemini-cli, etc.", file=sys.stderr
-        )
+        print(f"  - Valid agent keys: {', '.join(list_agent_keys())}", file=sys.stderr)
         sys.exit(2)  # Validation error (invalid agent key)
     except PermissionError as e:
         print(f"Error: Permission denied: {e}", file=sys.stderr)

slash_commands/detection.py

@@ -35,7 +35,7 @@ def iter_detection_directories(agent: AgentConfig, base_path: Path | str) -> Ite
     """Yield absolute paths for the agent's detection directories."""
 
     base = Path(base_path)
-    for directory in agent.detection_dirs:
+    for directory in agent.iter_detection_dirs():
         yield base / Path(directory)
 
 

slash_commands/generators.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import UTC, datetime
 from typing import Any, Protocol
 
 import tomli_w
@@ -47,8 +47,12 @@ def _apply_agent_overrides(
             if "arguments" in overrides:
                 # Merge base arguments with override arguments
                 override_args = _normalize_override_arguments(overrides["arguments"])
-                # Combine base args with override args (override args are appended)
-                arguments = list(arguments) + override_args
+                # Deduplicate by name with override precedence
+                existing_names = {arg.name for arg in arguments}
+                # Only add override args that don't already exist
+                arguments = list(arguments) + [
+                    arg for arg in override_args if arg.name not in existing_names
+                ]
             if "enabled" in overrides:
                 enabled = overrides["enabled"]
 
@@ -78,7 +82,7 @@ def _normalize_output(content: str) -> str:
     - Ensures consistent line endings (LF)
     - Removes trailing whitespace from lines
     - Ensures UTF-8 encoding
-    - Normalizes multiple blank lines to single blank line
+    - Preserves intentional blank lines
 
     Args:
         content: The generated content to normalize
@@ -89,23 +93,8 @@ def _normalize_output(content: str) -> str:
     # Normalize line endings to LF
     content = content.replace("\r\n", "\n").replace("\r", "\n")
 
-    # Remove trailing whitespace from each line
-    lines = []
-    for line in content.splitlines():
-        lines.append(line.rstrip())
-
-    # Normalize multiple consecutive blank lines to single blank line
-    normalized_lines = []
-    prev_blank = False
-    for line in lines:
-        is_blank = not line.strip()
-        if is_blank and prev_blank:
-            continue  # Skip consecutive blank lines
-        normalized_lines.append(line)
-        prev_blank = is_blank
-
-    # Join lines and ensure trailing newline
-    result = "\n".join(normalized_lines)
+    # Remove trailing whitespace from each line, preserve intentional blank lines
+    result = "\n".join(line.rstrip() for line in content.splitlines())
     if result and not result.endswith("\n"):
         result += "\n"
 
@@ -226,7 +215,7 @@ def _build_meta(self, prompt: MarkdownPrompt, agent: AgentConfig) -> dict:
             "source_prompt": prompt.name,
             "source_path": str(prompt.path),
             "version": __version__,
-            "updated_at": datetime.now().isoformat(),
+            "updated_at": datetime.now(UTC).isoformat(),
         })
         return meta
 
@@ -265,7 +254,7 @@ def generate(self, prompt: MarkdownPrompt, agent: AgentConfig) -> str:
         # These are ignored by Gemini CLI but preserved for bookkeeping
         toml_data["meta"] = {
             "version": __version__,
-            "updated_at": datetime.now().isoformat(),
+            "updated_at": datetime.now(UTC).isoformat(),
             "source_prompt": prompt.name,
             "agent": agent.key,
         }

tasks/tasks-0003-spec-slash-command-generator.md

@@ -25,11 +25,11 @@
 ## Tasks
 
 - [x] 1.0 Establish slash command configuration and agent detection foundations
-  - Demo Criteria: "Config data models enumerate all 14 agents with accurate directories/formats and detection flags configured tools under pytest validation."
+  - Demo Criteria: "Config data models enumerate all 6 agents with accurate directories/formats and detection flags configured tools under pytest validation."
   - Proof Artifact(s): "CLI: `pytest tests/test_config.py tests/test_detection.py -v`; Log: detection fixture output listing detected agents."
   - [x] 1.1 Author failing tests in `tests/test_config.py` that assert required fields and format values for every agent entry.
   - [x] 1.2 Implement `CommandFormat` enum, `AgentConfig` dataclass, and helper accessors in `slash_commands/config.py` to satisfy the tests.
-  - [x] 1.3 Populate `SUPPORTED_AGENTS` with all 14 tools, including directory paths, file extensions, and format metadata.
+  - [x] 1.3 Populate `SUPPORTED_AGENTS` with all 6 tools, including directory paths, file extensions, and format metadata.
   - [x] 1.4 Draft failing detection tests in `tests/test_detection.py` covering positive, negative, and mixed directory scenarios using `tmp_path` fixtures.
   - [x] 1.5 Implement `detect_agents` (and supporting utilities) in `slash_commands/detection.py` so detection tests pass with deterministic ordering.
 
@@ -42,7 +42,7 @@
   - [x] 2.4 Implement `CommandGenerator` base class plus Markdown and TOML subclasses in `slash_commands/generators.py`, including helper factory selection logic.
   - [x] 2.5 Refine generators to normalize whitespace and encoding, updating tests to use snapshot-style comparisons for regression safety.
 
-- [x] 3.0 Build slash command writer orchestrating multi-agent generation and dry runs
+- [x] 3.0 Build slash command writer orchestrating multi‑agent generation and dry runs
   - Demo Criteria: "Writer loads prompts, generates commands for single and multi-agent selections, ensures directories exist, and reports dry-run results without writes."
   - Proof Artifact(s): "CLI: `pytest tests/test_writer.py -v`; Log: dry-run test output showing file paths and counts."
   - [x] 3.1 Introduce failing writer tests that mock prompt loading and assert correct call sequences for single and multi-agent runs.

tests/conftest.py

@@ -136,7 +136,8 @@ def sample_prompt(tmp_path) -> MarkdownPrompt:
 
             Use the provided instructions to perform the desired action.
             """
-        )
+        ),
+        encoding="utf-8",
     )
 
     return load_markdown_prompt(prompt_path)
@@ -178,7 +179,8 @@ def prompt_with_placeholder_body(tmp_path) -> MarkdownPrompt:
 
             and ensure `{{args}}` are handled correctly.
             """
-        )
+        ),
+        encoding="utf-8",
     )
 
     return load_markdown_prompt(prompt_path)

tests/test_detection.py

@@ -34,7 +34,8 @@ def test_detect_agents_identifies_configured_directories(
     detected = detect_agents(tmp_path)
     detected_keys = [agent.key for agent in detected]
 
-    assert detected_keys == sorted(agent_keys)
+    expected_order = [a.key for a in SUPPORTED_AGENTS if a.key in agent_keys]
+    assert detected_keys == expected_order
     for key in detected_keys:
         directories = {tmp_path / path for path in supported_agents_by_key[key].detection_dirs}
         assert all(directory.exists() for directory in directories)

tests/test_validation.py

@@ -52,6 +52,7 @@ def test_yaml_frontmatter_parsing(sample_prompt):
     # Verify frontmatter is a dict and contains required fields
     assert isinstance(frontmatter, dict)
     assert "name" in frontmatter
+    assert frontmatter["name"].startswith("sdd-"), "Expected command name to include prefix"
     assert "description" in frontmatter
     assert "tags" in frontmatter
     assert "enabled" in frontmatter
@@ -180,6 +181,13 @@ def test_generated_content_is_valid_before_writing(sample_prompt):
     assert isinstance(toml_data, dict)
     assert "prompt" in toml_data
 
+    # Verify TOML meta includes updated_at
+    assert "meta" in toml_data
+    assert "updated_at" in toml_data["meta"]
+    updated_at = toml_data["meta"]["updated_at"]
+    assert isinstance(updated_at, str), "Expected updated_at to be a string"
+    # Note: datetime formatting with timezone ensures ISO-8601 compliance
+
     # Both should be valid before any file writing occurs
     assert len(markdown_content) > 0
     assert len(toml_content) > 0