@amrhas82/agentic-kit 1.0.0 → 1.2.0

package/README.md

@@ -1,449 +1,352 @@
-# Agentic Toolkit
+# Agentic Kit
 
-A comprehensive, production-ready toolkit featuring 13 specialized agents and up to 14 powerful skills for end-to-end software development, product management, and design. Built for teams that need intelligent, collaborative AI agents working together seamlessly.
+> **AI-powered development toolkit with 13 specialized agents and 22 skills for end-to-end software development**
 
-## Table of Contents
+[![npm version](https://img.shields.io/npm/v/@amrhas82/agentic-kit)](https://www.npmjs.com/package/@amrhas82/agentic-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-- [Quick Start (5 minutes)](#quick-start)
-- [Installation](#installation)
-- [Variants](#variants)
-- [Agents Overview](#agents-overview)
-- [Skills Overview](#skills-overview)
-- [Architecture](#architecture)
-- [Troubleshooting](#troubleshooting)
-- [Contributing](#contributing)
-- [Documentation Index](#documentation-index)
+**Supported Tools:**
+[![Claude](https://img.shields.io/badge/Claude-Supported-blue?logo=anthropic)](https://claude.ai)
+[![Opencode](https://img.shields.io/badge/Opencode-Supported-green)](https://github.com/amrhas82/opencode)
+[![Ampcode](https://img.shields.io/badge/Ampcode-Supported-orange)](https://github.com/amrhas82/ampcode)
+[![Droid](https://img.shields.io/badge/Droid-Supported-red)](https://github.com/amrhas82/droid)
 
-## Quick Start
+A comprehensive toolkit featuring specialized AI agents and powerful skills for product management, agile development, content creation, and design. **Now with an interactive multi-tool installer** supporting Claude, Opencode, Ampcode, and Droid.
 
-### 1. Choose Your Variant
+---
 
-- **Lite**: 3 core agents for essential tasks (smallest footprint)
-- **Standard**: All 13 agents + 8 core skills (recommended for most users)
-- **Pro**: All 13 agents + all 14 skills (maximum capabilities)
+## 🚀 Quick Start
 
-### 2. Installation
+### Interactive Installer (Recommended)
 
-**Via Claude Code:**
-```
-/plugin marketplace add agentic-kit
-```
+Install Agentic Kit with the interactive multi-tool installer:
 
-**Via npx:**
 ```bash
-npx agentic-kit              # Standard variant (default)
-npx agentic-kit --variant=lite
-npx agentic-kit --variant=pro
-```
-
-### 3. Your First Task (15 minutes)
-
-1. Open Claude and invoke an agent:
-   ```
-   @Product Manager: Create a PRD for a task management app
-   ```
-
-2. The agent executes with full context from the toolkit
-
-3. Access your results and continue collaborating
+# Install globally
+npm install -g @amrhas82/agentic-kit
 
-See [QUICK-START.md](QUICK-START.md) for detailed walkthrough.
-
-## Installation
-
-### Prerequisites
-
-- Claude account (Free, Claude+ or Pro required for full functionality)
-- Internet connection
-
-### Installation Methods
+# Run interactive installer
+agentic-kit install
+```
 
-#### Claude Code (Recommended)
+The installer guides you through:
+1. **Select Variant** - Lite, Standard, or Pro
+2. **Select Tools** - Claude, Opencode, Ampcode, Droid (or all)
+3. **Configure Paths** - Use defaults or customize
+4. **Install** - Watch real-time progress
 
-```
-/plugin marketplace add agentic-kit
+**Silent Installation (CI/CD):**
+```bash
+agentic-kit install --silent --variant=standard --tools=claude
 ```
 
-This installs the Standard variant by default. For other variants:
-```
-/plugin marketplace add agentic-kit-lite
-/plugin marketplace add agentic-kit-pro
-```
+📖 **[Full Installation Guide →](docs/INSTALLER_GUIDE.md)**
+🎬 **[Visual Demo (ASCII) →](docs/INSTALLATION_DEMO.md)** - See the installer in action!
 
-#### npx (Quick Try)
+### Variants
 
-```bash
-# Standard variant (recommended)
-npx agentic-kit
+| Variant | Agents | Skills | Size | Best For |
+|---------|--------|--------|------|----------|
+| **Lite** | 3 | 0 | 510 KB | Minimal setup, CI/CD, testing |
+| **Standard** ⭐ | 13 | 8 | 8.4 MB | Most users, document processing |
+| **Pro** | 13 | 22 | 9 MB | Advanced users, full features |
 
-# Lite variant
-npx agentic-kit --variant=lite
+### Supported Tools
 
-# Pro variant
-npx agentic-kit --variant=pro
-```
+- **Claude** - Conversational AI, markdown-first workflows
+- **Opencode** - CLI-optimized code generation
+- **Ampcode** - Amplified development, maximum velocity
+- **Droid** - Android-first mobile development
 
-#### Development Installation
+### Start Using
 
 ```bash
-# Clone repository
-git clone https://github.com/anthropic/agentic-toolkit.git
-cd agentic-kit
+# Get help
+@master: help
 
-# Install dependencies
-npm install
+# Create a Product Requirements Document
+@product-manager: Create a PRD for a task management app
 
-# Link locally
-npm link
+# Generate development tasks
+@generate-tasks: Break down this feature into tasks
+
+# Process task list
+@process-task-list: Execute this task list
 ```
 
-### Verification
+---
 
-After installation, verify agents are available:
+## 📖 Documentation
+
+| Document | Description |
+|----------|-------------|
+| **[INSTALLER_GUIDE.md](docs/INSTALLER_GUIDE.md)** | 📦 Complete installation guide with troubleshooting |
+| **[INSTALLATION_DEMO.md](docs/INSTALLATION_DEMO.md)** | 🎬 Visual demo with ASCII art showing installer in action |
+| **[KNOWLEDGE_BASE.md](docs/KNOWLEDGE_BASE.md)** | Complete reference: all agents, skills, architecture |
+| **[QUICK-START.md](QUICK-START.md)** | 15-minute onboarding guide |
+| **[VARIANTS.md](VARIANTS.md)** | Compare variants and choose the right one |
+| **[VARIANT_CONFIGURATION.md](docs/VARIANT_CONFIGURATION.md)** | Variant system details and customization |
+| **[PACKAGE_VALIDATION_REPORT.md](docs/PACKAGE_VALIDATION_REPORT.md)** | Package validation and quality report |
+| **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** | Common issues and solutions |
+| **[CONTRIBUTING.md](docs/CONTRIBUTING.md)** | Contribution guidelines |
+| **[PUBLISHING.md](docs/PUBLISHING.md)** | Publishing guide for maintainers |
 
-```
-@Master: *help
-```
-
-You should see a list of available commands. If agents don't appear, see [Troubleshooting](TROUBLESHOOTING.md).
+---
 
-## Variants
+## ⚙️ Installation Options
 
-### Comparison Matrix
+### Option 1: Interactive Installer ⭐ (Recommended)
 
-| Feature | Lite | Standard | Pro |
-|---------|------|----------|-----|
-| **Agents** | 3 | 13 | 13 |
-| **Core Skills** | 1 | 8 | 8 |
-| **Advanced Skills** | 0 | 0 | 8 |
-| **Size** | ~2MB | ~8MB | ~16MB |
-| **Best For** | Explorers | Teams | Power Users |
-| **Price** | Free | $9/mo | $29/mo |
+**Multi-Tool Support:** Install for Claude, Opencode, Ampcode, or Droid
 
-### Which Variant Should I Choose?
+```bash
+# Install package globally
+npm install -g @amrhas82/agentic-kit
 
-**Choose Lite if:**
-- You're new to AI agents
-- You want to explore basic capabilities
-- You have minimal disk space
-- You only need essential agents
+# Run interactive installer
+agentic-kit install
+```
 
-**Choose Standard if:**
-- You're building products or features
-- Your team needs multiple agent types
-- You want comprehensive skill coverage
-- You want professional document creation
+**Features:**
+- 🎯 Choose variant (Lite/Standard/Pro)
+- 🛠️ Select tools (Claude, Opencode, Ampcode, Droid, or all)
+- 📁 Configure installation paths
+- 📊 Real-time progress tracking
+- ✅ Automatic verification
+- 🔄 Rollback on failure
 
-**Choose Pro if:**
-- You need all 16 skills
-- You want web app testing, MCP integration
-- You need algorithmic art and advanced features
-- You want maximum flexibility
+**Advanced Options:**
+```bash
+# Silent installation for CI/CD
+agentic-kit install --silent --variant=standard --tools=claude
 
-See [VARIANTS.md](VARIANTS.md) for detailed comparison and upgrade paths.
+# Install multiple tools
+agentic-kit install --variant=pro --tools=claude,opencode
 
-## Agents Overview
+# Custom path
+agentic-kit install --tools=claude --path claude=/custom/path
 
-The toolkit includes 13 specialized agents that work together:
+# Uninstall
+agentic-kit install --uninstall --tools=claude
+```
 
-### Core Agents (All Variants)
+📖 **[See Full Installation Guide](docs/INSTALLER_GUIDE.md)** for detailed instructions, troubleshooting, and FAQ
 
-**Master** - Central orchestration and resource execution
-- Universal executor for any task
-- Direct access to all agentic resources
-- Command-driven interface with *help, *task, *checklist commands
+### Option 2: Claude Code via GitHub
 
-**Orchestrator** - Workflow management and task coordination
-- Breaks down complex tasks into steps
-- Coordinates between agents
-- Tracks progress and dependencies
+Install directly from GitHub (no marketplace approval needed):
 
-### Product & Business Agents (Standard/Pro)
+```bash
+/plugin add github:amrhas82/agentic-kit
+```
 
-**Product Manager** - Product strategy and vision
-- Creates product roadmaps
-- Defines success metrics
-- Analyzes market and competitive landscape
+**Advantages:** Instant access, always latest version, no waiting
 
-**Product Owner** - Requirements and backlog management
-- Writes user stories and acceptance criteria
-- Prioritizes backlog
-- Manages feature specifications
+### Option 3: npx (Run Temporarily)
 
-**Business Analyst** - Business requirements analysis
-- Analyzes business needs
-- Creates functional specifications
-- Documents requirements
+Run the CLI without installing (doesn't install to your system):
 
-### Development Agents (Standard/Pro)
+```bash
+# Standard variant
+npx @amrhas82/agentic-kit
 
-**Full-Stack Developer** - Implementation and coding
-- Writes production-quality code
-- Handles frontend, backend, database
-- Writes tests and documentation
+# Other variants
+npx agkit --variant=lite
+npx agkit --variant=pro
+```
 
-**Holistic Architect** - System design and architecture
-- Creates system architecture diagrams
-- Designs data models and APIs
-- Plans scaling and performance
+**Note:** `npx` downloads and runs the package temporarily. Nothing is installed permanently.
 
-### Design & Quality Agents (Standard/Pro)
+### Option 4: Marketplace
 
-**UX Expert** - User experience and interface design
-- Creates wireframes and mockups
-- Designs user flows
-- Ensures accessibility and usability
+```bash
+/plugin marketplace add github:amrhas82/agentic-kit
+```
 
-**QA Test Architect** - Quality assurance and testing
-- Creates comprehensive test strategies
-- Designs test cases
-- Plans automation and continuous testing
+---
 
-### Workflow Agents (Standard/Pro)
+## 🤖 What's Included
 
-**Scrum Master** - Project management and coordination
-- Creates sprint plans
-- Facilitates standups
-- Tracks velocity and burndown
+### Agents (13 Total)
 
-**Create PRD** - Product Requirements Documents
-- Generates structured PRDs
-- Follows industry best practices
-- Includes success metrics
+**Core Orchestration:**
+- Master - Central coordination
+- Orchestrator - Workflow management
+- Scrum Master - Agile project management
 
-**Generate Tasks** - Task decomposition
-- Breaks features into actionable tasks
-- Estimates effort
-- Assigns priorities
+**Product & Requirements:**
+- Product Manager - Strategy and vision
+- Product Owner - Backlog management
+- Business Analyst - Requirements analysis
 
-**Process Task List** - Task tracking
-- Manages task lists
-- Tracks progress
-- Handles task completion
+**Development:**
+- Full-Stack Developer - Implementation
+- Holistic Architect - System design
+- UX Expert - Interface design
+- QA Test Architect - Quality assurance
 
-See [AGENTS.md](AGENTS.md) for detailed agent directory with use cases, prerequisites, and examples.
+**Specialized Workflows:**
+- Create PRD - Generate product requirements
+- Generate Tasks - Break down features
+- Process Task List - Execute task lists
 
-## Skills Overview
+[See full agent details →](docs/KNOWLEDGE_BASE.md#agents)
 
-The toolkit includes powerful skills that extend agent capabilities:
+### Skills (22 Total)
 
-### Document Processing (All Standard/Pro)
+**Document Processing (Standard & Pro):**
+- PDF, DOCX, XLSX, PPTX
 
-- **PDF** - Extract, merge, split, fill forms, OCR
-- **DOCX** - Create, edit, format Word documents
-- **XLSX** - Create, analyze, format spreadsheets
-- **PPTX** - Create, edit presentations
+**Design & Branding (Standard & Pro):**
+- Canvas Design, Theme Factory, Brand Guidelines, Internal Communications
 
-### Design & Content (All Standard/Pro)
+**Advanced (Pro Only - 14 additional skills):**
+- Video Production, Audio Transcription, Data Visualization
+- Web Scraping, API Integration, Database Query
+- Machine Learning, Blockchain Tools, IoT Integration
+- Security Audit, Performance Profiling, DevOps Automation
+- Cloud Deployment, Code Migration
 
-- **Canvas Design** - Create visual designs and artwork
-- **Theme Factory** - Apply themes and styling
-- **Brand Guidelines** - Apply brand consistency
-- **Internal Communications** - Generate internal documents
+[See full skill details →](docs/KNOWLEDGE_BASE.md#skills)
 
-### Advanced Skills (Pro Only)
+---
 
-- **MCP Builder** - Build Model Context Protocol servers
-- **Skill Creator** - Create custom skills
-- **Web App Testing** - Test web applications
-- **Slack GIF Creator** - Generate animated GIFs
-- **Algorithmic Art** - Generate algorithmic art
-- **Artifacts Builder** - Build complex HTML artifacts
+## 🔧 Key Features
 
-See [SKILLS.md](SKILLS.md) for complete skill directory, capabilities, use cases, and examples.
+- **✅ Interactive Multi-Tool Installer** - Install for Claude, Opencode, Ampcode, or Droid
+- **✅ Variant System** - Choose Lite, Standard, or Pro based on your needs
+- **✅ Persistent Skills** - Auto-load on session start
+- **✅ Multi-Tool Support** - Same content, optimized for each tool
+- **✅ Auto-Discovery** - Agents register automatically
+- **✅ Rich Documentation** - Comprehensive guides and examples
+- **✅ Production-Ready** - Battle-tested workflows with full validation
 
-## Architecture
+---
 
-### Directory Structure
+## 💡 Example Workflows
 
+**Create a Product:**
 ```
-agentic-kit/
-├── agents/                    (13 agent definitions)
-│   ├── master.md
-│   ├── orchestrator.md
-│   ├── product-manager.md
-│   ├── product-owner.md
-│   ├── business-analyst.md
-│   ├── full-stack-dev.md
-│   ├── holistic-architect.md
-│   ├── ux-expert.md
-│   ├── qa-test-architect.md
-│   ├── scrum-master.md
-│   ├── 1-create-prd.md
-│   ├── 2-generate-tasks.md
-│   └── 3-process-task-list.md
-│
-├── skills/                    (16 skills, variant-dependent)
-│   ├── pdf/
-│   ├── docx/
-│   ├── xlsx/
-│   ├── pptx/
-│   ├── canvas-design/
-│   ├── theme-factory/
-│   ├── brand-guidelines/
-│   ├── internal-comms/
-│   ├── mcp-builder/           (Pro only)
-│   ├── skill-creator/         (Pro only)
-│   ├── webapp-testing/        (Pro only)
-│   ├── slack-gif-creator/     (Pro only)
-│   ├── algorithmic-art/       (Pro only)
-│   └── artifacts-builder/     (Pro only)
-│
-├── resources/                 (Consolidated content)
-│   ├── templates/
-│   ├── data/
-│   ├── utils/
-│   └── checklists/
-│
-├── hooks/                     (Auto-discovery)
-│   └── register-agents.js
-│
-└── .claude-plugin/            (Plugin manifests)
-    ├── plugin.json            (Overview)
-    ├── plugin-lite.json
-    ├── plugin-standard.json
-    └── plugin-pro.json
+@product-manager: Create a PRD for a mobile expense tracker
+@generate-tasks: Generate implementation tasks from the PRD
+@full-stack-dev: Implement the first task
 ```
 
-### Ultra-Lean Architecture Benefits
-
-- **Modular Design** - Each agent and skill is independent
-- **Auto-Discovery** - Agents auto-register via hooks
-- **No Runtime Dependencies** - Works without external services
-- **Fast Loading** - Minimal startup overhead
-- **Easy Extension** - Add custom agents and skills easily
-
-### How Agents Are Registered
+**Generate Documents:**
+```
+@master: Create a PDF report of our Q4 metrics
+@master: Generate a branded PowerPoint for the board meeting
+```
 
-1. **Hook Trigger** - Plugin loads `hooks/register-agents.js`
-2. **Directory Scan** - Hook scans `agents/` directory
-3. **Metadata Extraction** - Parses agent markdown files
-4. **Context Registration** - Registers in Claude's context
-5. **Auto-Invocation** - Agents appear with @ mention
+**Design & Branding:**
+```
+@ux-expert: Create wireframes for the login flow
+@master: Apply our brand guidelines to this design
+```
 
-### How Skills Are Loaded
+---
 
-1. **Manifest Declaration** - Variant manifest lists skills
-2. **Path Resolution** - Resolves skill directory paths
-3. **Runtime Access** - Skills available to agents
-4. **Dynamic Loading** - Load on demand when invoked
+## 📦 npm Scripts
 
-See [ARCHITECTURE.md](ARCHITECTURE.md) for technical deep dive.
+Agentic Kit includes several npm scripts for common operations:
 
-## Troubleshooting
+### Installation Scripts
 
-### Agents Not Appearing in Auto-Invocation
+```bash
+# Run interactive installer
+npm run install-interactive
 
-**Problem:** Can't find agents with @ mention
+# Uninstall a tool
+npm run uninstall-tool
+```
 
-**Solutions:**
-1. Verify installation: `@Master: *help`
-2. Refresh Claude (F5)
-3. Check variant manifest includes your agent
-4. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+### Testing Scripts
 
-### Skills Not Loading
+```bash
+# Run all tests
+npm test
 
-**Problem:** Skill commands don't work
+# Run installer tests only
+npm run test-installer
+```
 
-**Solutions:**
-1. Verify your variant includes the skill
-2. Check skill path in manifest
-3. Ensure skill files are present
-4. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+### Validation Scripts
 
-### Reference or Path Issues
+```bash
+# Validate package structure
+npm run validate
 
-**Problem:** Agents reference missing files
+# Validate all tool packages
+npm run validate-packages
+```
 
-**Solutions:**
-1. Run validation script: `./validate-references.sh`
-2. Reinstall toolkit
-3. Report issue with output from validation
+### Publishing Scripts
 
-See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for comprehensive troubleshooting guide.
+```bash
+# Publish to npm
+npm run publish:npm
 
-## Contributing
+# Publish to GitHub packages
+npm run publish:github
 
-We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting:
+# Publish to both registries
+npm run publish:both
+```
 
-- How to add custom agents
-- How to add custom skills
-- Code style and standards
-- Testing requirements
-- Submission process
+**CLI Commands** (after global install):
 
-### Quick Contribution Guide
+```bash
+# Install agents and skills
+agentic-kit install
 
-**Add a New Agent:**
-1. Create `agents/your-agent-name.md`
-2. Follow standard agent format
-3. Update variant manifests
-4. Test with auto-invocation
-5. Submit pull request
+# Install with options
+agentic-kit install --variant=standard --tools=claude
 
-**Add a New Skill:**
-1. Create `skills/your-skill-name/`
-2. Add SKILL.md with documentation
-3. Update variant manifests
-4. Test integration
-5. Submit pull request
+# Uninstall
+agentic-kit install --uninstall --tools=claude
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+# Help
+agentic-kit install --help
+```
 
-## Documentation Index
+---
 
-- **[QUICK-START.md](QUICK-START.md)** - 15-minute onboarding for non-technical users
-- **[AGENTS.md](AGENTS.md)** - Complete agent directory with descriptions and use cases
-- **[SKILLS.md](SKILLS.md)** - Complete skill directory with capabilities and examples
-- **[VARIANTS.md](VARIANTS.md)** - Variant comparison and decision matrix
-- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Technical documentation and design
-- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
-- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Developer guide for contributions
+## 🤝 Contributing
 
-## Support
+We welcome contributions! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.
 
-### Getting Help
+**Quick contribution:**
+1. Fork the repo
+2. Create a feature branch
+3. Add your agent or skill
+4. Submit a pull request
 
-1. Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
-2. Review [QUICK-START.md](QUICK-START.md) for getting started
-3. See [AGENTS.md](AGENTS.md) for agent-specific guidance
-4. Visit Claude support: https://support.anthropic.com
+---
 
-### Reporting Issues
+## 📊 Stats
 
-Include:
-- Installation method and variant
-- Steps to reproduce
-- Error messages or logs
-- Output from `./validate-references.sh`
+- **13** Specialized Agents
+- **22** Powerful Skills
+- **3** Variants (Lite/Standard/Pro)
+- **4** Supported Tools (Claude, Opencode, Ampcode, Droid)
+- **MIT** License
+- **Production-Ready** with full validation
 
-## Version History
+---
 
-- **1.0.0** (Nov 2024) - Initial release
-  - 13 agents
-  - 16 skills
-  - 3 variants (Lite, Standard, Pro)
-  - Ultra-lean architecture
-  - Comprehensive documentation
+## 🔗 Links
 
-## License
+- **npm:** https://www.npmjs.com/package/@amrhas82/agentic-kit
+- **GitHub:** https://github.com/amrhas82/agentic-kit
+- **Issues:** https://github.com/amrhas82/agentic-kit/issues
+- **Knowledge Base:** [KNOWLEDGE_BASE.md](docs/KNOWLEDGE_BASE.md)
 
-Copyright 2024 Anthropic. See LICENSE file for details.
+---
 
-## Roadmap
+## 📄 License
 
-Planned improvements:
-- Additional specialized agents
-- Custom skill marketplace
-- Enhanced auto-discovery
-- Performance optimizations
-- Community contributions integration
+MIT © 2025 amrhas82
 
 ---
 
-**Version:** 1.0.0
-**Last Updated:** Nov 2024
-**Status:** Production Ready
-
-Start with [QUICK-START.md](QUICK-START.md) if you're new, or jump to [AGENTS.md](AGENTS.md) to explore available agents.
+**Need help?** Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) or [open an issue](https://github.com/amrhas82/agentic-kit/issues)