feat: migrate from shared-commands to IDK package

[adslaton]

Summary

• Migrated from local shared-commands to published @stillrivercode/information-dense-keywords package
• Updated CLAUDE.md and GEMINI.md to reference IDK vocabulary and AI.md context
• Removed shared-commands directory and replaced with IDK integration
• Updated tests to validate IDK integration instead of shared-commands security
• Removed template install.sh file

Key Changes

• IDK Package Installation: Installed Information Dense Keywords Dictionary locally
• AI Context Updates: Both CLAUDE.md and GEMINI.md now reference standardized IDK vocabulary
• Directory Cleanup: Removed entire shared-commands directory (7,371 lines removed)
• Test Updates: Replaced security tests with IDK integration tests
• Template Cleanup: Removed install.sh as it comes from template

Benefits

• Standardized AI command vocabulary across all AI assistants
• Reduced maintenance burden (no local shared-commands to maintain)
• Access to community-maintained command dictionary
• Consistent AI communication patterns
• Automatic updates from IDK package

Test Results

• ✅ IDK Integration Tests: 7/7 passed
• ✅ ESLint Config Tests: 7/7 passed
• ✅ App Tests: 11/11 passed

🤖 Generated with Claude Code

[github-actions]

🔒 Security Scan Results

✅ npm audit - Dependency Security

No vulnerable dependencies found.

⚠️ audit-ci Security Check

No results file generated.

✅ ESLint Security Analysis

No security issues found.

---

✅ All security scans passed! No issues found.

[github-actions]

🤖 AI Review

Pull Request Review: Migration to Information Dense Keywords (IDK) Package

Summary of Changes

This PR successfully migrates from a local shared-commands directory to the published @stillrivercode/information-dense-keywords package. The migration involves:

• Removal: 7,371 lines of local shared-commands infrastructure
• Addition: Comprehensive IDK vocabulary documentation and integration
• Updates: AI context files (CLAUDE.md, GEMINI.md) with IDK command references
• Testing: New IDK integration tests replacing security-focused tests

Strengths of the Implementation

1. Comprehensive Documentation Architecture

• Well-organized dictionary structure under docs/dictionary/ with clear categorization
• Each command has detailed documentation with expected output formats
• Excellent cross-referencing between related commands

2. Standardized AI Communication

• Consistent vocabulary across all AI assistants (Claude, Gemini, etc.)
• Clear command definitions with usage examples
• Support for command chaining with documented patterns

3. Maintenance Benefits

• Outsourced package maintenance reduces local burden
• Access to community-maintained command dictionary
• Automatic updates through package management

4. Quality Documentation Standards

• Consistent markdown formatting across all files
• Comprehensive examples and usage patterns
• Clear expected output formats for each command

Issues and Concerns

1. Missing Implementation Details

# Critical: How is IDK actually installed/used?
# The migration doc mentions these commands but they're not in package.json:
npx @stillrivercode/information-dense-keywords

Issue: The PR mentions installing IDK locally but doesn't show:

• Package.json dependencies
• Actual installation commands
• Integration with existing workflows

2. Test Coverage Gaps

// tests/idk-integration.test.js is mentioned but not shown in diff
// What does "7/7 passed" actually test?

Issue: Cannot verify the quality of new integration tests since they're not visible in the diff.

3. Workflow Integration Unclear

# shared-commands had actual shell scripts:
# ./shared-commands/commands/create-spec-issue.sh
# How do these translate to IDK commands?

Issue: The migration removes concrete implementation scripts but doesn't clearly show how IDK replaces the automation functionality.

4. Template Installation Removal

# install.sh removed - how do new users set up the environment?

Issue: Removing the installation script may create friction for new contributors.

Security Considerations

1. External Dependency Risk

• Concern: Dependency on external npm package introduces supply chain risk
• Mitigation: Should pin to specific version and review updates carefully

2. Command Injection Prevention

// Need to verify IDK package doesn't execute arbitrary commands
// Especially with dynamic command generation

Performance Implications

1. Positive Impact

• Reduced repository size (7,371 lines removed)
• Faster cloning and development setup
• No local script execution overhead

2. Potential Concerns

• Network dependency for package installation
• Initial setup complexity if not properly documented

Documentation Quality Assessment

Excellent Structure

# Each command follows consistent format:
- Definition
- Example prompts  
- Expected output format
- Usage notes
- Related commands

Comprehensive Coverage

• Core operations (SELECT, CREATE, DELETE, FIX)
• Development workflows (analyze, debug, optimize)
• Documentation commands (document, explain, research)
• Quality assurance (test, review)
• Git operations (commit, push, pr)

Suggestions for Improvement

1. Add Missing Implementation Details

// package.json should include:
{
  "dependencies": {
    "@stillrivercode/information-dense-keywords": "^1.0.0"
  },
  "scripts": {
    "idk:install": "npx @stillrivercode/information-dense-keywords",
    "idk:update": "npm update @stillrivercode/information-dense-keywords"
  }
}

2. Create Migration Guide for Users

## For Existing Users
- Old: `./shared-commands/commands/create-spec-issue.sh --title "Feature"`
- New: Use IDK: `CREATE spec --title "Feature"`

3. Add Rollback Documentation

## Emergency Rollback
1. `git revert [commit-hash]`
2. `git restore shared-commands/` (if needed)
3. Re-run old setup scripts

4. Include Integration Tests in Review

The new test file should be included in the diff for proper review.

5. Version Pinning

// Pin to exact version initially
"@stillrivercode/information-dense-keywords": "1.0.0"

Test Coverage Assessment

Cannot fully assess - The new tests/idk-integration.test.js file is not shown in the diff. This file should be included to verify:

• Proper IDK integration testing
• Command validation
• Error handling
• Integration with existing workflows

Overall Recommendation: REQUEST CHANGES

Required Changes:

1. Show package.json changes - How is IDK actually installed?
2. Include test files - Need to see tests/idk-integration.test.js
3. Add installation documentation - Replace removed install.sh guidance
4. Clarify workflow integration - How do IDK commands replace shell scripts?

Suggested Changes:

1. Add version pinning for security
2. Include migration guide for existing users
3. Add rollback documentation
4. Consider keeping a minimal setup script

Approval Conditions:

Once the required changes are addressed, this PR should be approved as it represents a significant improvement in:

• Code maintainability
• Standardization across AI assistants
• Community-driven command evolution
• Documentation quality

The concept and execution are excellent, but the implementation details need clarification for safe deployment.

---

This review was automatically generated by anthropic/claude-sonnet-4 via OpenRouter. Please consider it as supplementary feedback alongside human review.

[github-actions]

🤖 AI Review

Pull Request Review

Summary of Changes

This PR implements a significant migration from a local shared-commands directory to the published @stillrivercode/information-dense-keywords (IDK) package. The migration includes:

• Package Integration: Replaced local shared-commands (7,371 lines) with IDK package
• AI Context Updates: Updated CLAUDE.md, GEMINI.md, and added new AI.md with standardized vocabulary
• Documentation Structure: Created comprehensive IDK dictionary docs in docs/dictionary/
• Test Migration: Replaced shared-commands security tests with IDK integration tests
• Configuration Updates: Modified package.json and eslint.config.js for new structure

Code Quality and Best Practices

Strengths ✅

• Comprehensive Documentation: Excellent structured documentation in docs/dictionary/ with consistent formatting
• Standardized AI Communication: Clear, well-defined command vocabulary for AI assistants
• Modular Organization: Well-organized directory structure by command categories
• Consistent Patterns: All dictionary entries follow the same format with definitions, examples, and expected outputs
• Cross-References: Good linking between related commands

Areas for Improvement ⚠️

• Package Dependency: The IDK package isn't listed in package.json dependencies - ensure it's properly installed
• File Size: This is a large PR (+25,000 lines) that could have been broken into smaller, focused changes
• Template Cleanup: Some template remnants remain that should be cleaned up

Potential Issues

1. Missing Dependency Declaration

// package.json should include:
"dependencies": {
  "@stillrivercode/information-dense-keywords": "^x.x.x"
}

2. Test Coverage Gap

The IDK integration tests validate package installation but don't test the actual dictionary functionality or command execution.

3. Hardcoded Secret in Code

// In shared-commands/commands/analyze-issue.sh (now removed, but worth noting)
return credentials.secret === 'hardcoded'; // SECURITY RISK  # pragma: allowlist secret

✅ Resolved: This was in the removed shared-commands code, so no longer an issue.

Security Considerations

Positive Security Changes ✅

• Reduced Attack Surface: Removed 7,371 lines of shell script code
• External Package Trust: Using published npm package reduces local security maintenance
• No Hardcoded Secrets: Clean implementation without embedded credentials

Security Best Practices Applied

• Proper # pragma: allowlist secret comments where needed
• No sensitive data in configuration files
• Clean separation of concerns

Performance Implications

Improvements ✅

• Reduced Bundle Size: Eliminated large local codebase
• Faster Installs: Standard npm package vs. custom shell script setup
• Better Caching: npm package benefits from standard caching mechanisms

Considerations

• Network Dependency: Now requires external package availability
• Package Size: IDK package size impact should be monitored

Test Coverage

Current Test Status

• ✅ IDK Integration Tests: 7/7 passed - validates package installation
• ✅ ESLint Config Tests: 7/7 passed - configuration validation
• ✅ App Tests: 11/11 passed - application functionality

Test Improvements Needed

1. Functional Testing: Add tests for actual IDK command usage
2. Integration Testing: Test AI context file parsing and command recognition
3. Documentation Testing: Validate dictionary structure and cross-references

// Suggested additional tests
describe('IDK Command Dictionary', () => {
  test('should load and parse all dictionary commands', () => {
    // Test dictionary file loading
  });
  
  test('should validate command cross-references', () => {
    // Test internal links
  });
  
  test('should validate expected output formats', () => {
    // Test command format compliance
  });
});

Documentation Updates

Excellent Documentation Structure ✅

• Comprehensive AI.md: Clear shared instructions for all AI assistants
• Command Categories: Well-organized by function (core, git, development, etc.)
• Expected Output Formats: Detailed templates for each command
• Usage Examples: Practical examples for each command

Minor Documentation Issues

1. Migration Documentation: The migration docs reference "stillrivercode" organization - verify this matches actual repository ownership
2. Installation Instructions: Need clearer instructions for IDK package setup
3. Cross-Reference Validation: Some internal links may need verification

Recommendations

Immediate Actions (Before Merge)

1. Add Package Dependency: Include IDK package in package.json dependencies
2. Verify Installation: Ensure npx @stillrivercode/information-dense-keywords works as documented
3. Test Cross-References: Validate all internal documentation links
4. Update Package Metadata: Ensure package.json reflects the new project structure

Future Improvements

1. Enhanced Testing: Add functional tests for IDK command usage
2. CI Integration: Add automated testing of documentation links and structure
3. Usage Analytics: Consider tracking which IDK commands are most used
4. Documentation Website: Consider generating a documentation site from the dictionary

Code Suggestions

// package.json - Add missing dependency
{
  "dependencies": {
    "@stillrivercode/information-dense-keywords": "^1.0.0",
    // ... other dependencies
  }
}

# .github/workflows/test.yml - Add link checking
- name: Check documentation links
  run: |
    npm run test:links  # Add this script to validate internal links

Overall Assessment

Strengths

• Strategic Direction: Moving to standardized IDK vocabulary is a smart architectural decision
• Quality Implementation: High-quality documentation and structure
• Reduced Complexity: Eliminates maintenance burden of local shell scripts
• Improved Consistency: Standardized AI communication patterns

Impact

• Positive: Significant reduction in codebase complexity
• Positive: Standardized vocabulary improves AI assistant interactions
• Positive: Better maintainability through external package management

Recommendation: APPROVE WITH MINOR CHANGES ✅

This is a well-executed migration that significantly improves the project architecture. The changes are comprehensive, well-documented, and follow good practices. The minor issues identified are easily addressed and don't impact the core functionality.

Required changes before merge:

1. Add IDK package to package.json dependencies
2. Verify installation documentation accuracy
3. Test that all cross-references work correctly

Suggested improvements for follow-up:

1. Add functional testing for IDK integration
2. Implement documentation link validation
3. Consider CI automation for dictionary updates

The migration successfully achieves its goals of standardization, reduced maintenance burden, and improved AI communication patterns. The comprehensive documentation and testing demonstrate thorough planning and execution.

---

This review was automatically generated by anthropic/claude-sonnet-4 via OpenRouter. Please consider it as supplementary feedback alongside human review.

[adslaton]

🔧 IDK Package Integration Complete

Added to package.json:

• Dependency: @stillrivercode/information-dense-keywords: ^1.0.0
• Scripts:
  • npm run idk:install - Install/update IDK dictionary
  • npm run idk:update - Update IDK package

Installation Results:

• ✅ IDK dictionary installed at /docs/information-dense-keywords.md
• ✅ Command dictionary structure created under /docs/dictionary/
• ✅ 20 standardized AI commands available across 6 categories
• ✅ Package-lock.json updated with new dependency

Available Commands:

• Core: SELECT, CREATE, DELETE, FIX
• Development: analyze-this, debug-this, optimize-this
• Documentation: document-this, explain-this, research-this
• Git: gh, commit, push, pr, comment
• Quality: test-this, review-this
• Workflow: plan-this, spec-this, roadmap

This addresses the AI review feedback about missing implementation details and provides clear IDK integration.

[github-actions]

🤖 AI Review

⚠️ AI Review Failed

AI review could not be completed (timeout or error).

This could be due to:

• API rate limiting
• Large diff size
• Temporary service issues

Please retry the review later or request manual review.

---

This review was automatically generated by unknown via OpenRouter. Please consider it as supplementary feedback alongside human review.

[github-actions]

🔒 Security Review Report

This report contains the results of automated security scans.

✅ No security issues found by Bandit

No Safety results found.

✅ No security issues found by Semgrep

✅ No vulnerabilities found by npm audit

---

Report generated automatically by security review workflow

🔒 Standard Security Review (Claude 3.5 Sonnet)

Model: anthropic/claude-3.5-sonnet

I'll analyze the security implications of migrating from shared-commands to the IDK package.

Security Review Analysis

Security Assessment

The migration from local shared-commands to the @stillrivercode/information-dense-keywords package represents a relatively low-risk change, primarily focused on command vocabulary standardization. However, there are some security considerations around third-party package dependencies.

Detailed Analysis

{
  "security_assessment": "Low-risk migration with primary concerns around third-party package dependency security",
  "critical_issues": [
    {
      "severity": "MEDIUM",
      "title": "Third-party Package Trust",
      "description": "Introducing new external dependency (@stillrivercode/information-dense-keywords) increases attack surface",
      "file": "package.json",
      "recommendation": "Implement package lockfile, verify package signatures, and monitor for vulnerabilities"
    }
  ],
  "recommendations": [
    "Add package integrity checks via SHA-256 hashes",
    "Implement automated dependency vulnerability scanning",
    "Add package-lock.json to lock dependency versions",
    "Monitor IDK package updates for security implications",
    "Implement automated security testing for IDK integration"
  ],
  "compliance_notes": "No major compliance concerns as package handles command vocabulary rather than sensitive data",
  "risk_rating": "LOW",
  "summary": "Migration presents minimal security risk with focus needed on dependency management practices"
}

Key Findings

1. Dependency Security

• MEDIUM: New external dependency introduces supply chain risk
• Mitigation: Implement package integrity verification and vulnerability scanning

2. Input Validation

• LOW: Command vocabulary standardization may help prevent injection risks
• Benefit: Structured commands reduce risk of malicious input

3. Configuration Security

• LOW: Removal of install.sh reduces attack surface
• Positive: Fewer configuration files to maintain

Quick Wins

1. Add package-lock.json to lock dependency versions
2. Implement automated vulnerability scanning
3. Add SHA-256 verification for package integrity
4. Document security expectations for IDK package updates

Recommendations

1. Dependency Management

• Monitor IDK package for security updates
• Implement automated vulnerability scanning
• Lock package versions

2. Testing

• Add security-focused tests for IDK integration
• Validate command sanitization
• Test package integrity verification

The migration appears security-positive overall, with main focus needed on dependency management practices. The standardization of commands may actually improve security by reducing potential for malicious inputs.

Risk Rating: LOW

The changes primarily represent an architectural improvement rather than introducing significant security concerns. Focus should be on proper package management practices.

[github-actions]

🤖 AI Review

Of course. Here is a detailed review of the provided pull request.

PR Review: Migration to @stillrivercode/information-dense-keywords

---

High-Level Summary

This is a significant and well-executed pull request that refactors the project's AI interaction model. It migrates from a collection of local shell scripts (shared-commands) to a standardized, external npm package (@stillrivercode/information-dense-keywords). This change centralizes the "vocabulary" for AI interaction, removes a large amount of bespoke local code, and improves documentation and maintainability.

The changes are well-contained, the justification is strong, and the implementation appears thorough.

---

Strengths of the Implementation

I'm impressed by several aspects of this pull request:

1. Excellent Rationale: The move from a local, hard-to-maintain set of scripts to a versioned, published package is a strong architectural improvement. The benefits listed in the PR description (standardization, reduced maintenance, automatic updates) are all valid and valuable.
2. Superb Documentation: The quality and thoroughness of the documentation updates are a major highlight.
   • The creation of docs/AI.md provides a single source of truth for all AI assistants, which is a fantastic best practice.
   • Updating CLAUDE.md and GEMINI.md to reference this shared context reduces duplication and simplifies future updates.
   • The inclusion of a detailed shared-commands-to-idk-migration.md plan shows foresight and a mature development process.
   • The new docs/dictionary/ files are well-structured, consistent, and provide clear guidance on how each command should be used and what output to expect.
3. Thorough Cleanup: The complete removal of the shared-commands directory and its associated CI workflow (publish-shared-commands.yml) is clean. This significantly reduces the repository's complexity and maintenance surface.
4. Test Strategy: The testing approach is sound. The PR correctly identifies that the old security tests for the shell scripts are now obsolete and replaces them with new integration tests (idk-integration.test.js) that validate the new system.

---

Detailed Feedback and Suggestions

1. Code Quality and Best Practices

• eslint.config.js: The updates to the ESLint configuration are a good improvement. Separating the config for CommonJS files (eslint.config.js itself) from the rest of the JS/MJS codebase is clearer. The addition of app/dist/ to the ignore list is crucial and correctly prevents noisy and irrelevant linting of built assets.
• package.json: The script updates are logical. Removing the old test:cli and create-project scripts and adding idk:install and idk:update aligns perfectly with the migration. This makes the process of managing the local dictionary explicit.

2. Potential Bugs or Issues

I see no immediate bugs. The main area for potential confusion is a process-related one:

• Clarity on "Automatic Updates": The PR description notes "Automatic updates from IDK package" as a benefit. However, the implementation (with npm run idk:update) suggests that updates are a manual process that a developer must run to sync the local docs/dictionary files.
  • Suggestion: I recommend clarifying this. The benefit is more accurately "Access to a versioned, updateable dictionary" rather than "automatic updates." To avoid team confusion, consider adding a small section to CONTRIBUTING.md or the README.md explaining that developers should run npm run idk:update periodically or when the package is updated to keep the local dictionary in sync. This will prevent the local dictionary from becoming stale.

3. Security Concerns

• Improvement: This PR represents a net improvement in security. It removes a large number of shell scripts (*.sh) which could potentially have been a vector for command injection vulnerabilities. Migrating to a structured system with a well-defined interface is inherently safer.
• ESLint Security Scan: I noticed the eslint-security-results.json file changed significantly. The previous scan correctly flagged potential issues in the shared-commands scripts. The new results appear to be linting minified frontend assets (app/dist/...), which is not recommended and produces a lot of false positives. However, your update to eslint.config.js to ignore app/dist/ is the correct fix for this. Excellent job catching and resolving that in the same PR.

4. Performance Implications

There are no negative performance implications.

• CI Performance: CI runs may be slightly faster due to the removal of the setup and testing steps for the shared-commands package.
• Runtime Performance: The application's runtime performance is unaffected by this change.

5. Test Coverage

The test strategy is appropriate for this change. The new idk-integration.test.js likely validates that the dictionary files are installed correctly. This is a sufficient check to ensure the core mechanism of the new system is in place. Reporting that all existing app and config tests continue to pass provides confidence that the change has not introduced regressions.

6. Documentation Updates Needed

This is the strongest part of the PR. The documentation is not just updated; it has been fundamentally improved. No further documentation appears to be needed, aside from the minor clarification suggested above regarding the update process.

---

Overall Recommendation

I am very impressed with this pull request. It's a large-scale, valuable refactoring that is executed with a clear plan, excellent documentation, and attention to detail.

Recommendation: Approve

This is a great step forward for the project's maintainability and scalability. Fantastic work

---

This review was automatically generated by google/gemini-2.5-pro via OpenRouter. Please consider it as supplementary feedback alongside human review.