@amrhas82/agentic-kit 1.10.0 → 1.11.0

package/CHANGELOG.md

@@ -17,6 +17,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.11.0] - 2026-01-20
+
+### Added
+- `/stash` command for saving session context for compaction recovery or handoffs (added to all packages: claude, opencode, ampcode, droid)
+
+### Changed
+- Updated command count from 20 to 21 across all documentation
+- README.md: Updated command counts and added stash to command list
+- installer/cli.js: Updated welcome banner to reflect 21 commands
+- package.json: Updated description to reflect 21 commands
+
+### Fixed
+- package.json: Fixed validate script path to point to scripts/validate-package.js
+
+---
+
 ## [1.2.1] - 2025-11-05
 
 ### Changed
@@ -288,6 +304,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Upgrade Guide
 
+### From 1.2.1 to 1.11.0
+
+**No breaking changes.** Added new `/stash` command for session context management.
+
+**New:**
+- `/stash` command for saving session context
+- Updated command count from 20 to 21
+
+**Action Required:**
+- None for existing installations - upgrade is seamless
+
+**To Upgrade:**
+```bash
+# Via npm
+npm install -g @amrhas82/agentic-kit@latest
+
+# Run installer
+agentic-kit
+```
+
+---
+
 ### From 1.1.0 to 1.2.0
 
 **No breaking changes.** Major new feature: Interactive Multi-Tool Installer.
@@ -359,7 +397,9 @@ npx @amrhas82/agentic-kit
 
 | Version | Date | Key Features |
 |---------|------|--------------|
-| **1.2.0** | 2025-11-04 | Interactive multi-tool installer, 22 skills, 4 tools support, 254 tests |
+| **1.11.0** | 2026-01-20 | Added /stash command (21 total commands) |
+| **1.2.1** | 2025-11-05 | Package optimization, repository cleanup |
+| **1.2.0** | 2025-11-05 | Interactive multi-tool installer, 22 skills, 4 tools support, 254 tests |
 | **1.1.0** | 2025-11-02 | Session persistence, docs consolidation, marketplace catalog |
 | **1.0.0** | 2025-11-02 | Initial release: 13 agents, 14 skills, 3 variants |
 

package/README.md

@@ -1,15 +1,15 @@
 <div align="center">
 
 ```
- █████╗  ██████╗ ███████╗███╗   ██╗████████╗██╗ ██████╗    ██╗  ██╗██╗████████╗
-██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██║██╔════╝    ██║ ██╔╝██║╚══██╔══╝
-███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ██║██║         █████╔╝ ██║   ██║
-██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ██║██║         ██╔═██╗ ██║   ██║
-██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██║╚██████╗    ██║  ██╗██║   ██║
-╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝ ╚═════╝    ╚═╝  ╚═╝╚═╝   ╚═╝
+          █████╗  ██████╗ ███████╗███╗   ██╗████████╗██╗ ██████╗    ██╗  ██╗██╗████████╗
+         ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██║██╔════╝    ██║ ██╔╝██║╚══██╔══╝
+         ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ██║██║         █████╔╝ ██║   ██║
+         ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ██║██║         ██╔═██╗ ██║   ██║
+         ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██║╚██████╗    ██║  ██╗██║   ██║
+         ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝ ╚═════╝    ╚═╝  ╚═╝╚═╝   ╚═╝
 ```
 
-**AI development toolkit with 14 specialized agents and 20 commands per tool**
+**AI development toolkit with 14 specialized agents and 21 commands per tool**
 
 </div>
 
@@ -36,15 +36,15 @@ npm install -g @amrhas82/agentic-kit
 agentic-kit
 
 # Choose tool(s): claude, opencode, ampcode, or droid
-# Each tool gets 14 agents + 20 commands
+# Each tool gets 14 agents + 21 commands
 ```
 
 ### Supported Tools
 
-- **Claude Code** - 14 subagents + 11 skills + 9 commands
-- **Opencode** - 14 agent references + 20 commands
-- **Ampcode** - 14 agent references + 20 commands
-- **Droid** - 14 agent references + 20 commands
+- **Claude Code** - 14 subagents + 11 skills + 10 commands
+- **Opencode** - 14 agent references + 21 commands
+- **Ampcode** - 14 agent references + 21 commands
+- **Droid** - 14 agent references + 21 commands
 
 **Key Difference:**
 - **Claude Code**: Full subagent system with orchestrator + skills (auto-triggering)
@@ -93,7 +93,7 @@ agentic-kit
 - **system-architect** - System design and architecture
 - **ui-designer** - UI/UX design and wireframes
 
-### 20 Commands/Skills
+### 21 Commands/Skills
 
 **Auto-Triggering Skills (4)** - Claude Code only:
 - **test-driven-development** - Write test first, watch fail, minimal passing code
@@ -101,7 +101,7 @@ agentic-kit
 - **verification-before-completion** - Verify before claiming done
 - **subagent-spawning** - TDD-aware templates for fresh subagents
 
-**Manual Skills/Commands (16):**
+**Manual Skills/Commands (17):**
 - **brainstorming** - Structured brainstorming sessions
 - **code-review** - Implementation review against requirements
 - **condition-based-waiting** - Replace timeouts with condition polling
@@ -117,6 +117,7 @@ agentic-kit
 - **review** - Comprehensive code review
 - **security** - Vulnerability scanning
 - **ship** - Pre-deployment checklist
+- **stash** - Save session context for compaction recovery or handoffs
 - **test-generate** - Generate test suites
 
 ---
@@ -160,30 +161,10 @@ agentic-kit
 
 ---
 
-## 🔧 Advanced Usage
-
-### Silent Installation (CI/CD)
-```bash
-agentic-kit --tool claude --yes
-```
-
-### Multiple Tools
-```bash
-agentic-kit
-# Enter: claude opencode
-```
-
-### Uninstall
-```bash
-agentic-kit --uninstall claude
-```
-
----
-
 ## 📊 Stats
 
 - **14** Specialized Agents
-- **20** Workflow Commands & Skills
+- **21** Workflow Commands & Skills
 - **4** Supported Tools (Claude, Opencode, Ampcode, Droid)
 - **MIT** License
 

package/docs/INSTALLATION_LOCATIONS.md

@@ -0,0 +1,299 @@
+# Installation Locations
+
+This document explains **where** Agentic Kit files get installed depending on the installation method.
+
+---
+
+## Installation Methods & Locations
+
+### 1. Claude Code Plugin (Recommended)
+
+**Command:**
+```bash
+/plugin add github:amrhas82/agentic-kit
+```
+
+**Install Location:**
+```
+~/.config/claude-code/plugins/github-amrhas82-agentic-kit/
+```
+
+**What's Installed:**
+- All plugin files (agents, skills, manifests, hooks)
+- Files remain until you uninstall with `/plugin remove`
+
+**How it Works:**
+- Claude Code clones the GitHub repository
+- Files are placed in Claude's plugin directory
+- Agents and skills become available in Claude Code immediately
+- Persists across Claude Code sessions
+
+**Verify Installation:**
+```bash
+ls ~/.config/claude-code/plugins/ | grep agentic-kit
+```
+
+---
+
+### 2. npx (Temporary Execution)
+
+**Command:**
+```bash
+npx @amrhas82/agentic-kit
+npx agkit --variant=lite
+```
+
+**Install Location:**
+```
+~/.npm/_npx/[hash]/@amrhas82/agentic-kit/
+```
+
+**What's Installed:**
+- Package downloaded to npx cache directory
+- **TEMPORARY** - cleared when cache is cleaned
+- Does NOT install permanently
+
+**How it Works:**
+- Downloads package from npm registry
+- Caches in npx directory
+- Runs the CLI script (cli.js)
+- Shows installation instructions
+- Files are NOT available after process exits
+
+**This is NOT a permanent installation method!**
+
+npx is designed for:
+- Trying the package without installing
+- One-time runs
+- Testing different variants
+
+**To actually use Agentic Kit, use Claude Code plugin installation instead.**
+
+---
+
+### 3. npm install (Local Project)
+
+**Command:**
+```bash
+npm install @amrhas82/agentic-kit
+```
+
+**Install Location:**
+```
+./node_modules/@amrhas82/agentic-kit/
+```
+
+**What's Installed:**
+- All package files in your project's node_modules
+- Available as a dependency
+- Persists as long as node_modules exists
+
+**How it Works:**
+- Downloads package from npm registry
+- Installs to local node_modules directory
+- Makes files available for require/import
+- Typical for Node.js projects
+
+**When to Use:**
+- Building a Node.js app that uses Agentic Kit
+- Want to version control dependencies (package.json)
+- Need local access to files
+
+**Note:** This doesn't make agents available in Claude Code automatically. You still need to use Claude Code plugin installation for that.
+
+---
+
+### 4. npm install -g (Global)
+
+**Command:**
+```bash
+npm install -g @amrhas82/agentic-kit
+```
+
+**Install Location:**
+```
+# Linux/macOS
+/usr/local/lib/node_modules/@amrhas82/agentic-kit/
+
+# Or with nvm
+~/.nvm/versions/node/vX.X.X/lib/node_modules/@amrhas82/agentic-kit/
+
+# Windows
+%AppData%\npm\node_modules\@amrhas82\agentic-kit\
+```
+
+**What's Installed:**
+- Package files in global node_modules
+- CLI binaries in PATH
+- Available system-wide
+
+**How it Works:**
+- Downloads package from npm registry
+- Installs globally
+- Adds `agentic-kit` and `agkit` commands to PATH
+
+**When to Use:**
+- Want CLI commands available globally
+- Building tools that use Agentic Kit
+
+---
+
+## Comparison Table
+
+| Method | Location | Permanent? | Claude Code? | Use Case |
+|--------|----------|------------|--------------|----------|
+| **Claude Code Plugin** | `~/.config/claude-code/plugins/` | ✅ Yes | ✅ Yes | **Recommended - Use Agentic Kit in Claude** |
+| **npx** | `~/.npm/_npx/[hash]/` | ❌ No (temporary) | ❌ No | Testing, one-time runs |
+| **npm install** | `./node_modules/` | ✅ Yes | ❌ No | Node.js project dependency |
+| **npm install -g** | `/usr/local/lib/node_modules/` | ✅ Yes | ❌ No | Global CLI access |
+
+---
+
+## How Files Are Structured
+
+When installed, you get:
+
+```
+agentic-kit/
+├── .claude-plugin/           # Plugin manifests
+│   ├── plugin.json           # Main manifest
+│   ├── plugin-lite.json      # Lite variant
+│   ├── plugin-standard.json  # Standard variant
+│   └── plugin-pro.json       # Pro variant
+├── agents/                   # All 13 agent definitions
+├── skills/                   # All 14 skill definitions
+├── hooks/                    # Plugin hooks
+│   ├── register-agents.js    # Agent registration
+│   └── session-start.js      # Session persistence
+├── resources/                # Templates, workflows, data
+├── cli.js                    # CLI wrapper
+├── index.js                  # Entry point
+├── package.json              # npm package info
+└── README.md                 # Documentation
+```
+
+---
+
+## Finding Your Installation
+
+### Claude Code Plugin
+```bash
+# Linux/macOS
+ls ~/.config/claude-code/plugins/
+
+# macOS alternative
+ls ~/Library/Application Support/Claude/plugins/
+
+# Check inside Claude Code
+# Type: /plugin list
+```
+
+### npx Cache
+```bash
+# List npx cache
+ls ~/.npm/_npx/
+
+# Clear npx cache
+rm -rf ~/.npm/_npx
+```
+
+### npm Local
+```bash
+# Check local installation
+ls node_modules/@amrhas82/agentic-kit/
+
+# Or use npm
+npm list @amrhas82/agentic-kit
+```
+
+### npm Global
+```bash
+# Find global installation
+npm list -g @amrhas82/agentic-kit
+
+# Or check directory
+npm root -g
+```
+
+---
+
+## Uninstalling
+
+### Claude Code Plugin
+```bash
+/plugin remove github-amrhas82-agentic-kit
+```
+
+### npm Local
+```bash
+npm uninstall @amrhas82/agentic-kit
+```
+
+### npm Global
+```bash
+npm uninstall -g @amrhas82/agentic-kit
+```
+
+### npx Cache
+```bash
+# npx cache is automatically cleaned periodically
+# Or force clean:
+rm -rf ~/.npm/_npx
+```
+
+---
+
+## Package Publishing Locations
+
+When you publish:
+
+### npm.js Registry
+```
+https://www.npmjs.com/package/@amrhas82/agentic-kit
+```
+
+Users download from:
+```
+https://registry.npmjs.org/@amrhas82/agentic-kit/-/agentic-kit-1.1.0.tgz
+```
+
+### GitHub Packages
+```
+https://github.com/amrhas82/agentic-kit/packages
+```
+
+Users download from:
+```
+https://npm.pkg.github.com/@amrhas82/agentic-kit
+```
+
+### GitHub Repository
+```
+https://github.com/amrhas82/agentic-kit
+```
+
+Claude Code clones from:
+```
+git clone https://github.com/amrhas82/agentic-kit.git
+```
+
+---
+
+## Summary
+
+**For most users:**
+- **Use Claude Code plugin installation** → Installs to Claude's plugin directory
+- This is the recommended method for using Agentic Kit
+
+**For developers:**
+- **npm install** (local) → For Node.js projects
+- **npm install -g** (global) → For CLI access
+
+**For testing:**
+- **npx** → Temporary, doesn't actually install
+
+---
+
+**Where do agents/skills become available?**
+
+Only **Claude Code plugin installation** makes agents and skills available in Claude Code. Other methods just download files but don't integrate with Claude Code.

package/docs/RELEASE_NOTES_1.2.0.md

@@ -0,0 +1,323 @@
+# Agentic Kit v1.2.0 Release Notes
+
+**Release Date**: November 5, 2025
+**Type**: Major Feature Release
+**Status**: Production Ready
+
+---
+
+## 🎉 What's New
+
+### Interactive Multi-Tool Installer System
+
+The headline feature of v1.2.0 is a complete installation system supporting four AI development tools with three variant levels and comprehensive features:
+
+#### 🚀 Core Features
+
+- **4-Step Interactive Installation**: Guided process from variant selection to completion
+- **Multi-Tool Support**: Install Claude, Opencode, Ampcode, and Droid simultaneously
+- **Variant Selection**: Choose Lite (510 KB), Standard (8.4 MB), or Pro (9 MB)
+- **Real-Time Progress**: Beautiful ANSI progress bars with ETA and transfer speed
+- **Automatic Rollback**: Failed installations automatically restore previous state
+- **Resume Capability**: Interrupted installations can be resumed from where they stopped
+- **Silent Mode**: Perfect for CI/CD pipelines (`--silent --variant=standard --tools=claude`)
+
+#### 📊 Installation Reporting (New in Phase 9)
+
+- **Comprehensive Reports**: Detailed installation reports saved to `~/.agentic-kit-install.log`
+  - Success/failure status
+  - Per-tool component counts and verification
+  - System information and timing data
+  - Errors and warnings with context
+
+#### 📈 Anonymous Telemetry (New in Phase 9)
+
+- **Opt-In Only**: Clear consent prompt with transparent data policy
+- **Privacy-First**: Only anonymous usage data (variant, tool count, timing, OS)
+- **No Personal Data**: Never collects paths, user info, or identifying data
+- **Easy Opt-Out**: Use `--no-telemetry` flag or modify config file
+- **Local Storage**: Data stored locally, not sent to external servers
+- **Full Documentation**: See `docs/PRIVACY.md` for complete details
+
+#### 🔒 Security Hardening (New in Phase 9)
+
+- **Path Traversal Prevention**: Validates all paths to prevent `../../etc/passwd` attacks
+- **Symlink Protection**: Resolves and validates symlinks before operations
+- **Input Validation**: Whitelisted tool names, variants, and sanitized paths
+- **DoS Prevention**: File size limits (1MB) for JSON parsing
+- **Null Byte Detection**: Prevents null byte injection in paths and files
+- **Secure Permissions**: Sensitive files created with 0600 permissions
+- **No Command Injection**: All file operations use Node.js APIs, no shell execution
+- **Full Documentation**: See `docs/SECURITY.md` for security measures
+
+#### 🔄 Legacy Migration (New in Phase 9)
+
+- **Automatic Detection**: Finds pre-1.2.0 installations without manifests
+- **Smart Classification**: Classifies legacy installations as Lite/Standard/Pro
+- **Preserves Customizations**: User-created agents and skills are retained
+- **Migration Prompt**: Clear prompts with migration details
+- **Rollback Support**: Easy rollback if migration is unwanted
+- **Full Documentation**: See `docs/MIGRATION.md` for migration guide
+
+---
+
+## 📦 What's Included
+
+### Tools & Variants
+
+| Tool | Description | Optimization |
+|------|-------------|--------------|
+| **Claude** | Conversational AI assistant | Markdown-first, conversational patterns |
+| **Opencode** | CLI-optimized codegen | Terminal workflows, command-line first |
+| **Ampcode** | Amplified development | Maximum velocity, automation |
+| **Droid** | Android development | Mobile-first, Android Studio integration |
+
+| Variant | Agents | Skills | Size | Best For |
+|---------|--------|--------|------|----------|
+| **Lite** | 3 | 0 | 510 KB | CI/CD, minimal setups, testing |
+| **Standard** ⭐ | 13 | 8 | 8.4 MB | Most users, document processing |
+| **Pro** | 13 | 22 | 9 MB | Advanced users, full feature set |
+
+### Components
+
+- **13 Specialized Agents**: master, orchestrator, story-writer, feature-planner, and more
+- **22 Skills**: pdf, docx, xlsx, pptx, canvas-design, theme-factory, and 16 others
+- **8 Core Skills** (Standard): Essential document and design tools
+- **14 Advanced Skills** (Pro only): Specialized tools for power users
+
+---
+
+## 🚀 Installation
+
+### Quick Start
+
+```bash
+# Install globally
+npm install -g @amrhas82/agentic-kit
+
+# Run interactive installer
+agentic-kit install
+```
+
+### Silent Mode (CI/CD)
+
+```bash
+# Install Claude with Standard variant
+agentic-kit install --silent --variant=standard --tools=claude
+
+# Install all tools with Pro variant
+agentic-kit install --silent --variant=pro --tools=claude,opencode,ampcode,droid
+```
+
+### Advanced Usage
+
+```bash
+# Custom path
+agentic-kit install --variant=standard --tools=claude --path claude=~/my-custom-path
+
+# Multiple tools with different paths
+agentic-kit install --variant=pro --tools=claude,opencode \
+  --path claude=~/.claude-custom \
+  --path opencode=~/.opencode-custom
+
+# Disable telemetry
+agentic-kit install --no-telemetry
+
+# Uninstall
+agentic-kit install --uninstall claude
+
+# Upgrade variant
+agentic-kit install --upgrade claude pro
+```
+
+---
+
+## 📚 Documentation
+
+### New Documentation (Phase 9)
+
+- **[PRIVACY.md](docs/PRIVACY.md)** - Transparent data collection policy
+- **[SECURITY.md](docs/SECURITY.md)** - Security measures and best practices
+- **[MIGRATION.md](docs/MIGRATION.md)** - Guide for migrating from < 1.2.0
+
+### Existing Documentation
+
+- **[INSTALLER_GUIDE.md](docs/INSTALLER_GUIDE.md)** - Complete installation guide (850+ lines)
+- **[VARIANT_CONFIGURATION.md](docs/VARIANT_CONFIGURATION.md)** - Variant system details
+- **[PACKAGE_BASELINE.md](docs/PACKAGE_BASELINE.md)** - Package structure reference
+- **[TESTING.md](docs/TESTING.md)** - Testing strategy and execution
+- **[INSTALLATION_DEMO.md](docs/INSTALLATION_DEMO.md)** - Visual demo of installer
+
+---
+
+## ✅ Testing & Quality Assurance
+
+### Test Coverage
+
+- **263 Total Tests**: All passing with zero failures
+- **9 Validation Tests**: Core module validation (new in Phase 9.6)
+- **88 Variant Tests**: Comprehensive variant parsing validation
+- **44 Package Tests**: Package manager functionality
+- **35 Installation Tests**: Installation engine testing
+- **40 Integration Tests**: End-to-end scenarios
+- **34 Path Tests**: Path validation and confirmation
+- **13 Display Tests**: Summary display verification
+
+### Validation Results
+
+- ✅ All 12 tool/variant combinations validated
+- ✅ Zero errors, zero warnings
+- ✅ 100% installation success rate
+- ✅ Production-ready status confirmed
+
+---
+
+## 🔧 Technical Details
+
+### Architecture
+
+```
+agentic-kit/
+├── installer/
+│   ├── cli.js                    # Interactive CLI
+│   ├── package-manager.js        # Variant management
+│   ├── installation-engine.js    # File operations
+│   ├── verification-system.js    # Post-install validation
+│   ├── path-manager.js           # Path validation (enhanced security)
+│   ├── state-manager.js          # Resume capability
+│   ├── report-template.js        # Report generation (new Phase 9.2)
+│   └── telemetry.js             # Anonymous stats (new Phase 9.3)
+├── packages/
+│   ├── claude/                   # Claude-optimized package
+│   ├── opencode/                 # Opencode-optimized package
+│   ├── ampcode/                  # Ampcode-optimized package
+│   └── droid/                    # Droid-optimized package
+└── tests/
+    ├── installer/                # 254 installer tests
+    └── validation-test.js        # 9 core validation tests (new Phase 9.6)
+```
+
+### Requirements
+
+- **Node.js**: 14.0.0 or higher
+- **npm**: 6.0.0 or higher
+- **Disk Space**:
+  - Lite: ~1 MB
+  - Standard: ~10 MB
+  - Pro: ~12 MB
+- **Permissions**: Write access to installation directories
+
+---
+
+## 🐛 Bug Fixes
+
+- Fixed file count mismatches in progress tracking
+- Improved error messages for permission issues
+- Enhanced path validation for edge cases
+- Better handling of interrupted installations
+- Resolved symlink-related installation issues
+
+---
+
+## 🔄 Migration from v1.1.x
+
+### Automatic Migration
+
+When you run the installer, it will automatically detect v1.1.x installations and offer to migrate:
+
+```bash
+$ agentic-kit install
+
+⚠ Legacy installation detected at ~/.claude
+  Found: 13 agents, 5 skills, 1 resource, 2 hooks
+
+Migrate to new installer? (Y/n): y
+
+✓ Migration complete!
+```
+
+### What's Preserved
+
+- ✅ All existing agents and skills
+- ✅ Custom user-created files
+- ✅ Directory structure
+- ✅ File permissions
+
+### What's Added
+
+- ➕ `manifest.json` with installation metadata
+- ➕ Upgrade/downgrade capability
+- ➕ Better uninstall support
+
+See **[MIGRATION.md](docs/MIGRATION.md)** for detailed migration guide.
+
+---
+
+## 🎯 Highlights
+
+### For Developers
+
+- **Faster Installation**: Optimized file operations with progress tracking
+- **Better Debugging**: Comprehensive reports and error messages
+- **CI/CD Ready**: Silent mode with exit codes and automation support
+- **Security First**: Path traversal prevention and input validation
+- **Resume Support**: Never lose progress on interrupted installations
+
+### For Teams
+
+- **Multi-Tool Management**: Install and manage 4 tools from one installer
+- **Variant Flexibility**: Easy upgrades between Lite/Standard/Pro
+- **Consistent Structure**: All tools follow same structure (13 agents, 22 skills)
+- **Tool-Specific Optimization**: Each tool optimized for its platform
+- **Quality Assurance**: 263 tests ensure reliability
+
+### For Organizations
+
+- **Privacy-Focused**: Transparent telemetry with easy opt-out
+- **Security-Hardened**: Comprehensive security measures documented
+- **Migration Path**: Clear upgrade path from older versions
+- **Documentation**: Extensive guides for all features
+- **Production-Ready**: 100% validation, zero errors
+
+---
+
+## 📊 Statistics
+
+- **Lines of Code**: ~8,500 (installer system)
+- **Documentation**: ~5,000 lines across 8 documents
+- **Tests**: 263 passing tests
+- **Success Rate**: 100% installation success
+- **Validation**: 12/12 tool/variant combinations validated
+- **Security Checks**: 7 layers of security validation
+
+---
+
+## 🙏 Acknowledgments
+
+This release represents a significant milestone in making Agentic Kit more accessible, secure, and user-friendly. Special thanks to all contributors and users who provided feedback during development.
+
+---
+
+## 📞 Support
+
+- **Documentation**: https://github.com/amrhas82/agentic-kit/docs
+- **Issues**: https://github.com/amrhas82/agentic-kit/issues
+- **Security**: See [SECURITY.md](docs/SECURITY.md) for vulnerability reporting
+
+---
+
+## 🔮 What's Next (v1.3.0)
+
+Planned features for the next release:
+
+- GUI installer for desktop environments
+- Package management (add/remove individual agents and skills)
+- Automatic update notifications
+- Team/enterprise deployment support
+- Additional tool integrations
+- Enhanced telemetry dashboard (local-only)
+- Performance optimizations
+
+---
+
+**Enjoy Agentic Kit v1.2.0!** 🎉

package/installer/cli.js

@@ -451,7 +451,7 @@ ${colors.bright}${colors.cyan}██╔══██║██║   ██║█
 ${colors.bright}${colors.cyan}██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██║╚██████╗    ██║  ██╗██║   ██║${colors.reset}
 ${colors.bright}${colors.cyan}╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝ ╚═════╝    ╚═╝  ╚═╝╚═╝   ╚═╝${colors.reset}
 
-${colors.bright}v1.10.0 | 14 agents + 20 commands per tool${colors.reset}
+${colors.bright}v1.11.0 | 14 agents + 21 commands per tool${colors.reset}
     `);
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@amrhas82/agentic-kit",
-  "version": "1.10.0",
-  "description": "AI development toolkit with 14 specialized agents and 20 commands. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
+  "version": "1.11.0",
+  "description": "AI development toolkit with 14 specialized agents and 21 commands. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
   "main": "index.js",
   "bin": {
     "agentic-kit": "./installer/cli.js",
@@ -14,7 +14,7 @@
     "uninstall-tool": "node installer/cli.js --uninstall",
     "clean": "rm -rf tests/tmp/ && echo 'Cleaned test artifacts'",
     "clean:git": "git clean -fdx tests/tmp/",
-    "validate": "node ./validate-package.js",
+    "validate": "node ./scripts/validate-package.js",
     "validate-packages": "node scripts/validate-all-packages.js",
     "prepublishOnly": "npm run clean && npm run validate",
     "publish:npm": "npm publish --registry https://registry.npmjs.org --access public",

package/packages/ampcode/AGENT.md

@@ -25,7 +25,7 @@ These subagents are available when using Claude Code CLI. Ampcode can reference
 | system-architect | Architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
 | ui-designer | UX Expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
 
-## Ampcode Commands (20 total)
+## Ampcode Commands (21 total)
 
 | ID | Description | Usage | Auto |
 |---|---|---|---|
@@ -43,6 +43,7 @@ These subagents are available when using Claude Code CLI. Ampcode can reference
 | security | Security vulnerability scan and analysis | /security | - |
 | ship | Pre-deployment verification checklist | /ship | - |
 | skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> | false |
+| stash | Save session context for compaction recovery or handoffs | /stash ["optional-name"] | - |
 | subagent-spawning | Provides TDD-aware templates for spawning fresh subagents | Used by 3-process-task-list and other agents | true |
 | systematic-debugging | Four-phase debugging framework - investigate root cause before any fixes | /systematic-debugging <bug-or-error-description> | false |
 | test-driven-development | Write test first, watch it fail, write minimal code to pass | /test-driven-development <feature-or-behavior-to-test> | true |

package/packages/ampcode/commands/stash.md

@@ -0,0 +1,45 @@
+---
+name: stash
+description: Stash session context [name]
+usage: /stash ["optional-name"]
+argument-hint: [optional stash name]
+---
+
+Save session context for compaction recovery or handoffs.
+
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+
+**What it does**
+1. Captures current conversation context and key decisions
+2. Records active work in progress
+3. Stores important findings and insights
+4. Creates stash file in `~/.claude/stash/`
+5. Enables context restoration after compaction
+
+**When to use**
+- Before long-running tasks that may trigger compaction
+- When handing off work to another agent or session
+- After completing major investigation or analysis
+- Before taking a break from complex multi-step work
+
+**Commands**
+```bash
+# Stash with auto-generated name
+/stash
+
+# Stash with custom name
+/stash "feature-auth-investigation"
+
+# List available stashes
+ls ~/.claude/stash/
+
+# Restore from stash
+cat ~/.claude/stash/<name>.md
+```
+
+**Reference**
+- Stashes stored in `~/.claude/stash/`
+- Automatically includes: timestamp, active plan, recent decisions
+- Maximum context retention with minimal token usage

package/packages/claude/CLAUDE.md

@@ -41,7 +41,7 @@ These subagents are available when using Claude Code CLI. Droid can reference th
 | testing-anti-patterns | Prevents testing mock behavior and production pollution with test-only methods | /testing-anti-patterns <testing-scenario> | true |
 | verification-before-completion | Requires running verification commands before making any success claims | /verification-before-completion <work-to-verify> | true |
 
-### Commands (9 total)
+### Commands (10 total)
 
 | ID | Description | Usage |
 |---|---|---|
@@ -53,6 +53,7 @@ These subagents are available when using Claude Code CLI. Droid can reference th
 | review | Comprehensive code review including quality, tests, and architecture | /review |
 | security | Security vulnerability scan and analysis | /security |
 | ship | Pre-deployment verification checklist | /ship |
+| stash | Save session context for compaction recovery or handoffs | /stash ["optional-name"] |
 | test-generate | Generate comprehensive test suites for existing code | /test-generate <code-section> |
 
 All resources are auto-discovered from frontmatter in their respective directories:

package/packages/claude/commands/stash.md

@@ -0,0 +1,45 @@
+---
+name: stash
+description: Stash session context [name]
+usage: /stash ["optional-name"]
+argument-hint: [optional stash name]
+---
+
+Save session context for compaction recovery or handoffs.
+
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+
+**What it does**
+1. Captures current conversation context and key decisions
+2. Records active work in progress
+3. Stores important findings and insights
+4. Creates stash file in `~/.claude/stash/`
+5. Enables context restoration after compaction
+
+**When to use**
+- Before long-running tasks that may trigger compaction
+- When handing off work to another agent or session
+- After completing major investigation or analysis
+- Before taking a break from complex multi-step work
+
+**Commands**
+```bash
+# Stash with auto-generated name
+/stash
+
+# Stash with custom name
+/stash "feature-auth-investigation"
+
+# List available stashes
+ls ~/.claude/stash/
+
+# Restore from stash
+cat ~/.claude/stash/<name>.md
+```
+
+**Reference**
+- Stashes stored in `~/.claude/stash/`
+- Automatically includes: timestamp, active plan, recent decisions
+- Maximum context retention with minimal token usage

package/packages/droid/AGENTS.md

@@ -25,7 +25,7 @@ These subagents are available when using Claude Code CLI. Droid can reference th
 | system-architect | Architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
 | ui-designer | UX Expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
 
-## Droid Commands (20 total)
+## Droid Commands (21 total)
 
 | ID | Description | Usage | Auto |
 |---|---|---|---|
@@ -43,6 +43,7 @@ These subagents are available when using Claude Code CLI. Droid can reference th
 | security | Security vulnerability scan and analysis | /security | - |
 | ship | Pre-deployment verification checklist | /ship | - |
 | skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> | false |
+| stash | Save session context for compaction recovery or handoffs | /stash ["optional-name"] | - |
 | subagent-spawning | Provides TDD-aware templates for spawning fresh subagents | Used by 3-process-task-list and other agents | true |
 | systematic-debugging | Four-phase debugging framework - investigate root cause before any fixes | /systematic-debugging <bug-or-error-description> | false |
 | test-driven-development | Write test first, watch it fail, write minimal code to pass | /test-driven-development <feature-or-behavior-to-test> | true |

package/packages/droid/commands/stash.md

@@ -0,0 +1,45 @@
+---
+name: stash
+description: Stash session context [name]
+usage: /stash ["optional-name"]
+argument-hint: [optional stash name]
+---
+
+Save session context for compaction recovery or handoffs.
+
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+
+**What it does**
+1. Captures current conversation context and key decisions
+2. Records active work in progress
+3. Stores important findings and insights
+4. Creates stash file in `~/.claude/stash/`
+5. Enables context restoration after compaction
+
+**When to use**
+- Before long-running tasks that may trigger compaction
+- When handing off work to another agent or session
+- After completing major investigation or analysis
+- Before taking a break from complex multi-step work
+
+**Commands**
+```bash
+# Stash with auto-generated name
+/stash
+
+# Stash with custom name
+/stash "feature-auth-investigation"
+
+# List available stashes
+ls ~/.claude/stash/
+
+# Restore from stash
+cat ~/.claude/stash/<name>.md
+```
+
+**Reference**
+- Stashes stored in `~/.claude/stash/`
+- Automatically includes: timestamp, active plan, recent decisions
+- Maximum context retention with minimal token usage

package/packages/opencode/AGENTS.md

@@ -25,7 +25,7 @@ These subagents are available when using Claude Code CLI. Opencode can reference
 | system-architect | Architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
 | ui-designer | UX Expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
 
-## Opencode Commands (20 total)
+## Opencode Commands (21 total)
 
 | ID | Description | Usage | Auto |
 |---|---|---|---|
@@ -43,6 +43,7 @@ These subagents are available when using Claude Code CLI. Opencode can reference
 | security | Security vulnerability scan and analysis | /security | - |
 | ship | Pre-deployment verification checklist | /ship | - |
 | skill-creator | Guide for creating effective skills and extending Claude capabilities | /skill-creator <skill-type> <skill-description> | false |
+| stash | Save session context for compaction recovery or handoffs | /stash ["optional-name"] | - |
 | subagent-spawning | Provides TDD-aware templates for spawning fresh subagents | Used by 3-process-task-list and other agents | true |
 | systematic-debugging | Four-phase debugging framework - investigate root cause before any fixes | /systematic-debugging <bug-or-error-description> | false |
 | test-driven-development | Write test first, watch it fail, write minimal code to pass | /test-driven-development <feature-or-behavior-to-test> | true |

package/packages/opencode/command/stash.md

@@ -0,0 +1,45 @@
+---
+name: stash
+description: Stash session context [name]
+usage: /stash ["optional-name"]
+argument-hint: [optional stash name]
+---
+
+Save session context for compaction recovery or handoffs.
+
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+
+**What it does**
+1. Captures current conversation context and key decisions
+2. Records active work in progress
+3. Stores important findings and insights
+4. Creates stash file in `~/.claude/stash/`
+5. Enables context restoration after compaction
+
+**When to use**
+- Before long-running tasks that may trigger compaction
+- When handing off work to another agent or session
+- After completing major investigation or analysis
+- Before taking a break from complex multi-step work
+
+**Commands**
+```bash
+# Stash with auto-generated name
+/stash
+
+# Stash with custom name
+/stash "feature-auth-investigation"
+
+# List available stashes
+ls ~/.claude/stash/
+
+# Restore from stash
+cat ~/.claude/stash/<name>.md
+```
+
+**Reference**
+- Stashes stored in `~/.claude/stash/`
+- Automatically includes: timestamp, active plan, recent decisions
+- Maximum context retention with minimal token usage

package/packages/subagentic-manual.md

@@ -31,10 +31,10 @@ Install for your platform:
 
 | Platform | Installation | What's Included |
 |----------|--------------|-----------------|
-| **Claude Code** | `cp -r claude/* ~/.claude/` | 14 subagents + 11 skills + 9 commands |
-| **Droid** | `cp -r droid/* ~/.factory/` | 20 commands (subagent references) |
-| **Ampcode** | `cp -r ampcode/* ~/.config/amp/` | 20 commands (subagent references) |
-| **OpenCode** | `cp -r opencode/* ~/.config/opencode/` | 20 commands (subagent references) |
+| **Claude Code** | `cp -r claude/* ~/.claude/` | 14 subagents + 11 skills + 10 commands |
+| **Droid** | `cp -r droid/* ~/.factory/` | 21 commands (subagent references) |
+| **Ampcode** | `cp -r ampcode/* ~/.config/amp/` | 21 commands (subagent references) |
+| **OpenCode** | `cp -r opencode/* ~/.config/opencode/` | 21 commands (subagent references) |
 
 **Key Difference**:
 - **Claude Code** implements full subagent system with orchestrator
@@ -54,8 +54,8 @@ Install for your platform:
 - test-driven-development, testing-anti-patterns, verification-before-completion (auto-trigger)
 - brainstorming, code-review, systematic-debugging, docs-builder, etc.
 
-**9 Commands** - Simple workflow helpers
-- debug, explain, git-commit, optimize, refactor, review, security, ship, test-generate
+**10 Commands** - Simple workflow helpers
+- debug, explain, git-commit, optimize, refactor, review, security, ship, stash, test-generate
 
 **Orchestration System**
 - Automatic intent matching to 9 workflow patterns
@@ -64,7 +64,7 @@ Install for your platform:
 
 ### Droid/Ampcode/OpenCode (Commands Only)
 
-**20 Commands** - All workflow capabilities in command form
+**21 Commands** - All workflow capabilities in command form
 - Combines Claude's skills + commands into unified command set
 - Same functionality, different invocation model (no auto-triggering)
 - Includes reference documentation for Claude's subagents
@@ -105,7 +105,7 @@ Install for your platform:
 
 ## 🛠 Commands Reference
 
-### Claude Code: 20 Total (11 Skills + 9 Commands)
+### Claude Code: 21 Total (11 Skills + 10 Commands)
 
 **Auto-Triggering Skills (4)**
 - `test-driven-development` - Write test first, watch fail, minimal passing code
@@ -122,7 +122,7 @@ Install for your platform:
 - `skill-creator` - Guide for creating new skills
 - `systematic-debugging` - Four-phase debugging framework
 
-**Simple Commands (9)**
+**Simple Commands (10)**
 - `debug` - Systematic investigation techniques
 - `explain` - Explain code for newcomers
 - `git-commit` - Intelligent commit creation
@@ -131,9 +131,10 @@ Install for your platform:
 - `review` - Comprehensive code review
 - `security` - Vulnerability scanning
 - `ship` - Pre-deployment checklist
+- `stash` - Save session context for compaction recovery or handoffs
 - `test-generate` - Test suite generation
 
-### Droid/Ampcode/OpenCode: 20 Commands
+### Droid/Ampcode/OpenCode: 21 Commands
 
 Same functionality as Claude's skills+commands, but:
 - All invoked as commands (no auto-triggering)
@@ -143,7 +144,7 @@ Same functionality as Claude's skills+commands, but:
 **Command Categories**:
 - **Development & Testing (10)**: test-driven-development, testing-anti-patterns, test-generate, code-review, systematic-debugging, root-cause-tracing, debug, condition-based-waiting, verification-before-completion, subagent-spawning
 - **Code Operations (6)**: refactor, optimize, explain, review, security, ship
-- **Strategy & Planning (4)**: brainstorming, skill-creator, docs-builder, git-commit
+- **Session & Planning (5)**: brainstorming, skill-creator, docs-builder, git-commit, stash
 
 ---
 
@@ -242,7 +243,7 @@ Subagent workflows require manual coordination.
 ├── CLAUDE.md           # Registry + orchestrator workflows
 ├── agents/             # 14 subagent implementations (*.md)
 ├── skills/             # 11 skills (subdirectories with SKILL.md)
-└── commands/           # 9 commands (*.md)
+└── commands/           # 10 commands (*.md)
 ```
 
 **Features**:
@@ -255,7 +256,7 @@ Subagent workflows require manual coordination.
 ```
 ~/.factory/
 ├── AGENTS.md           # Reference doc (subagents + commands)
-└── commands/           # 20 commands (*.md)
+└── commands/           # 21 commands (*.md)
 ```
 
 **Features**:
@@ -267,7 +268,7 @@ Subagent workflows require manual coordination.
 ```
 ~/.config/amp/
 ├── AGENT.md            # Reference doc (subagents + commands)
-└── commands/           # 20 commands (*.md)
+└── commands/           # 21 commands (*.md)
 ```
 
 **Features**:
@@ -279,7 +280,7 @@ Subagent workflows require manual coordination.
 ```
 ~/.config/opencode/
 ├── AGENTS.md           # Reference doc (subagents + commands)
-└── command/            # 20 commands (*.md)
+└── command/            # 21 commands (*.md)
 ```
 
 **Features**: