Docs Workflow Start

Interactive entry point for the documentation workflow.

Parse arguments

Same argument set as docs-orchestrator. See argument reference for full descriptions.

• $1 — JIRA ticket ID (optional at this stage)
• --workflow <name> — Named workflow YAML
• --pr <url>... — PR/MR URLs
• --mkdocs — MkDocs format instead of AsciiDoc
• --draft — Write to staging area only
• --docs-repo-path <path> — Target docs repo for update-in-place
• --source-code-repo <url-or-path>... — Source code repos
• --create-merge-request — Open MR/PR after reviews
• --no-source-repo — Skip source repo resolution
• --auto-discover-repos — Skip secondary repo confirmation
• --max-secondary-repos <N> — Max secondary repos (default: 3)

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: "<all original 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?

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?

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

Q3: Where should the documentation be written?

Q4: Create a linked JIRA ticket in another 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)

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-analysis 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:"

Repeat until the user selects Done. Each URL becomes a --pr <url> 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?

--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 <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 <PROJECT>.

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:

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: "<ticket> <constructed flags>"

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: "<ticket>"

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 "<ticket>" | 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 <name> 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 <selected-step-names...> \
  --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 "<name>" is not recognized. Valid steps are: <valid_steps list>. 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 <url-or-path> or --pr <url>, 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?

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 <step>: no source repository configured."
• when: create_merge_request — skip this step if create-merge-request was not selected. Log: "Skipping <step>: 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 <step>: using existing artifacts at <base-path>/<step>/"
2. If when condition is not met → skip with message (see above)
3. Otherwise, construct the args and invoke:

Skill: <step.skill>, args: "<ticket> --base-path <BASE_PATH> <step-specific-flags>"

Step-specific flags — each step gets <ticket> --base-path <BASE_PATH> plus:

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 <BASE_PATH>/<step-name>/
2. If missing, report the failure: "Step <step> failed — expected output at <path> not found." STOP — do not continue to subsequent steps.
3. If present, report success: "Step <step> completed. Output: <path>"

After all steps complete, display a summary:

Completed steps:

• requirements: .agent_workspace/proj-123/requirements/
• planning: .agent_workspace/proj-123/planning/
• writing: .agent_workspace/proj-123/writing/

Skipped steps:

• code-analysis: no source repository configured