Docs Orchestrator

Docs Orchestrator

When the user invokes /docs-orchestrator or /docs-tools:docs-orchestrator, run THIS skill directly. Do NOT redirect to docs-workflow-start or any other skill.

Claude is the orchestrator. The YAML is a step list. The hook is a safety net.

This skill teaches you how to run a documentation workflow pipeline. You read the step list from YAML, run each step skill sequentially, manage progress state via a JSON file, and handle iteration loops and confirmation gates.

Pre-flight

Install the workflow completion Stop hook (safe to re-run, skips if already installed):

bash ${CLAUDE_SKILL_DIR}/scripts/setup-hooks.sh

Do not source .env files or check for tokens/CLIs here — Python scripts (jira_reader.py, resolve_source.py, etc.) load .env files and validate prerequisites themselves, producing clear errors on failure.

Parse arguments

When displaying available options to the user (e.g., on skill load or when asking for flags), reproduce the descriptions below verbatim — do not summarize or paraphrase them.

• $1 — JIRA ticket ID (required). If missing, STOP and ask the user.
• --workflow — Use .agent_workspace/docs-.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 ... — 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 (.agent_workspace//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 — 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 ... — 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 .agent_workspace//code-repo//) 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, writing, and technical-review 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 — 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

Examples

# Minimal — just a ticket
/docs-orchestrator PROJ-123

# PR-driven with MkDocs output
/docs-orchestrator PROJ-123 --pr https://github.com/org/repo/pull/42 --mkdocs

# Multiple PRs from different repos, written to a separate docs repo
/docs-orchestrator PROJ-123 \
  --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
/docs-orchestrator PROJ-123 \
  --source-code-repo https://github.com/org/operator \
  --draft \
  --create-merge-request

# Local source repo + PR (checks out PR branch within repo)
/docs-orchestrator PROJ-123 \
  --source-code-repo /home/user/local-checkout \
  --pr https://github.com/org/repo/pull/99

# Custom workflow YAML
/docs-orchestrator PROJ-123 --workflow quick

# Code-evidence workflow — auto-discovers repo from JIRA, or pass explicitly
/docs-orchestrator PROJ-123 --workflow code-evidence

# Code-evidence workflow — explicit repo (overrides auto-discovery)
/docs-orchestrator PROJ-123 \
  --workflow code-evidence \
  --source-code-repo https://github.com/org/operator

Resolve source repository

After parsing arguments and before running steps, resolve the source code repository if one is configured. This makes the repo available to all downstream steps that need it (requirements, code-evidence, writing).

All clone, verify, PR-resolution, and source.yaml logic is handled by the resolve_source.py script. The orchestrator calls the script and acts on the JSON result.

Pre-flight resolution

Run the script with whatever source information is available from CLI args. Always pass --ticket and --plugin-root so the script can attempt JIRA-based discovery if explicit sources are absent:

python3 ${CLAUDE_SKILL_DIR}/scripts/resolve_source.py \
  --base-path  \
  --ticket  \
  --plugin-root ${CLAUDE_PLUGIN_ROOT} \
  [--repo ...] \
  [--pr ...]

The script checks sources in priority order:

1. CLI --source-code-repo flag — clone or verify the path
2. Per-ticket source.yaml — read and apply existing config
3. PR-derived — resolve repo URL and branch from --pr via gh pr view or glab mr view
4. JIRA ticket discovery — query the ticket's git_links and auto-discovered PR URLs, extract repo URLs, and select the primary repo by reference count. If multiple repos tie, return an error listing candidates
5. No source — exit code 2, defer resolution until after requirements

The script outputs JSON to stdout:

{
  "status": "resolved",
  "repo_path": ".agent_workspace/proj-123/code-repo/operator",
  "repo_url": "https://github.com/org/operator",
  "ref": "pr-branch-name",
  "scope": null
}

Handle the result

| Exit code | status | Action | |---|---|---| | 0 | resolved | Set has_source_repo = true. Record options.source in the progress file from the JSON fields (repo_path, repo_url, ref, scope) | | 1 | error | STOP with the error message from the JSON | | 2 | no_source | Mark steps with when: has_source_repo as deferred. Source resolution will be retried after requirements (see [Post-requirements source resolution](#post-requirements-source-resolution)) |

If discovered_repos is present in the result (multiple repos found), log all resolved repos. If additional_repos is present, record them in the progress file alongside the primary source. If warnings is present, log each warning.

Per-ticket source config schema

Writers can create /source.yaml before starting a workflow to pre-configure the source repo and scope. The script also writes this file after a successful clone so that resume picks it up automatically.

# .agent_workspace//source.yaml
repo: https://github.com/org/operator   # URL or local path (required)
ref: main                                # branch, tag, or commit (default: HEAD)
scope:
  include:                               # glob patterns — what to index and search
    - "src/controllers/**"
    - "pkg/api/v1/**"
    - "README.md"
  exclude:                               # glob patterns — what to skip
    - "**/vendor/**"
    - "**/testdata/**"
    - "**/*_test.go"

All fields except repo are optional. If scope is omitted, the entire repository is in scope.

Load the step list

1. Determine the YAML file

• If --workflow was specified → .agent_workspace/docs-.yaml
• Otherwise → .agent_workspace/docs-workflow.yaml
• If the project-level file doesn't exist → fall back to the plugin default at skills/docs-orchestrator/defaults/docs-workflow.yaml

2. Read the YAML

Read the YAML file and extract the ordered step list. Each step has: name, skill, description, optional when, and optional inputs.

3. Validate requires conditions

If the YAML includes a top-level workflow.requires list, check each condition before evaluating steps or running anything:

• has_source_repo → a source repo must be resolvable. The pre-flight resolution script tries all sources in priority order: CLI --source-code-repo, source.yaml, --pr-derived, and JIRA ticket discovery (git links and auto-discovered PRs). If none yield a source repo, STOP immediately with: "This workflow requires a source code repository. No repo could be discovered from the JIRA ticket. Options: (1) re-run with --source-code-repo , (2) re-run with --pr , (3) create .agent_workspace//source.yaml with a repo: field, or (4) link PRs to the JIRA ticket and re-run."

Unlike when (which makes individual steps conditional), requires is a workflow-level precondition — the entire workflow fails if a required condition is not met. This prevents users from running a code-evidence workflow without a repo and only discovering the problem after requirements and planning have already completed.

The has_source_repo precondition supports two modes:

• Explicit: User passes --source-code-repo → guaranteed grounding against the specified repo
• Auto-discovered: User passes only a JIRA ticket → pre-flight discovers the repo from JIRA git links and linked PRs

4. Evaluate when conditions

• when: create_merge_request → run this step only if --create-merge-request was passed
• when: has_source_repo → evaluation depends on timing:
• If a source repo was already resolved pre-flight (via --source-code-repo, --pr, or source.yaml) → step runs normally (pending)
• If no source is resolved yet but post-requirements discovery is possible (case 4 above) → mark the step deferred (not skipped). The orchestrator re-evaluates after requirements completes
• After post-requirements resolution: deferred steps become pending (source found) or skipped (no source found)
• Steps with no when always run
• Steps that don't meet their when condition and cannot be deferred are marked skipped in the progress file

5. Validate the step list

All of the following must be true. If any check fails, STOP with a clear error:

• All step names are unique
• All skill references resolve to a known skill (bare names like docs-workflow-writing are preferred; fully qualified plugin:skill format is also accepted)
• Input dependencies are satisfied — for each step with inputs, every referenced step name must be present in the step list (unless it has a when condition that would skip it)

Input dependencies

Steps declare their inputs as a list of upstream step names in the YAML:

- name: writing
  skill: docs-workflow-writing
  inputs: [planning]

- name: create-merge-request
  skill: docs-tools:docs-workflow-create-merge-request
  when: create_merge_request
  inputs: [writing, style-review, technical-review]

The orchestrator validates at load time that every step name in inputs exists in the step list. Step skills read their input data from the upstream step's output folder by convention (see below).

Conditional input dependencies: If an upstream step in inputs has a when condition and was skipped, that dependency is considered satisfied. The downstream step is responsible for checking whether the optional input data actually exists (e.g., the writing step checks for evidence.json and uses it if present, but proceeds without it). Only upstream steps that ran and failed block downstream execution.

Custom workflow validation: If a step's inputs references a step that does not exist in the current YAML step list, fail at load time with an error (e.g., "Step 'writing' requires 'planning', but 'planning' is not in the step list").

Output conventions

Every step writes to a predictable folder based on the ticket ID and step name:

.agent_workspace///

The ticket ID is converted to lowercase for directory names (e.g., PROJ-123 → proj-123).

Resolve base path

Resolve the base path to an absolute path so agents (which may run in a different working directory) can locate files correctly:

BASE_PATH="$(cd "$(git rev-parse --show-toplevel)" && pwd)/.agent_workspace/${TICKET_LOWER}"

Use this absolute BASE_PATH for the progress file's base_path field and for all --base-path arguments passed to step skills.

Folder structure

.agent_workspace/proj-123/
  source.yaml                        (per-ticket source config, if applicable)
  code-repo/
    /                     (each repo gets its own subdirectory)
  requirements/
    requirements.md
    step-result.json                 (sidecar: title)
  scope-req-audit/                     (if source repo is available)
    evidence-status.json
    summary.md
    step-result.json                 (sidecar: recommendation, grounded, partial, absent, total, discovered_repos_count)
  planning/
    plan.md
    step-result.json                 (sidecar: module_count)
  code-evidence/                     (if source repo is available)
    evidence.json
    summary.md
    step-result.json                 (sidecar: topic_count, snippet_count, repo_path)
  writing/
    _index.md
    step-result.json                 (sidecar: files, mode, format)
    assembly_*.adoc (or docs/*.md for mkdocs)
    modules/
  technical-review/
    review.md
    step-result.json                 (sidecar: confidence, severity_counts)
  style-review/
    review.md
    step-result.json                 (sidecar: common fields only)
  create-merge-request/
    step-result.json                 (sidecar: commit_sha, branch, pushed, url, action, platform, skipped)
  workflow/
    docs-workflow_proj-123.json

Each step skill knows its own output folder and writes there. Each step reads input from upstream step folders referenced in its inputs list. The orchestrator passes the base path .agent_workspace// — step skills derive everything else by convention.

Step result sidecars

Every step that produces markdown output also writes a step-result.json sidecar with structured metadata. See [schema/step-result-schema.md](schema/step-result-schema.md) for the full schema. Downstream scripts and the orchestrator prefer sidecar data when present, falling back to parsing the markdown output for backward compatibility.

Progress file

Claude writes the progress file directly using the Write tool. Create it after parsing arguments, before step 1. Update it after each step. Also write the active workflow marker at the same time (see [Active workflow marker](#active-workflow-marker)).

Location: .agent_workspace//workflow/_.json

The workflow_type field and filename prefix match the YAML's workflow.name. This allows multiple workflow types to run against the same ticket without conflict.

Schema

{
  "workflow_type": "",
  "ticket": "",
  "base_path": "/absolute/path/to/.agent_workspace/",
  "status": "in_progress",
  "created_at": "",
  "updated_at": "",
  "options": {
    "format":

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [abhatt-rh](https://github.com/abhatt-rh)
- **Source:** [abhatt-rh/redhat-docs-agent-tools](https://github.com/abhatt-rh/redhat-docs-agent-tools)
- **License:** Apache-2.0
- **Homepage:** https://redhat-documentation.github.io/redhat-docs-agent-tools/

Install and usage instructions live in the source repository linked above.