refactor(skills): convert index-docs.xml to native skill directory

[alexeyv]

Summary

• Converts index-docs.xml into a native skill directory at src/core/tasks/bmad-index-docs/
• Updates parent manifest and module-help.csv references
• Deletes the legacy XML file

Test plan

• Run installer and verify bmad-index-docs is discovered as a skill
• Confirm no remaining references to index-docs.xml

🤖 Generated with Claude Code

[github-actions]

@coderabbitai review

[augmentcode]

🤖 Augment PR Summary

Summary: Migrates the legacy index-docs.xml task into a native skill directory for consistent skill discovery.

Changes: Adds src/core/tasks/bmad-index-docs/ with SKILL.md, workflow.md, and bmad-skill-manifest.yaml (type: skill).

Removes the index-docs.xml entry from the parent src/core/tasks/bmad-skill-manifest.yaml.

Deletes the old src/core/tasks/index-docs.xml definition.

Updates module-help / manifest references to use the new skill location (per PR).

Notes: Behavior/instructions are preserved in Markdown (execution steps, output format, halt conditions, validation).

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. No suggestions at this time.

Comment augment review to trigger a new review at any time.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR migrates the XML-based "Index Docs" task into a native skill format by introducing a new bmad-index-docs directory with Markdown and YAML files, while removing the legacy XML task definition and its registration from the core manifest.

Changes

Cohort / File(s)	Summary
New bmad-index-docs skill src/core/tasks/bmad-index-docs/SKILL.md, src/core/tasks/bmad-index-docs/bmad-skill-manifest.yaml, src/core/tasks/bmad-index-docs/workflow.md	Introduces new skill implementation with metadata, manifest declaration, and detailed workflow instructions for generating or updating directory index documentation.
Legacy task removal src/core/tasks/bmad-skill-manifest.yaml, src/core/tasks/index-docs.xml	Removes old XML task entry from core manifest and deletes the complete XML task definition file.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• bmad-code-org/BMAD-METHOD#1868: Refactors SKILL.md as the canonical skill entrypoint, aligning with this PR's introduction of SKILL.md-based skills.
• bmad-code-org/BMAD-METHOD#1857: Performs the same XML-to-skill conversion pattern with workflow.md and manifest updates for a different task.
• bmad-code-org/BMAD-METHOD#1871: Executes identical conversion from XML task to native skill directory structure with matching file additions and manifest cleanup.

Suggested reviewers

• bmadcode

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: converting index-docs.xml from XML format to a native skill directory structure.
Description check	✅ Passed	The description is directly related to the changeset, explaining the conversion of index-docs.xml to a native skill directory and related updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 10

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/core/tasks/bmad-index-docs/SKILL.md`:
- Line 3: The SKILL.md description claims it "references all docs in the folder"
but the workflow (src/core/tasks/bmad-index-docs/workflow.md) actually scans
files and subdirectories and may include non‑Markdown filenames; update SKILL.md
frontmatter to accurately reflect the workflow behavior (either change the
description to say it "generates/updates an index of files and subdirectories"
or narrow the workflow to only include documentation files), and make the
corresponding change in workflow.md or the scanning logic so both SKILL.md and
workflow.md agree; reference SKILL.md and workflow.md when making the edits to
ensure the advertised scope and actual scanning logic match.
- Line 3: The skill description in SKILL.md currently mandates a specific folder
but doesn't instruct what to do if the user doesn't provide one; update the
description and agent behavior so that when the folder is not specified the
agent prompts a clarifying question (e.g., "Which folder should I index? Please
provide a path or confirm current directory") and offers sensible defaults
(current directory or root) and confirmation before proceeding to
generate/update index.md; reference the description string and the index.md
generation flow to add this prompt and default-handling logic.
- Line 6: The body of SKILL.md is missing the critical precondition that the
user must specify a target folder (the frontmatter key indicating the folder to
operate on); update the body of src/core/tasks/bmad-index-docs/SKILL.md to
explicitly state that the user must identify and provide the target folder
(e.g., “Specify the target folder in the frontmatter as `target_folder:
<path>`”), so the operational instruction is not hidden in descriptive text and
the invocation contract matches the frontmatter requirement.

In `@src/core/tasks/bmad-index-docs/workflow.md`:
- Around line 48-51: Update the HALT CONDITIONS section under "HALT CONDITIONS"
to include a check for a missing target (e.g., add a bullet "HALT if no target
directory provided or empty"); ensure the implementation that reads the target
(the code path that validates the directory input referenced by these bullets)
explicitly validates for undefined/empty input before attempting to access the
filesystem, and treat that case as a hard halt with a clear error message to
prevent the agent from inventing a path.
- Around line 8-10: Update the "Step 1: Scan Directory" description to
explicitly state the recursion rule used by the workflow: indicate whether
scanning is recursive (e.g., "recursively list all files and subdirectories"),
how deep it goes (unlimited or N levels), and how to handle hidden files,
symlinks, and exclusions (e.g., ignore .git and node_modules). Reference the
"Step 1: Scan Directory" heading in workflow.md and add a concise sentence
specifying the chosen behavior so implementations produce consistent indexes for
nested subdirectories.
- Around line 56-61: The validation currently excludes only files whose names
start with "." but not hidden directories, so update the scanning/filtering
logic used in "Step 1" to skip any path that contains a directory segment
beginning with "." (e.g., .git, .obsidian); ensure the file-filter or glob
excludes hidden directories (check the function or routine that walks
subdirectories in the Step 1 implementation) by checking each path segment for a
leading "." and ignoring those entire directory trees before reading files,
while leaving the other rules (relative ./ paths, grouping, description
generation, alphabetical sorting) intact.
- Around line 57-60: The workflow currently sorts files within groups but never
defines the order of the groups themselves, making output nondeterministic; fix
by deterministically ordering the groups (e.g., sort the array of group keys
alphabetically) before any iteration/serialization so the top-level groups are
stable across runs; locate the grouping implementation (functions likely named
groupFiles, buildGroups, or generateWorkflow) and insert an alphabetical sort of
the group names/keys prior to emitting or iterating over the groups.
- Around line 20-22: The Step 4 "Create/Update Index" logic currently writes
index.md but does not exclude that generated file from the listing; update the
workflow so when building the file list for writing/updating index.md it filters
out any entry whose filename or path equals "index.md" (or the exact target name
used by the workflow) to avoid self-inclusion and make the process idempotent;
ensure this exclusion is applied wherever the listing is computed in the
"Create/Update Index" step so the freshly written index.md is never added to its
own contents.
- Around line 20-22: Clarify and implement explicit update semantics for "Step
4: Create/Update Index" regarding index.md: specify whether the skill will
replace the entire index.md, preserve handwritten sections, or update only a
designated managed block, and update the workflow text accordingly;prefer adding
clear managed-block markers (e.g., <!-- BEGIN MANAGED INDEX --> / <!-- END
MANAGED INDEX -->) and state that only content inside that block will be
regenerated while everything outside is preserved, and include instructions for
idempotent reruns and how conflicts are handled so manual content isn't
accidentally overwritten.
- Line 18: Update the step that currently says "Read each file to understand its
actual purpose..." to only attempt content reads for defined supported text
types (e.g., .txt, .md, .html, .json, .csv) and add a clear fallback path for
other or unreadable files (e.g., treat images/binaries/PDFs as
"binary/preview-only" with a note, skip very large files above a size threshold,
or extract metadata only). Mention the supported types list, a max file-size
limit, and the fallback behavior for unreadable/non-text content so the workflow
does not attempt to read every discovered file.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8d4e4b5f-d291-4ceb-817d-1d5d1bdce94b

📥 Commits

Reviewing files that changed from the base of the PR and between 956c43f and 9bc208f.

⛔ Files ignored due to path filters (1)

• src/core/module-help.csv is excluded by !**/*.csv

📒 Files selected for processing (5)

• src/core/tasks/bmad-index-docs/SKILL.md
• src/core/tasks/bmad-index-docs/bmad-skill-manifest.yaml
• src/core/tasks/bmad-index-docs/workflow.md
• src/core/tasks/bmad-skill-manifest.yaml
• src/core/tasks/index-docs.xml

💤 Files with no reviewable changes (2)

• src/core/tasks/bmad-skill-manifest.yaml
• src/core/tasks/index-docs.xml