Open
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:
WalkthroughIntroduces a headless, scheduled documentation pipeline for the Ambient adapter, adds setup automation and batch-controller skill, standardizes skill naming to unprefixed bare names across agents/skills/commands, updates plugin version, and adjusts workspace/workflow configuration and .gitignore to allow the batch-controller skill artifacts. Changes
Sequence Diagram(s)sequenceDiagram
participant AmbientScheduler as Ambient Scheduler
participant BatchController as Batch Controller Skill
participant Setup as setup.sh
participant JIRA
participant DocsOrch as Docs Orchestrator
participant Workflow as Workflow Skills
AmbientScheduler->>BatchController: start batch-controller
BatchController->>Setup: run adapters/ambient/setup.sh
Setup-->>BatchController: symlinks created
BatchController->>JIRA: query issues with trigger label
JIRA-->>BatchController: return ticket list
loop per ticket
BatchController->>DocsOrch: invoke docs-orchestrator --draft (ticket)
DocsOrch->>Workflow: execute steps (requirements→planning→writing→tech-review→style-review)
Workflow-->>DocsOrch: artifacts & status
DocsOrch-->>BatchController: result (success/failure)
alt success
BatchController->>JIRA: update labels → DOCS_DONE_LABEL
else failure
BatchController->>JIRA: update labels → DOCS_FAILED_LABEL
end
end
BatchController->>BatchController: write .claude/docs/batch-summary.md
BatchController-->>AmbientScheduler: session complete
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 error)
✅ Passed checks (7 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: 17
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🟡 Minor comments (4)
plugins/docs-tools/reference/mkdocs-reference.md-292-292 (1)
292-292:⚠️ Potential issue | 🟡 MinorSame guideline concern as
asciidoc-reference.md— bare skill name instead of fully qualified.Changed from
vale-tools:lint-with-valetolint-with-vale. If this is intentional for Ambient compatibility, ensure consistency across all reference documentation and update the coding guidelines to reflect the new convention.Based on learnings: "Always use fully qualified
plugin:skillnames (for example,docs-tools:jira-reader,vale-tools:lint-with-vale)".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/reference/mkdocs-reference.md` at line 292, The entry in mkdocs-reference.md uses the bare skill name `lint-with-vale` instead of the fully qualified form `vale-tools:lint-with-vale`, creating an inconsistency with asciidoc-reference.md and the project's guideline ("Always use fully qualified plugin:skill names"); update mkdocs-reference.md to use `vale-tools:lint-with-vale` (or, if the intent is to adopt ambient/bare names project-wide, update all reference docs including asciidoc-reference.md and the coding guidelines to reflect the new convention) and ensure other examples like `docs-tools:jira-reader` remain fully qualified for consistency.plugins/docs-tools/skills/docs-orchestrator/SKILL.md-230-230 (1)
230-230:⚠️ Potential issue | 🟡 MinorAdd a language hint to the fenced code block.
The fence starting on Line 230 is missing a language tag (MD040).
Suggested fix
- ``` + ```text Skill: docs-tools:docs-workflow-writing, args: "<ticket> --base-path <base_path> --fix-from <base_path>/technical-review/review.md" ```🤖 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 230, The fenced code block containing `Skill: docs-tools:docs-workflow-writing, args: "<ticket> --base-path <base_path> --fix-from <base_path>/technical-review/review.md"` is missing a language hint; change the opening fence from ``` to ```text so the block becomes a text fenced code block (i.e., replace the lone backtick fence with ```text to satisfy MD040).adapters/ambient/CLAUDE.md-23-35 (1)
23-35:⚠️ Potential issue | 🟡 MinorAdd a language tag to the fenced code block
The output-structure fence is missing a language identifier and triggers markdownlint MD040.
Suggested patch
-``` +```text .claude/docs/ ...</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@adapters/ambient/CLAUDE.mdaround lines 23 - 35, The fenced code block
showing the output-structure (the directory tree starting with ".claude/docs/")
lacks a language identifier and triggers markdownlint MD040; update that fenced
block in adapters/ambient/CLAUDE.md by adding a language tag (e.g., "text")
after the openingso the block becomestext to suppress MD040 while
preserving the directory tree content.</details> </blockquote></details> <details> <summary>adapters/ambient/.claude/skills/batch-controller/SKILL.md-47-47 (1)</summary><blockquote> `47-47`: _⚠️ Potential issue_ | _🟡 Minor_ **Add language identifiers to fenced blocks** These three fences are missing a language tag and trigger markdownlint MD040. Also applies to: 53-53, 67-67 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@adapters/ambient/.claude/skills/batch-controller/SKILL.mdat line 47, The
markdown file SKILL.md contains three fenced code blocks missing language
identifiers (causing markdownlint MD040); update each triple-backtick fence in
SKILL.md to include the appropriate language tag (for examplebash,json,markdownlint pass—locate the three fence-only blocks and replace their opening ``` with the correct ```<language> tokens.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@adapters/ambient/.ambient/ambient.json`:
- Line 12: The "Technical Reviews" artifact glob in ambient.json points to
".claude/docs/drafts/**/_technical_review.md" which doesn't match the skill
output "<base-path>/technical-review/review.md"; update the "Technical Reviews"
value to a glob that matches the producer output (e.g., change the string value
for the "Technical Reviews" key to a pattern that captures
"<base-path>/technical-review/review.md" such as
".claude/docs/**/technical-review/**/review.md" or a similar pattern used across
other artifact entries) so batch runs will include the produced review.md files.
In `@adapters/ambient/.claude/skills/batch-controller/SKILL.md`:
- Around line 47-49: Replace the bare skill invocations (e.g., the line starting
"Skill: jira-reader, args: ...") with the fully qualified plugin:skill form
required by our docs (use the plugin prefix for the jira reader, e.g. "Skill:
jira:reader, args: ..."), and update the other two occurrences noted (the blocks
around lines 53-55 and 67-69) to the same plugin:skill syntax so all skill
references use the fully qualified form.
In `@AGENTS.md`:
- Around line 25-29: The AGENTS.md change replaced fully qualified plugin:skill
names with bare skill names (e.g., "jira-reader", "rh-ssg-formatting",
"lint-with-vale"), which conflicts with the repo's skill-reference policy;
revert these examples to fully qualified forms (e.g., "docs-tools:jira-reader",
"docs-tools:rh-ssg-formatting", "vale-tools:lint-with-vale") and update any
affected examples that reference those bare names (including the examples cited
in the comment) so the document consistently uses plugin:skill notation per the
guidelines.
In `@plugins/docs-tools/agents/docs-reviewer.md`:
- Line 5: The frontmatter "skills" list and inline references use bare skill
names; revert every bare occurrence to fully qualified "plugin:skill" form
(e.g., change "lint-with-vale" to "plugin:lint-with-vale") across this agent
spec including the frontmatter key "skills" and any inline/instructional
references inside the agent text and instruction blocks (search for occurrences
of each bare skill name such as lint-with-vale, docs-review-modular-docs,
ibm-sg-*, rh-ssg-* and replace them with plugin:<skill-name>); ensure all
cross-references, skill invocations, and inline mentions consistently use the
plugin:prefix so the agent spec and skill calls (the skills list and any
instruction/description fields) are fully qualified.
In `@plugins/docs-tools/agents/docs-writer.md`:
- Line 5: The frontmatter line listing skills uses bare names (skills:
jira-reader, lint-with-vale, docs-review-modular-docs,
docs-review-content-quality); update each to the fully qualified form
plugin:skill (e.g., plugin:jira-reader, plugin:lint-with-vale, etc.) and ensure
any inline Skill tool invocations or textual references in this agent file
(including the occurrences noted around lines 371 and 378) are likewise changed
to the same plugin:skill identifiers so all frontmatter, tool calls, and
cross-references use the required fully qualified format.
In `@plugins/docs-tools/agents/requirements-analyst.md`:
- Line 5: The frontmatter `skills:` list currently uses bare names (jira-reader,
article-extractor, redhat-docs-toc, docs-convert-gdoc-md) and any inline skill
mentions are unqualified; update the frontmatter and all inline references to
use fully qualified plugin:skill identifiers (e.g., plugin:jira-reader,
plugin:article-extractor, plugin:redhat-docs-toc, plugin:docs-convert-gdoc-md)
so every skill reference (both in the `skills:` entry and any inline text)
follows the required plugin:skill form; also scan the document for other
occurrences of these bare names and replace them with the same fully qualified
identifiers.
In `@plugins/docs-tools/commands/docs-review.md`:
- Line 9: Replace bare command/skill identifiers like "docs-review" with the
fully qualified plugin:skill form (e.g., "docs-tools:docs-review") wherever they
appear in the document and cross-references; update the command heading, any
in-text mentions, and all occurrences referenced by the reviewer (including the
other blocks noted) so they follow the enforced naming rule and satisfy the
linter/CI. Ensure you update every instance of "docs-review" to
"docs-tools:docs-review" and verify cross-reference links use the same qualified
identifier.
In `@plugins/docs-tools/commands/docs-technical-review.md`:
- Line 85: Update the command doc so all skill names are fully plugin-qualified:
replace occurrences of docs-convert-gdoc-md with its plugin-qualified form
(e.g., plugin:docs-convert-gdoc-md) and jira-reader with plugin-qualified form
(e.g., plugin:jira-reader) wherever they appear in the document (including the
table row "Read via `docs-convert-gdoc-md` skill, save to temp file", any agent
frontmatter, inline references, and cross-references); ensure both
`docs-convert-gdoc-md` and `jira-reader` are consistently updated throughout the
file and the adjacent lines mentioned in the comment.
In `@plugins/docs-tools/commands/docs-workflow.md`:
- Line 9: The Name section and multiple command/skill references were
de-prefixed (e.g., "docs-workflow") which breaks linting and naming-policy;
revert those to fully qualified plugin:skill identifiers (for example, replace
plain "docs-workflow" with its fully qualified form "plugin:docs-workflow" as
appropriate) and ensure the Name section matches that qualified identifier;
update every affected token in the file (including the Name header and all
command/skill references listed in the comment) so they use plugin:skill form
and re-run the command linter/CI to confirm compliance.
In `@plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml`:
- Line 9: The step entries use bare skill IDs (e.g., the skill value
"docs-workflow-requirements") which violate the orchestrator spec in SKILL.md
requiring fully qualified plugin:skill references; update each of those skill
keys in plugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yaml
to the fully qualified form using the plugin name (e.g.,
"docs-tools:docs-workflow-requirements") for every step that currently has a
bare ID (the occurrences at the shown lines and the other listed occurrences),
ensuring every "skill:" value follows plugin:skill format so the orchestrator
validation will accept them.
In `@plugins/docs-tools/skills/docs-orchestrator/SKILL.md`:
- Around line 74-80: Replace bare skill references with the file's required
fully-qualified plugin:skill form: update the step entry for create-jira and any
other bare skill usages (e.g., the skill value docs-workflow-create-jira and
similar occurrences around the later block) so that "skill:
docs-workflow-create-jira" becomes "skill: <plugin>:docs-workflow-create-jira"
(use the same plugin prefix used elsewhere in this file) and apply the same
change to the other mentioned entries (the create-jira step and the analogous
entries at the later occurrences).
In `@plugins/docs-tools/skills/docs-workflow-style-review/SKILL.md`:
- Around line 47-50: The dispatch prompt uses an unqualified agent/tool name
"docs-reviewer" via the subagent_type parameter; update all occurrences
(including the shown dispatch and the other affected blocks around the same
file: the occurrences at the other noted ranges) to use the fully-qualified
plugin:skill name (e.g., "plugin:docs-reviewer") so that agent frontmatter and
Skill tool invocations follow the repository convention; specifically change the
subagent_type value and any inline references to the agent/skill to the
fully-qualified "plugin:docs-reviewer" form.
In `@plugins/docs-tools/skills/ibm-sg-audience-and-medium/SKILL.md`:
- Line 11: The skill reference in SKILL.md uses a bare name
"rh-ssg-accessibility" which violates the required fully-qualified plugin:skill
format; update that reference to "docs-tools:rh-ssg-accessibility" (and any
other bare cross-references in this file) so it matches the established
convention, and if this change was intentional across the repo, either revert to
fully-qualified names here or coordinate a repo-wide rules update to the coding
guidelines; search for the symbol "rh-ssg-accessibility" and replace occurrences
with "docs-tools:rh-ssg-accessibility" in the skill text and cross-reference
sections (e.g., the Precedence line).
In `@plugins/docs-tools/skills/ibm-sg-language-and-grammar/SKILL.md`:
- Line 11: The skill reference was changed from the fully-qualified form to an
unqualified name—replace the unqualified reference "rh-ssg-grammar-and-language"
with the fully qualified plugin:skill name
"docs-tools:rh-ssg-grammar-and-language" wherever it appears (specifically in
the Precedence line of SKILL.md) so the documentation and agent instructions
follow the required "plugin:skill" naming convention; ensure any inline text
references and cross-references use the fully-qualified form consistently.
In `@plugins/docs-tools/skills/ibm-sg-legal-information/SKILL.md`:
- Line 11: The skill reference was shortened incorrectly; restore the fully
qualified plugin:skill name by changing the plain reference
`rh-ssg-legal-and-support` back to `docs-tools:rh-ssg-legal-and-support`
wherever it appears (e.g., the line with "Precedence" in SKILL.md) so
cross-references adhere to the established convention for agent instructions,
Skill invocations, and inline references.
In `@plugins/docs-tools/skills/ibm-sg-numbers-and-measurement/SKILL.md`:
- Line 11: The skill reference in SKILL.md was changed from the fully qualified
form to a bare name; restore the fully qualified plugin:skill format by
replacing occurrences of "rh-ssg-formatting" with "docs-tools:rh-ssg-formatting"
so cross-references follow the required convention; update the text in SKILL.md
where the Precedence line and any other inline references mention the skill
(look for the token "rh-ssg-formatting") and ensure the fully qualified
"docs-tools:rh-ssg-formatting" is used consistently in agent instructions, Skill
invocations, and cross-references.
In `@plugins/docs-tools/skills/ibm-sg-technical-elements/SKILL.md`:
- Line 11: The cross-reference in SKILL.md removed the required plugin prefix
and should use the fully qualified plugin:skill name; restore the "docs-tools:"
prefix so references read "docs-tools:rh-ssg-technical-examples" (and similarly
"docs-tools:rh-ssg-gui-and-links" if present), ensuring all inline text
references, Skill invocations, and cross-references follow the guideline of
using fully qualified plugin:skill names (e.g.,
docs-tools:rh-ssg-technical-examples).
---
Minor comments:
In `@adapters/ambient/.claude/skills/batch-controller/SKILL.md`:
- Line 47: The markdown file SKILL.md contains three fenced code blocks missing
language identifiers (causing markdownlint MD040); update each triple-backtick
fence in SKILL.md to include the appropriate language tag (for example ```bash,
```json, ```ts, etc.) matching the content of each block so syntax highlighting
and markdownlint pass—locate the three fence-only blocks and replace their
opening ``` with the correct ```<language> tokens.
In `@adapters/ambient/CLAUDE.md`:
- Around line 23-35: The fenced code block showing the output-structure (the
directory tree starting with ".claude/docs/") lacks a language identifier and
triggers markdownlint MD040; update that fenced block in
adapters/ambient/CLAUDE.md by adding a language tag (e.g., "text") after the
opening ``` so the block becomes ```text to suppress MD040 while preserving the
directory tree content.
In `@plugins/docs-tools/reference/mkdocs-reference.md`:
- Line 292: The entry in mkdocs-reference.md uses the bare skill name
`lint-with-vale` instead of the fully qualified form
`vale-tools:lint-with-vale`, creating an inconsistency with
asciidoc-reference.md and the project's guideline ("Always use fully qualified
plugin:skill names"); update mkdocs-reference.md to use
`vale-tools:lint-with-vale` (or, if the intent is to adopt ambient/bare names
project-wide, update all reference docs including asciidoc-reference.md and the
coding guidelines to reflect the new convention) and ensure other examples like
`docs-tools:jira-reader` remain fully qualified for consistency.
In `@plugins/docs-tools/skills/docs-orchestrator/SKILL.md`:
- Line 230: The fenced code block containing `Skill:
docs-tools:docs-workflow-writing, args: "<ticket> --base-path <base_path>
--fix-from <base_path>/technical-review/review.md"` is missing a language hint;
change the opening fence from ``` to ```text so the block becomes a text fenced
code block (i.e., replace the lone backtick fence with ```text to satisfy
MD040).
🪄 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: 3d1c968b-e0ce-4db3-b0d3-f68863a38fe0
📒 Files selected for processing (32)
.gitignoreAGENTS.mdadapters/ambient/.ambient/ambient.jsonadapters/ambient/.claude/skills/batch-controller/SKILL.mdadapters/ambient/CLAUDE.mdadapters/ambient/docs-workflow.yamladapters/ambient/setup.shplugins/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/agents/technical-reviewer.mdplugins/docs-tools/commands/docs-review.mdplugins/docs-tools/commands/docs-technical-review.mdplugins/docs-tools/commands/docs-workflow.mdplugins/docs-tools/reference/asciidoc-reference.mdplugins/docs-tools/reference/mkdocs-reference.mdplugins/docs-tools/skills/docs-orchestrator/SKILL.mdplugins/docs-tools/skills/docs-orchestrator/defaults/docs-workflow.yamlplugins/docs-tools/skills/docs-review-modular-docs/SKILL.mdplugins/docs-tools/skills/docs-workflow-planning/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.mdplugins/docs-tools/skills/git-pr-reader/SKILL.mdplugins/docs-tools/skills/ibm-sg-audience-and-medium/SKILL.mdplugins/docs-tools/skills/ibm-sg-language-and-grammar/SKILL.mdplugins/docs-tools/skills/ibm-sg-legal-information/SKILL.mdplugins/docs-tools/skills/ibm-sg-numbers-and-measurement/SKILL.mdplugins/docs-tools/skills/ibm-sg-structure-and-format/SKILL.mdplugins/docs-tools/skills/ibm-sg-technical-elements/SKILL.md
Comment on lines
+25
to
+29
| Use bare skill names for portability. Qualified names (`plugin:skill`) are only needed to disambiguate when two plugins have the same skill name: | ||
|
|
||
| - `docs-tools:jira-reader` (not `jira-reader`) | ||
| - `docs-tools:rh-ssg-formatting` (not `rh-ssg-formatting`) | ||
| - `vale-tools:lint-with-vale` (not `vale`) | ||
| - `jira-reader` (not `docs-tools:jira-reader`) | ||
| - `rh-ssg-formatting` (not `docs-tools:rh-ssg-formatting`) | ||
| - `lint-with-vale` (not `vale-tools:lint-with-vale`) |
There was a problem hiding this comment.
This convention change conflicts with repository skill-reference policy.
Switching AGENTS.md to bare names will propagate invalid examples (including Line 62 and Line 74) across the repo.
Suggested fix
-Use bare skill names for portability. Qualified names (`plugin:skill`) are only needed to disambiguate when two plugins have the same skill name:
+Use fully qualified skill names (`plugin:skill`) in agent instructions, Skill invocations, inline references, and cross-references.
-- `jira-reader` (not `docs-tools:jira-reader`)
-- `rh-ssg-formatting` (not `docs-tools:rh-ssg-formatting`)
-- `lint-with-vale` (not `vale-tools:lint-with-vale`)
+- `docs-tools:jira-reader`
+- `docs-tools:rh-ssg-formatting`
+- `vale-tools:lint-with-vale`🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@AGENTS.md` around lines 25 - 29, The AGENTS.md change replaced fully
qualified plugin:skill names with bare skill names (e.g., "jira-reader",
"rh-ssg-formatting", "lint-with-vale"), which conflicts with the repo's
skill-reference policy; revert these examples to fully qualified forms (e.g.,
"docs-tools:jira-reader", "docs-tools:rh-ssg-formatting",
"vale-tools:lint-with-vale") and update any affected examples that reference
those bare names (including the examples cited in the comment) so the document
consistently uses plugin:skill notation per the guidelines.
| 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. | ||
| 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 | ||
| skills: jira-reader, lint-with-vale, docs-review-modular-docs, docs-review-content-quality |
There was a problem hiding this comment.
Use fully qualified skill identifiers in this agent file
The changed references switched to bare names, but this path requires plugin:skill format in frontmatter and inline instructions.
Suggested patch
-skills: jira-reader, lint-with-vale, docs-review-modular-docs, docs-review-content-quality
+skills: docs-tools:jira-reader, vale-tools:lint-with-vale, docs-tools:docs-review-modular-docs, docs-tools:docs-review-content-quality
@@
-Run `lint-with-vale` against each file. Fix all ERROR-level issues before saving. Address WARNING-level issues when possible.
+Run `vale-tools:lint-with-vale` against each file. Fix all ERROR-level issues before saving. Address WARNING-level issues when possible.
@@
-The `docs-review-modular-docs` (AsciiDoc only) and `docs-review-content-quality` skills provide additional structural and quality checks. The docs-reviewer agent runs the full suite of review skills.
+The `docs-tools:docs-review-modular-docs` (AsciiDoc only) and `docs-tools:docs-review-content-quality` skills provide additional structural and quality checks. The docs-reviewer agent runs the full suite of review skills.Also applies to: 371-371, 378-378
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/docs-tools/agents/docs-writer.md` at line 5, The frontmatter line
listing skills uses bare names (skills: jira-reader, lint-with-vale,
docs-review-modular-docs, docs-review-content-quality); update each to the fully
qualified form plugin:skill (e.g., plugin:jira-reader, plugin:lint-with-vale,
etc.) and ensure any inline Skill tool invocations or textual references in this
agent file (including the occurrences noted around lines 371 and 378) are
likewise changed to the same plugin:skill identifiers so all frontmatter, tool
calls, and cross-references use the required fully qualified format.
| Review documentation for audience and medium issues: accessibility, global audiences, tone, AI assistant style, mobile, marketing, and video content. | ||
|
|
||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `docs-tools:rh-ssg-accessibility` for accessibility). | ||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `rh-ssg-accessibility` for accessibility). |
There was a problem hiding this comment.
Critical: Skill reference violates established naming conventions
The skill reference rh-ssg-accessibility at line 11 removed the docs-tools: prefix, changing from the fully qualified format. This violates established conventions requiring plugin:skill format for cross-references between skills.
As per coding guidelines: "Always use fully qualified plugin:skill names (for example, docs-tools:jira-reader, vale-tools:lint-with-vale) in agent instructions, Skill invocations, inline text references, and cross-references between skills"
This appears to be part of a repository-wide naming convention change. If intentional, the coding guidelines must be updated to reflect the new bare-name convention.
Based on learnings: "Applies to /{AGENTS,agents,instructions,docs}//*.{yaml,yml,md} : Always use fully qualified plugin:skill names (for example, docs-tools:jira-reader, vale-tools:lint-with-vale) in agent instructions, Skill invocations, inline text references, and cross-references between skills"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/docs-tools/skills/ibm-sg-audience-and-medium/SKILL.md` at line 11,
The skill reference in SKILL.md uses a bare name "rh-ssg-accessibility" which
violates the required fully-qualified plugin:skill format; update that reference
to "docs-tools:rh-ssg-accessibility" (and any other bare cross-references in
this file) so it matches the established convention, and if this change was
intentional across the repo, either revert to fully-qualified names here or
coordinate a repo-wide rules update to the coding guidelines; search for the
symbol "rh-ssg-accessibility" and replace occurrences with
"docs-tools:rh-ssg-accessibility" in the skill text and cross-reference sections
(e.g., the Precedence line).
| Review documentation for language and grammar issues: abbreviations, capitalization, active voice, inclusive language, pronouns, contractions, and preferred terminology. | ||
|
|
||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `docs-tools:rh-ssg-grammar-and-language` for conscious language and contractions). | ||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `rh-ssg-grammar-and-language` for conscious language and contractions). |
There was a problem hiding this comment.
Critical: Skill reference violates established naming conventions
Removed docs-tools: prefix from skill reference (docs-tools:rh-ssg-grammar-and-language → rh-ssg-grammar-and-language), violating guidelines requiring fully qualified plugin:skill names.
As per coding guidelines: "Always use fully qualified plugin:skill names (for example, docs-tools:jira-reader, vale-tools:lint-with-vale) in agent instructions, Skill invocations, inline text references, and cross-references between skills"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/docs-tools/skills/ibm-sg-language-and-grammar/SKILL.md` at line 11,
The skill reference was changed from the fully-qualified form to an unqualified
name—replace the unqualified reference "rh-ssg-grammar-and-language" with the
fully qualified plugin:skill name "docs-tools:rh-ssg-grammar-and-language"
wherever it appears (specifically in the Precedence line of SKILL.md) so the
documentation and agent instructions follow the required "plugin:skill" naming
convention; ensure any inline text references and cross-references use the
fully-qualified form consistently.
| Review documentation for legal issues: claims and recommendations, company names, trademarks, copyright notices, personal information, and republishing. | ||
|
|
||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `docs-tools:rh-ssg-legal-and-support` for Technology Preview and Developer Preview). | ||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `rh-ssg-legal-and-support` for Technology Preview and Developer Preview). |
There was a problem hiding this comment.
Critical: Skill reference violates established naming conventions
Removed docs-tools: prefix from skill reference (docs-tools:rh-ssg-legal-and-support → rh-ssg-legal-and-support), violating guidelines requiring fully qualified plugin:skill names for cross-references.
As per coding guidelines: "Always use fully qualified plugin:skill names (for example, docs-tools:jira-reader, vale-tools:lint-with-vale) in agent instructions, Skill invocations, inline text references, and cross-references between skills"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/docs-tools/skills/ibm-sg-legal-information/SKILL.md` at line 11, The
skill reference was shortened incorrectly; restore the fully qualified
plugin:skill name by changing the plain reference `rh-ssg-legal-and-support`
back to `docs-tools:rh-ssg-legal-and-support` wherever it appears (e.g., the
line with "Precedence" in SKILL.md) so cross-references adhere to the
established convention for agent instructions, Skill invocations, and inline
references.
| Review documentation for number and measurement issues: numerals vs. words, formatting, currency, dates, times, units, and phone numbers. | ||
|
|
||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `docs-tools:rh-ssg-formatting` for date formats). | ||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `rh-ssg-formatting` for date formats). |
There was a problem hiding this comment.
Critical: Skill reference violates established naming conventions
Removed docs-tools: prefix from skill reference, changing from fully qualified docs-tools:rh-ssg-formatting to bare rh-ssg-formatting. This contradicts guidelines requiring fully qualified plugin:skill names for cross-references.
As per coding guidelines: "Always use fully qualified plugin:skill names (for example, docs-tools:jira-reader, vale-tools:lint-with-vale) in agent instructions, Skill invocations, inline text references, and cross-references between skills"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/docs-tools/skills/ibm-sg-numbers-and-measurement/SKILL.md` at line
11, The skill reference in SKILL.md was changed from the fully qualified form to
a bare name; restore the fully qualified plugin:skill format by replacing
occurrences of "rh-ssg-formatting" with "docs-tools:rh-ssg-formatting" so
cross-references follow the required convention; update the text in SKILL.md
where the Precedence line and any other inline references mention the skill
(look for the token "rh-ssg-formatting") and ensure the fully qualified
"docs-tools:rh-ssg-formatting" is used consistently in agent instructions, Skill
invocations, and cross-references.
| Review documentation for technical element issues: code examples, command line, command syntax, files, keyboard keys, menus, UI elements, and web addresses. | ||
|
|
||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `docs-tools:rh-ssg-technical-examples` for code blocks and IP addresses, `docs-tools:rh-ssg-gui-and-links` for UI elements). | ||
| **Precedence**: For Red Hat documentation, the Red Hat Supplementary Style Guide (SSG) takes precedence over IBM Style Guide rules. Where guidance conflicts, follow the RH SSG skill for that topic (e.g., `rh-ssg-technical-examples` for code blocks and IP addresses, `rh-ssg-gui-and-links` for UI elements). |
There was a problem hiding this comment.
Critical: Skill reference violates established naming conventions
Removed docs-tools: prefix from rh-ssg-technical-examples, violating guidelines requiring fully qualified plugin:skill names for cross-references.
As per coding guidelines: "Always use fully qualified plugin:skill names (for example, docs-tools:jira-reader, vale-tools:lint-with-vale) in agent instructions, Skill invocations, inline text references, and cross-references between skills"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/docs-tools/skills/ibm-sg-technical-elements/SKILL.md` at line 11, The
cross-reference in SKILL.md removed the required plugin prefix and should use
the fully qualified plugin:skill name; restore the "docs-tools:" prefix so
references read "docs-tools:rh-ssg-technical-examples" (and similarly
"docs-tools:rh-ssg-gui-and-links" if present), ensuring all inline text
references, Skill invocations, and cross-references follow the guideline of
using fully qualified plugin:skill names (e.g.,
docs-tools:rh-ssg-technical-examples).
There was a problem hiding this comment.
🧹 Nitpick comments (1)
.coderabbit.yaml (1)
65-73: Tighten enforcement so qualified names are only allowed when disambiguation is actually needed.Line 73 currently only flags slash-command syntax, so
plugin:skillusage can still pass even when no collision exists, which weakens the bare-name standard declared in Line 65-Line 68.Suggested diff
- Flag any use of old slash-command syntax. Do NOT flag bare skill names — they are correct. + Flag: + - Any use of old slash-command syntax + - Any qualified `plugin:skill` reference when no same-name collision exists + + Do NOT flag bare skill names — they are correct. + Allow qualified `plugin:skill` only when disambiguation is required.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.coderabbit.yaml around lines 65 - 73, Update the enforcement that currently only flags slash-command syntax to also reject qualified plugin:skill names unless disambiguation is required: detect occurrences of the pattern `plugin:skill` and, when collecting all skill references, compute bare-name collisions (identical skill after removing `plugin:`); if no collision exists for that bare name, treat the qualified form as invalid and emit a lint error; only permit `plugin:skill` when the same bare name appears from multiple plugins (i.e., a true collision) so the algorithm enforces the bare-name standard described in the "Bare skill names" section and still flags old slash-command syntax.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.coderabbit.yaml:
- Around line 65-73: Update the enforcement that currently only flags
slash-command syntax to also reject qualified plugin:skill names unless
disambiguation is required: detect occurrences of the pattern `plugin:skill`
and, when collecting all skill references, compute bare-name collisions
(identical skill after removing `plugin:`); if no collision exists for that bare
name, treat the qualified form as invalid and emit a lint error; only permit
`plugin:skill` when the same bare name appears from multiple plugins (i.e., a
true collision) so the algorithm enforces the bare-name standard described in
the "Bare skill names" section and still flags old slash-command syntax.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 00b88caa-69a2-4d3d-a05d-76fd7cafbffd
📒 Files selected for processing (2)
.coderabbit.yamlplugins/docs-tools/.claude-plugin/plugin.json
✅ Files skipped from review due to trivial changes (1)
- plugins/docs-tools/.claude-plugin/plugin.json
There was a problem hiding this comment.
🧹 Nitpick comments (2)
adapters/ambient/.claude/skills/batch-controller/SKILL.md (2)
21-33: Add explicit exit code check after setup.sh invocation.The setup.sh invocation doesn't check the exit code before proceeding. While the instruction at line 33 states to stop if symlink generation fails, an explicit exit code check would make the failure detection more robust and immediate.
🔍 Suggested improvement
```bash REPO_ROOT="$(git rev-parse --show-toplevel)" -bash "${REPO_ROOT}/adapters/ambient/setup.sh" +bash "${REPO_ROOT}/adapters/ambient/setup.sh" || { + echo "ERROR: setup.sh failed - cannot proceed without symlinks" + exit 1 +}</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@adapters/ambient/.claude/skills/batch-controller/SKILL.mdaround lines 21 -
33, Add an explicit exit-code check immediately after invoking setup.sh: when
calling bash "${REPO_ROOT}/adapters/ambient/setup.sh" capture its failure and
exit the script (e.g., test the command's exit status with || or an if and call
echo with a clear error message and exit 1). This ensures the subsequent symlink
verification (the ls .claude/skills/ and ls .claude/agents/ checks) is only
reached if setup.sh succeeded and prevents continuing on a failed setup.</details> --- `50-51`: **Consider adding language specifier to silence markdownlint.** The fenced code blocks containing Skill invocations lack language specifiers, triggering markdownlint warnings (MD040). Since these are pseudocode blocks per repository convention rather than executable code, you could optionally add `text` as the language identifier to silence the linter while preserving the special syntax. <details> <summary>📝 Optional fix for markdownlint</summary> ````diff -``` +```text Skill: jira-reader, args: "--jql \"labels = ${DOCS_TRIGGER_LABEL:-ambient-docs-ready}\" --max-results 20"Apply the same pattern to the other two Skill invocation blocks. </details> Also applies to: 56-57, 70-71 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@adapters/ambient/.claude/skills/batch-controller/SKILL.mdaround lines 50 -
51, The fenced code blocks containing Skill invocation lines (for example the
block with "Skill: jira-reader, args: "--jql \"labels =
${DOCS_TRIGGER_LABEL:-ambient-docs-ready}\" --max-results 20"") are missing a
language specifier and trigger markdownlint MD040; update those three fenced
blocks (the one shown plus the blocks at the other two invocation locations) to
start withtext instead ofso the blocks remain pseudocode but the linter
is satisfied.</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@adapters/ambient/.claude/skills/batch-controller/SKILL.md:
- Around line 21-33: Add an explicit exit-code check immediately after invoking
setup.sh: when calling bash "${REPO_ROOT}/adapters/ambient/setup.sh" capture its
failure and exit the script (e.g., test the command's exit status with || or an
if and call echo with a clear error message and exit 1). This ensures the
subsequent symlink verification (the ls .claude/skills/ and ls .claude/agents/
checks) is only reached if setup.sh succeeded and prevents continuing on a
failed setup.- Around line 50-51: The fenced code blocks containing Skill invocation lines
(for example the block with "Skill: jira-reader, args: "--jql \"labels =
${DOCS_TRIGGER_LABEL:-ambient-docs-ready}\" --max-results 20"") are missing a
language specifier and trigger markdownlint MD040; update those three fenced
blocks (the one shown plus the blocks at the other two invocation locations) to
start withtext instead ofso the blocks remain pseudocode but the linter
is satisfied.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro **Run ID**: `a9f49b59-f302-475f-adeb-8fdb31eb11af` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 7135d19bce1638a6af0a8f00b01f4c11c628228f and 475d3b5e794281fd91e47127554283627134fb26. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `adapters/ambient/.claude/skills/batch-controller/SKILL.md` * `adapters/ambient/setup.sh` </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (1)</summary> * adapters/ambient/setup.sh </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
adapters/ambient/CLAUDE.md (1)
44-56: Add language specifiers to code blocks.The code blocks at lines 44-56 (and also at lines 60-66) are missing language specifiers, which markdownlint flags as MD040 warnings. Adding language specifiers improves syntax highlighting and tooling support.
✨ Proposed fix
-``` +```text .claude/docs/ ├── batch-summary.mdApply similar changes to the code blocks in the Configuration section (lines 60-66).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@adapters/ambient/CLAUDE.md` around lines 44 - 56, The fenced code blocks that render the directory trees (the block starting with ".claude/docs/" and the similar block in the Configuration section) are missing language specifiers; update each opening fence to include a language (e.g., use ```text) so the trees become ```text ... ``` which satisfies MD040 and enables proper syntax highlighting and tooling support.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@adapters/ambient/.claude/skills/batch-controller/SKILL.md`:
- Around line 110-114: Update the example table row in
adapters/ambient/.claude/skills/batch-controller/SKILL.md to reflect the actual
output path used by the docs-orchestrator implementation: replace the example
output path string ".claude/docs/drafts/proj-123/" with
".claude/docs/proj-123/writing/" (also align similar examples in
adapters/ambient/CLAUDE.md if present) so the documented example matches the
real behavior from plugins/docs-tools/skills/docs-orchestrator and
plugins/docs-tools/skills/docs-workflow-writing.
- Around line 24-38: setup.sh currently uses ln -sfn for creating symlinks
(lines creating batch-controller and agents links) without validating the source
paths, so broken symlinks can be silently created and SKILL.md's guidance is
misleading; update adapters/ambient/setup.sh to explicitly test each source path
(e.g., the batch-controller plugin directory and any agents plugin dir) with
test -e or [ -d ] before running ln -sfn and call exit 1 with a clear error if a
source is missing, and update SKILL.md verification instructions to validate
symlink targets (e.g., using readlink -f or resolving the symlink and checking
the target exists) rather than only listing symlink names.
In `@adapters/ambient/CLAUDE.md`:
- Around line 67-69: The README line in CLAUDE.md that claims "All skill
references use bare names (no `plugin:skill` prefix)" conflicts with repository
conventions requiring fully qualified names; update the Skill resolution section
(mentioning `.claude/skills/`, `.claude/agents/`, and `setup.sh`) to state that
all skill references must use fully qualified `plugin:skill` names (e.g.,
`docs-tools:jira-reader`, `vale-tools:lint-with-vale`) in agent frontmatter,
Skill invocations, inline references, and cross-references, and adjust any
example text to use the fully qualified form.
- Around line 40-56: Update the "## Output structure" section in
adapters/ambient/CLAUDE.md to match the real output layout used by the
implementation: remove the nonexistent .claude/docs/drafts/<ticket>/ entries and
replace the flat entries with a per-ticket directory .claude/docs/<ticket>/
containing requirements/, planning/, prepare-branch/, writing/ (with _index.md,
assembly_*.adoc, modules/), technical-review/, style-review/, and
workflow/docs-workflow_<ticket>.json, keeping batch-summary.md at the root; use
the actual skills as references (plugins/docs-tools/skills/docs-orchestrator and
plugins/docs-tools/skills/docs-workflow-writing) when editing the documented
structure and example tree under the "Output structure" heading.
---
Nitpick comments:
In `@adapters/ambient/CLAUDE.md`:
- Around line 44-56: The fenced code blocks that render the directory trees (the
block starting with ".claude/docs/" and the similar block in the Configuration
section) are missing language specifiers; update each opening fence to include a
language (e.g., use ```text) so the trees become ```text ... ``` which satisfies
MD040 and enables proper syntax highlighting and tooling support.
🪄 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: fda1c648-fbbe-44f2-ae36-dd78a9b46eb1
📒 Files selected for processing (3)
.ambient/ambient.jsonadapters/ambient/.claude/skills/batch-controller/SKILL.mdadapters/ambient/CLAUDE.md
✅ Files skipped from review due to trivial changes (1)
- .ambient/ambient.json
adapters/ambient/CLAUDE.md
Outdated
Comment on lines
+67
to
+69
| ## Skill resolution | ||
|
|
||
| Skills and agents are loaded via symlinks in `.claude/skills/` and `.claude/agents/` at the repo root. The batch controller runs `setup.sh` at session start to generate these symlinks from the plugin directories. All skill references use bare names (no `plugin:skill` prefix). |
There was a problem hiding this comment.
Naming convention change conflicts with established guidelines.
Line 69 states "All skill references use bare names (no plugin:skill prefix)", which conflicts with multiple retrieved learnings requiring fully qualified plugin:skill names. While the PR objectives indicate this is an intentional standardization to bare names, this creates an inconsistency with the repository's documented conventions.
Based on learnings: "Always use fully qualified plugin:skill names (for example, docs-tools:jira-reader, vale-tools:lint-with-vale) in agent instructions, Skill invocations, inline text references, and cross-references between skills" and "All skill references must use fully qualified plugin:skill names everywhere - in agent frontmatter, Skill tool invocations, inline text references, and cross-references".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@adapters/ambient/CLAUDE.md` around lines 67 - 69, The README line in
CLAUDE.md that claims "All skill references use bare names (no `plugin:skill`
prefix)" conflicts with repository conventions requiring fully qualified names;
update the Skill resolution section (mentioning `.claude/skills/`,
`.claude/agents/`, and `setup.sh`) to state that all skill references must use
fully qualified `plugin:skill` names (e.g., `docs-tools:jira-reader`,
`vale-tools:lint-with-vale`) in agent frontmatter, Skill invocations, inline
references, and cross-references, and adjust any example text to use the fully
qualified form.
aireilly
reviewed
Apr 4, 2026
aireilly
approved these changes
Apr 4, 2026
mcljot
commented
Apr 5, 2026
| load_env_file() | ||
|
|
||
| token = os.environ.get('JIRA_AUTH_TOKEN') | ||
| token = os.environ.get('JIRA_API_TOKEN') or os.environ.get('JIRA_AUTH_TOKEN') |
Collaborator
Author
There was a problem hiding this comment.
@aireilly this PR changes the expected variable for Jira authentication. s/JIRA_AUTH_TOKEN/JIRA_API_TOKEN cause that's native ACP variable. Would need users to make the adjustment in their ~/.env
Member
There was a problem hiding this comment.
It's a fallback, so users wouldn't need to do anything?
Add Ambient Code Platform integration for headless, scheduled documentation pipeline sessions. New ACP infrastructure: - .ambient/ambient.json — session manifest with systemPrompt, startupPrompt, and results globs - .claude/skills/batch-controller/ — headless batch entry point - adapters/ambient/CLAUDE.md — ACP operational guidelines - adapters/ambient/setup.sh — environment bootstrap - adapters/ambient/scripts/ — repo-setup, repo-publish, batch-progress - adapters/ambient/hooks/ — batch-completion stop hook - adapters/ambient/repo-mapping.yaml — JIRA project to repo mapping Skill/agent/reference resolution: - Pre-committed symlinks in .claude/skills/, .claude/agents/, and .claude/reference/ pointing to plugin directories - .claude/docs-workflow.yaml — headless 5-step workflow variant - .gitignore updated to track .claude/ symlinks while ignoring other .claude/ contents Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Modify existing plugin files to work in both CLI and headless ACP contexts: Auth portability: - Rename JIRA_AUTH_TOKEN to JIRA_API_TOKEN (matching ACP convention), with backward-compatible fallback in all scripts - Add auth fallback blocks in agents Output path migration: - Change hardcoded .claude/docs/ paths to artifacts/ Subagent dispatch enforcement: - Add "You MUST use the Agent tool" to step skills Orchestrator improvements: - Add --repo-path flag for targeting external repo clones - Resolve base_path to absolute for agent CWD compatibility - Move --format to always-passed base args - Add prerequisite docs for jira-reader Python dependencies Label management: - Add --labels-add/--labels-remove to jira_writer.py Stop hook fix: - Per-workflow stop counter (prevents cross-ticket interference) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
These skills were added on main in PR #72 (docs-review-e2e refactor) and need .claude/skills/ symlinks for ACP skill discovery. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add scripts/sync-claude-symlinks.sh to auto-discover plugin skills/agents/references and sync symlinks in .claude/. Includes --check mode for PR validation. Add GitHub Actions workflow that validates on PRs and auto-commits on merge to main. Also commits 48 previously missing symlinks for dita-tools, cqa-tools, jtbd-tools, and hello-world plugin skills/references. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace scripts/jira_writer.py with ${CLAUDE_SKILL_DIR}/scripts/jira_writer.py
in label operation examples so they resolve correctly on ACP.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Rename .claude/docs-workflow.yaml to .claude/docs-acp.yaml with --workflow acp invocation; clarifies this is the headless ACP variant - Fix orchestrator: --format only passed to writing and style-review steps, not all steps (planning/requirements/tech-review don't use it) - Delete orphaned docs-workflow-create-pr directories (stale __pycache__ from unmerged commit-analyst branch) - Add explanatory comments to .gitignore for .claude/* exceptions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Bug fixes: - Fix format mismatch: asciidoc → adoc in repo-mapping.yaml + normalization in repo-setup.sh - Fix push failure on existing remote branch by fetching before --force-with-lease in repo-publish.sh - Fix working directory drift with explicit cd-back instructions in batch-controller New adapter scripts (replacing LLM-driven logic): - repo-create-mr.sh: deterministic MR/PR creation for GitLab and GitHub - batch-find-tickets.sh: ticket discovery with orphaned label recovery, auto-discovers jira_reader.py path, handles single-result JSON output - resolve-repo-context.sh: translates repo-info.json into orchestrator flags Plugin improvements (self-contained, no adapter dependencies): - Tech review early-exit when MEDIUM with zero critical/significant issues - SME verification section added to technical-reviewer output template - Orchestrator skips preflight when setup sentinel exists Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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.
Summary
Add Ambient Code Platform (ACP) integration to run the docs-tools pipeline as scheduled, headless sessions. ACP sessions scrape JIRA for tickets
labeled
ambient-docs-ready, claim them immediately (preventing double-processing by overlapping sessions), run each through the full documentationworkflow, and optionally clone target repos, push feature branches, and create merge requests.
The 35 symlinks in
.claude/skills/,.claude/agents/, and.claude/reference/are pointers to plugin directories — not copies. They allow ACP todiscover skills at startup without runtime copying.
Commits
1. Add ACP adapter, batch controller, and session configuration
New ACP infrastructure:
.ambient/ambient.json.claude/skills/batch-controller/SKILL.mdadapters/ambient/CLAUDE.mdadapters/ambient/setup.sh.claude/docs-workflow.yamladapters/ambient/repo-mapping.yaml.claude/skills/*(35 symlinks)plugins/*/skills/.claude/agents/*(5 symlinks)plugins/docs-tools/agents/.claude/reference/*(4 symlinks)2. Add repo integration: clone, publish, MR/PR
adapters/ambient/scripts/repo-setup.shrepo-info.jsonadapters/ambient/scripts/repo-publish.shpublish-info.json3. Align plugin code with ACP and platform conventions
Modifies 29 existing files under
plugins/docs-tools/. Every change serves one of:JIRA_AUTH_TOKEN→JIRA_API_TOKEN(with backward fallback), add MCP-first auth with 3-step fallback in all agents.claude/docs/→artifacts/(matching ACP platform convention)--repo-pathflag, absolutebase_pathresolution,--formatas global base argLabel lifecycle
ambient-docs-ready → ticket awaiting processing
ambient-docs-processing → ticket claimed by a session
ambient-docs-generated → pipeline completed (terminal)
ambient-docs-failed → pipeline failed (terminal)
Test plan
bash adapters/ambient/setup.sh— verify symlink check, credential mapping, pip installbash adapters/ambient/scripts/repo-setup.sh VROOM-999 --dry-run— verify repo resolutionbash adapters/ambient/scripts/repo-publish.sh VROOM-999 --dry-run— verify manifest parsing/docs-orchestrator PROJ-123in CLI — verify no regressionpython3 -c "import json; json.load(open('.ambient/ambient.json'))"— valid JSONls -la .claude/skills/ | head -5— verify symlinks resolveSummary by CodeRabbit
New Features
Documentation
Chores