feat: add workflow_dispatch trigger to release workflow

.github/workflows/quality-checks.yml

@@ -67,22 +67,13 @@ jobs:
       - name: Run Node.js tests
         run: npm test
 
-      - name: Run shell script tests
+      - name: Run dictionary validation tests
         run: |
-          if [ -d "tests" ]; then
-            EXIT_CODE=0
-            for script in tests/test_*.sh; do
-              if [ -f "$script" ]; then
-                echo "Running $script"
-                if bash "$script"; then
-                  echo "✅ $script passed"
-                else
-                  echo "❌ $script failed with exit code $?"
-                  EXIT_CODE=1
-                fi
-              fi
-            done
-            exit $EXIT_CODE
+          if [ -d "tests" ] && [ -f "tests/run-all-tests.js" ]; then
+            echo "Running Information Dense Keywords Dictionary test suite"
+            node tests/run-all-tests.js
+          else
+            echo "No dictionary test suite found - skipping validation tests"
           fi
 
 

.github/workflows/release.yml

@@ -4,6 +4,15 @@ on:
   push:
     branches:
       - main
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'The branch to run the release from'
+        required: true
+        type: choice
+        options:
+          - main
+        default: 'main'
 
 permissions:
   contents: write

.pre-commit-config.yaml

@@ -20,6 +20,12 @@ repos:
         entry: npx eslint --fix
         language: node
         types: [javascript, jsx, ts, tsx]
+      - id: dictionary-validation
+        name: Dictionary Validation Tests
+        entry: node tests/run-all-tests.js
+        language: node
+        files: ^(information-dense-keywords\.md|dictionary/.*\.md|tests/.*\.js)$
+        pass_filenames: false
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: v0.41.0
     hooks:

CONTRIBUTING.md

@@ -66,7 +66,7 @@ npm run format:check
 
 # Run all tests
 npm test
-```
+```bash
 
 ### Examples
 
@@ -79,7 +79,7 @@ Good command definition:
 
 **Example Prompt**:
 `CREATE a new React component called 'LoginButton' with a click handler that calls the 'handleLogin' function.`
-```
+```bash
 
 ## 🚀 Submitting Changes
 

README.md

@@ -1,31 +1,161 @@
 # Information Dense Keywords Dictionary
 
-This repository contains a dictionary of commands that an AI assistant can be trained to understand. The goal is to create a shared, efficient vocabulary for common software development tasks.
+A comprehensive, modular dictionary of commands for AI assistants in software development. This repository provides a shared, efficient vocabulary that makes human-AI collaboration more productive and consistent.
 
 ## 🎯 What You Get
 
-A curated list of action-oriented keywords that can be used to instruct an AI model. This provides a shared vocabulary for common development tasks, making human-AI collaboration more efficient.
+A curated collection of action-oriented keywords organized in a modular structure. Each command compresses common prompts into memorable keywords with comprehensive definitions and expected output formats.
 
 **Key Features:**
 
-- 📝 **Core command definitions** for SELECT, CREATE, DELETE, FIX, and more
-- 🤖 **AI-powered workflows** for automated issue analysis and dictionary enhancement
-- 🔧 **GitHub integration** with automated PR reviews and validation
-- 🛡️ **Robust CI/CD** with security scanning and emergency controls
+- 📚 **20+ command definitions** across Core, Development, Documentation, QA, Workflow, and Git categories
+- 🏗️ **Modular architecture** with organized `dictionary/` structure for easy navigation
+- 🔗 **Command chaining** support for complex workflows
+- 📋 **Expected Output Formats** for consistent, predictable results
+- 🔧 **GitHub integration** with automated workflows and validation
+- 🛡️ **Quality assurance** with security scanning and emergency controls
 
-## 💡 How to Use
+## 📦 Installation & Usage
 
-See the [AI Usage Guide](examples/ai-usage-guide.md) for a detailed explanation of how an AI assistant should use this dictionary.
+### For Individual Users
 
-### Quick Start
+#### Option 1: Direct Reference (Recommended)
 
-1. **For AI Assistants**: Reference the [command definitions](information-dense-keywords.md) to understand user intent
-2. **For Developers**: Use commands like `SELECT auth logic`, `CREATE login component`, or `FIX validation error`
-3. **For Contributors**: Add issues with labels like `ai-task` to trigger automated analysis
+1. **Bookmark the main index**: [Information Dense Keywords Dictionary](information-dense-keywords.md)
+2. **Copy commands directly** from the definitions when prompting your AI assistant
+3. **Chain commands** for complex workflows: `analyze this auth system then spec this improvement then plan this implementation`
+
+#### Option 2: Clone the Repository
+
+```bash
+# Clone the repository
+git clone https://github.com/stillriver/idk.git
+cd idk
+
+# Browse the dictionary
+open information-dense-keywords.md  # macOS
+xdg-open information-dense-keywords.md  # Linux
+start information-dense-keywords.md  # Windows
+```bash
+
+### For Teams & Organizations
+
+#### Option 1: Git Submodule
+
+```bash
+# Add as a submodule to your project
+git submodule add https://github.com/stillriver/idk.git docs/idk
+
+# Reference in your project documentation
+echo "See [IDK Dictionary](information-dense-keywords.md) for AI command reference" >> README.md
+```bash
+
+#### Option 2: Fork & Customize
+
+```bash
+# Fork the repository on GitHub
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/idk.git
+cd idk
+
+# Add your custom commands
+mkdir dictionary/custom
+# Add your team-specific commands to dictionary/custom/
+# Update information-dense-keywords.md with links to your custom commands
+```bash
+
+### For AI Assistant Developers
+
+#### Integration Instructions
+
+1. **Read the AI guidance**: [AI.md](AI.md), [CLAUDE.md](CLAUDE.md), [GEMINI.md](GEMINI.md)
+2. **Implement command recognition** using the definitions in `dictionary/`
+3. **Follow output formats** specified in each command definition
+4. **Support command chaining** as documented in the main index
+
+## 🚀 Quick Start Examples
+
+### Basic Commands
+
+```bash
+SELECT the authentication logic from auth.py
+CREATE a React login component
+FIX the validation error in user registration
+DELETE the unused styling files
+```bash
+
+### Advanced Commands
+
+```bash
+analyze this database schema for performance issues
+debug this memory leak in the payment processor
+optimize this query that's taking 10 seconds
+test this user service with comprehensive unit tests
+review this pull request for security vulnerabilities
+```bash
+
+### Command Chaining
+
+```bash
+research this OAuth2 patterns then spec this authentication system then plan this implementation
+analyze this API performance then optimize this bottleneck then test this solution
+```bash
+
+## 📁 Dictionary Structure
+
+```bash
+information-dense-keywords.md     # Main index with links to all commands
+dictionary/
+├── core/                        # SELECT, CREATE, DELETE, FIX
+├── development/                 # analyze this, debug this, optimize this
+├── documentation/               # document this, explain this, research this
+├── quality-assurance/          # test this, review this
+├── workflow/                   # plan this, spec this
+└── git/                       # commit, push, pr, gh, comment
+```bash
+
+## 🎓 Learning Path
+
+1. **Start with Core Commands**: Master SELECT, CREATE, DELETE, FIX
+2. **Explore by Category**: Pick a category that matches your workflow
+3. **Practice Command Chaining**: Combine commands for complex tasks
+4. **Customize for Your Team**: Add domain-specific commands as needed
+
+## 💡 Usage Tips
+
+- **Be Specific**: `analyze this authentication flow for security vulnerabilities` vs `analyze this`
+- **Chain Logically**: Use "then" for sequential operations, "and" for parallel
+- **Reference Files**: Include file paths and line numbers when possible
+- **Use Expected Formats**: Each command specifies its expected output structure
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please read the [contributing guidelines](CONTRIBUTING.md) for more information.
+We welcome contributions! Here's how to help:
+
+1. **Add New Commands**: Create files in appropriate `dictionary/` subdirectories
+2. **Improve Definitions**: Enhance existing command documentation
+3. **Report Issues**: Use GitHub issues for bugs or feature requests
+4. **Share Usage Patterns**: Help us understand how teams use the dictionary
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+## 📋 Command Categories
+
+| Category | Commands | Purpose |
+|----------|----------|---------|
+| **Core** | SELECT, CREATE, DELETE, FIX | Basic operations |
+| **Development** | analyze this, debug this, optimize this | Code analysis & improvement |
+| **Documentation** | document this, explain this, research this | Knowledge creation |
+| **Quality Assurance** | test this, review this | Testing & validation |
+| **Workflow** | plan this, spec this | Project planning |
+| **Git** | commit, push, pr, gh, comment | Version control |
+
+## 🔗 Related Resources
+
+- [AI Usage Guide](examples/ai-usage-guide.md) - Detailed implementation guidance
+- [Command Definitions](information-dense-keywords.md) - Complete command index
+- [Architecture Decision Records](adrs/) - Design decisions and evolution
+- [Roadmap](docs/roadmaps/ROADMAP.md) - Future development plans
 
 ## 📄 License
 

adrs/001-idk-expansion-engine.md

@@ -1,26 +1,70 @@
-# ADR 001: IDK Dictionary as a Single Markdown File
+# ADR 001: IDK Dictionary Architecture Evolution
 
-**Status**: Accepted
+**Status**: Superseded by Modular Architecture
 
 **Context**:
 
-The project has gone through several iterations:
+The project has evolved through several iterations:
 
 1. A collection of structured YAML files.
 2. A CLI tool with a programmatic syntax (`expand Keyword[param=value]`).
 3. A CLI tool with a natural language syntax (`SELECT Keyword with feature`).
+4. **[Previous]** A single, well-structured Markdown file named `information-dense-keywords.md`.
+5. **[Current]** A modular dictionary with an index file and organized command definitions.
 
-All of these approaches were deemed overly complex for the core goal of the project: to provide a simple, shared vocabulary for human-AI communication.
+The single-file approach served well initially but became unwieldy as the dictionary grew. With comprehensive Expected Output Formats and detailed definitions, the file became too large for easy navigation and maintenance.
 
-**Decision**:
+**Updated Decision**:
 
-We will simplify the project to a single, well-structured Markdown file named `idk-dictionary.md`. This file will contain a curated list of commands and their definitions, intended to be used as a reference for constructing prompts for an AI assistant.
+We will restructure the project to use a **modular dictionary architecture**:
 
-This approach prioritizes simplicity, maintainability, and ease of use over technical complexity.
+- `information-dense-keywords.md` becomes an **index** with links to command definitions
+- Individual command definitions are stored in `dictionary/` subdirectories organized by category
+- Each command gets its own markdown file with complete definition, examples, and expected output format
+
+**New Structure**:
+
+```yaml
+information-dense-keywords.md          # Index with links
+dictionary/
+├── core/                             # Core CRUD operations
+│   ├── select.md
+│   ├── create.md
+│   ├── delete.md
+│   └── fix.md
+├── development/                      # Development commands
+│   ├── analyze-this.md
+│   ├── debug-this.md
+│   └── optimize-this.md
+├── documentation/                    # Documentation commands
+│   ├── document-this.md
+│   └── explain-this.md
+├── quality-assurance/               # QA commands
+│   ├── test-this.md
+│   └── review-this.md
+├── workflow/                        # Workflow commands
+│   ├── plan-this.md
+│   └── spec-this.md
+└── git/                            # Git operations
+    ├── commit.md
+    ├── push.md
+    ├── pr.md
+    └── gh.md
+```yaml
+
+**Benefits of Modular Architecture**:
+
+- **Maintainability**: Each command can be edited independently
+- **Scalability**: Easy to add new commands without bloating the index
+- **Navigation**: Quick reference via index, detailed definitions in dedicated files
+- **Organization**: Logical grouping by functionality
+- **Collaboration**: Multiple contributors can work on different commands simultaneously
+- **Reusability**: Individual command definitions can be referenced or imported separately
 
 **Consequences**:
 
-- The project is significantly simplified, with no need for a CLI tool, a complex file structure, or a validation script.
-- The focus is shifted from building a tool to curating a high-quality dictionary of commands.
-- The barrier to entry for contributors is lowered, as they only need to edit a single Markdown file.
-- The project is more flexible, as users can easily copy, paste, and modify the commands to fit their specific needs.
+- Improved organization and maintainability of the growing dictionary
+- Better separation of concerns between overview (index) and detailed definitions
+- Enhanced contributor experience with focused, manageable file sizes
+- Maintained simplicity while supporting growth and complexity
+- Preserved ease of use through clear index structure with direct links