chore: git cache cleanup

2026-03-04 18:34:49 +00:00
parent c32cce2a88
commit 27c252600a
2001 changed files with 683185 additions and 0 deletions
--- a/docs/implementation/AGENT_SKILLS_MIGRATION_SUMMARY.md
+++ b/docs/implementation/AGENT_SKILLS_MIGRATION_SUMMARY.md
@@ -0,0 +1,220 @@
+# Agent Skills Migration - Research Summary
+
+**Date**: 2025-12-20
+**Status**: Research Complete - Ready for Implementation
+
+## What Was Accomplished
+
+### 1. Complete Script Inventory
+
+- Identified **29 script files** in `/scripts` directory
+- Analyzed all scripts referenced in `.vscode/tasks.json`
+- Classified scripts by priority, complexity, and use case
+
+### 2. AgentSkills.io Specification Research
+
+- Thoroughly reviewed the [agentskills.io specification](https://agentskills.io/specification)
+- Understood the SKILL.md format requirements:
+  - YAML frontmatter with required fields (name, description)
+  - Optional fields (license, compatibility, metadata, allowed-tools)
+  - Markdown body content with instructions
+- Learned directory structure requirements:
+  - Each skill in its own directory
+  - SKILL.md is required
+  - Optional subdirectories: `scripts/`, `references/`, `assets/`
+
+### 3. Comprehensive Migration Plan Created
+
+**Location**: `docs/plans/current_spec.md`
+
+The plan includes:
+
+#### A. Directory Structure
+
+- Complete `.agentskills/` directory layout for all 24 skills
+- Proper naming conventions (lowercase, hyphens, no special characters)
+- Organized by category (testing, security, utility, linting, docker)
+
+#### B. Detailed Skill Specifications
+
+For each of the 24 skills to be created:
+
+- Complete SKILL.md frontmatter with all required fields
+- Skill-specific metadata (original script, exit codes, parameters)
+- Documentation structure with purpose, usage, examples
+- Related skills cross-references
+
+#### C. Implementation Phases
+
+**Phase 1** (Days 1-3): Core Testing & Build
+
+- `test-backend-coverage`
+- `test-frontend-coverage`
+- `integration-test-all`
+
+**Phase 2** (Days 4-7): Security & Quality
+
+- 8 security and integration test skills
+- CrowdSec, Coraza WAF, Trivy scanning
+
+**Phase 3** (Days 8-9): Development Tools
+
+- Version checking, cache clearing, version bumping, DB recovery
+
+**Phase 4** (Days 10-12): Linting & Docker
+
+- 12 linting and Docker management skills
+- Complete migration and deprecation of `/scripts`
+
+#### D. Task Configuration Updates
+
+- Complete `.vscode/tasks.json` with all new paths
+- Preserves existing task labels and behavior
+- All 44 tasks updated to reference `.agentskills` paths
+
+#### E. .gitignore Updates
+
+- Added `.agentskills` runtime data exclusions
+- Keeps skill definitions (SKILL.md, scripts) in version control
+- Excludes temporary files, logs, coverage data
+
+## Key Decisions Made
+
+### 1. Skills to Create (24 Total)
+
+Organized by category:
+
+- **Testing**: 3 skills (backend, frontend, integration)
+- **Security**: 8 skills (Trivy, CrowdSec, Coraza, WAF, rate limiting)
+- **Utility**: 4 skills (version check, cache clear, version bump, DB recovery)
+- **Linting**: 6 skills (Go, frontend, TypeScript, Markdown, Dockerfile)
+- **Docker**: 3 skills (dev env, local env, build)
+
+### 2. Scripts NOT to Convert (11 scripts)
+
+Internal/debug utilities that don't fit the skill model:
+
+- `check_go_build.sh`, `create_bulk_acl_issues.sh`, `debug_db.py`, `debug_rate_limit.sh`, `gopls_collect.sh`, `cerberus_integration.sh`, `install-go-1.25.5.sh`, `qa-test-auth-certificates.sh`, `release.sh`, `repo_health_check.sh`, `verify_crowdsec_app_config.sh`
+
+### 3. Metadata Standards
+
+Each skill includes:
+
+- `author: Charon Project`
+- `version: "1.0"`
+- `category`: testing|security|build|utility|docker|linting
+- `original-script`: Reference to source file
+- `exit-code-0` and `exit-code-1`: Exit code meanings
+
+### 4. Backward Compatibility
+
+- Original `/scripts` kept for 1 release cycle
+- Clear deprecation notices added
+- Parallel run period in CI
+- Rollback plan documented
+
+## Next Steps
+
+### Immediate Actions
+
+1. **Review the Plan**: Team reviews `docs/plans/current_spec.md`
+2. **Approve Approach**: Confirm phased implementation strategy
+3. **Assign Resources**: Determine who implements each phase
+
+### Phase 1 Kickoff (When Approved)
+
+1. Create `.agentskills/` directory
+2. Implement first 3 skills (testing)
+3. Update tasks.json for Phase 1
+4. Test locally and in CI
+5. Get team feedback before proceeding
+
+## Files Modified/Created
+
+### Created
+
+- `docs/plans/current_spec.md` - Complete migration plan (replaces old spec)
+- `docs/plans/bulk-apply-security-headers-plan.md.backup` - Backup of old plan
+- `AGENT_SKILLS_MIGRATION_SUMMARY.md` - This summary
+
+### Modified
+
+- `.gitignore` - Added `.agentskills` runtime data patterns
+
+## Validation Performed
+
+### Script Analysis
+
+✅ Read and understood 8 major scripts:
+
+- `go-test-coverage.sh` - Complex coverage filtering and threshold validation
+- `frontend-test-coverage.sh` - npm test with Istanbul coverage
+- `integration-test.sh` - Full E2E test with health checks and routing
+- `coraza_integration.sh` - WAF testing with block/monitor modes
+- `crowdsec_integration.sh` - Preset management testing
+- `crowdsec_decision_integration.sh` - Comprehensive ban/unban testing
+- `crowdsec_startup_test.sh` - Startup integrity checks
+- `db-recovery.sh` - SQLite integrity and recovery
+
+### Specification Compliance
+
+✅ All proposed SKILL.md structures follow agentskills.io spec:
+
+- Valid `name` fields (1-64 chars, lowercase, hyphens only)
+- Descriptive `description` fields (1-1024 chars with keywords)
+- Optional fields used appropriately (license, compatibility, metadata)
+- `allowed-tools` lists all external commands
+- Exit codes documented
+
+### Task Configuration
+
+✅ Verified all 44 tasks in `.vscode/tasks.json`
+✅ Mapped each script reference to new `.agentskills` path
+✅ Preserved task properties (labels, groups, problem matchers)
+
+## Estimated Timeline
+
+- **Research & Planning**: ✅ Complete (1 day)
+- **Phase 1 Implementation**: 3 days
+- **Phase 2 Implementation**: 4 days
+- **Phase 3 Implementation**: 2 days
+- **Phase 4 Implementation**: 2 days
+- **Deprecation Period**: 18+ days (1 release cycle)
+- **Cleanup**: After 1 release
+
+**Total Migration**: ~12 working days
+**Full Transition**: ~30 days including deprecation period
+
+## Risk Assessment
+
+| Risk | Mitigation |
+|------|------------|
+| Breaking CI workflows | Parallel run period, fallback to `/scripts` |
+| Skills not AI-discoverable | Comprehensive keyword testing, iterate on descriptions |
+| Script execution differences | Extensive testing in CI and local environments |
+| Documentation drift | Clear deprecation notices, redirect updates |
+| Developer confusion | Quick migration timeline, clear communication |
+
+## Questions for Team
+
+1. **Approval**: Does the phased approach make sense?
+2. **Timeline**: Is 12 days reasonable, or should we adjust?
+3. **Priorities**: Should any phases be reordered?
+4. **Validation**: Do we have access to `skills-ref` validation tool?
+5. **Rollout**: Should we do canary releases for each phase?
+
+## Conclusion
+
+Research is complete with a comprehensive, actionable plan. The migration to Agent Skills will:
+
+- Make scripts AI-discoverable
+- Improve documentation and maintainability
+- Follow industry-standard specification
+- Maintain backward compatibility
+- Enable future enhancements (skill composition, versioning, analytics)
+
+**Plan is ready for review and implementation approval.**
+
+---
+
+**Next Action**: Team review of `docs/plans/current_spec.md`