Docs Workflow Start

Docs Workflow Start

Interactive entry point for the documentation workflow.

Parse arguments

Same argument set as docs-orchestrator:

• $1 — JIRA ticket ID (optional at this stage)
• --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, 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-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

Determine mode

Pass-through mode: If ANY -- switches are present in the args string, invoke docs-orchestrator directly with all original arguments. Do NOT use AskUserQuestion.

Skill: docs-orchestrator, args: ""

Interactive mode: If no -- switches are present (bare invocation or just a ticket ID), go to the Interactive mode — required steps section below.

Interactive mode — required steps

STOP. You MUST follow steps 1–5 below IN ORDER. Do not skip any step. Do not invoke the orchestrator or any step skill until you reach step 5. Do not assume defaults — ask every question.

Step 1: Get ticket ID

If no ticket ID was provided in args, ask the user conversationally:

> What is the JIRA ticket ID? (e.g., PROJ-123)

The ticket ID is required. After obtaining it, proceed to step 2.

Step 2: Action selection — call AskUserQuestion

You MUST call the AskUserQuestion tool now with 1 question. Do not skip this.

What would you like to do?

| Option | Description | |--------|-------------| | Run full workflow (Recommended) | Run the complete docs pipeline from requirements through to MR creation | | Run specific step(s) | Run one or more individual workflow steps with prerequisites included automatically | | Resume existing workflow | Continue a previously started workflow for this ticket |

Wait for the user's answer before proceeding.

• If "Resume existing workflow": skip steps 3–4 and go directly to step 5 (resume path).
• If "Run full workflow": proceed to step 3A.
• If "Run specific step(s)": proceed to step 3B.

Step 3A: Full workflow configuration — call AskUserQuestion

You MUST call the AskUserQuestion tool now with ALL 4 questions at once. Do not skip this.

Q1: What output format should the documentation use?

| Option | Description | |--------|-------------| | AsciiDoc (Recommended) | Standard Red Hat documentation format | | Material for MkDocs | Markdown-based documentation format |

Q2: Do you have source code related to this ticket?

| Option | Description | |--------|-------------| | Yes — I have a PR URL | A pull request or merge request URL | | Yes — I have a repo URL or path | A repository URL or local directory path | | No source code | Proceed without code-evidence retrieval |

Q3: Where should the documentation be written?

| Option | Description | |--------|-------------| | Current repo — update in place (Recommended) | Detect framework and write directly to the current repository | | A different repo | Write to a specified repository path | | Draft — staging area only | Write to staging area without modifying any repository |

Q4: Create a linked JIRA ticket in another project?

| Option | Description | |--------|-------------| | No (Recommended) | Skip JIRA ticket creation | | Yes | Create a linked ticket in another JIRA project |

Wait for all answers before proceeding to step 4.

Step 3B: Specific steps selection — call AskUserQuestion

You MUST call the AskUserQuestion tool now with 1 question. Set multiSelect: true on this question so the user can select multiple steps. Do not skip this.

Which step(s) do you want to run? (multiSelect: true)

| Option | Description | |--------|-------------| | requirements | Analyze JIRA ticket and extract documentation requirements | | code-evidence | Retrieve code evidence from source repository | | writing | Write documentation from an existing plan | | technical-review | Review existing documentation for technical accuracy |

For steps not listed (planning, style-review, create-merge-request), the user can type the step name via the "Other" option.

Invalid step names: If the user enters a step name via "Other" that is not recognized, the dependency resolver will report the error with a list of valid step names. Surface this error to the user and ask them to correct their selection.

After receiving the answer, determine which configuration questions are relevant:

• Format? — include if any of these steps are selected: writing, style-review
• Source code? — include if code-evidence is selected
• Placement? — include if any of these steps are selected: writing, create-merge-request
• Create MR/PR? — include if create-merge-request is selected

If any questions are relevant, call AskUserQuestion with those questions (same text and options as step 3A). If no questions are relevant, proceed to step 4.

Step 4: Free-text follow-ups

Based on answers from step 3, collect any needed free-text inputs. Use AskUserQuestion with textInput: true for each value, so the user has a clear input prompt. Only ask questions that apply:

If "Yes — I have a PR URL" was selected:

Ask via AskUserQuestion (textInput): "Enter the first PR/MR URL:"

Then ask: "Enter another PR/MR URL, or select Done:"

| Option | Description | |--------|-------------| | Done | No more PR URLs |

Repeat until the user selects Done. Each URL becomes a --pr flag.

If "Yes — I have a repo URL or path" was selected:

Ask via AskUserQuestion (textInput): "Enter the source repo URL or local path:"

Then ask via AskUserQuestion:

Do you also have PR URL(s) for this repo?

| Option | Description | |--------|-------------| | No (Recommended) | Proceed without PR URLs | | Yes | Enter PR URL(s) |

--source-code-repo and --pr can coexist — the PR branch gets checked out within the repo. If the user selects Yes, collect PR URLs using the same loop as above.

If "A different repo" was selected for placement:

Ask via AskUserQuestion (textInput): "Enter the target docs repository path:"

Maps to --docs-repo-path .

If "Yes" was selected for Create JIRA:

Ask via AskUserQuestion (textInput): "Enter the target JIRA project key (e.g., DOCS):"

Maps to --create-jira .

If no follow-ups are needed, proceed directly to step 5.

Step 5: Build CLI flags and execute

Build the args string from collected answers:

| Answer | CLI flag | |--------|----------| | Material for MkDocs | --mkdocs | | PR URL(s) | --pr (repeat for each URL) | | Repo URL or path | --source-code-repo | | Draft — staging area only | --draft | | Target docs repo path | --docs-repo-path | | Create JIRA = Yes | --create-jira | | --workflow was provided in args | --workflow (pass through) |

AsciiDoc format and current repo placement are defaults — no flags needed.

Precedence: If both --docs-repo-path and --draft would be set, --docs-repo-path wins — log a warning and omit --draft (matches orchestrator behavior).

NOW invoke the orchestrator (or run specific steps — see below).

Full workflow execution

Invoke the orchestrator with the ticket ID and all constructed flags:

Skill: docs-orchestrator, args: " "

Example:

Skill: docs-orchestrator, args: "PROJ-123 --mkdocs --pr https://github.com/org/repo/pull/42 --draft"

Resume execution

For the resume path (user selected "Resume existing workflow" in step 2):

Skill: docs-orchestrator, args: ""

The orchestrator detects the existing progress file and resumes automatically.

Specific steps execution

When running individual steps, dependencies are resolved automatically and each step skill is invoked directly.

1. Resolve base path

TICKET_LOWER=$(echo "" | tr '[:upper:]' '[:lower:]')
BASE_PATH="$(cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && pwd)/.agent_workspace/${TICKET_LOWER}"
mkdir -p "$BASE_PATH"

2. Resolve the YAML path

Determine which workflow YAML to use. If --workflow was provided (from the parsed args), use the named variant; otherwise use the default:

if [[ -n "$WORKFLOW_NAME" && -f ".agent_workspace/docs-${WORKFLOW_NAME}.yaml" ]]; then
  YAML_PATH=".agent_workspace/docs-${WORKFLOW_NAME}.yaml"
elif [[ -f ".agent_workspace/docs-workflow.yaml" ]]; then
  YAML_PATH=".agent_workspace/docs-workflow.yaml"
else
  YAML_PATH="${CLAUDE_PLUGIN_ROOT}/skills/docs-orchestrator/defaults/docs-workflow.yaml"
fi

3. Compute execution plan

Run the dependency resolver:

python3 ${CLAUDE_SKILL_DIR}/scripts/resolve_steps.py \
  --yaml "$YAML_PATH" \
  --steps  \
  --base-path "$BASE_PATH"

If the script exits with code 1, the user entered an invalid step name. Read the error field and valid_steps list from the JSON output and tell the user:

> Step name "\" is not recognized. Valid steps are: \. Please try again.

Then re-ask the step selection question via AskUserQuestion.

4. Validate requires conditions

Check the requires field in the resolver's JSON output. If the workflow declares requires: [has_source_repo] and no source repo or PR URL was collected in step 3B/4, STOP immediately with:

> This workflow requires a source code repository. Pass --source-code-repo or --pr , or select a source code option when prompted.

This catches the problem before any steps run — the same early guard the orchestrator applies for full workflow mode.

5. Handle existing artifacts (smart hybrid confirmation)

Read the JSON output. If steps_with_artifacts is non-empty, use AskUserQuestion:

Some prerequisite steps already have output from a previous run. Re-use existing artifacts or re-run?

| Option | Description | |--------|-------------| | Re-use existing artifacts (Recommended) | Skip completed prerequisites and only run what's missing | | Re-run all steps | Discard existing output and re-run everything from scratch |

If steps_with_artifacts is empty, skip this question and run all steps.

6. Evaluate when conditions

For each step in the execution plan with a when field:

• when: has_source_repo — skip this step if no source repo or PR URL was provided. Log: "Skipping \: no source repository configured."
• when: create_merge_request — skip this step if create-merge-request was not selected. Log: "Skipping \: merge request creation not requested."

7. Run steps sequentially

For each step in execution_plan order:

1. If has_artifacts: true AND user chose "Re-use existing artifacts" → skip with message: "Skipping \: using existing artifacts at \/\/"
2. If when condition is not met → skip with message (see above)
3. Otherwise, construct the args and invoke:

Skill: , args: " --base-path  "

Step-specific flags — each step gets --base-path plus:

| Step | Additional flags from collected config | |------|---------------------------------------| | requirements | [--pr ]... [--repo ] | | planning | (none) | | code-evidence | --repo [--scope-include ] [--scope-exclude ] | | writing | --format [--draft] [--repo ] [--repo-path ] | | style-review | --format | | technical-review | (none) | | create-merge-request | [--draft] [--repo-path ] |

The format flag defaults to adoc unless the user selected Material for MkDocs.

8. Verify and report

After each step completes:

1. Check the step's output directory exists at //
2. If missing, report the failure: "Step \ failed — expected output at \ not found." STOP — do not continue to subsequent steps.
3. If present, report success: "Step \ completed. Output: \"

After all steps complete, display a summary:

> Completed steps: > - requirements: .agentworkspace/proj-123/requirements/ > - planning: .agentworkspace/proj-123/planning/ > - writing: .agent_workspace/proj-123/writing/ > > Skipped steps: > - code-evidence: no source repository configured

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
• Source: 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.