fix: always clone into code-repo/<name>/, support multi-value --repo/--pr, qualify agent names

Three changes:

1. resolve_source.py: single repos now clone into code-repo/<repo_name>/
   instead of flat into code-repo/. Consistent with multi-repo behavior.

2. resolve_source.py: --repo and --pr accept multiple space-delimited
   values (nargs="+"). Multiple --repo values each get cloned into their
   own subdirectory with primary + additional_repos in the result.

3. All workflow step skills: use fully qualified agent names
   (docs-tools:<agent>) in prose, descriptions, and subagent_type fields
   to prevent "agent not found" errors from bare name dispatch.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

rh-pre-commit.version: 2.3.2
rh-pre-commit.check-secrets: ENABLED

Author: aireilly

plugins/docs-tools/skills/docs-orchestrator/SKILL.md

@@ -2,7 +2,7 @@
 name: docs-orchestrator
 description: Documentation workflow orchestrator. Reads the step list from .claude/docs-workflow.yaml (or the plugin default). Runs steps sequentially, manages progress state, handles iteration and confirmation gates. Claude is the orchestrator — the YAML is a step list, not a workflow engine.
 
-argument-hint: <ticket> [--workflow <name>] [--pr <url>]... [--source-code-repo <url-or-path>] [--mkdocs] [--draft] [--docs-repo-path <path>] [--create-jira <PROJECT>] [--create-merge-request]
+argument-hint: <ticket> [--workflow <name>] [--pr <url>...] [--source-code-repo <url-or-path>...] [--mkdocs] [--draft] [--docs-repo-path <path>] [--create-jira <PROJECT>] [--create-merge-request]
 
 allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, AskUserQuestion
 ---
@@ -31,11 +31,11 @@ When displaying available options to the user (e.g., on skill load or when askin
 
 - `$1` — JIRA ticket ID (required). If missing, STOP and ask the user.
 - `--workflow <name>` — Use `.claude/docs-<name>.yaml` instead of `docs-workflow.yaml`. Allows running alternative pipelines (e.g., writing-only, review-only). Falls back to the plugin default at `skills/docs-orchestrator/defaults/docs-workflow.yaml` if no project-level YAML exists
-- `--pr <url>` — PR/MR URLs (repeatable, accumulated into a list). Accepts GitHub PRs (`gh` CLI) and GitLab MRs (`glab` CLI). Used both as requirements input (agent reads diffs/descriptions) and for source repo resolution (repo URL and branch derived from the first PR/MR). When multiple PRs from different repos are provided, all repos are resolved and treated equally as source material
+- `--pr <url>...` — PR/MR URLs (space-delimited, one or more). Accepts GitHub PRs (`gh` CLI) and GitLab MRs (`glab` CLI). Used both as requirements input (agent reads diffs/descriptions) and for source repo resolution (repo URL and branch derived from the first PR/MR). When multiple PRs from different repos are provided, all repos are resolved and treated equally as source material
 - `--mkdocs` — Use Material for MkDocs format instead of AsciiDoc. Propagates to the writing step (generates `.md` with MkDocs front matter) and style-review step (applies Markdown-appropriate rules). Sets `options.format` to `"mkdocs"` in the progress file
 - `--draft` — Write documentation to the staging area (`.claude/docs/<ticket>/writing/`) instead of directly into the repo. Uses DRAFT placement mode: no framework detection, no file placement into the target repo. Without this flag, UPDATE-IN-PLACE is the default
 - `--docs-repo-path <path>` — Target documentation repository for UPDATE-IN-PLACE mode. The docs-writer explores this directory for framework detection (Antora, MkDocs, Docusaurus, etc.) and writes files there instead of the current working directory. Propagates to `writing` and `create-merge-request` steps (mapped to their internal `--repo-path` flag). **Precedence**: if both `--docs-repo-path` and `--draft` are passed, `--docs-repo-path` wins — log a warning and ignore `--draft`
-- `--source-code-repo <url-or-path>` — Source code repository for code evidence and requirements enrichment. Accepts remote URLs (https://, git@, ssh:// — shallow-cloned to `.claude/docs/<ticket>/code-repo/`) or local paths (used directly). Passed to requirements, code-evidence, and writing steps (mapped to their internal `--repo` flag). Without `--pr`, the entire repo is the subject matter; with `--pr`, the PR branch is checked out so code-evidence reflects the PR's state. Takes highest priority in source resolution, overriding `source.yaml` and PR-derived URLs
+- `--source-code-repo <url-or-path>...` — Source code repository/repositories for code evidence and requirements enrichment (space-delimited, one or more). Accepts remote URLs (https://, git@, ssh:// — each shallow-cloned to `.claude/docs/<ticket>/code-repo/<repo_name>/`) or local paths (used directly). The first repo is treated as primary; additional repos are returned as `additional_repos` in the result. Passed to requirements, code-evidence, and writing steps (mapped to their internal `--repo` flag). Without `--pr`, the entire repo is the subject matter; with `--pr`, the PR branch is checked out on the primary repo so code-evidence reflects the PR's state. Takes highest priority in source resolution, overriding `source.yaml` and PR-derived URLs
 - `--create-jira <PROJECT>` — Create a linked JIRA ticket in the specified project after the planning step completes. Runs the standalone `docs-workflow-create-jira` workflow (use `--workflow workflow-create-jira`). Requires `JIRA_API_TOKEN` to be set
 - `--create-merge-request` — Create a branch, commit, push, and open a merge request or pull request after reviews complete. Activates the `create-merge-request` workflow step (guarded by `when: create_merge_request`). Off by default
 
@@ -50,8 +50,7 @@ When displaying available options to the user (e.g., on skill load or when askin
 
 # Multiple PRs from different repos, written to a separate docs repo
 /docs-orchestrator PROJ-123 \
-  --pr https://github.com/org/backend/pull/10 \
-  --pr https://gitlab.example.com/org/frontend/-/merge_requests/5 \
+  --pr https://github.com/org/backend/pull/10 https://gitlab.example.com/org/frontend/-/merge_requests/5 \
   --docs-repo-path /home/user/docs-repo
 
 # Source repo without PRs, draft mode, with merge request creation
@@ -87,8 +86,8 @@ Run the script with whatever source information is available from CLI args:
 ```bash
 python3 ${CLAUDE_SKILL_DIR}/scripts/resolve_source.py \
   --base-path <base_path> \
-  [--repo <url-or-path>] \
-  [--pr <url>]...
+  [--repo <url-or-path>...] \
+  [--pr <url>...]
 ```
 
 The script checks sources in priority order:
@@ -103,7 +102,7 @@ The script outputs JSON to stdout:
 ```json
 {
   "status": "resolved",
-  "repo_path": ".claude/docs/proj-123/code-repo",
+  "repo_path": ".claude/docs/proj-123/code-repo/operator",
   "repo_url": "https://github.com/org/operator",
   "ref": "pr-branch-name",
   "scope": null
@@ -225,8 +224,8 @@ Use this absolute `BASE_PATH` for the progress file's `base_path` field and for
 ```
 .claude/docs/proj-123/
   source.yaml                        (per-ticket source config, if applicable)
-  code-repo/                         (single repo: flat clone; multi-repo: subdirs)
-    <repo-name>/                     (only when multiple repos are resolved)
+  code-repo/
+    <repo-name>/                     (each repo gets its own subdirectory)
   requirements/
     requirements.md
     step-result.json                 (sidecar: title)

plugins/docs-tools/skills/docs-orchestrator/scripts/resolve_source.py

@@ -165,6 +165,11 @@ def _normalize_git_url(url):
     return url.rstrip("/").removesuffix(".git")
 
 
+def _repo_name_from_url(url):
+    """Extract the repository name from a git URL."""
+    return _normalize_git_url(url).split("/")[-1]
+
+
 def _resolve_pr_info(pr_url):
     """Extract repo URL and branch from a GitHub PR or GitLab MR URL.
 
@@ -390,7 +395,7 @@ def _write_source_yaml(base_path, repo, ref):
 def _resolve_multiple_prs(pr_urls, base_path):
     """Resolve and clone repos from a list of PR/MR URLs.
 
-    Groups PRs by repo, clones each repo into code-repo/<repo_name>/,
+    Groups PRs by repo, clones each into code-repo/<repo_name>/,
     and returns a success result with primary + additional repos.
     """
     # Group PRs by normalized repo URL
@@ -413,17 +418,12 @@ def _resolve_multiple_prs(pr_urls, base_path):
 
     resolved_repos = []
     errors = []
-    use_subdirs = len(repo_groups) > 1
-
     for normalized, info in repo_groups.items():
         repo_url = info["repo_url"]
         ref = info["ref"]
 
-        if use_subdirs:
-            repo_name = normalized.split("/")[-1]
-            repo_clone_dir = base_path / "code-repo" / repo_name
-        else:
-            repo_clone_dir = base_path / "code-repo"
+        repo_name = _repo_name_from_url(repo_url)
+        repo_clone_dir = base_path / "code-repo" / repo_name
 
         if repo_clone_dir.exists():
             if not _verify_existing_clone(repo_clone_dir, ref, expected_repo_url=repo_url):
@@ -482,23 +482,24 @@ def _success(repo_path, repo_url=None, ref=None, scope=None, discovered_repos=No
     return result
 
 
-def resolve(args):
-    """Main resolution logic. Returns a result dict."""
-    base_path = Path(args.base_path)
-    clone_dir = base_path / "code-repo"
+def _resolve_explicit_repos(repo_values, pr_urls, base_path):
+    """Resolve one or more explicit --repo values.
 
-    # Collect PR URLs from args
-    pr_urls = args.pr or []
+    Clones each remote repo into code-repo/<repo_name>/.
+    For a single repo with PRs, the first PR's branch is checked out.
+    Returns primary + additional repos when multiple are given.
+    """
+    resolved_repos = []
+    errors = []
 
-    # --- Priority 1: Explicit --repo flag ---
-    if args.repo:
-        repo_value = args.repo
+    for i, repo_value in enumerate(repo_values):
         ref = None
-        scope = None
 
         if _is_remote_url(repo_value):
-            # If PRs provided, get the branch from the first PR
-            if pr_urls:
+            clone_dir = base_path / "code-repo" / _repo_name_from_url(repo_value)
+
+            # First repo gets the PR branch (if any)
+            if i == 0 and pr_urls:
                 try:
                     _, pr_branch = _resolve_pr_info(pr_urls[0])
                     ref = pr_branch
@@ -508,37 +509,68 @@ def resolve(args):
                         file=sys.stderr,
                     )
 
-            # Clone or verify
             if clone_dir.exists():
                 if not _verify_existing_clone(clone_dir, ref, expected_repo_url=repo_value):
-                    return {
-                        "status": "error",
-                        "message": (
-                            f"Existing clone at {clone_dir} is invalid "
-                            "or points to a different repo."
-                        ),
-                    }
+                    errors.append(
+                        f"Existing clone at {clone_dir} is invalid "
+                        "or points to a different repo."
+                    )
+                    continue
             else:
                 if not _clone_repo(repo_value, clone_dir, ref):
-                    return {
-                        "status": "error",
-                        "message": (
-                            f"Cannot clone {repo_value}. "
-                            "For private repos, ensure gh is authenticated."
-                        ),
-                    }
+                    errors.append(
+                        f"Cannot clone {repo_value}. "
+                        "For private repos, ensure gh is authenticated."
+                    )
+                    continue
 
-            _write_source_yaml(base_path, repo_value, ref)
-            return _success(clone_dir, repo_url=repo_value, ref=ref, scope=scope)
+            resolved_repos.append({
+                "repo_path": str(clone_dir),
+                "repo_url": repo_value,
+                "ref": ref,
+            })
         else:
-            # Local path
             local = Path(repo_value)
             if not local.exists() or not local.is_dir():
-                return {
-                    "status": "error",
-                    "message": f"Source repo path does not exist: {repo_value}",
-                }
-            return _success(local, ref=ref, scope=scope)
+                errors.append(f"Source repo path does not exist: {repo_value}")
+                continue
+            resolved_repos.append({
+                "repo_path": str(local),
+                "repo_url": None,
+                "ref": None,
+            })
+
+    if not resolved_repos:
+        return {
+            "status": "error",
+            "message": f"Could not resolve any repos. Errors: {'; '.join(errors)}",
+        }
+
+    primary = resolved_repos[0]
+    _write_source_yaml(base_path, primary.get("repo_url") or primary["repo_path"], primary["ref"])
+
+    result = _success(
+        primary["repo_path"],
+        repo_url=primary.get("repo_url"),
+        ref=primary["ref"],
+    )
+    if len(resolved_repos) > 1:
+        result["additional_repos"] = resolved_repos[1:]
+    if errors:
+        result["warnings"] = errors
+    return result
+
+
+def resolve(args):
+    """Main resolution logic. Returns a result dict."""
+    base_path = Path(args.base_path)
+
+    # Collect PR URLs from args
+    pr_urls = args.pr or []
+
+    # --- Priority 1: Explicit --repo flag ---
+    if args.repo:
+        return _resolve_explicit_repos(args.repo, pr_urls, base_path)
 
     # --- Priority 2: source.yaml ---
     source_config = _read_source_yaml(base_path)
@@ -556,6 +588,7 @@ def resolve(args):
                 pass
 
         if _is_remote_url(repo_value):
+            clone_dir = base_path / "code-repo" / _repo_name_from_url(repo_value)
             if clone_dir.exists():
                 if not _verify_existing_clone(clone_dir, ref, expected_repo_url=repo_value):
                     return {
@@ -611,12 +644,13 @@ def main():
     )
     parser.add_argument(
         "--repo",
-        help="Source repo URL or local path",
+        nargs="+",
+        help="Source repo URL(s) or local path(s), space-delimited",
     )
     parser.add_argument(
         "--pr",
-        action="append",
-        help="PR/MR URL (repeatable)",
+        nargs="+",
+        help="PR/MR URL(s), space-delimited",
     )
     parser.add_argument(
         "--scan-requirements",

plugins/docs-tools/skills/docs-workflow-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-workflow-planning
-description: Create a documentation plan from requirements analysis output. Dispatches the docs-planner agent. Invoked by the orchestrator.
+description: Create a documentation plan from requirements analysis output. Dispatches the docs-tools:docs-planner agent. Invoked by the orchestrator.
 argument-hint: <ticket> --base-path <path>
 allowed-tools: Read, Write, Glob, Grep, Edit, Bash, Skill, Agent
 ---
@@ -43,7 +43,7 @@ mkdir -p "$OUTPUT_DIR"
 
 ### 2. Dispatch agent
 
-**You MUST use the Agent tool** to invoke the `docs-planner` subagent. Do NOT read the agent's markdown file or attempt to perform the agent's work yourself — the agent has a specialized system prompt and must run as an isolated subagent.
+**You MUST use the Agent tool** to invoke the `docs-tools:docs-planner` subagent. Do NOT read the agent's markdown file or attempt to perform the agent's work yourself — the agent has a specialized system prompt and must run as an isolated subagent.
 
 **Agent tool parameters:**
 - `subagent_type`: `docs-tools:docs-planner`

plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md

@@ -11,8 +11,8 @@ Step skill for the docs-orchestrator pipeline. Follows the step skill contract:
 
 This skill uses a two-pass architecture to analyze documentation requirements:
 
-1. **Discovery pass** — A single `requirements-discoverer` agent enumerates requirements from JIRA, PRs, and specs, producing a JSON skeleton
-2. **Deep analysis pass** — One `requirements-analyst` agent per requirement, all running in parallel, each performing thorough analysis with a clean context window
+1. **Discovery pass** — A single `docs-tools:requirements-discoverer` agent enumerates requirements from JIRA, PRs, and specs, producing a JSON skeleton
+2. **Deep analysis pass** — One `docs-tools:requirements-analyst` agent per requirement, all running in parallel, each performing thorough analysis with a clean context window
 3. **Merge** — The orchestrator assembles per-requirement JSON results into the standard `requirements.md` format
 
 ## Arguments
@@ -45,7 +45,7 @@ mkdir -p "$OUTPUT_DIR"
 
 ### 2. Pass 1 — Discovery
 
-Dispatch one `requirements-discoverer` agent to enumerate requirements from all sources.
+Dispatch one `docs-tools:requirements-discoverer` agent to enumerate requirements from all sources.
 
 ```
 Agent:
@@ -83,7 +83,7 @@ If `requirements` is empty, write a minimal `requirements.md` noting that no req
 
 ### 4. Pass 2 — Fan out deep analysis
 
-For each requirement in the discovery skeleton, dispatch one `requirements-analyst` agent. Launch ALL agents in a **single message** (parallel execution).
+For each requirement in the discovery skeleton, dispatch one `docs-tools:requirements-analyst` agent. Launch ALL agents in a **single message** (parallel execution).
 
 For each requirement, use: