redhat-documentation · mcljot · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026
diff --git a/plugins/docs-tools/.claude-plugin/plugin.json b/plugins/docs-tools/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "docs-tools",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Documentation review, writing, and workflow tools for Red Hat AsciiDoc and Markdown documentation.",
   "author": {
     "name": "Red Hat Documentation Team",

diff --git a/plugins/docs-tools/agents/docs-planner.md b/plugins/docs-tools/agents/docs-planner.md
diff --git a/plugins/docs-tools/agents/docs-reviewer.md b/plugins/docs-tools/agents/docs-reviewer.md
@@ -39,14 +39,15 @@ Apply all review skills listed below. Process one file at a time, write findings
 
 ## When invoked
 
-1. **Extract the JIRA ID** from the task context or source folder:
-   - Look for patterns like `JIRA-123`, `RHAISTRAT-248`, `OSDOCS-456`
-   - Convert to lowercase for folder naming: `jira-123`, `rhaistrat-248`
-   - This ID determines the drafts folder location
+1. **Determine the source location** from the task prompt:
+   - If the prompt specifies a source path (e.g., `<base-path>/writing/` or a repo location), use that
+   - If no path is specified, fall back to `.claude/docs/drafts/<jira-id>/` (legacy convention)
+   - Within the source location, look for modules in a `modules/` subfolder and assemblies/pages at the root
 
-2. **Locate source drafts** from `.claude/docs/drafts/<jira-id>/`:
-   - Modules in: `.claude/docs/drafts/<jira-id>/modules/`
-   - Assemblies in: `.claude/docs/drafts/<jira-id>/`
+2. **Extract the workflow ID** for the report header:
+   - From the task prompt (e.g., "Review docs for PROJ-123" → `PROJ-123`)
+   - From the source folder name as a fallback
+   - This is used only for labeling the report, not for path construction
 
 3. **Determine the error level** to report (default: suggestion):
    - **suggestion**: Show all issues (suggestions + warnings + errors)
@@ -61,8 +62,8 @@ Apply all review skills listed below. Process one file at a time, write findings
    - Run Vale once. Fix obvious errors and warnings where the fix is clear. Skip ambiguous issues. Do NOT re-run Vale repeatedly.
    - Read and apply all applicable review skills from the table above (use `docs-tools:docs-review-modular-docs` for .adoc files). Record findings.
 
-6. **Edit files in place** in `.claude/docs/drafts/<jira-id>/`:
-   - Apply all fixes directly to the source files in the drafts folder
+6. **Edit files in place** at the source location:
+   - Apply all fixes directly to the source files
    - Do NOT create copies in a separate reviews folder
 
 7. **Write findings for this file to the report** before moving to the next file.
@@ -189,35 +190,30 @@ Severity levels align with Vale rule levels and Red Hat documentation requiremen
 
 ## Output location
 
-**All files are edited in place in `.claude/docs/drafts/<jira-id>/`. The review report is saved to the same drafts folder.**
+**All files are edited in place at the source location. The review report is saved to the output path specified in the task prompt.**
 
-```
-.claude/docs/drafts/<jira-id>/
-├── _review_report.md                 # Combined review report for all files
+When invoked by the orchestrator, the report path is provided explicitly (e.g., `<base-path>/style-review/review.md`). When invoked standalone or by the legacy command, save to `_review_report.md` in the source folder.
+
+```text
+<source-location>/
+├── _review_report.md                 # Combined review report (standalone/legacy)
 ├── assembly_<name>.adoc              # Reviewed assembly files (edited in place)
 └── modules/                          # Reviewed module files (edited in place)
     ├── <concept-name>.adoc
     ├── <procedure-name>.adoc
     └── <reference-name>.adoc
 ```
 
-### JIRA ID extraction
-
-Extract the JIRA ID from:
-1. The drafts folder path: `.claude/docs/drafts/rhaistrat-248/` -> `rhaistrat-248`
-2. The task context or user request: "Review docs for RHAISTRAT-248" -> `rhaistrat-248`
-3. Use lowercase with hyphens
-
 ### Review report
 
-Save the combined review report to: `.claude/docs/drafts/<jira-id>/_review_report.md`
+Save the combined review report to the path specified in the task prompt. If no output path is given, save to `<source-location>/_review_report.md`.
 
 Use this report format:
 
 ```markdown
 # Documentation Review Report
 
-**Source**: Ticket: <JIRA-ID>
+**Source**: <WORKFLOW-ID>
 **Date**: YYYY-MM-DD
 
 ## Summary

diff --git a/plugins/docs-tools/agents/docs-writer.md b/plugins/docs-tools/agents/docs-writer.md
@@ -1,6 +1,6 @@
 ---
 name: docs-writer
-description: Use PROACTIVELY when writing or drafting documentation. Creates complete CONCEPT, PROCEDURE, REFERENCE, and ASSEMBLY modules in AsciiDoc (default) or Material for MkDocs Markdown format. MUST BE USED for any documentation writing, drafting, or content creation task.
+description: Use PROACTIVELY when writing or drafting documentation. Creates complete CONCEPT, PROCEDURE, REFERENCE, and ASSEMBLY modules in AsciiDoc (default) or Material for MkDocs Markdown format. Supports multiple content paradigms (JTBD, user-stories) via runtime reference files. MUST BE USED for any documentation writing, drafting, or content creation task.
 tools: Read, Write, Glob, Grep, Edit, Bash, Skill
 skills: docs-tools:jira-reader, vale-tools:lint-with-vale, docs-tools:docs-review-modular-docs, docs-tools:docs-review-content-quality
 ---
@@ -101,27 +101,21 @@ When the prompt says **"Placement mode: DRAFT"**, write files to the `.claude/do
 
 Follow the output folder structures and workflows described in the "Draft mode output" section below.
 
-## Jobs to Be Done (JTBD) framework
+## Content paradigm
 
-Apply JTBD principles from the docs-planner agent. The key writing implications are:
+The task prompt specifies which content paradigm to use. Before writing, read the corresponding paradigm reference file and apply its conventions throughout your writing.
 
-### Titling strategy
+| Paradigm | Reference file |
+|----------|---------------|
+| `jtbd` (default) | Read `plugins/docs-tools/reference/paradigm-jtbd.md` — "For writers" section |
+| `user-stories` | Read `plugins/docs-tools/reference/paradigm-user-stories.md` — "For writers" section |
 
-Use outcome-driven titles with natural language:
+If the task prompt does not specify a paradigm, default to `jtbd`.
 
-| Type | Bad (Feature-focused) | Good (Outcome-focused) |
-|------|----------------------|------------------------|
-| CONCEPT | "Autoscaling architecture" | "How autoscaling responds to demand" |
-| PROCEDURE | "Configuring HPA settings" | "Scale applications automatically" |
-| REFERENCE | "HPA configuration parameters" | "Autoscaling configuration options" |
-| ASSEMBLY | "Horizontal Pod Autoscaler" | "Scale applications based on demand" |
-
-### Writing with JTBD
-
-- **Abstracts**: Describe what the user will achieve, not what the product does
-- **Procedures**: Frame steps around completing the user's job
-- **Concepts**: Explain how understanding this helps the user succeed
-- **References**: Present information users need to complete their job
+The paradigm reference determines:
+- Titling strategy (outcome-focused vs feature-descriptive)
+- How to frame abstracts, procedures, concepts, and references
+- Title and heading conventions
 
 ## When invoked
 
@@ -273,11 +267,11 @@ For format-specific syntax (AsciiDoc `[role="_abstract"]` vs MkDocs first paragr
 ### Titles and headings
 
 - **Length**: 3-11 words, sentence case, no end punctuation
-- **Outcome-focused**: Describe what users achieve, not product features
-- **Concept titles**: Noun phrase (e.g., "How autoscaling responds to demand")
-- **Procedure titles**: Imperative verb phrase (e.g., "Scale applications automatically")
-- **Reference titles**: Noun phrase (e.g., "Autoscaling configuration options")
-- **Assembly titles** (AsciiDoc only): Top-level user job (e.g., "Manage application scaling")
+- **Paradigm-specific style**: Follow the titling conventions from the paradigm reference file (outcome-focused for JTBD, feature-descriptive for user-stories)
+- **Concept titles**: Noun phrase
+- **Procedure titles**: Imperative verb phrase
+- **Reference titles**: Noun phrase for the data set
+- **Assembly titles** (AsciiDoc only): Top-level topic title following paradigm conventions
 - Industry-standard terms (SSL, API, RBAC) are acceptable; avoid product-specific vocabulary
 
 ### Prerequisites

diff --git a/plugins/docs-tools/agents/requirements-analyst.md b/plugins/docs-tools/agents/requirements-analyst.md
@@ -30,6 +30,37 @@ Proceeding with incorrect or assumed information leads to:
 
 **It is ALWAYS better to stop and wait for correct access than to produce incorrect documentation.**
 
+## Parse arguments
+
+- `$1` — Workflow ID. If it matches `[A-Z]+-[0-9]+` (case-insensitive), it is also auto-included as a JIRA ticket source.
+- `--base-path <path>` — Base output directory for all step outputs
+- `--pr <url>` — PR/MR URLs (repeatable)
+- `--jql <query>` — JQL query for bulk JIRA ticket fetch (uses `jira_reader.py --jql <query> --fetch-details`)
+- `--tickets <list>` — Comma-separated list of JIRA ticket IDs (fetches each via `jira_reader.py --issue`)
+- `--inputs <path-or-url>` — Additional input sources (repeatable). Each value is auto-detected by type:
+
+| Pattern | Type | Processing |
+|---|---|---|
+| `docs.google.com/document/...` | Google Doc | Convert via `gdoc2md.py` |
+| `docs.google.com/presentation/...` | Google Slides | Convert via `gdoc2md.py` |
+| `docs.google.com/spreadsheets/...` | Google Sheets | Convert via `gdoc2md.py` |
+| `https://...` or `http://...` (non-Google) | Web article | Extract via `article_extractor.py` |
+| Everything else | Local file path | Read via Read tool |
+
+### Processing --inputs values
+
+**Google Drive URLs:**
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/docs-convert-gdoc-md/scripts/gdoc2md.py "<url>"
+```
+
+**Web URLs (non-Google):**
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "<url>"
+```
+
+**Local files:** Read directly using the Read tool.
+
 ## When invoked
 
 1. Gather source materials:
@@ -428,12 +459,22 @@ python3 ${CLAUDE_PLUGIN_ROOT}/skills/redhat-docs-toc/scripts/toc_extractor.py --
 
 ### Extracting article content with article-extractor
 
-Download and extract content from Red Hat documentation pages:
+Download and extract content from web pages:
 
 ```bash
 python3 ${CLAUDE_PLUGIN_ROOT}/skills/article-extractor/scripts/article_extractor.py --url "https://docs.redhat.com/..."
 ```
 
+### Converting Google Drive documents with docs-convert-gdoc-md
+
+Convert Google Docs, Slides, and Sheets to Markdown/CSV:
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/skills/docs-convert-gdoc-md/scripts/gdoc2md.py "<google-drive-url>"
+```
+
+Supports Google Docs (→ Markdown), Slides (→ Markdown), and Sheets (→ CSV). Requires `gcloud auth login --enable-gdrive-access`.
+
 ## Key principles
 
 1. **User focus**: Prioritize requirements that affect user experience