Initial commit

doc-indexer/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: doc-indexer
+description: Use this skill at the beginning of any session or when needing to understand available project documentation. Provides just-in-time context by scanning YAML frontmatter from all markdown files in the docs/ directory without loading full content.
+---
+
+# Document Indexer Skill
+
+## Purpose
+
+Provide just-in-time context about available project documentation without loading full file content into the context window. The doc-indexer scans all markdown files in the `docs/` directory, extracts their YAML frontmatter metadata, and returns a structured map of available documentation. This enables efficient discovery of specs, plans, retrospectives, and other documentation while minimizing token usage.
+
+## When to Use
+
+Use this skill in the following situations:
+
+- At the beginning of any work session to understand the current state of documentation
+- When starting work on a new issue to identify relevant specs and context
+- Before proposing changes to understand existing specifications
+- When planning a sprint to review available approved specs
+- Anytime you need an overview of project documentation without reading full files
+
+## Prerequisites
+
+- The project must have a `docs/` directory
+- Documentation files should follow the convention of including YAML frontmatter
+- The `jq` tool is NOT required (script works without it)
+
+## Workflow
+
+### Step 1: Run the Documentation Scanner
+
+Execute the helper script to scan all markdown files in the docs/ directory:
+
+```bash
+bash scripts/scan-docs.sh
+```
+
+This will output a human-readable summary showing each document's frontmatter metadata.
+
+For machine-readable JSON output (useful for programmatic processing):
+
+```bash
+bash scripts/scan-docs.sh -j
+```
+
+### Step 2: Review the Documentation Map
+
+The scanner returns information about all markdown files found in `docs/`, including:
+
+- **File path**: Location of the documentation file
+- **Frontmatter metadata**: Key-value pairs from YAML frontmatter (title, status, type, etc.)
+- **Compliance warnings**: Files missing YAML frontmatter are flagged
+
+**Example human-readable output**:
+```
+---
+file: docs/specs/001-synthesis-flow.md
+title: SynthesisFlow Methodology
+status: approved
+type: spec
+---
+file: docs/changes/my-feature/proposal.md
+title: My Feature Proposal
+status: in-review
+type: proposal
+[WARNING] Non-compliant file (no frontmatter): docs/README.md
+```
+
+**Example JSON output**:
+```json
+[
+  {
+    "file": "docs/specs/001-synthesis-flow.md",
+    "compliant": true,
+    "frontmatter": {
+      "title": "SynthesisFlow Methodology",
+      "status": "approved",
+      "type": "spec"
+    }
+  },
+  {
+    "file": "docs/README.md",
+    "compliant": false,
+    "frontmatter": null
+  }
+]
+```
+
+### Step 3: Use the Map to Identify Relevant Documentation
+
+Based on the documentation map, identify which specific files to read for your current task:
+
+- **For implementation work**: Look for approved specs related to your issue
+- **For spec proposals**: Review existing specs to understand the current state
+- **For sprint planning**: Identify approved specs ready for implementation
+- **For learning context**: Find retrospectives and design docs
+
+### Step 4: Read Specific Documentation Files
+
+Once you've identified relevant files from the map, use the Read tool to load their full content:
+
+```bash
+# Example: Read a specific spec identified from the map
+Read docs/specs/001-synthesis-flow.md
+```
+
+This two-step approach (scan first, then read selectively) minimizes token usage while ensuring you have access to all necessary context.
+
+## Error Handling
+
+### No docs/ Directory
+
+**Symptom**: Script reports "No such file or directory"
+
+**Solution**:
+- Verify you're in the project root directory
+- Check if the project has been initialized with `project-init` skill
+- Create `docs/` directory structure if needed
+
+### Files Missing Frontmatter
+
+**Symptom**: Script outputs "[WARNING] Non-compliant file (no frontmatter): ..."
+
+**Impact**: These files won't have structured metadata in the output
+
+**Solution**:
+- Add YAML frontmatter to documentation files for better discoverability
+- Frontmatter should be at the top of the file between `---` markers
+- Example format:
+  ```markdown
+  ---
+  title: My Document
+  status: draft
+  type: design
+  ---
+
+  # Document content starts here
+  ```
+
+### Script Permission Errors
+
+**Symptom**: "Permission denied" when running the script
+
+**Solution**:
+```bash
+chmod +x scripts/scan-docs.sh
+```
+
+## Output Interpretation Guide
+
+### Frontmatter Fields
+
+Common frontmatter fields you'll encounter:
+
+- **title**: Human-readable document title
+- **status**: Document state (draft, in-review, approved, archived)
+- **type**: Document category (spec, proposal, design, retrospective, plan)
+- **epic**: Associated epic issue number
+- **sprint**: Sprint identifier
+- **author**: Document author
+- **created**: Creation date
+- **updated**: Last update date
+
+### Using JSON Output Programmatically
+
+The JSON output mode is particularly useful when:
+
+- Filtering documents by specific criteria (e.g., only approved specs)
+- Counting documents by type or status
+- Building automated workflows
+- Integrating with other tools
+
+Example using `jq` to filter approved specs:
+```bash
+bash scripts/scan-docs.sh -j | jq '.[] | select(.frontmatter.status == "approved")'
+```
+
+## Notes
+
+- The scanner is non-invasive and read-only - it never modifies files
+- Large projects with many docs benefit most from this just-in-time approach
+- The script scans recursively through all subdirectories in `docs/`
+- Empty frontmatter sections are treated as non-compliant
+- The scan is fast and can be run frequently without performance concerns
+- Consider running this at the start of each work session to stay current with documentation changes

doc-indexer/scripts/scan-docs.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# This script finds all markdown files in the docs/ directory, extracts the YAML frontmatter,
+# reports any files that are missing frontmatter, and can output as JSON.
+
+JSON_OUTPUT=false
+
+usage() {
+    echo "Usage: $0 [-j]"
+    echo "  -j: Output the result as a JSON array."
+    exit 1
+}
+
+while getopts ":j" opt; do
+  case ${opt} in
+    j )
+      JSON_OUTPUT=true
+      ;;
+    \? )
+      echo "Invalid option: $OPTARG" 1>&2
+      usage
+      ;;
+  esac
+done
+
+if [ "$JSON_OUTPUT" = true ]; then
+    # Use a temporary file to store the JSON objects
+    json_objects_file=$(mktemp)
+    
+    while IFS= read -r -d '' file; do
+        frontmatter=$(awk '/^---$/{if(c>0){exit} c++} c>0' "$file" | sed '1d')
+
+        # Basic JSON escaping for file path
+        escaped_file=$(echo "$file" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g')
+
+        json_object="{"
+        json_object+="\"file\": \"$escaped_file\","
+        if [ -n "$frontmatter" ]; then
+            json_object+="\"compliant\": true,"
+            json_object+="\"frontmatter\": {"
+            
+            # Convert YAML to JSON:
+            # 1. Remove leading/trailing whitespace
+            # 2. Escape double quotes
+            # 3. Add quotes around keys and values
+            # 4. Join with commas
+            frontmatter_json=$(echo "$frontmatter" | sed -e 's/^[ \t]*//;s/[ \t]*$//' | awk -F': ' 'NF>1{gsub(/"/, "\\\""); printf "\"%s\": \"%s\",", $1, $2}' | sed 's/,$//')
+            
+            json_object+="$frontmatter_json"
+            json_object+="}"
+        else
+            json_object+="\"compliant\": false,"
+            json_object+="\"frontmatter\": null"
+        fi
+        json_object+="}"
+        
+        echo "$json_object" >> "$json_objects_file"
+    done < <(find docs -name "*.md" -print0)
+
+    # Now, assemble the final JSON array
+    echo "["
+    if [ -s "$json_objects_file" ]; then
+        paste -sd, "$json_objects_file"
+    fi
+    echo "]"
+    
+    # Clean up the temporary file
+    rm "$json_objects_file"
+else
+    while IFS= read -r -d '' file; do
+        frontmatter=$(awk '/^---$/{if(c>0){exit} c++} c>0' "$file" | sed '1d')
+
+        if [ -n "$frontmatter" ]; then
+            echo "---"
+            echo "file: $file"
+            echo "$frontmatter"
+        else
+            echo "[WARNING] Non-compliant file (no frontmatter): $file"
+        fi
+    done < <(find docs -name "*.md" -print0)
+fi