feat: add docs-workflow-start interactive launcher skill#95
Merged
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:
WalkthroughAdds an interactive skill Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Skill as "docs-workflow-start"
participant Ask as "AskUserQuestion"
participant Resolver as "resolve_steps.py"
participant Orchestrator as "docs-orchestrator"
User->>Skill: Invoke (ticket only) or with flags
Skill->>Skill: Detect pass-through vs interactive
alt Pass-through (flags present)
Skill->>Orchestrator: Forward original args
else Interactive (no flags)
Skill->>Ask: Round 1 (format, source, placement, JIRA)
Ask-->>Skill: Answers
Skill->>Ask: Round 2 conditional follow-ups
Ask-->>Skill: Additional inputs
Skill->>Skill: Map answers → orchestrator flags
alt Full workflow
Skill->>Orchestrator: Execute with mapped flags
else Specific step(s)
Skill->>Resolver: Request execution plan (workflow YAML, steps)
Resolver-->>Skill: JSON plan (execution_plan, prereq, artifacts)
Skill->>Skill: Evaluate `when` conditions & select steps
loop For each selected step
Skill->>Skill: Invoke step skill
Skill->>Skill: Verify expected output dir exists
end
else Resume run
Skill->>Orchestrator: Execute with ticket ID only
end
end
Skill-->>User: Report completed and skipped steps
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 (2 errors, 1 warning)
✅ 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: 3
🧹 Nitpick comments (1)
plugins/docs-tools/skills/docs-workflow-start/SKILL.md (1)
25-301: Consider moving most branching/validation flow into a helper script.This file currently carries substantial procedural orchestration logic inline. A script-backed planner/executor (JSON out, errors to stderr) would make this skill easier to test and maintain while keeping
SKILL.mdfocused on invocation and user-facing behavior.Based on learnings, “Do NOT embed procedural logic (conditionals, path construction, validation) inline in SKILL.md. If a skill needs to make decisions before dispatching an agent, defer that logic to a script that emits structured output.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/skills/docs-workflow-start/SKILL.md` around lines 25 - 301, The SKILL.md currently embeds procedural orchestration (sections like "Determine mode", "Compute execution plan", "Resolve base path", "Evaluate `when` conditions", and "Run steps sequentially"); factor that logic into a helper script (e.g., a new CLI script like docs_workflow_planner.py or a shell script) that: accepts the raw args/ticket, performs branching/validation (mode detection, base-path/YAML resolution, dependency resolution, `when` evaluation, artifact checks), and emits a structured JSON plan to stdout and errors to stderr (matching the existing contract used by resolve_steps.py); then simplify SKILL.md to describe user-facing behavior and show invoking the helper script (Skill: docs-tools:docs-orchestrator, args: "PROJ-123 <flags>") plus how to interpret the planner's JSON output. Ensure references to the existing resolver (resolve_steps.py) are preserved or called from the new helper where appropriate.
🤖 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/skills/docs-workflow-start/scripts/resolve_steps.py`:
- Around line 101-120: The resolver currently silently ignores unknown
dependency names (in resolve_transitive_deps), which hides typos and produces
invalid plans; update the walker so that when a dependency/step name referenced
in step_map[name]["inputs"] is missing from step_map it immediately raises a
JSON-serializable error (include the missing dependency name and the step that
referenced it) instead of returning early; apply the identical check & error
behavior to the other dependency resolver block referenced in the review (the
similar logic at lines ~142-159) so all invalid inputs fail fast with a clear
JSON error payload.
In `@plugins/docs-tools/skills/docs-workflow-start/SKILL.md`:
- Around line 270-277: The Step flag matrix in SKILL.md is missing the --repo
flag for the requirements and writing steps; update the table rows for the
"requirements" and "writing" steps to include `--repo <repo_path>` (e.g., make
requirements show `[--pr <url>]... --repo <repo_path>` and writing show
`--format <adoc|mkdocs> --repo <repo_path> [--draft]`) so the per-step contract
matches the orchestrator's documented contract for those steps and preserves
source-repo context.
- Line 29: Update the fenced code blocks in SKILL.md to include language
identifiers so Markdown linter MD040 passes; specifically annotate the example
blocks containing the "Skill: ..." pseudo-invocations with ```text (or ```bash
where a shell command is shown) — update the occurrences that show examples like
"Skill: docs-tools:docs-orchestrator, args: \"<all original args>\"", "Skill:
docs-tools:docs-orchestrator, args: \"<ticket>\"", "Skill:
docs-tools:docs-orchestrator, args: \"<ticket> <constructed flags>\"", "Skill:
docs-tools:docs-orchestrator, args: \"PROJ-123 --mkdocs --pr
https://github.com/org/repo/pull/42 --draft\"" and "Skill: <step.skill>, args:
\"<ticket> --base-path <BASE_PATH> <step-specific-flags>\"" by adding the
appropriate language tag after the opening backticks.
---
Nitpick comments:
In `@plugins/docs-tools/skills/docs-workflow-start/SKILL.md`:
- Around line 25-301: The SKILL.md currently embeds procedural orchestration
(sections like "Determine mode", "Compute execution plan", "Resolve base path",
"Evaluate `when` conditions", and "Run steps sequentially"); factor that logic
into a helper script (e.g., a new CLI script like docs_workflow_planner.py or a
shell script) that: accepts the raw args/ticket, performs branching/validation
(mode detection, base-path/YAML resolution, dependency resolution, `when`
evaluation, artifact checks), and emits a structured JSON plan to stdout and
errors to stderr (matching the existing contract used by resolve_steps.py); then
simplify SKILL.md to describe user-facing behavior and show invoking the helper
script (Skill: docs-tools:docs-orchestrator, args: "PROJ-123 <flags>") plus how
to interpret the planner's JSON output. Ensure references to the existing
resolver (resolve_steps.py) are preserved or called from the new helper where
appropriate.
🪄 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 Plus
Run ID: e518ad8e-1db1-473f-80ec-824dcebb5777
📒 Files selected for processing (3)
plugins/docs-tools/.claude-plugin/plugin.jsonplugins/docs-tools/skills/docs-workflow-start/SKILL.mdplugins/docs-tools/skills/docs-workflow-start/scripts/resolve_steps.py
Parses the workflow YAML without PyYAML, walks the inputs graph to compute transitive dependencies, checks for existing artifacts, and emits a JSON execution plan. Part of #92 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
New skill that uses AskUserQuestion to gather workflow configuration when invoked without CLI switches. Supports full workflow, individual steps with automatic dependency resolution, and resume. Part of #92 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
aireilly
force-pushed
the
feat/docs-workflow-start
branch
from
66abe38 to
d5eed58
Compare
The AskUserQuestion interaction for missing PR/repo broke scripted/CI/ambient execution modes. Now skips code-evidence directly with a log message suggesting --repo or --pr flags. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
The table still said "Prompt the user" for the no_source case after the prompt was removed. Updated to "Skip code-evidence". Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
There was a problem hiding this comment.
🧹 Nitpick comments (1)
plugins/docs-tools/skills/docs-workflow-start/SKILL.md (1)
3-3: Consider qualifying the skill name in the description.The description references "docs-orchestrator" without the
docs-tools:prefix. Based on learnings, inline text references to skills should use fully qualifiedplugin:skillnames for consistency and to avoid ambiguity.📝 Proposed refinement
-description: Interactive entry point for the docs workflow. When invoked with no CLI switches, uses AskUserQuestion to gather configuration. Supports full workflow, individual steps with auto-resolved prerequisites, and resuming previous runs. When switches are provided, passes through directly to docs-orchestrator. +description: Interactive entry point for the docs workflow. When invoked with no CLI switches, uses AskUserQuestion to gather configuration. Supports full workflow, individual steps with auto-resolved prerequisites, and resuming previous runs. When switches are provided, passes through directly to docs-tools:docs-orchestrator.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/docs-tools/skills/docs-workflow-start/SKILL.md` at line 3, The description string should use the fully qualified plugin:skill name for the referenced skill; update the description in SKILL.md to replace the bare "docs-orchestrator" reference with "docs-tools:docs-orchestrator" (keep the rest of the sentence intact) so inline references follow the plugin:skill convention.
🤖 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/skills/docs-workflow-start/SKILL.md`:
- Line 3: The description string should use the fully qualified plugin:skill
name for the referenced skill; update the description in SKILL.md to replace the
bare "docs-orchestrator" reference with "docs-tools:docs-orchestrator" (keep the
rest of the sentence intact) so inline references follow the plugin:skill
convention.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 5128cb5d-64e1-4a6a-a60e-3c23d38451d5
📒 Files selected for processing (3)
plugins/docs-tools/.claude-plugin/plugin.jsonplugins/docs-tools/skills/docs-workflow-start/SKILL.mdplugins/docs-tools/skills/docs-workflow-start/scripts/resolve_steps.py
✅ 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)
- plugins/docs-tools/skills/docs-workflow-start/scripts/resolve_steps.py
rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Silent skip of missing input deps could mask typos (e.g. inputs: [planing]). Now emits an explicit JSON error before resolving steps. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Remove docs-tools: prefix from Skill references (bare names resolve within the same plugin). Replace parent-traversal CLAUDE_SKILL_DIR/../ with CLAUDE_PLUGIN_ROOT for cross-skill docs-orchestrator YAML path. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Aidan Reilly <aireilly@redhat.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
aireilly
force-pushed
the
feat/docs-workflow-start
branch
from
5cb31a9 to
e3e6418
Compare
… steps The step flag matrix was missing --repo for requirements and writing, causing the per-step contract to diverge from the orchestrator's documented contract. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
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
1 participant
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
docs-workflow-startskill — interactive entry point for the docs workflowAskUserQuestionto gather configuration when no CLI switches are providedresolve_steps.pydocs-orchestratorunchangedCloses #92
New files
plugins/docs-tools/skills/docs-workflow-start/SKILL.mdplugins/docs-tools/skills/docs-workflow-start/scripts/resolve_steps.pyHow it works
Interactive mode (no switches): 3 rounds of AskUserQuestion
Pass-through mode (any
--switch present): forwards directly todocs-orchestratorSpecific steps: resolves transitive dependencies automatically. If user asks for
writing, the resolver includesrequirements → planning → prepare-branchas prerequisites. Existing artifacts from prior runs trigger a smart confirmation prompt.Test plan
docs-workflow-startwith no args — verify AskUserQuestion flow triggersdocs-workflow-start PROJ-123 --mkdocs— verify pass-through to orchestrator (no AskUserQuestion)resolve_steps.py --steps bogus-step— verify error with valid step listresolve_steps.py --steps writing --base-path <path-with-existing-artifacts>— verifysteps_with_artifactspopulated🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Chores