diff --git a/PROGRESS.md b/PROGRESS.md new file mode 100644 index 000000000..636a4b7e9 --- /dev/null +++ b/PROGRESS.md @@ -0,0 +1,9 @@ +# Project Progress Tracking (Sentinel) + +| Date & Time | Task Description | Status | Commit / Evidence | +|-------------|------------------|--------|-------------------| +| 2026-02-12 17:45 | Initial PR Design & Planning | ✅ COMPLETED | Brainstorming Session | +| 2026-02-12 17:55 | OS Adaptability Mapping | ✅ COMPLETED | Updated skills/using-superpowers/SKILL.md | +| 2026-02-12 17:58 | Skill Discovery Indexing | ✅ COMPLETED | Added SKILLS_INDEX.md & Generator | +| 2026-02-12 18:02 | Sentinel Logic Integration | ✅ COMPLETED | Updated skills/executing-plans/SKILL.md | +| 2026-02-12 18:05 | Skill Index Verification | ✅ VERIFIED | SKILLS_INDEX.md generated correctly | diff --git a/docs/plans/2026-02-12-sentinel-discovery.md b/docs/plans/2026-02-12-sentinel-discovery.md new file mode 100644 index 000000000..fd7bccaa4 --- /dev/null +++ b/docs/plans/2026-02-12-sentinel-discovery.md @@ -0,0 +1,26 @@ +# Progress Sentinel & Dynamic Skill Discovery Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Enhance Superpowers with automated progress tracking, optimized skill discovery, and native Windows adaptability. + +**Architecture:** +1. **Sentinel**: Inject progress tracking requirements into core execution skills. +2. **Discovery**: Implement a summary index for all available skills to prevent context overload. +3. **Adaptability**: Provide a command mapping standard for cross-platform execution. + +--- + +### Task 1: Update `using-superpowers` (OS Adaptability) +**Files:** +- Modify: `skills/using-superpowers/SKILL.md` + +### Task 2: Implement Skill Discovery Index +**Files:** +- Create: `lib/scripts/generate_skills_index.js` +- Create: `skills/SKILLS_INDEX.md` + +### Task 3: Implement Sentinel Logic (Progress Tracking) +**Files:** +- Modify: `skills/executing-plans/SKILL.md` +- Create: `PROGRESS.md` (template) diff --git a/lib/scripts/generate_skills_index.js b/lib/scripts/generate_skills_index.js new file mode 100644 index 000000000..5160d168e --- /dev/null +++ b/lib/scripts/generate_skills_index.js @@ -0,0 +1,54 @@ +const fs = require('fs'); +const path = require('path'); + +function generateIndex(skillsDir, outputFile) { + let indexContent = "# Superpowers Skills Index\n\n"; + indexContent += "This index provides a lightweight summary of all available skills. Use this to discover relevant skills before loading their full instructions.\n\n"; + indexContent += "| Skill Name | Description |\n"; + indexContent += "|------------|-------------|\n"; + + const getFiles = (dir) => { + let results = []; + const list = fs.readdirSync(dir); + list.forEach(file => { + file = path.join(dir, file); + const stat = fs.statSync(file); + if (stat && stat.isDirectory()) { + results = results.concat(getFiles(file)); + } else if (file.endsWith('SKILL.md')) { + results.push(file); + } + }); + return results; + }; + + const skillFiles = getFiles(skillsDir); + const skills = []; + + skillFiles.forEach(file => { + const content = fs.readFileSync(file, 'utf8'); + const nameMatch = content.match(/^name:\s*(.+)$/m); + const descMatch = content.match(/^description:\s*(.+)$/m); + + const name = nameMatch ? nameMatch[1].trim() : path.basename(path.dirname(file)); + const description = descMatch ? descMatch[1].trim().replace(/^"|"$/g, '') : "No description available."; + + skills.push({ name, description }); + }); + + // Sort skills alphabetically by name + skills.sort((a, b) => a.name.localeCompare(b.name)); + + skills.forEach(skill => { + indexContent += `| ${skill.name} | ${skill.description} |\n`; + }); + + fs.writeFileSync(outputFile, indexContent); + console.log(`Generated index at ${outputFile}`); +} + +const baseDir = path.resolve(__dirname, '../..'); +const skillsDir = path.join(baseDir, 'skills'); +const outputFile = path.join(baseDir, 'skills/SKILLS_INDEX.md'); + +generateIndex(skillsDir, outputFile); diff --git a/lib/scripts/generate_skills_index.py b/lib/scripts/generate_skills_index.py new file mode 100644 index 000000000..c389df828 --- /dev/null +++ b/lib/scripts/generate_skills_index.py @@ -0,0 +1,36 @@ +import os +import re + +def generate_index(skills_dir, output_file): + index_content = "# Superpowers Skills Index\n\n" + index_content += "This index provides a lightweight summary of all available skills. Use this to discover relevant skills before loading their full instructions.\n\n" + index_content += "| Skill Name | Description |\n" + index_content += "|------------|-------------|\n" + + for root, dirs, files in os.walk(skills_dir): + if "SKILL.md" in files: + skill_path = os.path.join(root, "SKILL.md") + with open(skill_path, 'r', encoding='utf-8') as f: + content = f.read() + + # Extract frontmatter name and description + name_match = re.search(r'^name:\s*(.+)$', content, re.MULTILINE) + desc_match = re.search(r'^description:\s*(.+)$', content, re.MULTILINE) + + name = name_match.group(1).strip() if name_match else os.path.basename(root) + description = desc_match.group(1).strip().strip('"') if desc_match else "No description available." + + index_content += f"| {name} | {description} |\n" + + with open(output_file, 'w', encoding='utf-8') as f: + f.write(index_content) + +if __name__ == "__main__": + # Assuming the script runs from the repo root or lib/scripts + base_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "../..")) + skills_dir = os.path.join(base_dir, "skills") + output_file = os.path.join(base_dir, "skills/SKILLS_INDEX.md") + + # Also handle the awesome-automation if linked + generate_index(skills_dir, output_file) + print(f"Generated index at {output_file}") diff --git a/skills/SKILLS_INDEX.md b/skills/SKILLS_INDEX.md new file mode 100644 index 000000000..0463ecf67 --- /dev/null +++ b/skills/SKILLS_INDEX.md @@ -0,0 +1,20 @@ +# Superpowers Skills Index + +This index provides a lightweight summary of all available skills. Use this to discover relevant skills before loading their full instructions. + +| Skill Name | Description | +|------------|-------------| +| brainstorming | You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation. | +| dispatching-parallel-agents | Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | +| executing-plans | Use when you have a written implementation plan to execute in a separate session with review checkpoints | +| finishing-a-development-branch | Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup | +| receiving-code-review | Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | +| requesting-code-review | Use when completing tasks, implementing major features, or before merging to verify work meets requirements | +| subagent-driven-development | Use when executing implementation plans with independent tasks in the current session | +| systematic-debugging | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes | +| test-driven-development | Use when implementing any feature or bugfix, before writing implementation code | +| using-git-worktrees | Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification | +| using-superpowers | Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions | +| verification-before-completion | Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | +| writing-plans | Use when you have a spec or requirements for a multi-step task, before touching code | +| writing-skills | Use when creating new skills, editing existing skills, or verifying skills work before deployment | diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index c1b2533f4..6b2f57613 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -28,7 +28,8 @@ For each task: 1. Mark as in_progress 2. Follow each step exactly (plan has bite-sized steps) 3. Run verifications as specified -4. Mark as completed +4. **Update `PROGRESS.md` (at project root)** - REQUIRED: Add a line with current timestamp, task status, and commit hash/evidence. +5. Mark as completed ### Step 3: Report When batch complete: diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index 7867fcfc0..a36cfadd9 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -82,6 +82,33 @@ When multiple skills could apply, use this order: The skill itself tells you which. +## Skill Discovery (Handling Scale) + +When dealing with a large library of skills (e.g., automated SaaS skills), do not load all skills into context at once. Instead: + +1. **Read `skills/SKILLS_INDEX.md`** - This provides a lightweight summary of all available skills. +2. **Search for keywords** - Identify 2-3 specific skills that match your current task. +3. **Invoke specific skills** - Use the Skill tool (or Read tool in other environments) only on those highly relevant skills. + +--- + +## Windows & Cross-Platform Adaptability + +When executing commands, adapt to the user's OS. Do not assume a POSIX environment. + +| POSIX / Linux | Windows (CMD/PowerShell) | Purpose | +|---------------|--------------------------|---------| +| `ls -la` | `dir` | List files | +| `rm -rf ` | `rmdir /s /q ` | Delete directory | +| `cp -r` | `xcopy /e /i /y` | Copy directory | +| `grep "text"` | `findstr "text"` | Search in files | +| `cat file` | `type file` | View file content | +| `touch file` | `type nul > file` | Create empty file (CMD) | + +**Pro Tip:** Use the `run_command` tool to check environment before assuming command syntax. + +--- + ## User Instructions Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.