Add doc set generation from scratch via docset workflow#64
Open
Add doc set generation from scratch via docset workflow#64
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughRefactors the docs-tools orchestrator to support selectable content paradigms (JTBD and user-stories), shifts from ticket-based to workflow ID-based execution, adds multi-source input collection (JIRA, web, local files, Google Docs), introduces a new docset-scaffold workflow with MkDocs scaffolding, and transitions file location tracking from directory-based to manifest-file-based conventions. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 error, 1 warning)
✅ Passed checks (6 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md (1)
23-27: Add language specifier to fenced code block.The output path code block should have a language specifier to satisfy markdown linting.
📝 Proposed fix
## Output -``` +```text <base-path>/scaffold/scaffold-info.md</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/docs-tools/skills/docs-docset-scaffold/SKILL.mdaround lines 23 -
27, The fenced code block under the "## Output" section in SKILL.md lacks a
language specifier; update the opening fence for the output path block to
include a language (e.g., change the opening "" to "text") so the block
reads as a text code block and satisfies markdown linting.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@plugins/docs-tools/skills/docs-orchestrator/SKILL.md:
- Line 46: The docs-orchestrator SKILL.md declares forwarding the --no-jtbd flag
but the docs-workflow-writing SKILL.md lacks any argument-hint or parsing for
that flag, causing a contract drift; either add a matching argument-hint and
parsing documentation in the writing skill’s SKILL.md (include the --no-jtbd
flag in the argument-hint block, describe its behavior, and document how the
writing skill parses/consumes it) and ensure the downstream step actually
checks/propagates the flag, or remove the forwarding note from the
docs-orchestrator SKILL.md so the two skill contracts are consistent.- Line 38: The workflow ID (
$1/<id>) is currently interpolated directly
into filesystem paths like.claude/docs/<id>/...after only lowercasing, which
allows path traversal and invalid characters; add a strict slug allowlist
validation function (e.g., validateSlug or isValidDocId) and run it wherever
$1/<id>is consumed (places referencing.claude/docs/<id>/and the other
noted usages around lines 99-103, 134-135, 186) to reject or sanitize inputs
that do not match the regex (letters, digits, hyphen/underscore only, no dots or
slashes, length limits); if validation fails, stop and prompt the user for a
safe identifier rather than constructing paths.
Nitpick comments:
In@plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md:
- Around line 23-27: The fenced code block under the "## Output" section in
SKILL.md lacks a language specifier; update the opening fence for the output
path block to include a language (e.g., change the opening "" to "text")
so the block reads as a text code block and satisfies markdown linting.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro **Run ID**: `477c25b9-fbe3-4a50-ae8a-8d5d7f45af06` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 1b4e1432639dd3eb2fc62ea2fa9a745782395704 and ec485de51ffef3060a820ada6bad1fa019db02aa. </details> <details> <summary>📒 Files selected for processing (9)</summary> * `.claude-plugin/marketplace.json` * `plugins/docs-tools/.claude-plugin/plugin.json` * `plugins/docs-tools/agents/requirements-analyst.md` * `plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md` * `plugins/docs-tools/skills/docs-orchestrator/SKILL.md` * `plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml` * `plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml` * `plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh` * `plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| ## Parse arguments | ||
|
|
||
| - `$1` — JIRA ticket ID (required). If missing, STOP and ask the user. | ||
| - `$1` — Workflow ID (required). For the default `docs-workflow`, this is a JIRA ticket ID. For custom workflows (e.g., `--workflow docset`), this can be any identifier such as a doc set name. If missing, STOP and ask the user. |
There was a problem hiding this comment.
Sanitize <id> before using it in filesystem paths
<id> is now free-form, but it is interpolated into .claude/docs/<id>/... paths with only lowercase normalization. This can allow path traversal or invalid path characters. Add strict slug validation (allowlist) before any path construction.
Proposed hardening
-- `$1` — Workflow ID (required). For the default `docs-workflow`, this is a JIRA ticket ID. For custom workflows (e.g., `--workflow docset`), this can be any identifier such as a doc set name. If missing, STOP and ask the user.
+- `$1` — Workflow ID (required). For the default `docs-workflow`, this is a JIRA ticket ID. For custom workflows (e.g., `--workflow docset`), this can be a doc set identifier.
+ Validate before use: lowercase, trim, and allow only `[a-z0-9][a-z0-9._-]{0,127}`. Reject `/`, `\`, `..`, spaces, and shell metacharacters. If invalid, STOP with a clear error.Also applies to: 99-103, 134-135, 186-186
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/docs-tools/skills/docs-orchestrator/SKILL.md` at line 38, The
workflow ID (`$1` / `<id>`) is currently interpolated directly into filesystem
paths like `.claude/docs/<id>/...` after only lowercasing, which allows path
traversal and invalid characters; add a strict slug allowlist validation
function (e.g., validateSlug or isValidDocId) and run it wherever `$1`/`<id>` is
consumed (places referencing `.claude/docs/<id>/` and the other noted usages
around lines 99-103, 134-135, 186) to reject or sanitize inputs that do not
match the regex (letters, digits, hyphen/underscore only, no dots or slashes,
length limits); if validation fails, stop and prompt the user for a safe
identifier rather than constructing paths.
There was a problem hiding this comment.
🧹 Nitpick comments (5)
plugins/docs-tools/agents/docs-planner-jtbd.md (3)
581-581: Minor: Capitalize "Markdown" as a proper noun."Markdown" is a proper noun (the name of the formatting language).
📝 Suggested fix
-Download and analyze existing Red Hat documentation for planning. Extract article content as markdown: +Download and analyze existing Red Hat documentation for planning. Extract article content as Markdown:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/agents/docs-planner-jtbd.md` at line 581, The phrase "Extract article content as markdown:" should capitalize "Markdown" as a proper noun; update that exact string (e.g., in the docs-planner-jtbd text "Extract article content as markdown:") to "Extract article content as Markdown:" so the formatting language name is correctly capitalized.
516-516: Minor: Add hyphen to "High-level steps".The term "high level" should be hyphenated when used as a compound adjective.
📝 Suggested fix
-- **High level steps**: Extract from your procedu... +- **High-level steps**: Extract from your procedu...🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/agents/docs-planner-jtbd.md` at line 516, Replace the unhyphenated phrase "High level steps" with the compound adjective form "High-level steps" wherever it appears (specifically update the heading/text instance "High level steps: Extract from your procedure module planning. Include prerequisites identified during gap analysis." to "High-level steps: Extract from your procedure module planning. Include prerequisites identified during gap analysis."); ensure the change preserves surrounding punctuation and formatting.
33-105: Assess overlap withdocs-planner.mdfor consolidation opportunities.This JTBD planner agent shares significant structural elements with the feature-based
docs-planner.md(access verification, doc impact assessment, discovery phase, gap analysis, theme clustering, prioritization, self-review verification, output format). The differentiation is primarily in the planning methodology (JTBD hierarchy vs. feature hierarchy).Consider extracting shared sections (access verification, doc impact assessment, reference tracking, theme clustering, prioritization, self-review verification, skill usage) into a common reference file and having both agents include it. This would reduce duplication and ensure consistency when these shared sections need updates.
Based on learnings: "When modifying plugin files, check for overlapping functionality with existing content and open PRs - flag high similarity (>=85%) with recommendation to consolidate, moderate similarity (60-84%) with recommendation to differentiate."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/agents/docs-planner-jtbd.md` around lines 33 - 105, The JTBD planner duplicates many shared sections (access verification, doc impact assessment, reference tracking, theme clustering, prioritization, self-review verification, skill usage) from the feature-based planner; extract these shared sections into a single common reference module and update the JTBD workflow to import/include that module rather than copy/paste content, add a similarity-check step that flags high similarity >=85% (recommend consolidation) and moderate 60–84% (recommend differentiation) when modifying planner content, and update the JTBD planner's unique pieces (JTBD hierarchy, outcome-driven titling, job framing) to remain in the JTBD-specific document (look for headings "Core JTBD principles", "Why JTBD matters", and "Draft outcome-driven titles" to scope the unique content).plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py (1)
65-70: Consider specifying UTF-8 encoding for file operations.The
open()calls rely on the system default encoding. For cross-platform consistency and to handle non-ASCII characters in documentation plans, explicitly specifyingencoding='utf-8'is recommended.📝 Suggested fix
- with open(plan_file) as f: + with open(plan_file, encoding='utf-8') as f: content = f.read() result = extract(content, is_public=(visibility == "public")) - with open(output_file, "w") as f: + with open(output_file, "w", encoding='utf-8') as f: f.write(result)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py` around lines 65 - 70, The file I/O uses plain open() which relies on system encoding; update the two calls that open plan_file and output_file (the with open(plan_file) as f: read used before calling extract(...) and the with open(output_file, "w") as f: write) to explicitly pass encoding='utf-8' so reads/writes are consistent across platforms and handle non-ASCII characters.plugins/docs-tools/agents/docs-writer-jtbd.md (1)
8-383: Assess overlap withdocs-writer.mdfor consolidation opportunities.This JTBD writer agent shares extensive structural content with
docs-writer.md:
- Identical sections: source verification, placement modes, format-specific references, writing guidelines (style principles, ventilated prose, short descriptions, prerequisites, content depth, procedure steps), style compliance workflow, JIRA ID extraction, file naming
- The differentiation is primarily in lines 104-124 (titling strategy/framework) and lines 276-281 (titles and headings)
Consider extracting shared sections into a common reference file (e.g.,
plugins/docs-tools/reference/writer-common.md) that both agents can reference. This would reduce ~300 lines of duplication and ensure consistency when these shared sections need updates.Based on learnings: "When modifying plugin files, check for overlapping functionality with existing content and open PRs - flag high similarity (>=85%) with recommendation to consolidate, moderate similarity (60-84%) with recommendation to differentiate."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/agents/docs-writer-jtbd.md` around lines 8 - 383, The docs-writer-jtbd.md file duplicates large swaths of content already present in docs-writer.md; extract the shared sections (source verification, placement modes, format-specific references, writing guidelines, style compliance workflow, JIRA ID extraction, file naming, and ventilated prose rules) into a new common include (suggested name: writer-common.md) and replace the duplicated blocks in both docs-writer-jtbd.md and docs-writer.md with a single include or reference to that common file; preserve the unique JTBD-specific sections (titling strategy/framework and titles and headings) in docs-writer-jtbd.md and ensure both agents import writer-common.md so future updates only change one canonical source.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@plugins/docs-tools/agents/docs-planner-jtbd.md`:
- Line 581: The phrase "Extract article content as markdown:" should capitalize
"Markdown" as a proper noun; update that exact string (e.g., in the
docs-planner-jtbd text "Extract article content as markdown:") to "Extract
article content as Markdown:" so the formatting language name is correctly
capitalized.
- Line 516: Replace the unhyphenated phrase "High level steps" with the compound
adjective form "High-level steps" wherever it appears (specifically update the
heading/text instance "High level steps: Extract from your procedure module
planning. Include prerequisites identified during gap analysis." to "High-level
steps: Extract from your procedure module planning. Include prerequisites
identified during gap analysis."); ensure the change preserves surrounding
punctuation and formatting.
- Around line 33-105: The JTBD planner duplicates many shared sections (access
verification, doc impact assessment, reference tracking, theme clustering,
prioritization, self-review verification, skill usage) from the feature-based
planner; extract these shared sections into a single common reference module and
update the JTBD workflow to import/include that module rather than copy/paste
content, add a similarity-check step that flags high similarity >=85% (recommend
consolidation) and moderate 60–84% (recommend differentiation) when modifying
planner content, and update the JTBD planner's unique pieces (JTBD hierarchy,
outcome-driven titling, job framing) to remain in the JTBD-specific document
(look for headings "Core JTBD principles", "Why JTBD matters", and "Draft
outcome-driven titles" to scope the unique content).
In `@plugins/docs-tools/agents/docs-writer-jtbd.md`:
- Around line 8-383: The docs-writer-jtbd.md file duplicates large swaths of
content already present in docs-writer.md; extract the shared sections (source
verification, placement modes, format-specific references, writing guidelines,
style compliance workflow, JIRA ID extraction, file naming, and ventilated prose
rules) into a new common include (suggested name: writer-common.md) and replace
the duplicated blocks in both docs-writer-jtbd.md and docs-writer.md with a
single include or reference to that common file; preserve the unique
JTBD-specific sections (titling strategy/framework and titles and headings) in
docs-writer-jtbd.md and ensure both agents import writer-common.md so future
updates only change one canonical source.
In
`@plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py`:
- Around line 65-70: The file I/O uses plain open() which relies on system
encoding; update the two calls that open plan_file and output_file (the with
open(plan_file) as f: read used before calling extract(...) and the with
open(output_file, "w") as f: write) to explicitly pass encoding='utf-8' so
reads/writes are consistent across platforms and handle non-ASCII characters.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: cd4548e8-68b6-41d8-89cf-bfe1cdbf9264
📒 Files selected for processing (10)
.claude-plugin/marketplace.jsonplugins/docs-tools/.claude-plugin/plugin.jsonplugins/docs-tools/agents/docs-planner-jtbd.mdplugins/docs-tools/agents/docs-planner.mdplugins/docs-tools/agents/docs-writer-jtbd.mdplugins/docs-tools/agents/docs-writer.mdplugins/docs-tools/commands/docs-workflow.mdplugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.pyplugins/docs-tools/skills/docs-workflow-planning/SKILL.mdplugins/docs-tools/skills/docs-workflow-writing/SKILL.md
✅ Files skipped from review due to trivial changes (1)
- plugins/docs-tools/.claude-plugin/plugin.json
🚧 Files skipped from review as they are similar to previous changes (1)
- .claude-plugin/marketplace.json
There was a problem hiding this comment.
🧹 Nitpick comments (2)
plugins/docs-tools/agents/docs-planner.md (1)
278-283: Add language specifier to the fenced code block.The code block showing the Parent Topic outline example lacks a language identifier, which triggers a markdownlint warning (MD040).
Proposed fix
Example Parent Topic outline: -``` +```text Title: Horizontal pod autoscaler Description: [What] Automatically adjusts the number of pod replicas based on CPU, memory, or custom metrics. [When] Use when workloads have variable resource demands. Overview: The HPA controller monitors metrics and adjusts replica counts within configured bounds. Common tasks: 1. Configure HPA for a deployment → 2. Set custom metrics → 3. Monitor scaling events</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/docs-tools/agents/docs-planner.mdaround lines 278 - 283, The fenced
code block containing the Parent Topic outline (the block beginning with "Title:
Horizontal pod autoscaler" and its Description/Overview/Common tasks lines) is
missing a language specifier and triggers markdownlint MD040; change the opening
fence fromtotext (i.e., add the "text" language specifier) so the block
is recognized as plain text and the lint warning is resolved.</details> </blockquote></details> <details> <summary>plugins/docs-tools/skills/docs-orchestrator/SKILL.md (1)</summary><blockquote> `98-100`: **Add language specifiers to fenced code blocks.** Two code blocks lack language identifiers, triggering markdownlint warnings (MD040). <details> <summary>Proposed fix</summary> ```diff Every step writes to a predictable folder based on the workflow ID and step name: -``` +```text .claude/docs/<id>/<step-name>/ ``` ``` ```diff ### Folder structure -``` +```text .claude/docs/<id>/ requirements/ ... ``` </details> Also applies to: 106-126 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@plugins/docs-tools/skills/docs-orchestrator/SKILL.mdaround lines 98 - 100,
Add missing fenced-code language specifiers in SKILL.md for the two Markdown
blocks shown: the block containing ".claude/docs///" and the
larger block beginning ".claude/docs// requirements/ ...". Update those
triple-backtick fences to include a language (e.g., use "text") so they become
text ..., and scan the rest of SKILL.md (notably the section around the
second block) to ensure any other fenced code blocks also include a language
identifier to resolve MD040 warnings.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In@plugins/docs-tools/agents/docs-planner.md:
- Around line 278-283: The fenced code block containing the Parent Topic outline
(the block beginning with "Title: Horizontal pod autoscaler" and its
Description/Overview/Common tasks lines) is missing a language specifier and
triggers markdownlint MD040; change the opening fence fromtotext (i.e.,
add the "text" language specifier) so the block is recognized as plain text and
the lint warning is resolved.In
@plugins/docs-tools/skills/docs-orchestrator/SKILL.md:
- Around line 98-100: Add missing fenced-code language specifiers in SKILL.md
for the two Markdown blocks shown: the block containing
".claude/docs///" and the larger block beginning
".claude/docs// requirements/ ...". Update those triple-backtick fences to
include a language (e.g., use "text") so they becometext ..., and scan
the rest of SKILL.md (notably the section around the second block) to ensure any
other fenced code blocks also include a language identifier to resolve MD040
warnings.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro **Run ID**: `9cd1a18d-3717-4865-8a0f-94f19d5c8f4b` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between d94d873584216ced118aa0d9833b813133d93ca5 and 61899e32dcc57dad32630ea1b930eef6d7e2b259. </details> <details> <summary>📒 Files selected for processing (5)</summary> * `plugins/docs-tools/agents/docs-planner.md` * `plugins/docs-tools/commands/docs-workflow.md` * `plugins/docs-tools/skills/docs-orchestrator/SKILL.md` * `plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md` * `plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py` </details> <details> <summary>✅ Files skipped from review due to trivial changes (1)</summary> * plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Member
|
Could move the --JTBD switch to its own PR for legibility ¯(ツ)/¯ |
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/docs-tools/agents/docs-planner.md`:
- Around line 94-97: The bullet "Feature-based organization with parent topics
per feature" in the "Create a documentation plan" section hardcodes a specific
paradigm; change it to a paradigm-neutral instruction such as "Organize content
according to the chosen documentation paradigm (e.g., feature-based,
JTBD/user-stories), and define parent-topic structure as appropriate" so the
planner supports JTBD/user-stories at runtime; update the phrase under the
"Create a documentation plan" list (replace the exact text "Feature-based
organization with parent topics per feature") to this neutral wording.
In `@plugins/docs-tools/reference/paradigm-jtbd.md`:
- Around line 113-118: The fenced code block containing "Title: Improve
application performance" is unlabeled and triggers MD040; label it by replacing
the opening triple backticks with a language token (e.g., use ```text) so the
block is explicitly typed. Locate the fenced block that begins with the line
"Title: Improve application performance" and update its opening fence to include
the language identifier (for example change ``` to ```text) and keep the content
unchanged.
In `@plugins/docs-tools/reference/paradigm-user-stories.md`:
- Around line 82-87: The unlabeled fenced code block containing the "Title:
Horizontal pod autoscaler" parent-topic example should be given a language label
to satisfy MD040; update that block (the triple-backtick fence surrounding the
"Title: Horizontal pod autoscaler" / "Description" / "Overview" / "Common tasks"
lines) to include a language tag such as text (i.e., change ``` to ```text) so
the block is explicitly labeled.
In `@plugins/docs-tools/skills/docs-orchestrator/SKILL.md`:
- Around line 218-220: The scaffold command contract in this SKILL.md is too
broad vs the actual implementation: update the scaffold entry to match the
actual skill supported formats (change the scaffold line to only accept --format
mkdocs [--draft]) or alternatively implement adoc support in the
docs-docset-scaffold skill; ensure the SKILL.md entries for the 'scaffold'
symbol are consistent with the actual 'docs-docset-scaffold' implementation
(leave 'writing' and 'style-review' lines unchanged unless you also change their
implementations).
- Around line 246-248: The retry command shown for the skill
docs-tools:docs-workflow-writing omits the --paradigm flag causing non-default
paradigms to revert; update the args string so the retry includes the same
paradigm argument (e.g., add --paradigm <paradigm> alongside --base-path and
--fix-from) and ensure the placeholder/variable used matches how the calling
flow supplies paradigm so the technical-review retry preserves the original
paradigm selection.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 6fb12f99-5555-4f25-9719-0ff1e147d2c2
📒 Files selected for processing (9)
plugins/docs-tools/agents/docs-planner.mdplugins/docs-tools/agents/docs-writer.mdplugins/docs-tools/commands/docs-workflow.mdplugins/docs-tools/reference/paradigm-jtbd.mdplugins/docs-tools/reference/paradigm-user-stories.mdplugins/docs-tools/skills/docs-docset-scaffold/SKILL.mdplugins/docs-tools/skills/docs-orchestrator/SKILL.mdplugins/docs-tools/skills/docs-workflow-planning/SKILL.mdplugins/docs-tools/skills/docs-workflow-writing/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (3)
- plugins/docs-tools/agents/docs-writer.md
- plugins/docs-tools/skills/docs-workflow-planning/SKILL.md
- plugins/docs-tools/commands/docs-workflow.md
Comment on lines
+113
to
+118
| ``` | ||
| Title: Improve application performance | ||
| Description: [What] Tune the platform for demanding workloads. [Why] Keep applications responsive and resource usage efficient. | ||
| Overview: The product provides tools for resource allocation, pod scheduling, and workload profiling. | ||
| High-level steps: 1. Profile workloads → 2. Configure resource limits → 3. Monitor results | ||
| ``` |
There was a problem hiding this comment.
Label this fenced block with a language.
The example block is unlabeled and triggers MD040.
Suggested patch
-```
+```text
Title: Improve application performance
Description: [What] Tune the platform for demanding workloads. [Why] Keep applications responsive and resource usage efficient.
Overview: The product provides tools for resource allocation, pod scheduling, and workload profiling.
High-level steps: 1. Profile workloads → 2. Configure resource limits → 3. Monitor results</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 113-113: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/docs-tools/reference/paradigm-jtbd.md` around lines 113 - 118, The
fenced code block containing "Title: Improve application performance" is
unlabeled and triggers MD040; label it by replacing the opening triple backticks
with a language token (e.g., use ```text) so the block is explicitly typed.
Locate the fenced block that begins with the line "Title: Improve application
performance" and update its opening fence to include the language identifier
(for example change ``` to ```text) and keep the content unchanged.
Extend the docs-orchestrator to support generating entire MkDocs documentation sets from multiple input sources (JIRA tickets via JQL, local files, and Google Drive artifacts). Changes: - Generalize orchestrator $1 from "JIRA ticket ID" to "workflow ID" - Add --jql, --tickets, --inputs (repeatable), --no-jtbd flags - Make JIRA pre-flight conditional (only when JIRA access is needed) - Extend requirements-analyst agent with multi-source input handling - Add docs-docset-scaffold skill for MkDocs project scaffolding - Add docs-docset-workflow.yaml (7-step docset workflow definition) - Bump docs-tools version to 0.0.16 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rename existing JTBD agents to docs-planner-jtbd and docs-writer-jtbd. Create new base-named docs-planner and docs-writer agents with feature-based information architecture (dynamic categories, user-story framing, descriptive titles). Step skills conditionally dispatch based on --no-jtbd flag: default uses JTBD agents, --no-jtbd uses feature-based agents. Also updates legacy docs-workflow command references, adds feature-based heading patterns to extract-description.py, and bumps version to 0.0.17. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Remove stale "plumbing only" comment from orchestrator --no-jtbd flag - Add path sanitization rules for workflow ID (reject ../ traversal) - Add JIRA description verification check to feature-based planner - Update create-jira skill to reference both JTBD and feature-based formats - Add explicit utf-8 encoding to extract-description.py file I/O Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Use fully qualified docs-tools:agent-name format in the stage summary table to comply with the plugin:skill naming convention. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ries flags Consolidate four paradigm-specific agents (docs-planner, docs-planner-jtbd, docs-writer, docs-writer-jtbd) into two paradigm-agnostic agents that conditionally reference paradigm-specific guidance from new reference files. Replace the reductive --no-jtbd flag with positive, extensible --jtbd (default) and --user-stories flags, normalized internally to --paradigm <value>. - Create paradigm-jtbd.md and paradigm-user-stories.md reference files - Merge planner and writer agents to be paradigm-agnostic - Delete docs-planner-jtbd.md and docs-writer-jtbd.md - Update orchestrator, planning, writing, scaffold skills and legacy command - Update progress file schema: "paradigm" replaces "no_jtbd" Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…loops - Replace hardcoded "Feature-based organization" with paradigm-neutral wording in docs-planner.md - Narrow scaffold format contract from <adoc|mkdocs> to mkdocs-only - Add --paradigm to tech review fix iteration in orchestrator skill - Add Content paradigm to writer fix prompt in legacy command - Label bare code blocks in paradigm reference files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…truth Review and fix steps now read the writing manifest to find file locations instead of branching on --draft. This removes fragile flag-threading and eliminates conditional prompt duplication in downstream steps. - docs-reviewer: prompt-driven source paths, remove JIRA ID path coupling - tech-review/style-review: single prompt reads manifest, no --draft branch - writing fix mode: read manifest instead of assuming drafts location - prepare-branch: generalize $1 from "JIRA ticket ID" to "Workflow ID" - orchestrator: clarify folder structure for both placement modes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
mcljot
force-pushed
the
create-from-scratch
branch
from
37a620a to
da0f04e
Compare
There was a problem hiding this comment.
🧹 Nitpick comments (3)
plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md (2)
14-14: Minor wording nit: hyphenate compound modifier.Use “step-skill contract” for consistency/readability.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md` at line 14, Replace the unhyphenated phrase "step skill contract" with the hyphenated form "step-skill contract" in the SKILL.md description (the sentence starting "Step skill for the docs-orchestrator pipeline...") to maintain consistency and correct compound-modifier usage.
168-170: Expand verification beyond two files.Line 170 only validates
mkdocs.ymlanddocs/index.md. Since nav entries and category/topic placeholders are generated, verification should also ensure every nav target exists to prevent broken site builds.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md` around lines 168 - 170, Update the "Verify output" step (Step 6 / the Verify output check) to not only confirm mkdocs.yml and docs/index.md exist but also parse mkdocs.yml's nav section and validate that each referenced nav target file/path (including generated category/topic placeholders) actually exists under the output docs directory; ensure the check reports any missing nav targets so builds won't break.plugins/docs-tools/agents/docs-reviewer.md (1)
193-196: Clarify the invocation chain in the documentation.Line 195 states "When invoked by the orchestrator," but the orchestrator invokes the
docs-workflow-style-reviewskill, which then dispatches this agent. For precision, consider rephrasing to "When invoked by a workflow step skill" or "When invoked as part of a workflow."📝 Suggested wording improvement
-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. +When invoked by a workflow step skill (e.g., `docs-workflow-style-review`), 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.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/agents/docs-reviewer.md` around lines 193 - 196, Update the wording to clarify the invocation chain: replace "When invoked by the orchestrator" with a phrase that reflects the actual caller (for example "When invoked as part of a workflow" or "When invoked by a workflow step skill such as docs-workflow-style-review which dispatches this agent") so the doc accurately indicates that the docs-workflow-style-review skill invokes this agent and that the report path is provided by the workflow.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@plugins/docs-tools/agents/docs-reviewer.md`:
- Around line 193-196: Update the wording to clarify the invocation chain:
replace "When invoked by the orchestrator" with a phrase that reflects the
actual caller (for example "When invoked as part of a workflow" or "When invoked
by a workflow step skill such as docs-workflow-style-review which dispatches
this agent") so the doc accurately indicates that the docs-workflow-style-review
skill invokes this agent and that the report path is provided by the workflow.
In `@plugins/docs-tools/skills/docs-docset-scaffold/SKILL.md`:
- Line 14: Replace the unhyphenated phrase "step skill contract" with the
hyphenated form "step-skill contract" in the SKILL.md description (the sentence
starting "Step skill for the docs-orchestrator pipeline...") to maintain
consistency and correct compound-modifier usage.
- Around line 168-170: Update the "Verify output" step (Step 6 / the Verify
output check) to not only confirm mkdocs.yml and docs/index.md exist but also
parse mkdocs.yml's nav section and validate that each referenced nav target
file/path (including generated category/topic placeholders) actually exists
under the output docs directory; ensure the check reports any missing nav
targets so builds won't break.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: ddf2e430-4a77-4073-acfd-e0dca93e0951
📒 Files selected for processing (21)
plugins/docs-tools/.claude-plugin/plugin.jsonplugins/docs-tools/agents/docs-planner.mdplugins/docs-tools/agents/docs-reviewer.mdplugins/docs-tools/agents/docs-writer.mdplugins/docs-tools/agents/requirements-analyst.mdplugins/docs-tools/commands/docs-workflow.mdplugins/docs-tools/reference/paradigm-jtbd.mdplugins/docs-tools/reference/paradigm-user-stories.mdplugins/docs-tools/skills/docs-docset-scaffold/SKILL.mdplugins/docs-tools/skills/docs-orchestrator/SKILL.mdplugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yamlplugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yamlplugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.shplugins/docs-tools/skills/docs-workflow-create-jira/SKILL.mdplugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.pyplugins/docs-tools/skills/docs-workflow-planning/SKILL.mdplugins/docs-tools/skills/docs-workflow-prepare-branch/SKILL.mdplugins/docs-tools/skills/docs-workflow-requirements/SKILL.mdplugins/docs-tools/skills/docs-workflow-style-review/SKILL.mdplugins/docs-tools/skills/docs-workflow-tech-review/SKILL.mdplugins/docs-tools/skills/docs-workflow-writing/SKILL.md
✅ Files skipped from review due to trivial changes (9)
- plugins/docs-tools/skills/docs-workflow-create-jira/SKILL.md
- plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml
- plugins/docs-tools/.claude-plugin/plugin.json
- plugins/docs-tools/skills/docs-workflow-prepare-branch/SKILL.md
- plugins/docs-tools/skills/docs-orchestrator/hooks/workflow-completion-check.sh
- plugins/docs-tools/skills/docs-workflow-create-jira/scripts/extract-description.py
- plugins/docs-tools/skills/docs-orchestrator/defaults/docs-docset-workflow.yaml
- plugins/docs-tools/reference/paradigm-user-stories.md
- plugins/docs-tools/skills/docs-orchestrator/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (5)
- plugins/docs-tools/agents/docs-writer.md
- plugins/docs-tools/skills/docs-workflow-writing/SKILL.md
- plugins/docs-tools/commands/docs-workflow.md
- plugins/docs-tools/skills/docs-workflow-requirements/SKILL.md
- plugins/docs-tools/agents/requirements-analyst.md
…aults Remove modal split between single-ticket and multi-source mode in requirements handling — $1 now auto-detects JIRA ticket pattern and all source flags are always additive (4.4). Add manifest schema for _index.md inter-step contract (4.1). Add YAML workflow defaults with CLI > YAML > global precedence (6.4). Fix gerund procedure titles in user-stories paradigm reference (5.1). Replace non-standard plan template placeholders with [REPLACE: ...] directive (5.2). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The template population rule said "User stories" which hardcodes one paradigm. Replace with paradigm-neutral language that defers to the paradigm reference file, consistent with the runtime paradigm selection. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The article_extractor.py defaults to markdown, so --format markdown is noise. The orchestrator YAML defaults example duplicates the real file at defaults/docs-docset-workflow.yaml — replace with a pointer. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Member
|
I think there's too much going on in this for one PR |
aireilly
reviewed
Mar 28, 2026
|
|
||
| | Pattern | Type | Processing | | ||
| |---|---|---| | ||
| | `docs.google.com/document/...` | Google Doc | Convert via `gdoc2md.py` | |
Member
There was a problem hiding this comment.
The gdoc skill should handle this by default?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Extend the docs-orchestrator to support generating entire MkDocs documentation sets from multiple input sources (JIRA tickets via JQL, local files, and Google Drive artifacts).
Changes:
Summary by CodeRabbit
New Features
Documentation