fix(plugin): align standalone slash-command docs with default agents (#1261)

packages/claude-code-plugin/commands/act.md

@@ -42,22 +42,22 @@ This command activates ACT mode for the CodingBuddy workflow.
 **Purpose:**
 Execute implementation following TDD cycle, augmented coding principles, and quality standards
 
-**What ACT does (with Primary Developer Agent):**
+**What ACT does (with Software Engineer):**
 
-1. **Execute TDD Cycle** (via Primary Developer Agent)
+1. **Execute TDD Cycle** (via Software Engineer)
    - 🔴 For core logic: Red → Green → Refactor cycle
    - Write failing test first
    - Implement minimal code to pass
    - Refactor only after tests pass
-   - 🔴 **Required**: Follow Primary Developer Agent's TDD cycle
+   - 🔴 **Required**: Follow Software Engineer's TDD cycle
 
-2. **Implement Components** (via Primary Developer Agent)
+2. **Implement Components** (via Software Engineer)
    - Follow framework-specific component patterns
    - Use project design system components first
    - Apply project styling conventions
-   - 🔴 **Required**: Follow Primary Developer Agent's component strategy
+   - 🔴 **Required**: Follow Software Engineer's component strategy
 
-3. **Maintain Quality Standards** (via Primary Developer Agent)
+3. **Maintain Quality Standards** (via Software Engineer)
    - 🔴 Type safety (no unsafe type bypasses)
    - 🔴 Test coverage 90%+
    - 🔴 Pure/impure function separation
@@ -66,10 +66,10 @@ Execute implementation following TDD cycle, augmented coding principles, and qua
    - 🔴 Accessibility compliance
    - 🔴 **Required**: Reference Implementation Specialist Agents for comprehensive implementation verification (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)
 
-**Output Format (via Primary Developer Agent):**
+**Output Format (via Software Engineer):**
 ```
 # Mode: ACT
-## Agent : [Primary Developer Agent Name]
+## Agent : Software Engineer
 
 ## 🚀 Implementation Progress
 
@@ -176,19 +176,19 @@ To preserve this implementation session for future reference:
 ```
 
 **🔴 Required:**
-- All implementations must follow the Primary Developer Agent's code quality checklist
+- All implementations must follow the Software Engineer's code quality checklist
 - Respond in the language specified in the agent's communication.language setting
 - Execute one step at a time, verify tests after each step
 - On recoverable errors (file not found, command failure, path issues), try alternatives immediately
 - Only return to PLAN on unrecoverable blockers (missing dependencies, architectural conflicts)
 
 **Verification:**
-- Agent name should appear as `## Agent : [Primary Developer Agent Name]` in response
+- Agent name should appear as `## Agent : Software Engineer` in response
 - Mode indicator `# Mode: ACT` should be first line
 - Implementation Progress should show step-by-step completion
 - Implementation Specialist Verification sections should be included when applicable (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)
 - Quality Checks section should verify: Type Safety, Tests, Linting, Design System
-- Use `verification_guide` from Primary Developer Agent for detailed checklist validation
+- Use `verification_guide` from Software Engineer for detailed checklist validation
 - For TDD: Verify test file exists before implementation, test fails first (Red), then passes (Green)
 - For Test-After: Verify component exists before test file
 - Verify framework-specific component patterns are followed

packages/claude-code-plugin/commands/auto.md

@@ -45,7 +45,7 @@ Autonomous iterative development - automatically cycling through planning, imple
 
 1. **Initial Phase: PLAN**
    - Creates implementation plan following TDD and augmented coding principles
-   - Activates Primary Developer Agent automatically
+   - Activates Technical Planner automatically
    - Outputs structured plan with todo items
 
 2. **Execution Phase: ACT**
@@ -79,7 +79,7 @@ Autonomous iterative development - automatically cycling through planning, imple
 | `auto.maxIterations` | 3 | 1-10 | Maximum PLAN→ACT→EVAL cycles before forced exit |
 
 **🔴 Agent Activation (STRICT):**
-- When AUTO mode is triggered, **Primary Developer Agent** (loaded via parse_mode in MCP mode; defaults in standalone mode) **MUST** be automatically activated for PLAN and ACT phases
+- When AUTO mode is triggered, **Technical Planner** (PLAN phase) and **Software Engineer** (ACT phase) (loaded via parse_mode in MCP mode; defaults in standalone mode) **MUST** be automatically activated for their respective phases
 - During EVAL phase, **Code Reviewer Agent** (loaded via parse_mode in MCP mode; defaults in standalone mode) **MUST** be automatically activated
 - The respective Agent's workflow framework and all mandatory requirements MUST be followed
 - See agent definitions for complete agent frameworks
@@ -177,8 +177,8 @@ Remaining Issues:
 | Time efficiency | Optimized for quality | Optimized for control |
 
 **🔴 Required:**
-- All PLAN phases must follow the Primary Developer Agent's workflow framework
-- All ACT phases must follow the Primary Developer Agent's code quality checklist
+- All PLAN phases must follow the Technical Planner's workflow framework
+- All ACT phases must follow the Software Engineer's code quality checklist
 - All EVAL phases must follow the Code Reviewer Agent's evaluation framework
 - Respond in the language specified in the agent's communication.language setting
 - Continue iterating automatically until exit conditions are met (Critical = 0 AND High = 0)

packages/claude-code-plugin/commands/plan.md

@@ -76,34 +76,34 @@ See project rules for detailed question guidelines.
 
 ---
 
-**What PLAN does (with Primary Developer Agent):**
+**What PLAN does (with Technical Planner):**
 
-1. **Analyze Requirements** (via Primary Developer Agent)
+1. **Analyze Requirements** (via Technical Planner)
    - Understand user requirements
    - Identify core logic vs presentation components
    - Determine TDD (test-first) vs Test-After approach
-   - 🔴 **Required**: Follow Primary Developer Agent's workflow framework
+   - 🔴 **Required**: Follow Technical Planner's workflow framework
 
-2. **Plan Implementation** (via Primary Developer Agent workflow)
+2. **Plan Implementation** (via Technical Planner workflow)
    - 🔴 TDD for core logic (business logic, utilities, data access layers)
    - 🔴 Test-After for presentation (UI components, views)
    - Define file structure (types, constants, utils)
    - Plan test strategy
    - Consider framework-specific component patterns
    - 🔴 **Required**: Reference Planning Specialist Agents for comprehensive planning (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)
 
-3. **Output Structured PLAN** (via Primary Developer Agent)
+3. **Output Structured PLAN** (via Technical Planner)
    - Step-by-step implementation plan
    - Clear task breakdown
    - File naming conventions
    - Test coverage goals (90%+)
    - Type safety requirements
    - 🔴 **Required**: Create todo list using `todo_write` tool for all implementation steps
 
-**Output Format (via Primary Developer Agent):**
+**Output Format (via Technical Planner):**
 ```
 # Mode: PLAN
-## Agent : [Primary Developer Agent Name]
+## Agent : Technical Planner
 
 ## 📋 Plan Overview
 [High-level summary of what will be implemented]
@@ -236,18 +236,18 @@ To preserve this planning session for future reference:
 ```
 
 **🔴 Required:**
-- All plans must follow the Primary Developer Agent's workflow framework
+- All plans must follow the Technical Planner's workflow framework
 - Respond in the language specified in the agent's communication.language setting
 - Follow framework-specific component patterns as defined in project configuration
 - 🔴 **MUST use `todo_write` tool** to create todo list for all implementation steps
 - All todo items should be in `pending` status when created in PLAN mode
 
 **Verification:**
-- Agent name should appear as `## Agent : [Primary Developer Agent Name]` in response
+- Agent name should appear as `## Agent : Technical Planner` in response
 - Mode indicator `# Mode: PLAN` should be first line
 - Plan should include structured sections: Plan Overview, Todo List (created with todo_write), Implementation Steps, Planning Specialist sections (when applicable), Risk Assessment, File Structure, Quality Checklist
 - Todo list must be created using `todo_write` tool before outputting plan
-- All mandatory checklist items from the Primary Developer Agent should be considered during planning
+- All mandatory checklist items from the Technical Planner should be considered during planning
 - Planning Specialist Agents should be referenced when planning respective areas (Architecture, Test Strategy, Performance, Security, Accessibility, SEO, Design System, Documentation, Code Quality)
 
 ---

packages/claude-code-plugin/tests/test_standalone_docs_alignment.py

@@ -0,0 +1,131 @@
+"""Tests that slash-command docs match mode_engine.py DEFAULT_AGENTS.
+
+Prevents drift between standalone runtime defaults and command documentation.
+See: https://github.com/JeremyDev87/codingbuddy/issues/1261
+"""
+import os
+import re
+
+import pytest
+
+# Path helpers (relative to repo root)
+_PLUGIN_DIR = os.path.join(
+    os.path.dirname(__file__), os.pardir
+)
+_COMMANDS_DIR = os.path.join(_PLUGIN_DIR, "commands")
+_MODE_ENGINE = os.path.join(_PLUGIN_DIR, "hooks", "lib", "mode_engine.py")
+
+
+def _parse_default_agents():
+    """Parse DEFAULT_AGENTS dict from mode_engine.py source."""
+    with open(_MODE_ENGINE, encoding="utf-8") as f:
+        source = f.read()
+
+    # Match the DEFAULT_AGENTS block (greedy to capture all nested braces)
+    match = re.search(
+        r"DEFAULT_AGENTS\s*=\s*\{(.+?)\n\}", source, re.DOTALL
+    )
+    assert match, "Could not find DEFAULT_AGENTS in mode_engine.py"
+
+    agents = {}
+    for entry in re.finditer(
+        r'"(\w+)":\s*\{[^}]*"title":\s*"([^"]+)"', match.group(1)
+    ):
+        agents[entry.group(1)] = entry.group(2)
+    return agents
+
+
+def _read_command_md(mode):
+    """Read the command markdown for a given mode."""
+    path = os.path.join(_COMMANDS_DIR, f"{mode.lower()}.md")
+    if not os.path.isfile(path):
+        pytest.skip(f"{mode.lower()}.md not found")
+    with open(path, encoding="utf-8") as f:
+        return f.read()
+
+
+class TestStandaloneDocsAlignment:
+    """Ensure commands/*.md reference the correct default agents from mode_engine.py."""
+
+    @pytest.fixture(autouse=True)
+    def _load_defaults(self):
+        self.defaults = _parse_default_agents()
+
+    def test_default_agents_parsed(self):
+        """Sanity: we can parse all four modes from mode_engine.py."""
+        assert set(self.defaults.keys()) == {"PLAN", "ACT", "EVAL", "AUTO"}
+
+    def test_plan_md_references_technical_planner(self):
+        """plan.md standalone section must reference Technical Planner."""
+        content = _read_command_md("PLAN")
+        expected = self.defaults["PLAN"]  # "Technical Planner"
+        assert expected in content, (
+            f"plan.md must mention standalone default '{expected}'"
+        )
+        # The agent activation line should name the default
+        assert re.search(
+            rf"{re.escape(expected)}.*standalone", content
+        ), f"plan.md agent activation should reference '{expected}' for standalone"
+
+    def test_act_md_references_software_engineer(self):
+        """act.md standalone section must reference Software Engineer."""
+        content = _read_command_md("ACT")
+        expected = self.defaults["ACT"]  # "Software Engineer"
+        assert expected in content, (
+            f"act.md must mention standalone default '{expected}'"
+        )
+        assert re.search(
+            rf"{re.escape(expected)}.*standalone", content
+        ), f"act.md agent activation should reference '{expected}' for standalone"
+
+    def test_eval_md_references_code_reviewer(self):
+        """eval.md must reference Code Reviewer."""
+        content = _read_command_md("EVAL")
+        expected = self.defaults["EVAL"]  # "Code Reviewer"
+        assert expected in content, (
+            f"eval.md must mention standalone default '{expected}'"
+        )
+
+    def test_no_primary_developer_agent_in_plan(self):
+        """plan.md must not use the ambiguous 'Primary Developer Agent' term."""
+        content = _read_command_md("PLAN")
+        assert "Primary Developer Agent" not in content, (
+            "plan.md should use 'Technical Planner' instead of "
+            "'Primary Developer Agent'"
+        )
+
+    def test_no_primary_developer_agent_in_act(self):
+        """act.md must not use the ambiguous 'Primary Developer Agent' term."""
+        content = _read_command_md("ACT")
+        assert "Primary Developer Agent" not in content, (
+            "act.md should use 'Software Engineer' instead of "
+            "'Primary Developer Agent'"
+        )
+
+    def test_no_primary_developer_agent_in_auto(self):
+        """auto.md must not use the ambiguous 'Primary Developer Agent' term."""
+        content = _read_command_md("AUTO")
+        assert "Primary Developer Agent" not in content, (
+            "auto.md should use specific agent names instead of "
+            "'Primary Developer Agent'"
+        )
+
+    def test_auto_md_references_both_agents(self):
+        """auto.md must reference both Technical Planner and Software Engineer."""
+        content = _read_command_md("AUTO")
+        plan_agent = self.defaults["PLAN"]
+        act_agent = self.defaults["ACT"]
+        assert plan_agent in content, (
+            f"auto.md must mention PLAN default '{plan_agent}'"
+        )
+        assert act_agent in content, (
+            f"auto.md must mention ACT default '{act_agent}'"
+        )
+
+    def test_output_format_uses_concrete_agent_names(self):
+        """Output format templates must use concrete agent names, not placeholders."""
+        for mode in ("PLAN", "ACT"):
+            content = _read_command_md(mode)
+            assert "[Primary Developer Agent Name]" not in content, (
+                f"{mode.lower()}.md output format should use concrete agent name"
+            )