build updates

bmad-core/tasks/create-uxui-spec.md

@@ -1,95 +0,0 @@
-# Create UI/UX Specification Task
-
-## Purpose
-
-To collaboratively work with the user to define and document the User Interface (UI) and User Experience (UX) specifications for the project. This involves understanding user needs, defining information architecture, outlining user flows, and ensuring a solid foundation for visual design and frontend development. The output will populate a new document called `front-end-spec.md` following the `front-end-spec-tmpl` template.
-
-## Inputs
-
-- Project Brief (`project-brief.md` or equivalent)
-- Product Requirements Document (PRD) (`prd.md` or equivalent)
-- User feedback or research (if available)
-
-## Key Activities & Instructions
-
-### 1. Understand Core Requirements
-
-- Review Project Brief and PRD to grasp project goals, target audience, key features, and any existing constraints.
-- Ask clarifying questions about user needs, pain points, and desired outcomes.
-
-### 2. Define Overall UX Goals & Principles (for `front-end-spec-tmpl`)
-
-- Collaboratively establish and document:
-  - Target User Personas (elicit details or confirm existing ones).
-  - Key Usability Goals.
-  - Core Design Principles for the project.
-
-### 3. Develop Information Architecture (IA) (for `front-end-spec-tmpl`)
-
-- Work with the user to create a Site Map or Screen Inventory.
-- Define the primary and secondary Navigation Structure.
-- Use Mermaid diagrams or lists as appropriate for the template.
-
-### 4. Outline Key User Flows (for `front-end-spec-tmpl`)
-
-- Identify critical user tasks from the PRD/brief.
-- For each flow:
-  - Define the user's goal.
-  - Collaboratively map out the steps (use Mermaid diagrams or detailed step-by-step descriptions).
-  - Consider edge cases and error states.
-
-### 5. Discuss Wireframes & Mockups Strategy (for `front-end-spec-tmpl`)
-
-- Clarify where detailed visual designs will be created (e.g., Figma, Sketch) and ensure the `front-end-spec-tmpl` correctly links to these primary design files.
-- If low-fidelity wireframes are needed first, offer to help conceptualize layouts for key screens.
-
-### 6. Define Component Library / Design System Approach (for `front-end-spec-tmpl`)
-
-- Discuss if an existing design system will be used or if a new one needs to be developed.
-- If new, identify a few foundational components to start with (e.g., Button, Input, Card) and their key states/behaviors at a high level. Detailed technical specs will be in `front-end-architecture`.
-
-### 7. Establish Branding & Style Guide Basics (for `front-end-spec-tmpl`)
-
-- If a style guide exists, link to it.
-- If not, collaboratively define placeholders for: Color Palette, Typography, Iconography, Spacing.
-
-### 8. Specify Accessibility (AX) Requirements (for `front-end-spec-tmpl`)
-
-- Determine the target compliance level (e.g., WCAG 2.1 AA).
-- List any known specific AX requirements.
-
-### 9. Define Responsiveness Strategy (for `front-end-spec-tmpl`)
-
-- Discuss and document key Breakpoints.
-- Describe the general Adaptation Strategy.
-
-### 10. Output Generation & Iterative Refinement (Guided by `front-end-spec-tmpl`)
-
-- **a. Draft Section:** Incrementally populate one logical section of the `front-end-spec-tmpl` file based on your discussions.
-- **b. Present & Incorporate Initial Feedback:** Present the drafted section to the user for review. Discuss, explain and incorporate their initial feedback and revisions directly.
-- **c. [Offer Advanced Self-Refinement & Elicitation Options](#offer-advanced-self-refinement--elicitation-options)**
-
-## Offer Advanced Self-Refinement & Elicitation Options
-
-(This section is called when needed prior to this)
-
-Present the user with the following list of 'Advanced Reflective, Elicitation & Brainstorming Actions'. Explain that these are optional steps to help ensure quality, explore alternatives, and deepen the understanding of the current section before finalizing it and moving on. The user can select an action by number, or choose to skip this and proceed to finalize the section.
-
-"To ensure the quality of the current section: **[Specific Section Name]** and to ensure its robustness, explore alternatives, and consider all angles, I can perform any of the following actions. Please choose a number (8 to finalize and proceed):
-
-**Advanced Reflective, Elicitation & Brainstorming Actions I Can Take:**
-
-{Instruction for AI Agent: Display the title of each numbered item below. If the user asks what a specific option means, provide a brief explanation of the action you will take, drawing from detailed descriptions tailored for the context.}
-
-1.  **Critical Self-Review & User Goal Alignment**
-2.  **Generate & Evaluate Alternative Design Solutions**
-3.  **User Journey & Interaction Stress Test (Conceptual)**
-4.  **Deep Dive into Design Assumptions & Constraints**
-5.  **Usability & Accessibility Audit Review & Probing Questions**
-6.  **Collaborative Ideation & UI Feature Brainstorming**
-7.  **Elicit 'Unforeseen User Needs' & Future Interaction Questions**
-8.  **Finalize this Section and Proceed.**
-
-After I perform the selected action, we can discuss the outcome and decide on any further revisions for this section."
-
-REPEAT by Asking the user if they would like to perform another Reflective, Elicitation & Brainstorming Action UNIT the user indicates it is time to proceed ot the next section (or selects #8)

bmad-core/tasks/index-docs.md

@@ -1,12 +1,12 @@
-# Library Indexing Task
+# Index Documentation Task
 
 ## Purpose
 
-This task maintains the integrity and completeness of the `docs/index.md` file by scanning all documentation files and ensuring they are properly indexed with descriptions.
+This task maintains the integrity and completeness of the `docs/index.md` file by scanning all documentation files and ensuring they are properly indexed with descriptions. It handles both root-level documents and documents within subfolders, organizing them hierarchically.
 
 ## Task Instructions
 
-You are now operating as a Documentation Indexer. Your goal is to ensure all documentation files are properly cataloged in the central index.
+You are now operating as a Documentation Indexer. Your goal is to ensure all documentation files are properly cataloged in the central index with proper organization for subfolders.
 
 ### Required Steps
 
@@ -15,6 +15,7 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc
    - The `docs/` directory and all subdirectories
    - The existing `docs/index.md` file (create if absent)
    - All markdown (`.md`) and text (`.txt`) files in the documentation structure
+   - Note the folder structure for hierarchical organization
 
 2. For the existing `docs/index.md`:
 
@@ -22,6 +23,7 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc
    - Note existing file references and descriptions
    - Identify any broken links or missing files
    - Keep track of already-indexed content
+   - Preserve existing folder sections
 
 3. For each documentation file found:
 
@@ -29,6 +31,7 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc
    - Generate a brief description by analyzing the content
    - Create a relative markdown link to the file
    - Check if it's already in the index
+   - Note which folder it belongs to (if in a subfolder)
    - If missing or outdated, prepare an update
 
 4. For any missing or non-existent files found in index:
@@ -42,14 +45,54 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc
 
 5. Update `docs/index.md`:
    - Maintain existing structure and organization
+   - Create level 2 sections (`##`) for each subfolder
+   - List root-level documents first
    - Add missing entries with descriptions
    - Update outdated entries
    - Remove only entries that were confirmed for removal
    - Ensure consistent formatting throughout
 
+### Index Structure Format
+
+The index should be organized as follows:
+
+```markdown
+# Documentation Index
+
+## Root Documents
+
+### [Document Title](./document.md)
+
+Brief description of the document's purpose and contents.
+
+### [Another Document](./another.md)
+
+Description here.
+
+## Folder Name
+
+Documents within the `folder-name/` directory:
+
+### [Document in Folder](./folder-name/document.md)
+
+Description of this document.
+
+### [Another in Folder](./folder-name/another.md)
+
+Description here.
+
+## Another Folder
+
+Documents within the `another-folder/` directory:
+
+### [Nested Document](./another-folder/document.md)
+
+Description of nested document.
+```
+
 ### Index Entry Format
 
-Each entry in `docs/index.md` should follow this format:
+Each entry should follow this format:
 
 ```markdown
 ### [Document Title](relative/path/to/file.md)
@@ -62,24 +105,28 @@ Brief description of the document's purpose and contents.
 1. NEVER modify the content of indexed files
 2. Preserve existing descriptions in index.md when they are adequate
 3. Maintain any existing categorization or grouping in the index
-4. Use relative paths for all links
+4. Use relative paths for all links (starting with `./`)
 5. Ensure descriptions are concise but informative
 6. NEVER remove entries without explicit confirmation
 7. Report any broken links or inconsistencies found
 8. Allow path updates for moved files before considering removal
+9. Create folder sections using level 2 headings (`##`)
+10. Sort folders alphabetically, with root documents listed first
+11. Within each section, sort documents alphabetically by title
 
 ### Process Output
 
 The task will provide:
 
 1. A summary of changes made to index.md
-2. List of newly indexed files
+2. List of newly indexed files (organized by folder)
 3. List of updated entries
 4. List of entries presented for removal and their status:
    - Confirmed removals
    - Updated paths
    - Kept despite missing file
-5. Any other issues or inconsistencies found
+5. Any new folders discovered
+6. Any other issues or inconsistencies found
 
 ### Handling Missing Files
 
@@ -92,6 +139,7 @@ For each file referenced in the index but not found in the filesystem:
    Title: [Document Title]
    Path: relative/path/to/file.md
    Description: Existing description
+   Section: [Root Documents | Folder Name]
 
    Options:
 
@@ -105,13 +153,25 @@ For each file referenced in the index but not found in the filesystem:
 2. Wait for user confirmation before taking any action
 3. Log the decision for the final report
 
+### Special Cases
+
+1. **Sharded Documents**: If a folder contains an `index.md` file, treat it as a sharded document:
+   - Use the folder's `index.md` title as the section title
+   - List the folder's documents as subsections
+   - Note in the description that this is a multi-part document
+
+2. **README files**: Convert `README.md` to more descriptive titles based on content
+
+3. **Nested Subfolders**: For deeply nested folders, maintain the hierarchy but limit to 2 levels in the main index. Deeper structures should have their own index files.
+
 ## Required Input
 
 Please provide:
 
-1. Location of the `docs/` directory
+1. Location of the `docs/` directory (default: `./docs`)
 2. Confirmation of write access to `docs/index.md`
 3. Any specific categorization preferences
-4. Any files or directories to exclude from indexing
+4. Any files or directories to exclude from indexing (e.g., `.git`, `node_modules`)
+5. Whether to include hidden files/folders (starting with `.`)
 
-Would you like to proceed with library indexing? Please provide the required input above.
+Would you like to proceed with documentation indexing? Please provide the required input above.