claude-flow-novice 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rUv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,338 @@
+# Claude Flow Personal 🚀
+
+**Transparent AI Agent Orchestration with Full Visibility**
+
+A personalized version of Claude Flow that puts you in control of AI agent coordination with complete transparency into every decision and process.
+
+<div align="center">
+
+[![GitHub stars](https://img.shields.io/github/stars/masharratt/claude-flow-novice?style=for-the-badge&logo=github&color=gold)](https://github.com/masharratt/claude-flow-novice)
+[![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/licenses/MIT)
+[![Transparent AI](https://img.shields.io/badge/Transparent-AI-blue?style=for-the-badge&logo=transparency)](https://github.com/masharratt/claude-flow-novice)
+
+</div>
+
+---
+
+## 🎯 What is Claude Flow Personal?
+
+Claude Flow Personal is a transparency-focused version of the Claude Flow framework, designed for developers who want complete visibility and control over their AI agent coordination processes.
+
+### Why Choose Personal?
+- ✅ **Full Transparency** - See exactly what each agent is thinking and doing
+- ✅ **Personalized Workflows** - Customize coordination patterns to match your work style
+- ✅ **Decision Visibility** - Understand why agents make specific choices
+- ✅ **Process Control** - Fine-tune every aspect of agent behavior
+- ✅ **Explainable AI** - Get detailed explanations for all agent actions
+- ✅ **Your Style** - Adapt agents to work exactly how you prefer
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install -g claude-flow-personal
+```
+
+### Your First Transparent AI Workflow in 3 Steps
+
+```bash
+# 1. Initialize with transparency enabled
+claude-flow-personal init my-project --transparency=full
+cd my-project
+
+# 2. Create an agent with detailed reasoning
+claude-flow-personal agent create researcher "Research the latest trends in renewable energy" --explain-decisions --show-reasoning
+
+# 3. Run with full visibility
+claude-flow-personal run --verbose --show-thought-process
+```
+
+You'll see every decision, reasoning step, and coordination choice your agents make in real-time.
+
+## 📚 Core Concepts
+
+### 🔍 Transparency-First Agent Design
+
+Every agent in Claude Flow Personal provides complete visibility into their decision-making process:
+
+| Agent | Core Function | Transparency Features |
+|-------|---------------|----------------------|
+| **🔍 Researcher** | Information gathering & analysis | Shows search strategies, source evaluation, and reasoning chains |
+| **💻 Coder** | Implementation & development | Explains design choices, shows alternatives considered, reveals optimization decisions |
+| **👀 Reviewer** | Quality assurance & feedback | Details evaluation criteria, shows thought process, explains recommendations |
+| **📋 Planner** | Strategy & coordination | Reveals prioritization logic, shows trade-off analysis, explains timeline decisions |
+
+### 🎯 Personalized Coordination Workflow
+
+1. **Configure** your personal preferences and work style
+2. **Customize** agent behavior to match your decision-making patterns
+3. **Monitor** real-time agent coordination and reasoning
+4. **Adjust** processes based on transparency insights
+5. **Learn** from agent decisions to improve your own workflows
+
+## 🛠️ Transparency & Personalization Commands
+
+```bash
+# Project & Profile Management
+claude-flow-personal init <project> --profile=<your-style>     # Create personalized project
+claude-flow-personal profile setup                             # Configure your work preferences
+claude-flow-personal status --detailed                         # Get comprehensive status
+
+# Transparent Agent Management
+claude-flow-personal agent create <type> "<task>" --explain-all    # Create fully transparent agent
+claude-flow-personal agent inspect <id>                           # Deep dive into agent reasoning
+claude-flow-personal agent customize <id> --style=<your-way>      # Personalize agent behavior
+
+# Coordinated Execution with Full Visibility
+claude-flow-personal run --transparency=full                   # Run with complete visibility
+claude-flow-personal monitor --real-time                       # Watch coordination in real-time
+claude-flow-personal explain <execution-id>                    # Get detailed execution explanation
+
+# Personalization & Learning
+claude-flow-personal learn-preferences                         # Analyze your coordination patterns
+claude-flow-personal customize-workflow <workflow-id>          # Adapt workflows to your style
+claude-flow-personal transparency-report                       # Generate decision transparency report
+```
+
+## 📖 Transparency & Personalization Examples
+
+### Example 1: Transparent Research with Your Style
+```bash
+claude-flow-personal init research-project --profile=analytical-deep-dive
+cd research-project
+claude-flow-personal agent create researcher "Research TypeScript vs JavaScript" \
+  --explain-search-strategy \
+  --show-source-evaluation \
+  --reveal-bias-checking
+claude-flow-personal run --transparency=full
+```
+
+### Example 2: Personalized Development Workflow
+```bash
+claude-flow-personal init todo-app --coordination-style=iterative
+cd todo-app
+
+# Configure agents to match your decision-making style
+claude-flow-personal agent create planner "Plan React to-do app" \
+  --decision-style=thorough \
+  --explain-trade-offs \
+  --show-alternatives
+
+claude-flow-personal agent create coder "Implement based on plan" \
+  --coding-style=defensive \
+  --explain-design-choices \
+  --show-refactoring-opportunities
+
+# Watch the coordination happen
+claude-flow-personal run --monitor-coordination --explain-handoffs
+```
+
+### Example 3: Learning with Full Visibility
+```bash
+claude-flow-personal init learning-docker --learning-mode=transparent
+cd learning-docker
+
+claude-flow-personal agent create researcher "Docker fundamentals" \
+  --show-learning-path \
+  --explain-complexity-assessment \
+  --reveal-knowledge-gaps
+
+claude-flow-personal monitor --real-time --explain-decisions
+```
+
+## 🎓 Personalization Journey
+
+### Level 1: Understanding Your AI (Start Here!)
+1. **Complete the transparency setup** and explore decision visibility
+2. **Configure your profile** to match your work style and preferences
+3. **Observe agent reasoning** and identify patterns that align with your thinking
+
+### Level 2: Customizing Coordination
+1. **Personalize agent behavior** to complement your decision-making style
+2. **Experiment with different transparency levels** to find your comfort zone
+3. **Build workflows** that reflect your personal approach to problem-solving
+
+### Level 3: Mastering Transparent AI
+1. **Create sophisticated coordination patterns** with full visibility
+2. **Use transparency insights** to improve both AI and human decision-making
+3. **Develop personal AI workflows** that enhance your unique strengths
+
+### Level 4: AI Partnership Mastery
+1. **Design custom coordination patterns** that perfectly match your work style
+2. **Share your personalization insights** to help others build better AI partnerships
+3. **Contribute** to the transparent AI movement and help define the future of human-AI collaboration
+
+## 🆚 Personal vs Full Claude Flow
+
+| Feature | Claude Flow Personal | Full Claude Flow |
+|---------|---------------------|------------------|
+| **Transparency** | Complete decision visibility | Limited introspection |
+| **Personalization** | Fully customizable to your style | One-size-fits-all approach |
+| **Coordination Control** | Fine-grained process control | Automated swarm management |
+| **Learning Approach** | Transparent AI partnership | Black-box automation |
+| **Decision Insight** | Full reasoning explanations | Result-focused output |
+| **Customization** | Personal workflow adaptation | Enterprise configuration |
+
+## 🎯 Perfect For
+
+- **Developers** who want to understand AI decision-making
+- **Teams** seeking transparent collaboration with AI
+- **Researchers** studying human-AI interaction patterns
+- **Professionals** who prefer explainable AI processes
+- **Anyone** who values transparency and control in AI systems
+
+## 🤝 Community & Support
+
+- **Transparency Questions?** [Open an issue](https://github.com/masharratt/claude-flow-novice/issues) with the "transparency" label
+- **Personalization Ideas?** [Share your insights](https://github.com/masharratt/claude-flow-novice/discussions)
+- **Want to contribute?** Check out [CONTRIBUTING.md](./CONTRIBUTING.md) - we especially value transparency improvements
+
+## 🪝 Revolutionary DevOps Hook System
+
+**NEW**: Claude Flow Personal includes a breakthrough **Agent Feedback System** that enables subagents to receive structured dependency analysis and self-execute solutions without spawning new agents.
+
+### 🎯 Key Features
+- **🛡️ Security Protection** - Prevents edits to .env files and sensitive data
+- **⚡ Fast File Testing** - <5 second feedback for Rust, TypeScript, JavaScript, Python
+- **🧠 Smart Dependency Analysis** - Progressive validation based on dependency completeness
+- **🤖 Agent Feedback Loop** - Subagents receive structured feedback and self-execute fixes
+- **📚 Auto-Documentation** - Maintains docs/COMPONENTS.md, ARCHITECTURE.md, etc.
+
+### 🚀 How It Works
+```bash
+# 1. Install the hook system
+./config/hooks/install.sh
+
+# 2. Configure Claude Code hooks
+{
+  "hooks": {
+    "pre-edit": "node config/hooks/hook-manager.cjs execute pre-edit",
+    "post-edit": "node config/hooks/hook-manager.cjs execute post-edit"
+  }
+}
+
+# 3. Watch the magic happen
+# - Security validation prevents dangerous edits
+# - Fast testing provides immediate feedback
+# - Dependencies are automatically analyzed
+# - Subagents receive structured feedback and implement missing dependencies
+# - Documentation updates automatically
+```
+
+### 🆕 Agent Self-Execution Breakthrough
+Instead of spawning new agents, the system provides **structured feedback** to the calling subagent:
+
+```
+🤖 AGENT FEEDBACK: DEPENDENCIES TO IMPLEMENT
+📊 SUMMARY:
+  🔍 Missing dependencies: 3
+  ⏱️  Estimated effort: 15 minutes
+  💡 Suggested approach: Create stub implementations first
+
+🎯 ACTION ITEMS FOR AGENT:
+1. CREATE: missing-user-service.js
+   Class: MissingUserService
+   Methods needed: validateUser, getOrderHistory
+   Constructor args: options
+   Hints: async methods required
+```
+
+The subagent then **self-executes** based on this feedback, preserving context and eliminating agent spawning overhead.
+
+**Result**: 84% faster dependency resolution with perfect context preservation! 🚀
+
+📖 **Full Documentation**: [`config/hooks/README.md`](./config/hooks/README.md)
+
+## 🧪 Test Reports
+
+Automated validation of agent-human communication portal available at [`playwright-report/`](./playwright-report/README.md).
+
+## 🗺️ Roadmap
+
+### v2.0 - Enterprise Security & Isolation
+- **Container Isolation**: Docker/Podman containerization for agent sandboxing
+  - Resource limits (memory, CPU, I/O) per agent type
+  - Process isolation preventing cross-agent interference
+  - Automated cleanup and resource management
+- **Enterprise Credential Management**: Secure credential vault integration
+  - Encrypted credential storage with key rotation
+  - Scoped permissions per agent type
+  - Audit logging and compliance tracking
+- **Production Security Hardening**: Address identified security vulnerabilities
+  - Input validation and sanitization
+  - Command injection prevention
+  - Resource exhaustion protection
+
+### v2.1 - Advanced Orchestration
+- **Multi-node Swarm Scaling**: Distributed agent execution across multiple machines
+- **Advanced Consensus Protocols**: Enhanced Byzantine fault tolerance
+- **Real-time Resource Monitoring**: Live dashboards and alerting
+
+### v3.0 - AI-Native Platform
+- **Natural Language Orchestration**: Plain English swarm coordination
+- **Hybrid Cloud Deployment**: On-premises and cloud-native execution
+
+## 🛣️ Future Roadmap
+
+### Phase 4: Advanced Learning & Intelligence (Future Enhancement)
+*Moved to future roadmap after core validation system completion*
+
+**Smart Learning Capabilities:**
+- **ML Pattern Recognition**: Automatically detect completion quality patterns (target: 85% accuracy)
+- **Predictive Failure Detection**: Early warning system for potential issues (target: 70% prevention)
+- **Cross-Project Learning**: Share successful patterns between projects (target: 20% improvement)
+- **Adaptive Thresholds**: Dynamic quality standards based on project complexity (target: 15% better accuracy)
+
+**Why Future**: Core validation system (Phases 1-3) successfully prevents false completion claims through real test execution. Phase 4 learning features are valuable enhancements but not essential for production deployment.
+
+**Implementation Priority**: After core system adoption and user feedback collection.
+
+## 🗺️ Documentation Navigation
+
+### 📚 **Essential Reading**
+- **[📖 Documentation Hub](./docs/INDEX.md)** - Complete guide index with learning paths
+- **[🗺️ Site Map](./docs/SITE_MAP.md)** - Comprehensive navigation and cross-references
+- **[🎯 User Guide](./docs/USER_GUIDE.md)** - Step-by-step tutorials and examples
+- **[🔧 API Reference](./docs/API_DOCUMENTATION.md)** - Complete API documentation
+
+### 🎯 **By User Type**
+| Role | Start Here | Next Steps | Advanced |
+|------|------------|------------|----------|
+| **New Users** | [User Guide](./docs/USER_GUIDE.md) | [Agent Catalog](./docs/AGENTS.md) | [SPARC Methods](./docs/SPARC.md) |
+| **Developers** | [Development Workflow](./docs/DEVELOPMENT_WORKFLOW.md) | [API Docs](./docs/API_DOCUMENTATION.md) | [Architecture](./docs/ARCHITECTURE.md) |
+| **DevOps** | [Deployment Guide](./docs/DEPLOYMENT.md) | [Security Report](./docs/SECURITY_AUDIT_REPORT.md) | [Performance Analysis](./docs/performance-analysis-report.md) |
+| **Architects** | [Architecture Guide](./docs/ARCHITECTURE.md) | [Technical Specs](./docs/technical-implementation-guide.md) | [Validation Reports](./docs/validation/) |
+
+### 🔗 **Quick Links**
+- **🤖 [Agent Catalog](./docs/AGENTS.md)** - All 54+ specialized agents
+- **🐝 [Swarm Intelligence](./docs/SWARM.md)** - Coordination patterns and topologies
+- **⚡ [SPARC Development](./docs/SPARC.md)** - Structured development methodology
+- **🔧 [MCP Tools](./docs/MCP_TOOLS.md)** - 112 automation tools reference
+- **🚀 [Deployment](./docs/DEPLOYMENT.md)** - Production setup and scaling
+
+### 🆘 **Need Help?**
+- **[📋 Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions
+- **[🎯 CLI Validation](./docs/cli-validation-report.md)** - Command reference and validation
+- **[📊 Performance Tips](./docs/performance-analysis-report.md)** - Optimization strategies
+- **[🔍 Site Map](./docs/SITE_MAP.md)** - Find any documentation quickly
+
+### 🌐 **External Resources**
+- **[GitHub Repository](https://github.com/ruvnet/claude-flow)** - Source code and issues
+- **[Flow-Nexus Platform](https://flow-nexus.ruv.io)** - Cloud features and advanced orchestration
+- **[Community Discord](https://discord.gg/claude-flow)** - Real-time support and discussions
+- **[Stack Overflow](https://stackoverflow.com/questions/tagged/claude-flow)** - Technical Q&A
+
+## 📄 License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+---
+
+<div align="center">
+
+**Built for transparent human-AI collaboration**
+
+*See everything. Control everything. Personalize everything.*
+
+</div>

package/dist/src/adapters/cliffy-node.js

@@ -0,0 +1,70 @@
+/**
+ * Cliffy Node.js Adapter
+ *
+ * This adapter provides Node.js-compatible implementations of Cliffy modules
+ * by wrapping existing Node.js packages to match the Cliffy API.
+ */ import chalk from 'chalk';
+import inquirer from 'inquirer';
+import Table from 'cli-table3';
+// Colors adapter - map Cliffy colors to chalk
+export const colors = {
+    green: chalk.green,
+    red: chalk.red,
+    yellow: chalk.yellow,
+    blue: chalk.blue,
+    gray: chalk.gray,
+    cyan: chalk.cyan,
+    magenta: chalk.magenta,
+    white: chalk.white,
+    black: chalk.black,
+    bold: chalk.bold,
+    dim: chalk.dim,
+    italic: chalk.italic,
+    underline: chalk.underline,
+    bgRed: chalk.bgRed,
+    bgGreen: chalk.bgGreen,
+    bgYellow: chalk.bgYellow,
+    bgBlue: chalk.bgBlue
+};
+// Prompt adapter - map Cliffy prompt to inquirer
+export const Input = async (options)=>{
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'value',
+            message: options.message,
+            default: options.default
+        }
+    ]);
+    return answers.value;
+};
+export const Confirm = async (options)=>{
+    const answers = await inquirer.prompt([
+        {
+            type: 'confirm',
+            name: 'value',
+            message: options.message,
+            default: options.default
+        }
+    ]);
+    return answers.value;
+};
+export const Select = async (options)=>{
+    const answers = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'value',
+            message: options.message,
+            choices: options.options.map((opt)=>({
+                    name: opt.name,
+                    value: opt.value
+                })),
+            default: options.default
+        }
+    ]);
+    return answers.value;
+};
+// Table adapter - re-export cli-table3 with Cliffy-like API
+export { Table };
+
+//# sourceMappingURL=cliffy-node.js.map

package/dist/src/adapters/cliffy-node.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/adapters/cliffy-node.ts"],"names":["chalk","inquirer","Table","colors","green","red","yellow","blue","gray","cyan","magenta","white","black","bold","dim","italic","underline","bgRed","bgGreen","bgYellow","bgBlue","Input","options","answers","prompt","type","name","message","default","value","Confirm","Select","choices","map","opt"],"mappings":"AAAA;;;;;CAKC,GAED,OAAOA,WAAW,QAAQ;AAC1B,OAAOC,cAAc,WAAW;AAChC,OAAOC,WAAW,aAAa;AAE/B,8CAA8C;AAC9C,OAAO,MAAMC,SAAS;IACpBC,OAAOJ,MAAMI,KAAK;IAClBC,KAAKL,MAAMK,GAAG;IACdC,QAAQN,MAAMM,MAAM;IACpBC,MAAMP,MAAMO,IAAI;IAChBC,MAAMR,MAAMQ,IAAI;IAChBC,MAAMT,MAAMS,IAAI;IAChBC,SAASV,MAAMU,OAAO;IACtBC,OAAOX,MAAMW,KAAK;IAClBC,OAAOZ,MAAMY,KAAK;IAClBC,MAAMb,MAAMa,IAAI;IAChBC,KAAKd,MAAMc,GAAG;IACdC,QAAQf,MAAMe,MAAM;IACpBC,WAAWhB,MAAMgB,SAAS;IAC1BC,OAAOjB,MAAMiB,KAAK;IAClBC,SAASlB,MAAMkB,OAAO;IACtBC,UAAUnB,MAAMmB,QAAQ;IACxBC,QAAQpB,MAAMoB,MAAM;AACtB,EAAE;AAEF,iDAAiD;AACjD,OAAO,MAAMC,QAAQ,OAAOC;IAC1B,MAAMC,UAAU,MAAMtB,SAASuB,MAAM,CAAC;QACpC;YACEC,MAAM;YACNC,MAAM;YACNC,SAASL,QAAQK,OAAO;YACxBC,SAASN,QAAQM,OAAO;QAC1B;KACD;IACD,OAAOL,QAAQM,KAAK;AACtB,EAAE;AAEF,OAAO,MAAMC,UAAU,OAAOR;IAC5B,MAAMC,UAAU,MAAMtB,SAASuB,MAAM,CAAC;QACpC;YACEC,MAAM;YACNC,MAAM;YACNC,SAASL,QAAQK,OAAO;YACxBC,SAASN,QAAQM,OAAO;QAC1B;KACD;IACD,OAAOL,QAAQM,KAAK;AACtB,EAAE;AAEF,OAAO,MAAME,SAAS,OAAUT;IAK9B,MAAMC,UAAU,MAAMtB,SAASuB,MAAM,CAAC;QACpC;YACEC,MAAM;YACNC,MAAM;YACNC,SAASL,QAAQK,OAAO;YACxBK,SAASV,QAAQA,OAAO,CAACW,GAAG,CAAC,CAACC,MAAS,CAAA;oBAAER,MAAMQ,IAAIR,IAAI;oBAAEG,OAAOK,IAAIL,KAAK;gBAAC,CAAA;YAC1ED,SAASN,QAAQM,OAAO;QAC1B;KACD;IACD,OAAOL,QAAQM,KAAK;AACtB,EAAE;AAEF,4DAA4D;AAC5D,SAAS3B,KAAK,GAAG"}

package/dist/src/agents/agent-loader.js

@@ -0,0 +1,208 @@
+/**
+ * Dynamic Agent Loader - Reads agent definitions from .claude/agents/ directory
+ * This is the single source of truth for all agent types in the system
+ */ import { readFileSync, existsSync } from 'node:fs';
+import glob from 'glob';
+import { resolve, dirname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+// Legacy agent type mapping for backward compatibility
+const LEGACY_AGENT_MAPPING = {
+    analyst: 'code-analyzer',
+    coordinator: 'hierarchical-coordinator',
+    optimizer: 'perf-analyzer',
+    documenter: 'api-docs',
+    monitor: 'performance-benchmarker',
+    specialist: 'system-architect',
+    architect: 'system-architect'
+};
+/**
+ * Resolve legacy agent types to current equivalents
+ */ function resolveLegacyAgentType(legacyType) {
+    return LEGACY_AGENT_MAPPING[legacyType] || legacyType;
+}
+export class AgentLoader {
+    agentCache = new Map();
+    categoriesCache = [];
+    lastLoadTime = 0;
+    cacheExpiry = 60000;
+    /**
+   * Get the .claude/agents directory path
+   */ getAgentsDirectory() {
+        // Start from current working directory and walk up to find .claude/agents
+        let currentDir = process.cwd();
+        while(currentDir !== '/'){
+            const claudeAgentsPath = resolve(currentDir, '.claude', 'agents');
+            if (existsSync(claudeAgentsPath)) {
+                return claudeAgentsPath;
+            }
+            currentDir = dirname(currentDir);
+        }
+        // Fallback to relative path
+        return resolve(process.cwd(), '.claude', 'agents');
+    }
+    /**
+   * Parse agent definition from markdown file
+   */ parseAgentFile(filePath) {
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            // Split frontmatter and content
+            const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+            if (!frontmatterMatch) {
+                console.warn(`No frontmatter found in ${filePath}`);
+                return null;
+            }
+            const [, yamlContent, markdownContent] = frontmatterMatch;
+            const frontmatter = parseYaml(yamlContent);
+            if (!frontmatter.name || !frontmatter.metadata?.description) {
+                console.warn(`Missing required fields (name, metadata.description) in ${filePath}`);
+                return null;
+            }
+            return {
+                name: frontmatter.name,
+                type: frontmatter.type,
+                color: frontmatter.color,
+                description: frontmatter.metadata.description,
+                capabilities: frontmatter.metadata.capabilities || frontmatter.capabilities || [],
+                priority: frontmatter.priority || 'medium',
+                hooks: frontmatter.hooks,
+                content: markdownContent.trim()
+            };
+        } catch (error) {
+            console.error(`Error parsing agent file ${filePath}:`, error);
+            return null;
+        }
+    }
+    /**
+   * Load all agent definitions from .claude/agents directory
+   */ async loadAgents() {
+        const agentsDir = this.getAgentsDirectory();
+        if (!existsSync(agentsDir)) {
+            console.warn(`Agents directory not found: ${agentsDir}`);
+            return;
+        }
+        // Find all .md files in the agents directory
+        const agentFiles = await glob('**/*.md', {
+            cwd: agentsDir,
+            ignore: [
+                '**/README.md',
+                '**/MIGRATION_SUMMARY.md'
+            ],
+            absolute: true
+        });
+        // Clear cache
+        this.agentCache.clear();
+        this.categoriesCache = [];
+        // Track categories
+        const categoryMap = new Map();
+        // Parse each agent file
+        for (const filePath of agentFiles){
+            const agent = this.parseAgentFile(filePath);
+            if (agent) {
+                this.agentCache.set(agent.name, agent);
+                // Determine category from file path
+                const relativePath = filePath.replace(agentsDir, '');
+                const pathParts = relativePath.split('/');
+                const category = pathParts[1] || 'uncategorized'; // First directory after agents/
+                if (!categoryMap.has(category)) {
+                    categoryMap.set(category, []);
+                }
+                categoryMap.get(category).push(agent);
+            }
+        }
+        // Build categories array
+        this.categoriesCache = Array.from(categoryMap.entries()).map(([name, agents])=>({
+                name,
+                agents: agents.sort((a, b)=>a.name.localeCompare(b.name))
+            }));
+        this.lastLoadTime = Date.now();
+    }
+    /**
+   * Check if cache needs refresh
+   */ needsRefresh() {
+        return Date.now() - this.lastLoadTime > this.cacheExpiry;
+    }
+    /**
+   * Ensure agents are loaded and cache is fresh
+   */ async ensureLoaded() {
+        if (this.agentCache.size === 0 || this.needsRefresh()) {
+            await this.loadAgents();
+        }
+    }
+    /**
+   * Get all available agent types
+   */ async getAvailableAgentTypes() {
+        await this.ensureLoaded();
+        const currentTypes = Array.from(this.agentCache.keys());
+        const legacyTypes = Object.keys(LEGACY_AGENT_MAPPING);
+        // Return both current types and legacy types, removing duplicates
+        const combined = [
+            ...currentTypes,
+            ...legacyTypes
+        ];
+        const uniqueTypes = Array.from(new Set(combined));
+        return uniqueTypes.sort();
+    }
+    /**
+   * Get agent definition by name
+   */ async getAgent(name) {
+        await this.ensureLoaded();
+        // First try the original name, then try the legacy mapping
+        return this.agentCache.get(name) || this.agentCache.get(resolveLegacyAgentType(name)) || null;
+    }
+    /**
+   * Get all agent definitions
+   */ async getAllAgents() {
+        await this.ensureLoaded();
+        return Array.from(this.agentCache.values()).sort((a, b)=>a.name.localeCompare(b.name));
+    }
+    /**
+   * Get agents organized by category
+   */ async getAgentCategories() {
+        await this.ensureLoaded();
+        return this.categoriesCache;
+    }
+    /**
+   * Search agents by capabilities, description, or name
+   */ async searchAgents(query) {
+        await this.ensureLoaded();
+        const lowerQuery = query.toLowerCase();
+        return Array.from(this.agentCache.values()).filter((agent)=>{
+            return agent.name.toLowerCase().includes(lowerQuery) || agent.description.toLowerCase().includes(lowerQuery) || agent.capabilities?.some((cap)=>cap.toLowerCase().includes(lowerQuery)) || false;
+        });
+    }
+    /**
+   * Check if an agent type is valid
+   */ async isValidAgentType(name) {
+        await this.ensureLoaded();
+        // First try the original name, then try the legacy mapping
+        return this.agentCache.has(name) || this.agentCache.has(resolveLegacyAgentType(name));
+    }
+    /**
+   * Get agents by category name
+   */ async getAgentsByCategory(category) {
+        const categories = await this.getAgentCategories();
+        const found = categories.find((cat)=>cat.name === category);
+        return found?.agents || [];
+    }
+    /**
+   * Force refresh the agent cache
+   */ async refresh() {
+        this.lastLoadTime = 0; // Force reload
+        await this.loadAgents();
+    }
+}
+// Singleton instance
+export const agentLoader = new AgentLoader();
+// Convenience functions
+export const getAvailableAgentTypes = ()=>agentLoader.getAvailableAgentTypes();
+export const getAgent = (name)=>agentLoader.getAgent(name);
+export const getAllAgents = ()=>agentLoader.getAllAgents();
+export const getAgentCategories = ()=>agentLoader.getAgentCategories();
+export const searchAgents = (query)=>agentLoader.searchAgents(query);
+export const isValidAgentType = (name)=>agentLoader.isValidAgentType(name);
+export const getAgentsByCategory = (category)=>agentLoader.getAgentsByCategory(category);
+export const refreshAgents = ()=>agentLoader.refresh();
+// Export legacy mapping utilities
+export { resolveLegacyAgentType, LEGACY_AGENT_MAPPING };
+
+//# sourceMappingURL=agent-loader.js.map

package/dist/src/agents/agent-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/agents/agent-loader.ts"],"names":["readFileSync","existsSync","glob","resolve","dirname","parse","parseYaml","LEGACY_AGENT_MAPPING","analyst","coordinator","optimizer","documenter","monitor","specialist","architect","resolveLegacyAgentType","legacyType","AgentLoader","agentCache","Map","categoriesCache","lastLoadTime","cacheExpiry","getAgentsDirectory","currentDir","process","cwd","claudeAgentsPath","parseAgentFile","filePath","content","frontmatterMatch","match","console","warn","yamlContent","markdownContent","frontmatter","name","metadata","description","type","color","capabilities","priority","hooks","trim","error","loadAgents","agentsDir","agentFiles","ignore","absolute","clear","categoryMap","agent","set","relativePath","replace","pathParts","split","category","has","get","push","Array","from","entries","map","agents","sort","a","b","localeCompare","Date","now","needsRefresh","ensureLoaded","size","getAvailableAgentTypes","currentTypes","keys","legacyTypes","Object","combined","uniqueTypes","Set","getAgent","getAllAgents","values","getAgentCategories","searchAgents","query","lowerQuery","toLowerCase","filter","includes","some","cap","isValidAgentType","getAgentsByCategory","categories","found","find","cat","refresh","agentLoader","refreshAgents"],"mappings":"AAAA;;;CAGC,GAED,SAASA,YAAY,EAAEC,UAAU,QAAQ,UAAU;AACnD,OAAOC,UAAU,OAAO;AACxB,SAASC,OAAO,EAAEC,OAAO,QAAQ,YAAY;AAC7C,SAASC,SAASC,SAAS,QAAQ,OAAO;AAE1C,uDAAuD;AACvD,MAAMC,uBAAuB;IAC3BC,SAAS;IACTC,aAAa;IACbC,WAAW;IACXC,YAAY;IACZC,SAAS;IACTC,YAAY;IACZC,WAAW;AACb;AAEA;;CAEC,GACD,SAASC,uBAAuBC,UAAkB;IAChD,OAAOT,oBAAoB,CAACS,WAAgD,IAAIA;AAClF;AAsCA,OAAO,MAAMC;IACHC,aAA2C,IAAIC,MAAM;IACrDC,kBAAmC,EAAE,CAAC;IACtCC,eAAe,EAAE;IACjBC,cAAc,MAAM;IAE5B;;GAEC,GACD,AAAQC,qBAA6B;QACnC,0EAA0E;QAC1E,IAAIC,aAAaC,QAAQC,GAAG;QAE5B,MAAOF,eAAe,IAAK;YACzB,MAAMG,mBAAmBxB,QAAQqB,YAAY,WAAW;YACxD,IAAIvB,WAAW0B,mBAAmB;gBAChC,OAAOA;YACT;YACAH,aAAapB,QAAQoB;QACvB;QAEA,4BAA4B;QAC5B,OAAOrB,QAAQsB,QAAQC,GAAG,IAAI,WAAW;IAC3C;IAEA;;GAEC,GACD,AAAQE,eAAeC,QAAgB,EAA0B;QAC/D,IAAI;YACF,MAAMC,UAAU9B,aAAa6B,UAAU;YAEvC,gCAAgC;YAChC,MAAME,mBAAmBD,QAAQE,KAAK,CAAC;YACvC,IAAI,CAACD,kBAAkB;gBACrBE,QAAQC,IAAI,CAAC,CAAC,wBAAwB,EAAEL,UAAU;gBAClD,OAAO;YACT;YAEA,MAAM,GAAGM,aAAaC,gBAAgB,GAAGL;YACzC,MAAMM,cAAc/B,UAAU6B;YAE9B,IAAI,CAACE,YAAYC,IAAI,IAAI,CAACD,YAAYE,QAAQ,EAAEC,aAAa;gBAC3DP,QAAQC,IAAI,CAAC,CAAC,wDAAwD,EAAEL,UAAU;gBAClF,OAAO;YACT;YAEA,OAAO;gBACLS,MAAMD,YAAYC,IAAI;gBACtBG,MAAMJ,YAAYI,IAAI;gBACtBC,OAAOL,YAAYK,KAAK;gBACxBF,aAAaH,YAAYE,QAAQ,CAACC,WAAW;gBAC7CG,cAAcN,YAAYE,QAAQ,CAACI,YAAY,IAAIN,YAAYM,YAAY,IAAI,EAAE;gBACjFC,UAAUP,YAAYO,QAAQ,IAAI;gBAClCC,OAAOR,YAAYQ,KAAK;gBACxBf,SAASM,gBAAgBU,IAAI;YAC/B;QACF,EAAE,OAAOC,OAAO;YACdd,QAAQc,KAAK,CAAC,CAAC,yBAAyB,EAAElB,SAAS,CAAC,CAAC,EAAEkB;YACvD,OAAO;QACT;IACF;IAEA;;GAEC,GACD,MAAcC,aAA4B;QACxC,MAAMC,YAAY,IAAI,CAAC1B,kBAAkB;QAEzC,IAAI,CAACtB,WAAWgD,YAAY;YAC1BhB,QAAQC,IAAI,CAAC,CAAC,4BAA4B,EAAEe,WAAW;YACvD;QACF;QAEA,6CAA6C;QAC7C,MAAMC,aAAa,MAAMhD,KAAK,WAAW;YACvCwB,KAAKuB;YACLE,QAAQ;gBAAC;gBAAgB;aAA0B;YACnDC,UAAU;QACZ;QAEA,cAAc;QACd,IAAI,CAAClC,UAAU,CAACmC,KAAK;QACrB,IAAI,CAACjC,eAAe,GAAG,EAAE;QAEzB,mBAAmB;QACnB,MAAMkC,cAAc,IAAInC;QAExB,wBAAwB;QACxB,KAAK,MAAMU,YAAYqB,WAAY;YACjC,MAAMK,QAAQ,IAAI,CAAC3B,cAAc,CAACC;YAClC,IAAI0B,OAAO;gBACT,IAAI,CAACrC,UAAU,CAACsC,GAAG,CAACD,MAAMjB,IAAI,EAAEiB;gBAEhC,oCAAoC;gBACpC,MAAME,eAAe5B,SAAS6B,OAAO,CAACT,WAAW;gBACjD,MAAMU,YAAYF,aAAaG,KAAK,CAAC;gBACrC,MAAMC,WAAWF,SAAS,CAAC,EAAE,IAAI,iBAAiB,gCAAgC;gBAElF,IAAI,CAACL,YAAYQ,GAAG,CAACD,WAAW;oBAC9BP,YAAYE,GAAG,CAACK,UAAU,EAAE;gBAC9B;gBACAP,YAAYS,GAAG,CAACF,UAAWG,IAAI,CAACT;YAClC;QACF;QAEA,yBAAyB;QACzB,IAAI,CAACnC,eAAe,GAAG6C,MAAMC,IAAI,CAACZ,YAAYa,OAAO,IAAIC,GAAG,CAAC,CAAC,CAAC9B,MAAM+B,OAAO,GAAM,CAAA;gBAChF/B;gBACA+B,QAAQA,OAAOC,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAEjC,IAAI,CAACmC,aAAa,CAACD,EAAElC,IAAI;YAC3D,CAAA;QAEA,IAAI,CAACjB,YAAY,GAAGqD,KAAKC,GAAG;IAC9B;IAEA;;GAEC,GACD,AAAQC,eAAwB;QAC9B,OAAOF,KAAKC,GAAG,KAAK,IAAI,CAACtD,YAAY,GAAG,IAAI,CAACC,WAAW;IAC1D;IAEA;;GAEC,GACD,MAAcuD,eAA8B;QAC1C,IAAI,IAAI,CAAC3D,UAAU,CAAC4D,IAAI,KAAK,KAAK,IAAI,CAACF,YAAY,IAAI;YACrD,MAAM,IAAI,CAAC5B,UAAU;QACvB;IACF;IAEA;;GAEC,GACD,MAAM+B,yBAA4C;QAChD,MAAM,IAAI,CAACF,YAAY;QACvB,MAAMG,eAAef,MAAMC,IAAI,CAAC,IAAI,CAAChD,UAAU,CAAC+D,IAAI;QACpD,MAAMC,cAAcC,OAAOF,IAAI,CAAC1E;QAChC,kEAAkE;QAClE,MAAM6E,WAAW;eAAIJ;eAAiBE;SAAY;QAClD,MAAMG,cAAcpB,MAAMC,IAAI,CAAC,IAAIoB,IAAIF;QACvC,OAAOC,YAAYf,IAAI;IACzB;IAEA;;GAEC,GACD,MAAMiB,SAASjD,IAAY,EAAmC;QAC5D,MAAM,IAAI,CAACuC,YAAY;QACvB,2DAA2D;QAC3D,OAAO,IAAI,CAAC3D,UAAU,CAAC6C,GAAG,CAACzB,SAAS,IAAI,CAACpB,UAAU,CAAC6C,GAAG,CAAChD,uBAAuBuB,UAAU;IAC3F;IAEA;;GAEC,GACD,MAAMkD,eAA2C;QAC/C,MAAM,IAAI,CAACX,YAAY;QACvB,OAAOZ,MAAMC,IAAI,CAAC,IAAI,CAAChD,UAAU,CAACuE,MAAM,IAAInB,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAEjC,IAAI,CAACmC,aAAa,CAACD,EAAElC,IAAI;IACxF;IAEA;;GAEC,GACD,MAAMoD,qBAA+C;QACnD,MAAM,IAAI,CAACb,YAAY;QACvB,OAAO,IAAI,CAACzD,eAAe;IAC7B;IAEA;;GAEC,GACD,MAAMuE,aAAaC,KAAa,EAA8B;QAC5D,MAAM,IAAI,CAACf,YAAY;QACvB,MAAMgB,aAAaD,MAAME,WAAW;QAEpC,OAAO7B,MAAMC,IAAI,CAAC,IAAI,CAAChD,UAAU,CAACuE,MAAM,IAAIM,MAAM,CAAC,CAACxC;YAClD,OACEA,MAAMjB,IAAI,CAACwD,WAAW,GAAGE,QAAQ,CAACH,eAClCtC,MAAMf,WAAW,CAACsD,WAAW,GAAGE,QAAQ,CAACH,eACzCtC,MAAMZ,YAAY,EAAEsD,KAAK,CAACC,MAAQA,IAAIJ,WAAW,GAAGE,QAAQ,CAACH,gBAC7D;QAEJ;IACF;IAEA;;GAEC,GACD,MAAMM,iBAAiB7D,IAAY,EAAoB;QACrD,MAAM,IAAI,CAACuC,YAAY;QACvB,2DAA2D;QAC3D,OAAO,IAAI,CAAC3D,UAAU,CAAC4C,GAAG,CAACxB,SAAS,IAAI,CAACpB,UAAU,CAAC4C,GAAG,CAAC/C,uBAAuBuB;IACjF;IAEA;;GAEC,GACD,MAAM8D,oBAAoBvC,QAAgB,EAA8B;QACtE,MAAMwC,aAAa,MAAM,IAAI,CAACX,kBAAkB;QAChD,MAAMY,QAAQD,WAAWE,IAAI,CAAC,CAACC,MAAQA,IAAIlE,IAAI,KAAKuB;QACpD,OAAOyC,OAAOjC,UAAU,EAAE;IAC5B;IAEA;;GAEC,GACD,MAAMoC,UAAyB;QAC7B,IAAI,CAACpF,YAAY,GAAG,GAAG,eAAe;QACtC,MAAM,IAAI,CAAC2B,UAAU;IACvB;AACF;AAEA,qBAAqB;AACrB,OAAO,MAAM0D,cAAc,IAAIzF,cAAc;AAE7C,wBAAwB;AACxB,OAAO,MAAM8D,yBAAyB,IAAM2B,YAAY3B,sBAAsB,GAAG;AACjF,OAAO,MAAMQ,WAAW,CAACjD,OAAiBoE,YAAYnB,QAAQ,CAACjD,MAAM;AACrE,OAAO,MAAMkD,eAAe,IAAMkB,YAAYlB,YAAY,GAAG;AAC7D,OAAO,MAAME,qBAAqB,IAAMgB,YAAYhB,kBAAkB,GAAG;AACzE,OAAO,MAAMC,eAAe,CAACC,QAAkBc,YAAYf,YAAY,CAACC,OAAO;AAC/E,OAAO,MAAMO,mBAAmB,CAAC7D,OAAiBoE,YAAYP,gBAAgB,CAAC7D,MAAM;AACrF,OAAO,MAAM8D,sBAAsB,CAACvC,WAAqB6C,YAAYN,mBAAmB,CAACvC,UAAU;AACnG,OAAO,MAAM8C,gBAAgB,IAAMD,YAAYD,OAAO,GAAG;AAEzD,kCAAkC;AAClC,SAAS1F,sBAAsB,EAAER,oBAAoB,GAAG"}