@rfxlamia/skillkit 1.0.0 → 1.2.0

package/skills/skills/skillkit/CHANGELOG.md

@@ -0,0 +1,484 @@
+# Changelog
+
+All notable changes to the Claude Skill Kit project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [2.1.6] - 2026-03-14
+
+### Fixed
+- Installation via Claude Code plugin marketplace is currently broken due to a `disable-model-invocation` conflict between plugin commands and skills of the same name — marked as known issue in README
+
+### Documentation
+- Updated README installation section: recommend copying skills directly to `~/.claude/skills/` as the reliable method
+- Plugin marketplace section now clearly marked with ⚠️ known issue warning
+
+---
+
+## [2.1.0] - 2026-03-13
+
+### Added
+- **Full Mode Behavioral Testing Protocol** (`references/section-2-full-creation-workflow.md`)
+  - STEP 3 (RED): Subagent dispatch instructions for baseline pressure testing
+  - STEP 7 (GREEN): Compliance verification with skill loaded
+  - STEP 12 (REFACTOR): Combined pressure testing to close loopholes
+  - Pattern ported from `writing-skills` TDD methodology
+
+### Changed
+- `SKILL.md`: Full mode Steps 3, 7, 12 now reference section-2 (mandatory load)
+
+### Deprecated
+- `pressure_tester.py`: Superseded by section-2 Full Mode Behavioral Testing Protocol
+  - Script now exits with deprecation message and code 1
+  - Scenario definitions (PressureType, SkillType) preserved as reference data
+
+## [2.0.1] - 2026-03-06
+
+### Fixed
+- `decision_helper.py`: Added `mode_reasoning` alongside `mode_note` for output contract compatibility.
+- `test_generator.py`: Behavioral template generation is now gated to pytest mode only.
+- `pressure_tester.py`: Added explicit stub-mode warning output.
+
+### Changed
+- Updated hardcoded local path examples to portable path usage in SkillKit docs and tool guides.
+- Enforced stronger stop conditions in `SKILL.md` (mode selection, user approval gates, ambiguous routing).
+- Deprecated legacy structural-only `test_generator.py` usage in favor of v2 behavioral workflow guidance.
+
+## [2.0.0] - 2025-03-05
+
+### Added
+- **Workflow Modes**: Fast mode (original 12-step) and Full mode (15-step with TDD)
+- **Behavioral Testing**: `pressure_tester.py` for testing skill compliance under pressure
+- **Rationalization Catalog**: Pre-built tables for common agent rationalizations
+- **Quality Scoring v2**: 60/40 split (structural/behavioral) in full mode
+- **Mode Selection**: `--mode` flag across all tools
+- **TDD Integration**: RED-GREEN-REFACTOR cycle for skill creation
+
+### Changed
+- `decision_helper.py`: Now recommends workflow mode based on skill type
+- `init_skill.py`: Mode selection prompt during skill creation
+- `quality_scorer.py`: Added behavioral scoring dimension
+- `token_estimator.py`: Includes behavioral testing cost
+- `test_generator.py`: Generates behavioral pressure tests
+- SKILL.md: Updated to v2 workflow documentation
+
+### Migration Guide
+```bash
+# Existing skills continue to work (fast mode is default)
+# To use full mode:
+python3 scripts/init_skill.py my-skill --mode full
+```
+
+## [1.3.0] - 2025-02-06
+
+### Summary
+Major feature release adding **subagent creation capability** to skillkit. Previously, skillkit could only create skills and would stop if decision workflow recommended subagents. Now it can create BOTH skills and subagents with full workflows for each.
+
+### Added
+
+#### Subagent Creation Support (NEW)
+- **`init_subagent.py`** - Automation script for subagent initialization
+  - Creates SUBAGENT.md with comprehensive template
+  - Includes YAML frontmatter configuration
+  - Defines role, workflow, triggers, and examples
+  - **Usage**: `python scripts/init_subagent.py name --path /path`
+
+- **Section 6: Subagent Creation Workflow** (`references/section-6-subagent-creation-workflow.md`)
+  - 8-step process for creating subagents
+  - Step 0: Requirements & Role Definition
+  - Step 1: Initialize Structure
+  - Step 2: Define Configuration (YAML)
+  - Step 3: Define Role and Workflow
+  - Step 4: Define Response Format
+  - Step 5: Add Examples
+  - Step 6: Validation
+  - Step 7: Testing
+  - Step 8: Documentation & Deployment
+
+- **Subagent Creation Guide** (`knowledge/tools/23-subagent-creation-guide.md`)
+  - Step-by-step guide for using init_subagent.py
+  - SUBAGENT.md structure documentation
+  - Subagent types and tool permissions
+  - Validation checklist
+  - Testing and deployment guidance
+
+#### Updated Decision Workflow
+- **Section 4** now supports subagent creation path
+  - Previously: "Subagents" recommendation → STOP (out of scope)
+  - Now: "Subagents" recommendation → PROCEED to Section 6
+  - Added "Hybrid" recommendation handling
+
+#### Updated SKILL.md
+- New intent detection: "create subagent" routes to Section 6
+- Added Section 6 overview for subagent creation
+- Updated tool list to include init_subagent.py
+- Updated description to mention subagent creation
+- Renumbered sections (Section 7 → Section 8)
+
+#### Updated Knowledge Index
+- Added File 23: Subagent Creation Guide
+- Total files: 22 → 23
+
+### Changed
+
+- **Decision Helper** workflow now continues to subagent creation
+- **Tool count**: 9 → 10 automation scripts
+- **Primary triggers** updated to include "create subagent"
+
+### Migration Guide
+
+#### For Users
+
+No breaking changes. New capability is additive:
+- Existing skill creation workflows unchanged
+- New subagent creation workflow available
+- Decision workflow now has complete path for all recommendations
+
+#### Usage Examples
+
+**Create a Skill:**
+```bash
+python scripts/init_skill.py my-skill --path /path
+```
+
+**Create a Subagent:**
+```bash
+python scripts/init_subagent.py my-subagent --path /path
+```
+
+**Decision Workflow (now with subagent support):**
+```
+User: "Should I use Skill or Subagent for code review?"
+→ Run decision_helper.py
+→ If "Subagent" recommended
+→ PROCEED to Section 6 (Subagent Creation)
+```
+
+---
+
+## [1.2.1] - 2025-11-14
+
+### Summary
+Critical bug fixes for quality scoring and confidence calculation. Imperative voice detection improved by 11x, making quality scores more accurate and reliable.
+
+### Fixed
+
+- **quality_scorer.py**: Fixed imperative voice detection logic
+  - Strip YAML frontmatter before processing
+  - Remove markdown formatting (bold, italic, code, links)
+  - Check first 3 words instead of only first word
+  - Lowered threshold: 70% → 50% for full points (30% for partial)
+  - Added more imperative verbs (load, scan, extract, detect, etc.)
+  - **Impact**: Imperative detection improved from 3.33% to 37.50% (11x improvement)
+  - **Example**: readme-expert.skill score improved from 78/100 (Grade C) to 81/100 (Grade B)
+
+- **decision_helper.py**: Fixed confidence calculation bug for Subagent recommendations
+  - Score -3 was showing 82% confidence (should be 75%)
+  - Score -5 was showing 75% confidence (should be 85%)
+  - Confidence was increasing as scores got weaker (backwards logic)
+  - **Root cause**: Formulas used `(score + 5)` and `(score + 8)` which made confidence increase as absolute score decreased
+  - **Fix**: Changed to `(abs(score) - 3)` and `(abs(score) - 6)` to ensure confidence increases with stronger scores
+
+### Changed
+
+- **.gitignore**: Added test directories and Python cache files
+  - Added `__pycache__/` directories
+  - Added `test/` and `tests/` directories
+  - Prevents test artifacts from being committed
+
+### Testing
+
+- ✅ quality_scorer.py: Verified imperative detection on multiple skills
+- ✅ decision_helper.py: Tested with multiple score values to verify correct behavior
+- ✅ Style scores: Average improvement of 73% in scoring accuracy
+
+---
+
+## [1.2.0] - 2025-11-13
+
+### Summary
+Comprehensive quality assurance improvements addressing Test Session #3 findings. Focus: prevent file bloat, broken references, and tool inconsistencies. **81% of issues fixed** with new utility infrastructure.
+
+### Added
+
+#### Infrastructure & Utilities (v1.2)
+- **`budget_tracker.py`** - FileContentBudget class for hard content limits
+  - Hard line/token limits (P0: ≤150 lines, P1: ≤100, P2: ≤60)
+  - Real-time progress tracking with 80% warning threshold
+  - TokenCounter with no external dependencies (works in Claude.ai)
+  - STANDARD_BUDGETS constants for P0/P1/P2 priorities
+  - **Addresses Issue #2**: File Size Bloat (prevents 4-9x target overruns)
+
+- **`reference_validator.py`** - File reference validation system
+  - CrossReferenceValidator class: Comprehensive markdown/code/path reference detection
+  - SkillPackageValidator wrapper: Pre-packaging validation
+  - Orphaned file detection: Finds unreferenced files in skill directory
+  - ValidationResult dataclass: Structured error reporting
+  - **Addresses Issues #1, #5, #7**: Broken references, file validation, orphaned files
+
+- **Enhanced `validate_skill.py`** (v1.2)
+  - Integrated CrossReferenceValidator for comprehensive checking
+  - Detects: broken links, missing files, orphaned files
+  - Graceful fallback to simple validation if utility unavailable
+  - More detailed error messages with actionable suggestions
+
+- **Enhanced `package_skill.py`** (v1.2)
+  - Pre-packaging reference validation (detects issues before deployment)
+  - Orphaned file warnings
+  - New `--strict` flag for strict validation mode
+  - Prevents incomplete/broken skills in packages
+
+### Changed
+
+#### Parameter Standardization (v1.2)
+- **test_generator.py**: Major parameter restructuring
+  - `--format {pytest,unittest,plain}` → `--test-format {pytest,unittest,plain}` (test framework choice)
+  - `--output {text,json}` → `--format {text,json}` (standardized output style)
+  - Backward compatibility: Old `--output` still works with deprecation warning
+  - Migration path: Remove `--output` in v2.0.0
+  - **Addresses Issue #3**: Tool Parameter Inconsistency
+
+#### Documentation Updates (v1.2)
+- **SKILL.md**:
+  - Removed old [ENHANCED] and [NEW] labels for cleaner readability
+  - Step 1c: Clarified Verbalized Sampling strategy (3-4 searches, respect p>0.10 thresholds)
+  - Step 1f: Added concise execution planning overview with reference to detailed section
+  - Step 2.5/2.8: Moved detailed instructions to references/section-2-full-creation-workflow.md
+  - Section 6: Updated test_generator.py parameters documentation
+  - New "Quality Assurance Enhancements (v1.2+)" section highlighting improvements
+
+- **Tool Guides**: Updated 19-test-generator-guide.md with new parameter documentation
+
+#### Procedural Improvements (v1.2)
+- **Step 1c (Research)**: Documented enforcement of VS probability thresholds (p>0.10, p>0.12)
+  - Only execute 3-4 searches based on probability, not all 5
+  - Reduces research phase tokens: 13k → 8-10k (~25% savings)
+  - **Addresses Issue #4**: Research Tokens (60% fixed, procedural guidance added)
+
+- **Step 1f (Execution Planning)**: Description length validation documented
+  - Recommend validating description (max 1024 chars) before generation
+  - Prevents wasted tokens if description fails validation
+  - **Addresses Issue #6**: Description Validation (100% fixed via documentation)
+
+### Fixed
+
+- **Broken Reference Pattern** (Issue #1): Now detectable via validate_skill.py → package_skill.py validation chain
+- **File Size Bloat** (Issue #2): FileContentBudget class provides enforcement mechanism
+- **Tool Parameter Inconsistency** (Issue #3): All tools now standardized, backward compatible
+- **File Existence Validation** (Issue #5): Comprehensive markdown/code/path reference checking
+- **Orphaned Files** (Issue #7): Detection and warning in packaging step
+
+### Testing
+
+- ✅ Import tests: Both new utilities (budget_tracker, reference_validator) working
+- ✅ Parameter compatibility: test_generator.py accepts both --test-format and --format
+- ✅ Backward compatibility: Old --output parameter still works with deprecation warnings
+- ✅ Reference validation: Comprehensive file detection via multiple patterns
+
+### Migration Guide
+
+#### For Users Upgrading from v1.0.1
+
+**Breaking Changes:** None - Full backward compatibility maintained
+
+**Recommended Updates:**
+1. Review Step 1f (execution planning) section in SKILL.md for P0/P1/P2 approach
+2. Note: test_generator.py has new parameter structure:
+   - Old: `python scripts/test_generator.py skill/ --format pytest --output json`
+   - New: `python scripts/test_generator.py skill/ --test-format pytest --format json`
+   - Old parameters still work until v2.0.0 (with deprecation warnings)
+
+3. Test new validation: `python scripts/validate_skill.py skill/ --format json`
+   - Now catches broken references more comprehensively
+
+#### For Automation/CI-CD Pipelines
+
+- Parameter migration: Replace `--output` with `--format` for test_generator.py
+- New validation available: Use package_skill.py `--strict` flag for deployment gates
+- All tools now fully standardized with `--format json` support
+
+### Deprecations
+
+- `test_generator.py --output`: Use `--format` instead (removal planned v2.0.0)
+
+---
+
+## [1.0.1] - 2025-11-11
+
+### Added
+
+#### JSON Output Standardization (Issue #1)
+- **Shared utility module** (`scripts/utils/output_formatter.py`) for standardized JSON/text output
+- **JSON support** for all 9 automation tools via `--format {text|json}` parameter
+- **Standardized JSON schema** across all tools for consistency:
+  ```json
+  {
+    "status": "success" | "error",
+    "tool": "tool_name",
+    "timestamp": "ISO-8601",
+    "data": { /* tool-specific results */ }
+  }
+  ```
+- **Error response standardization** with helpful messages and troubleshooting hints
+
+#### Navigation & Documentation (Issue #5)
+- **Knowledge base index** (`knowledge/INDEX.md`) - comprehensive navigation guide for all 22 knowledge files
+  - Organized by: Topic, Workflow Step, Use Case
+  - Quick keyword search (A-Z)
+  - Loading strategy recommendations (Quick/Standard/Complex)
+  - Maintenance notes for future updates
+
+### Changed
+
+#### Tool Parameter Standardization
+- **token_estimator.py**: `--output` parameter renamed to `--format` (backward compatible)
+- **split_skill.py**: `--output` parameter renamed to `--format` (backward compatible)
+- **pattern_detector.py**: Added full JSON support via `--format` parameter
+  - Analysis mode: `--format json` for structured recommendations
+  - List mode: `--format json` for parseable pattern data
+  - Interactive mode: Text-only (JSON not applicable)
+- **decision_helper.py**: Added `--format` parameter with modes:
+  - Default: `json` (agent-layer optimization)
+  - Optional: `text` (human-readable for debugging)
+
+#### Documentation Updates
+- **SKILL.md**: Updated Section 6 with current tool capabilities
+  - Removed outdated "Known Issues" section
+  - Added "Tool Output Standardization" section
+  - Updated all tool usage examples with `--format` parameter
+- **knowledge/tools/15-cost-tools-guide.md**: Added JSON output documentation for token_estimator.py
+- **knowledge/tools/17-pattern-tools-guide.md**: Added JSON support documentation for pattern_detector.py
+- **knowledge/tools/18-decision-helper-guide.md**: Added text mode documentation for decision_helper.py
+
+### Fixed
+- **Inconsistent parameter names** across automation tools (all now use `--format`)
+- **Missing JSON output** for pattern_detector.py and decision_helper.py
+- **JSON parse errors** when piping tool output to `python -m json.tool`
+- **Automation blockers** - tools now fully support CI/CD integration
+
+### Testing
+- All 9 tools validated with `python -m json.tool` for JSON correctness
+- Backward compatibility verified - text mode still works as default
+- Regression tests passed for existing tool functionality
+
+---
+
+## [1.0.0] - 2025-11-10
+
+### Initial Release
+
+#### Core Workflow
+- 12-step skill creation workflow with validation gates
+- Research-driven approach with web search integration
+- Multi-proposal generation (3-5 options)
+- Execution planning with P0/P1/P2 prioritization
+- Token budget allocation and monitoring
+
+#### Automation Scripts (9 tools)
+1. **validate_skill.py** - Structure and YAML validation
+2. **token_estimator.py** - Token consumption and cost estimation
+3. **split_skill.py** - Progressive disclosure auto-splitting
+4. **pattern_detector.py** - Workflow pattern recommendation
+5. **decision_helper.py** - Skills vs Subagents decision tree
+6. **security_scanner.py** - Security vulnerability detection
+7. **test_generator.py** - Automated test generation
+8. **quality_scorer.py** - 5-category quality scoring (100 points)
+9. **migration_helper.py** - Document to skill conversion
+
+#### Knowledge Base (22 files)
+- **Foundation** (Files 01-08): Core concepts and decision frameworks
+- **Application** (Files 09-13): Real-world implementation guidance
+- **Tools** (Files 14-22): Automation script documentation
+
+#### Quality Features
+- Target quality score: 9.0+/10
+- Security scanning for hardcoded secrets and dangerous patterns
+- Token optimization with progressive disclosure
+- Comprehensive validation with automated fixes
+
+#### Integration
+- Anthropic's production-tested init_skill.py and package_skill.py
+- Web search for domain research (3-5 queries)
+- On-demand knowledge file loading
+- Structured workflows with checkpoints
+
+---
+
+## Version History Summary
+
+| Version | Date | Key Changes |
+|---------|------|-------------|
+| **2.1.0** | 2026-03-13 | Full mode TDD behavioral protocol, deprecate pressure_tester.py |
+| **2.0.1** | 2026-03-06 | Bug fixes: decision_helper, test_generator, pressure_tester stub warning |
+| **2.0.0** | 2025-03-05 | Workflow modes (fast/full), behavioral testing, quality scoring v2 |
+| **1.3.0** | 2025-02-06 | Subagent creation support, 10 tools, 23 knowledge files |
+| **1.2.1** | 2025-11-14 | Bug fixes: imperative detection (11x improvement), confidence calculation, gitignore |
+| **1.2.0** | 2025-11-13 | Quality assurance improvements, 81% of issues fixed, new utilities |
+| **1.0.1** | 2025-11-11 | JSON standardization, navigation improvements |
+| **1.0.0** | 2025-11-10 | Initial release with 12-step workflow, 9 tools, 22 knowledge files |
+
+---
+
+## Upgrade Guide
+
+### From 1.0.0 to 1.0.1
+
+#### Breaking Changes
+**None** - This release is fully backward compatible.
+
+#### Recommended Actions
+1. **Update tool invocations** to use `--format` parameter:
+   ```bash
+   # Old (still works)
+   python scripts/token_estimator.py skill-name/ --output json
+
+   # New (recommended)
+   python scripts/token_estimator.py skill-name/ --format json
+   ```
+
+2. **Use knowledge/INDEX.md** for faster file lookup:
+   - Quick topic search
+   - Workflow step mapping
+   - Use case examples
+
+3. **Update automation scripts** to use standardized JSON output:
+   ```bash
+   # Parseable JSON output
+   python scripts/pattern_detector.py "use case" --format json | python -m json.tool
+   ```
+
+#### Deprecations
+- `--output` parameter (token_estimator.py, split_skill.py) - Use `--format` instead
+  - **Timeline**: Will be removed in v2.0.0 (6+ months)
+  - **Migration**: Simple rename, all functionality preserved
+
+---
+
+## Future Roadmap
+
+### Planned for v1.1.0
+- Issue #4: Workflow tiering (Express/Standard/Full modes)
+- Improved quality scorer calibration
+- Additional pattern templates
+
+### Under Consideration
+- GitHub Actions integration
+- VS Code extension
+- Interactive web UI for skill creation
+
+---
+
+## Contributing
+
+Changes are tracked through:
+- GitHub issues for feature requests and bugs
+- Testing reports in `fixthis/` directory
+- Version-controlled documentation updates
+
+---
+
+**Generated with:** Claude Skill Kit v2.1.0
+**Last Updated:** 2026-03-14