@amrhas82/agentic-kit 1.0.0 → 1.1.0

package/README.md

@@ -1,449 +1,219 @@
-# 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 14 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)
+A comprehensive toolkit featuring specialized AI agents and powerful skills for product management, agile development, content creation, and design.
 
-## Quick Start
+---
+
+## 🚀 Quick Start
 
 ### 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)
+| Variant | Agents | Skills | Best For |
+|---------|--------|--------|----------|
+| **Lite** | 3 | 0 | Minimal setup, CI/CD pipelines |
+| **Standard** ⭐ | 13 | 8 | Most users, general development |
+| **Pro** | 13 | 14 | Advanced users, full feature set |
 
-### 2. Installation
+### 2. Install
 
-**Via Claude Code:**
-```
-/plugin marketplace add agentic-kit
+**Claude Code (Recommended):**
+```bash
+/plugin add github:amrhas82/agentic-kit
 ```
 
-**Via npx:**
+**npx (Run without installing):**
 ```bash
-npx agentic-kit              # Standard variant (default)
-npx agentic-kit --variant=lite
-npx agentic-kit --variant=pro
+npx @amrhas82/agentic-kit
+npx agkit --variant=lite
 ```
 
-### 3. Your First Task (15 minutes)
+### 3. Start Using
 
-1. Open Claude and invoke an agent:
-   ```
-   @Product Manager: Create a PRD for a task management app
-   ```
+```bash
+# Get help
+@master: help
 
-2. The agent executes with full context from the toolkit
+# Create a Product Requirements Document
+@product-manager: Create a PRD for a task management app
 
-3. Access your results and continue collaborating
+# Generate development tasks
+@generate-tasks: Break down this feature into tasks
 
-See [QUICK-START.md](QUICK-START.md) for detailed walkthrough.
+# Process task list
+@process-task-list: Execute this task list
+```
 
-## Installation
+---
 
-### Prerequisites
+## 📖 Documentation
 
-- Claude account (Free, Claude+ or Pro required for full functionality)
-- Internet connection
+| Document | Description |
+|----------|-------------|
+| **[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 |
+| **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** | Common issues and solutions |
+| **[CONTRIBUTING.md](docs/CONTRIBUTING.md)** | Contribution guidelines |
+| **[PUBLISHING.md](docs/PUBLISHING.md)** | Publishing guide for maintainers |
 
-### Installation Methods
+---
 
-#### Claude Code (Recommended)
+## ⚙️ Installation Options
 
-```
-/plugin marketplace add agentic-kit
-```
+### Option 1: Claude Code via GitHub ⭐
 
-This installs the Standard variant by default. For other variants:
-```
-/plugin marketplace add agentic-kit-lite
-/plugin marketplace add agentic-kit-pro
-```
-
-#### npx (Quick Try)
+Install directly from GitHub (no marketplace approval needed):
 
 ```bash
-# Standard variant (recommended)
-npx agentic-kit
+/plugin add github:amrhas82/agentic-kit
+```
 
-# Lite variant
-npx agentic-kit --variant=lite
+**Advantages:** Instant access, always latest version, no waiting
 
-# Pro variant
-npx agentic-kit --variant=pro
-```
+### Option 2: npx (Run Temporarily)
 
-#### Development Installation
+Run the CLI without installing (doesn't install to your system):
 
 ```bash
-# Clone repository
-git clone https://github.com/anthropic/agentic-toolkit.git
-cd agentic-kit
+# Standard variant
+npx @amrhas82/agentic-kit
 
-# Install dependencies
-npm install
-
-# Link locally
-npm link
+# Other variants
+npx agkit --variant=lite
+npx agkit --variant=pro
 ```
 
-### Verification
+**Note:** `npx` downloads and runs the package temporarily. Nothing is installed permanently. Use Option 3 (npm install) for permanent installation.
 
-After installation, verify agents are available:
+### Option 3: npm Install
 
+```bash
+npm install @amrhas82/agentic-kit
 ```
-@Master: *help
-```
-
-You should see a list of available commands. If agents don't appear, see [Troubleshooting](TROUBLESHOOTING.md).
-
-## Variants
-
-### Comparison Matrix
-
-| 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 |
-
-### Which Variant Should I Choose?
-
-**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
-
-**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
-
-**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
-
-See [VARIANTS.md](VARIANTS.md) for detailed comparison and upgrade paths.
-
-## Agents Overview
-
-The toolkit includes 13 specialized agents that work together:
-
-### Core Agents (All Variants)
-
-**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
-
-**Orchestrator** - Workflow management and task coordination
-- Breaks down complex tasks into steps
-- Coordinates between agents
-- Tracks progress and dependencies
-
-### Product & Business Agents (Standard/Pro)
-
-**Product Manager** - Product strategy and vision
-- Creates product roadmaps
-- Defines success metrics
-- Analyzes market and competitive landscape
-
-**Product Owner** - Requirements and backlog management
-- Writes user stories and acceptance criteria
-- Prioritizes backlog
-- Manages feature specifications
-
-**Business Analyst** - Business requirements analysis
-- Analyzes business needs
-- Creates functional specifications
-- Documents requirements
-
-### Development Agents (Standard/Pro)
-
-**Full-Stack Developer** - Implementation and coding
-- Writes production-quality code
-- Handles frontend, backend, database
-- Writes tests and documentation
 
-**Holistic Architect** - System design and architecture
-- Creates system architecture diagrams
-- Designs data models and APIs
-- Plans scaling and performance
+### Option 4: Marketplace
 
-### Design & Quality Agents (Standard/Pro)
-
-**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 (14 Total)
 
-### Document Processing (All Standard/Pro)
+**Document Generation (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):**
+- Algorithmic Art, Artifacts Builder, MCP Builder, Skill Creator, WebApp Testing, Slack GIF Creator
 
-- **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.
+- **✅ Persistent Skills** - Auto-load on session start
+- **✅ Variant Isolation** - Clean separation between tiers
+- **✅ Auto-Discovery** - Agents register automatically
+- **✅ Rich Documentation** - Comprehensive guides and examples
+- **✅ Production-Ready** - Battle-tested workflows
 
-## 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
-
-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
-
-### 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
-
-See [ARCHITECTURE.md](ARCHITECTURE.md) for technical deep dive.
-
-## Troubleshooting
-
-### Agents Not Appearing in Auto-Invocation
-
-**Problem:** Can't find agents with @ mention
-
-**Solutions:**
-1. Verify installation: `@Master: *help`
-2. Refresh Claude (F5)
-3. Check variant manifest includes your agent
-4. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
-
-### Skills Not Loading
-
-**Problem:** Skill commands don't work
-
-**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)
-
-### Reference or Path Issues
-
-**Problem:** Agents reference missing files
-
-**Solutions:**
-1. Run validation script: `./validate-references.sh`
-2. Reinstall toolkit
-3. Report issue with output from validation
-
-See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for comprehensive troubleshooting guide.
-
-## Contributing
-
-We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting:
-
-- How to add custom agents
-- How to add custom skills
-- Code style and standards
-- Testing requirements
-- Submission process
-
-### Quick Contribution Guide
-
-**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
-
-**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
+**Generate Documents:**
+```
+@master: Create a PDF report of our Q4 metrics
+@master: Generate a branded PowerPoint for the board meeting
+```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+**Design & Branding:**
+```
+@ux-expert: Create wireframes for the login flow
+@master: Apply our brand guidelines to this design
+```
 
-## 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
+- **14** Powerful Skills
+- **3** Variants (Lite/Standard/Pro)
+- **MIT** License
+- **Production-Ready**
 
-## 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)

package/TROUBLESHOOTING.md

@@ -718,7 +718,7 @@ npm install -g agentic-toolkit
 3. **[AGENTS.md](AGENTS.md)** - Agent documentation
 4. **[SKILLS.md](SKILLS.md)** - Skill documentation
 5. **[ARCHITECTURE.md](ARCHITECTURE.md)** - Technical details
-6. **[CONTRIBUTING.md](CONTRIBUTING.md)** - Extension guide
+6. **[CONTRIBUTING.md](docs/CONTRIBUTING.md)** - Extension guide
 
 ### Contacting Support