[DO NOT MERGE - EXPERIMENT] Import markdown to AsciiDoc

.claude/skills/docs-workflow-import-markdown

@@ -0,0 +1 @@
+../../plugins/docs-tools/skills/docs-workflow-import-markdown

plugins/docs-tools/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "docs-tools",
-  "version": "0.0.55",
+  "version": "0.0.56",
   "description": "Documentation review, writing, and workflow tools for Red Hat AsciiDoc and Markdown documentation.",
   "author": {
     "name": "Red Hat Documentation Team",

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

@@ -34,8 +34,9 @@ When displaying available options to the user (e.g., on skill load or when askin
 - `--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
-- `--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-jira <PROJECT>` — Create a linked JIRA ticket in the specified project after the planning step completes. Activates the `create-jira` workflow step (guarded by `when: create_jira_project`). 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
+- `--markdown <path>` — Path to an edited markdown file for the `import` workflow. Passed through to the `import-markdown` step. Required when using `--workflow import`
 
 ### Examples
 
@@ -70,6 +71,12 @@ When displaying available options to the user (e.g., on skill load or when askin
 /docs-orchestrator PROJ-123 \
   --workflow workflow-code-evidence \
   --source-code-repo https://github.com/org/operator
+
+# Import edited markdown back into AsciiDoc modules
+/docs-orchestrator custom-models-3.4 \
+  --workflow import \
+  --markdown /path/to/edited-doc.md \
+  --docs-repo-path /home/user/docs-repo
 ```
 
 ## Resolve source repository
@@ -358,7 +365,8 @@ Build the args string for the step skill. The orchestrator maps its user-facing
    - `requirements`: `[--pr <url>]... [--repo <repo_path>]`
    - `scope-req-audit`: `--repo <repo_path> [--grounded-threshold <float>] [--absent-threshold <float>]`
    - `code-evidence`: `--repo <repo_path> [--scope-include <globs>] [--scope-exclude <globs>] [--reindex]` — scope globs come from `source.yaml` or `options.source.scope` in the progress file
-   - `writing`: `--format <adoc|mkdocs> [--draft] [--repo <repo_path>] [--repo-path <path>]`
+   - `import-markdown`: `--markdown <path> [--repo-path <path>]`
+   - `writing`: `--format <adoc|mkdocs> [--draft] [--repo <repo_path>] [--repo-path <path>]` — for the import workflow, also pass `--import-from <base_path>/import-markdown/match-manifest.json`
    - `style-review`: `--format <adoc|mkdocs>`
    - `create-merge-request`: `[--draft] [--repo-path <path>]`
 

plugins/docs-tools/skills/docs-orchestrator/defaults/docs-import.yaml

@@ -0,0 +1,28 @@
+workflow:
+  name: docs-import
+  description: Import edited markdown back into AsciiDoc modules, creating a merge request for review.
+
+  steps:
+    - name: import-markdown
+      skill: docs-tools:docs-workflow-import-markdown
+      description: Split markdown and match sections to AsciiDoc modules
+
+    - name: prepare-branch
+      skill: docs-tools:docs-workflow-prepare-branch
+      description: Create feature branch
+      inputs: [import-markdown]
+
+    - name: writing
+      skill: docs-tools:docs-workflow-writing
+      description: Apply content updates to matched modules
+      inputs: [import-markdown, prepare-branch]
+
+    - name: commit
+      skill: docs-tools:docs-workflow-commit
+      description: Commit and push changes
+      inputs: [writing]
+
+    - name: create-mr
+      skill: docs-tools:docs-workflow-create-mr
+      description: Create merge request
+      inputs: [commit]

plugins/docs-tools/skills/docs-workflow-import-markdown/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: docs-workflow-import-markdown
+description: Split an edited markdown file by headings and match sections to existing AsciiDoc modules using URL fragment IDs. Produces a match manifest for the writing step.
+argument-hint: <ticket> --markdown <path> --base-path <path> [--repo-path <path>]
+allowed-tools: Bash, Read
+---
+
+# Import Markdown Step
+
+Step skill for the docs-orchestrator import pipeline. Follows the step skill contract: **run script → verify output**.
+
+## Execution
+
+### 1. Run the script
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/import_markdown.py <args>
+```
+
+Pass through the full args string. The script:
+
+1. Reads the markdown file
+2. Splits it into sections by heading level (`##`, `###`, `####`)
+3. Extracts `docs.redhat.com` URL fragment IDs from heading links
+4. Matches each section to an `.adoc` module in the target repo (by ID stem grep, then heading text fallback)
+5. Writes `match-manifest.json` to `<base-path>/import-markdown/`
+
+The script emits JSON on stdout:
+
+```json
+{
+  "manifest_path": "<base-path>/import-markdown/match-manifest.json",
+  "output_dir": "<base-path>/import-markdown",
+  "summary": {
+    "matched": 12,
+    "new": 3,
+    "skipped": 1,
+    "preamble_skipped": 1,
+    "total": 17
+  }
+}
+```
+
+If the script exits non-zero, stop and report the error from stderr.
+
+### 2. Verify output
+
+Check that the `manifest_path` from the JSON output exists.
+
+### 3. Report summary
+
+Print the summary to the user:
+
+```
+Import matching complete: <matched> matched, <new> new, <skipped> skipped
+```
+
+If there are skipped sections, add:
+
+```
+Skipped sections require manual attention — see match-manifest.json for details.
+```
+
+## Known limitations
+
+**Structural changes redistribute content.** When SMEs add new sub-headings and move existing content under them (e.g., splitting section 4.3 into 4.3 + 4.3.1), the parent section's content becomes empty while the child gets the content. The matched parent module will be updated with a near-empty body, and the child will be created as a new module. The content is not lost — it moves to the new module — but the writer should review the MR diff carefully to verify the restructuring is correct.