feat: release v0.2.0 with instruction file management and audit-north…#5
Merged
Conversation
added 30 commits
April 16, 2026 19:18
…star skill - Add instruction file management with managed blocks (CLAUDE.md, AGENTS.md, etc.) - Add easyskillz docs commands (sync, list, add, remove) - Add easyskillz export command to copy skills to other projects - Add audit-northstar skill for North Star principle compliance checking - Add INSTALL-SKILL.md guide for AI assistants - Expand meta-skill with all v0.2.0 commands - Upgrade instruction files automatically (remove old single-line hints) - Add docsFolders config field for tracked folders - Add comprehensive test coverage for new features BREAKING CHANGE: wirer.appendInstruction deprecated (kept for backward compatibility)
BREAKING CHANGE: Complete redesign of docs management - Replace managed blocks with centralized architecture - All instruction files now centralized in .easyskillz/docs/ - Symlinks created at expected locations (gitignored) - Two strategies: unified (one INSTRUCTION.md per folder) or tool-specific (separate per tool) - Auto-detection scans entire repo on sync - All-in or all-out approach - single opt-in, then fully automated - Remove docsFolders config - replaced with manageDocs + docsStrategy - Remove easyskillz docs add/remove commands - Keep easyskillz docs sync (force re-scan) and list (show centralized files) - Support hierarchical instruction files (root, subfolders, nested) - Update gitignore to ignore instruction file symlinks at all levels - All 52 tests passing
- Add interactive prompt for gitignore strategy (full/conflict-only/none) - Add configFiles registry field for conflict-prone config files - Add src/gitignore/ module with promptGitignoreSetup and updateGitignore - Update sync command to prompt for strategy on first run - Update register command to respect existing gitignore strategy - Non-TTY mode defaults to 'full' strategy - Fix prompt timing to work with already-synced repos - Fix null strategy handling in all code paths - Fix empty gitignore sections in conflict-only mode BREAKING CHANGE: wirer.updateGitignore() removed, use gitignore/updateGitignore module instead
- Enhance _easyskillz meta-skill with comprehensive documentation - Add 'Why Use easyskillz' section - Add 'Creating Skills - ALWAYS Use easyskillz' section with examples - Add file structure diagram - Add best practices section - Emphasize importance of using easyskillz add command - Improve managed block in instruction files - More comprehensive with code examples - Link to _easyskillz skill for full documentation - Explain source of truth and symlink architecture - Remove deprecated appendInstruction function from wirer.js - Make meta-skill so compelling that AIs naturally use easyskillz commands
- Create easyskillz-setup skill - First-time setup and sync workflow - Create easyskillz-add skill - Creating new skills with clear triggers - Create easyskillz-register skill - Adding new AI tools to project - Create easyskillz-reference skill - Complete documentation (replaces _easyskillz) - Remove _easyskillz meta-skill (replaced by easyskillz-reference) - Update META_SKILL constant to use easyskillz-reference - Update managed block to reference easyskillz-reference Each skill has: - Clear 'When to Use This Skill' section with specific triggers - Detailed instructions with examples - Expected output samples - Troubleshooting guidance - Related skills references Result: AIs can now easily identify which skill to use based on user intent
- Add AI agent detection utility (src/utils/detectAI.js) - Detects universal standards: AGENT, AI_AGENT - Detects tool-specific vars: CLAUDECODE, CURSOR_AGENT, GEMINI_CLI, etc. - Verified Windsurf detection: WINDSURF_CASCADE_TERMINAL - Shows helpful warnings when AI tries interactive commands - Implement easyskillz list command - Lists active and deactivated skills - JSON output support - Implement easyskillz deactivate <skill> command - Soft delete (renames to .skill.disabled/) - Removes symlinks from all tools - Reversible with activate - No confirmation needed (safe operation) - Implement easyskillz activate <skill> command - Restores deactivated skill - Re-wires to all registered tools - No confirmation needed (safe operation) - Implement easyskillz remove <skill> --confirm command - Hard delete (permanent) - AI detection with warning message - Interactive confirmation for humans - --confirm flag for AI agents - Implement easyskillz unregister <tool> --mode --confirm command - Two modes: full (delete tool dir) or revert (keep files) - AI detection with warning message - Interactive prompts for humans - --mode and --confirm flags for AI agents All commands are pipeable and AI-friendly by default.
BREAKING CHANGE: Complete command structure rewrite Old commands (removed): - easyskillz sync - easyskillz add - easyskillz list - easyskillz register New domain-based structure: - easyskillz skill <action> - easyskillz tool <action> - easyskillz project <action> - easyskillz docs <action> Key Features: 1. Domain-Based Organization - skill: add, remove, activate, deactivate, list - tool: register, unregister, list - project: sync, export - docs: sync, list 2. One-Shot Execution for AI Agents - If ANY flag provided = one-shot mode - All required flags must be provided (no defaults) - Missing flags = clear error messages - Example: easyskillz project sync --docs=yes --docs-strategy=unified --gitignore=full 3. AI Detection Before Interactive Prompts - Detects AI agents (Windsurf, Claude, Cursor, etc.) - Shows warning before entering interactive mode - Guides AI to use correct flags - Prevents AIs from getting stuck in prompts 4. Strict Flag Validation - One-shot mode requires ALL flags - No silent defaults when flags are provided - Clear error messages with usage examples 5. Interactive Mode for Humans - No flags = interactive prompts (if TTY) - AI detection prevents AIs from using interactive mode - Confirmation prompts for destructive operations Documentation: - Added docs/COMMAND_DESIGN.md with complete philosophy - Explains one-shot vs interactive modes - Documents all flags and behaviors Implementation: - Created src/domains/ for domain handlers - Updated src/commands/sync.js with flag support - Added AI detection to sync command - Comprehensive flag parsing in CLI
Release Notes: - Complete domain-based command rewrite (BREAKING CHANGE) - AI-first one-shot execution with strict flag validation - AI detection with helpful warnings - Windsurf detection verified (WINDSURF_CASCADE_TERMINAL) - Comprehensive command design philosophy documented Breaking Changes: - All commands now use domain-based structure - Old: easyskillz sync → New: easyskillz project sync - Old: easyskillz add → New: easyskillz skill add - Old: easyskillz register → New: easyskillz tool register New Features: - One-shot mode: any flag = all flags required - AI detection prevents interactive prompts - Domain handlers: skill, tool, project, docs - Strict flag validation with clear errors - Complete docs/COMMAND_DESIGN.md Files Changed: - Complete CLI rewrite (bin/easyskillz.js) - New domain handlers (src/domains/) - AI detection utility (src/utils/detectAI.js) - Updated sync command with flag support - Command design philosophy documentation
- Add COMMAND_GUIDANCE registry with detailed flag explanations
- Show questions AI should ask the user
- Display flag options with recommended values marked
- Provide recommended command for common use cases
- Add AI detection to plan() confirmation prompt
Command Guidance Added:
- project sync: docs, docs-strategy, gitignore flags
- skill remove: confirm flag
- tool unregister: mode and confirm flags
Warning Format:
1. ASK THE USER - specific questions to ask
2. UNDERSTAND the flags - each flag explained with options
3. RUN the command - syntax with placeholders
4. RECOMMENDED - suggested command for most users
Example Output:
📋 WHAT TO DO:
1. ASK THE USER these questions:
1. Do you want easyskillz to manage your instruction files?
2. If yes: Should instruction files be unified or tool-specific?
3. How should .gitignore be configured?
2. UNDERSTAND the flags:
--docs
Manage instruction files (CLAUDE.md, AGENTS.md, etc.)
[✓] yes: Centralize instruction files in .easyskillz/docs/
[ ] no: Leave instruction files as-is
💡 RECOMMENDED (for most users):
easyskillz project sync --docs=yes --docs-strategy=unified --gitignore=full
This ensures AIs know exactly what to ask and how to run commands.
Create foundation for object-oriented command pattern to centralize: - AI detection and warnings - Flag parsing and validation - Interactive prompt handling - One-shot mode detection - Error handling and JSON output Benefits: - Eliminates code duplication across commands - Centralizes AI detection logic - Automatic one-shot mode handling - Consistent error messages - Easier to maintain and extend Files Added: - src/core/BaseCommand.js - Base class for all commands - src/commands/remove.new.js - Refactored remove command example - src/commands/sync.new.js - Refactored sync command example - docs/OOP_ARCHITECTURE.md - Complete architecture documentation Features: - hasFlags() - Detect one-shot mode - validateOneShotFlags() - Validate required flags - prompt() - Safe prompting with AI detection - getFlagOrPrompt() - Get flag or prompt user - confirm() - Confirmation with --confirm flag support - jsonOutput() - Consistent JSON output - error() - Consistent error handling Next Steps: - Migrate all commands to use BaseCommand - Remove old procedural command files - Update tests for new architecture
BREAKING CHANGE: Complete command reorganization Old Structure: - src/commands/*.js (flat) New Structure: - src/commands/skill/*.js (AddCommand, RemoveCommand, etc.) - src/commands/tool/*.js (RegisterCommand, UnregisterCommand, etc.) - src/commands/project/*.js (SyncCommand, etc.) - src/core/BaseCommand.js (base class) All Commands Refactored: ✅ skill/AddCommand ✅ skill/RemoveCommand ✅ skill/DeactivateCommand ✅ skill/ActivateCommand ✅ skill/ListCommand ✅ tool/RegisterCommand ✅ tool/UnregisterCommand ✅ tool/ListCommand ✅ project/SyncCommand Benefits: - 40% less code per command - AI detection automatic - Consistent error handling - Clean domain separation - Easy to extend Domain Handlers Updated: - src/domains/skill.js - uses skill commands - src/domains/tool.js - uses tool commands - src/domains/project.js - uses project commands No backward compatibility - clean break for v2.0.0
- Add alpha installation instructions - Update all commands to domain-based structure - Add AI-friendly one-shot execution examples - Update project sync example - Highlight v2.0.0 changes Published: easyskillz@2.0.0-alpha.3
Bug 1: SyncCommand constructor missing - Added constructor(cwd, options) to match BaseCommand pattern - this.cwd was undefined, causing crash on detect() Bug 2: plan() blocking one-shot execution - Added skipConfirm parameter to plan() - SyncCommand now passes skipConfirm=true when hasFlags() - Allows one-shot AI execution without prompts Bug 3: docs commands referencing old command name - Updated error messages from 'easyskillz sync' to 'easyskillz project sync' - Both docsSync and docsList updated Tested: ✅ easyskillz project sync --docs=yes --docs-strategy=unified --gitignore=full ✅ easyskillz skill list ✅ easyskillz tool list ✅ easyskillz docs list All commands now work correctly in one-shot mode.
Create automated QA workflow that: - Builds package locally with npm pack - Installs in temporary test environment (.qa-temp/) - Tests all command flows exhaustively - Validates AI-first design principles - Checks philosophy compliance - Identifies friction points - Generates detailed QA report Test Coverage: ✅ Project sync (one-shot + interactive) ✅ Skill management (add/list/activate/deactivate/remove) ✅ Tool management (register/unregister/list) ✅ Docs management (sync/list) ✅ JSON output for all commands ✅ Error handling (missing args, invalid flags, etc.) ✅ AI detection and warnings ✅ Help system Philosophy Checks: ✅ AI-first design (one-shot execution) ✅ Domain-based organization ✅ Destructive operations require confirmation ✅ Error message clarity ✅ Flag consistency Friction Detection: ✅ Confusing messages ✅ Unexpected prompts ✅ Inconsistent behavior ✅ Missing feedback ✅ Old command references Usage: Ask AI: 'Run the easyskillz-qa skill and give me a full report' The AI will execute all tests and report bugs, violations, and friction. Also: - Added .qa-temp/ to .gitignore - Added *.tgz to .gitignore (npm pack output)
…o-repair Summary of changes: - Windsurf Dual-Wiring: single registration wires skills/ and workflows/ - Surgical Gitignore: managed block with markers preserves unmanaged tool files (hooks/scripts) - Skill Auto-Repair: automatically injects required Gemini CLI YAML frontmatter - Case-Insensitive Registration: tool IDs normalized to lowercase - Maintenance: restored deprecated wirer exports for backward compatibility
…tignore - Untracked .claude/settings.local.json and .cursor/rules - Simplified 'full' gitignore strategy to ignore root folders for hidden tool dirs - Removed redundant config file entries when root is ignored
- Added 'smart' and 'minimal' gitignore strategies - Updated sync prompt with detailed strategy explanations - Expanded meta-skill documentation with gitignore strategy details - Applied full gitignore to repository root
- Detectors now check multiple markers (e.g. folder root + config files) - Claude and Gemini detected even if settings.json is missing - Updated CONTRIBUTING.md with new detector pattern
- Updated main README with 'Automated Behaviors' and 'Gitignore Strategies' sections - Added README.md to each internal source subdirectory to explain roles and responsibilities
…atures - Created tests/e2e/helpers.js for repo mocking and CLI execution - Created tests/e2e/scenarios.test.js with 17 highly realistic user scenarios - Verified all scenarios pass locally
- Added tests/README.md to explain test suite - Removed internal research and outdated design proposals from docs/ - Cleaned up repository for public release
…ogic - Propagated skipAutoRepair to all wiring functions to support non-destructive export - Finalized surgical gitignore block with support for smart switching - Cleaned up test artifacts
- Updated package.json to v0.2.0 - Reorganized and finalized CHANGELOG.md
- Added .github/workflows/ci.yml - Configured to run unit and E2E tests on Node 18, 20, 22 - Triggers on PRs to main and release branches
- Updated tests/README.md with detailed E2E scenario catalog - Documented user context, actions, and expected results for all 21 scenarios
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What's New in v0.2.0
Features
easyskillz docscommands:sync,list,add,removeeasyskillz export: Copy skills + config to other projectsChanges
easyskillz syncnow writes managed blocks instead of single-line hintsBreaking Changes
wirer.appendInstructiondeprecated (kept for backward compatibility)Stats
Checklist