aios-core 2.1.0

package/.aios-core/development/tasks/index-docs.md

@@ -0,0 +1,388 @@
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: indexDocs()
+responsável: Morgan (Strategist)
+responsavel_type: Agente
+atomic_layer: Molecule
+
+**Entrada:**
+- campo: source
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid path or URL
+
+- campo: format
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: markdown|html|json
+
+- campo: template
+  tipo: string
+  origem: config
+  obrigatório: false
+  validação: Template name
+
+**Saída:**
+- campo: generated_doc
+  tipo: string
+  destino: File (docs/*)
+  persistido: true
+
+- campo: metadata
+  tipo: object
+  destino: File (frontmatter)
+  persistido: true
+
+- campo: toc
+  tipo: array
+  destino: Memory
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Template exists; source data available
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check template exists; source data available
+    error_message: "Pre-condition failed: Template exists; source data available"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Documentation generated; format valid; links working
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify documentation generated; format valid; links working
+    error_message: "Post-condition failed: Documentation generated; format valid; links working"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Documentation readable; examples work; links valid
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert documentation readable; examples work; links valid
+    error_message: "Acceptance criterion not met: Documentation readable; examples work; links valid"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** markdown-renderer
+  - **Purpose:** Markdown parsing and rendering
+  - **Source:** npm: marked or similar
+
+- **Tool:** template-engine
+  - **Purpose:** Document template processing
+  - **Source:** .aios-core/product/templates/
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** generate-docs.js
+  - **Purpose:** Documentation generation from templates
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/generate-docs.js
+
+---
+
+## Error Handling
+
+**Strategy:** fallback
+
+**Common Errors:**
+
+1. **Error:** Template Not Found
+   - **Cause:** Specified template does not exist
+   - **Resolution:** Verify template path in config
+   - **Recovery:** Use default template, log warning
+
+2. **Error:** Invalid Markdown
+   - **Cause:** Source contains invalid markdown syntax
+   - **Resolution:** Validate markdown before processing
+   - **Recovery:** Sanitize markdown, continue processing
+
+3. **Error:** Generation Failed
+   - **Cause:** Template rendering error or missing data
+   - **Resolution:** Check template syntax and data availability
+   - **Recovery:** Fallback to simple template, log error
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 2-5 min (estimated)
+cost_estimated: $0.001-0.003
+token_usage: ~1,000-3,000 tokens
+```
+
+**Optimization Notes:**
+- Parallelize independent operations; reuse atom results; implement early exits
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+# No checklists needed - this task maintains documentation index, validation is through file system checks
+tools:
+  - github-cli
+---
+
+# 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. 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 with proper organization for subfolders.
+
+### Required Steps
+
+1. First, locate and scan:
+
+   - 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`:
+
+   - Parse current entries
+   - 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:
+
+   - Extract the title (from first heading or filename)
+   - 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:
+
+   - Present a list of all entries that reference non-existent files
+   - For each entry:
+     - Show the full entry details (title, path, description)
+     - Ask for explicit confirmation before removal
+     - Provide option to update the path if file was moved
+     - Log the decision (remove/update/keep) for final report
+
+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 should follow this format:
+
+```markdown
+### [Document Title](relative/path/to/file.md)
+
+Brief description of the document's purpose and contents.
+```
+
+### Rules of Operation
+
+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 (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 (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 new folders discovered
+6. Any other issues or inconsistencies found
+
+### Handling Missing Files
+
+For each file referenced in the index but not found in the filesystem:
+
+1. Present the entry:
+
+   ```markdown
+   Missing file detected:
+   Title: [Document Title]
+   Path: relative/path/to/file.md
+   Description: Existing description
+   Section: [Root Documents | Folder Name]
+
+   Options:
+
+   1. Remove this entry
+   2. Update the file path
+   3. Keep entry (mark as temporarily unavailable)
+
+   Please choose an option (1/2/3):
+   ```
+
+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 (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 (e.g., `.git`, `node_modules`)
+5. Whether to include hidden files/folders (starting with `.`)
+
+Would you like to proceed with documentation indexing? Please provide the required input above.
+