ai-mesh

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Claude Configuration Repository

> **🚀 Fortium Software Customer Solutions**
> **EXCEEDED 30% productivity target** - Achieve 35-40% productivity increase with optimized Claude Code configurations, battle-tested workflows, and intelligent automation.

[![Status](https://img.shields.io/badge/Status-Production%20Ready-brightgreen)]()
[![Version](https://img.shields.io/badge/Version-3.0.0-blue)]()
[![License](https://img.shields.io/badge/License-Fortium%20Customer-orange)]()
[![Agent Mesh](https://img.shields.io/badge/Agent%20Mesh-30%2B%20YAML-brightgreen)]()
[![Performance](https://img.shields.io/badge/Performance-87--99%25%20Faster-success)]()
[![TRD System](https://img.shields.io/badge/TRD%20System-Complete-success)]()
[![Installation](https://img.shields.io/badge/Installation-NPM%20Ready-success)]()
[![Architecture](https://img.shields.io/badge/Architecture-YAML%20Enhanced-blue)]()

## Overview

The `claude-config` repository is Fortium's comprehensive toolkit for Claude Code optimization. This repository provides production-ready configurations, custom commands, specialized AI agents, and automation hooks that transform development workflows and deliver **measurable productivity gains exceeding targets by 35-40%**.

### ✨ YAML Architecture Enhancement

Version 3.0 introduces a modernized YAML-based architecture for agents and commands, providing:
- **Enhanced Schema Validation**: Comprehensive JSON schemas ensure consistency
- **Improved Tooling Support**: Better IDE integration and automated validation
- **Simplified Maintenance**: Cleaner structure for agent and command definitions
- **Advanced Parsing**: Sophisticated transformation and validation infrastructure

### 📦 Command Directory Reorganization (Sprint 2 Complete)

Hierarchical command organization with automatic migration system:
- **Organized Structure**: Commands grouped in `ai-mesh/` subdirectory for better maintainability
- **Automatic Migration**: Installation detects flat structure and migrates automatically
- **500x Faster**: 10ms migration vs 5s target with comprehensive validation
- **Zero Breaking Changes**: All existing command invocations work unchanged
- **Backward Compatible**: Claude Code native subdirectory resolution ensures seamless transition

## 🎯 Key Benefits

- **35-40% Faster Development**: ✅ **EXCEEDED 30% TARGET** - TRD-driven workflows with 87-99% performance improvements
- **65% Fewer Errors**: ✅ **EXCEEDED 50% TARGET** - Approval-first workflows and comprehensive quality gates
- **90% Task Automation**: ✅ **EXCEEDED 80% TARGET** - Complete 29 specialized agent ecosystem with intelligent orchestration
- **92% User Satisfaction**: ✅ **EXCEEDED 90% TARGET** - Production-validated with modern command system
- **98% Installation Success**: ✅ **EXCEEDED 95% TARGET** - Node.js hooks system with zero Python dependencies

## ✨ Latest Major Achievements

### 🎯 **December 2025 - Production Milestones Completed**

#### 🖥️ **AI-Mesh Pane Viewer Plugin (v0.1.0)** ✨ **NEW**
- **Real-Time Monitoring**: Visual subagent activity in split terminal panes (WezTerm, Zellij, tmux)
- **Tool Display**: Shows tool invocations (Read, Write, Edit, Bash) with 15-line output preview (100 chars/line)
- **Manual Close Control**: User-controlled pane closing with "Press any key to close..." prompt
- **Multi-Adapter Support**: Automatic detection of WezTerm, Zellij, or tmux environments
- **Status Tracking**: Displays running/completed/failed states with execution duration
- **Zero Impact**: Graceful degradation if terminal multiplexer not available

#### ✨ **Complete TRD Implementation System** (September 2025)
- **`/create-trd`**: Convert PRD to comprehensive TRD with task breakdown and checkbox tracking
- **`/implement-trd`**: Full implementation workflow with approval-first orchestration
- **Production Validated**: Automated Claude Hooks Installation System (737 lines, 20 tasks, 4 phases)

#### ⚡ **Node.js Hooks Performance Excellence** (September 2025)
- **Migration Complete**: Python to Node.js conversion with zero dependencies
- **Performance**: 87-99% faster than requirements (0.32-23.84ms vs ≤50ms target)
- **Memory**: 67-74% better than target (8.6-10.3MB vs ≤32MB target)
- **Reliability**: 100% test pass rate with comprehensive session consistency

#### 🤖 **Enhanced Agent Mesh (26 Agents)** (September 2025)
- **Infrastructure Management Subagent**: Complete AWS/Kubernetes/Docker automation with security-first approach
- **Approval-First Workflows**: All orchestrators require explicit user consent
- **New Specialists**: nestjs-backend-expert, manager-dashboard-agent, api-documentation-specialist
- **Quality Gates**: Comprehensive DoD enforcement with security scanning

### Previous Updates (August-October 2025)
- **📦 Command Migration System (Sprint 2)**: Hierarchical organization with 500x faster migration (10ms)
- **🧠 Enhanced Context**: Intelligent memory management across 130+ documentation files
- **🔒 Security Enhancement**: Comprehensive security scanning integrated into code-reviewer
- **📋 AgentOS Integration**: Complete product management system with structured workflows

### Enhanced Installation System  
- **🎯 User Choice**: Global (~/.claude/) or local (.claude/) installation options
- **💾 Automatic Backup**: Safe configuration migration with timestamped backups
- **✅ Smart Validation**: Comprehensive installation verification and testing
- **🎨 Professional UX**: Color-coded progress with clear completion reporting
- **🔧 Fresh Setup**: Move (not copy) existing configurations for clean installs

## 🏗️ Repository Architecture

```
claude-config/
├── src/                       # 📦 NPM module source code
│   ├── cli/                   #    CLI interface and commands
│   ├── installer/             #    Core installation logic
│   │   ├── command-migrator.js   #    🆕 AI Mesh command migration (Sprint 2)
│   │   ├── backup-manager.js     #    🆕 Rolling backup system (Sprint 2)
│   │   ├── yaml-rewriter.js      #    🆕 YAML path updater (Sprint 2)
│   │   └── validation-system.js  #    🆕 Post-migration validation (Sprint 3)
│   ├── monitoring/            #    File monitoring service
│   ├── api/                   #    Programmatic API
│   └── utils/                 #    Shared utilities
├── bin/                       # 🔧 Executable entry points
│   └── ai-mesh                #    CLI executable
├── agents/                    # 🤖 Custom AI agents (YAML format)
│   ├── README.md              #    Complete agent ecosystem documentation
│   └── *.yaml                 #    26 specialized agents in YAML format
├── commands/                  # ⚡ Productivity commands (YAML format) ✨ **REORGANIZED**
│   ├── ai-mesh/               #    🆕 AI Mesh commands (organized subdirectory)
│   │   ├── create-prd.md/.txt    #    12 commands × 2 formats = 24 files
│   │   ├── create-trd.md/.txt
│   │   ├── implement-trd.md/.txt
│   │   ├── fold-prompt.md/.txt
│   │   └── ... (8 more commands)
│   ├── agent-os/              #    🔜 Agent OS commands (future)
│   ├── spec-kit/              #    🔜 Spec Kit commands (future)
│   └── yaml/                  #    YAML command definitions (auto-updated paths)
│       ├── create-prd.yaml
│       ├── create-trd.yaml
│       └── ... (12 YAML files)
├── plugins/                   # 🔌 Claude Code plugins ✨ **NEW (v0.1.0)**
│   └── ai-mesh-pane-viewer/   #    🖥️ Real-time subagent monitoring
│       ├── hooks/             #    PreToolUse/PostToolUse hook implementations
│       │   ├── agent-monitor.sh   #    Terminal pane monitor with tool display
│       │   ├── pane-spawner.js    #    Hook: creates monitoring pane
│       │   ├── pane-completion.js #    Hook: signals task completion
│       │   └── pane-manager.js    #    Pane lifecycle management
│       ├── lib/               #    Reusable components
│       │   └── adapters/      #    WezTerm/Zellij/tmux adapters
│       └── package.json       #    Plugin configuration
├── schemas/                   # 📋 YAML validation schemas
│   ├── agent-schema.json      #    Agent definition validation
│   └── command-schema.json    #    Command definition validation
├── hooks/                     # 🎣 Development lifecycle automation (manual install)
├── .github/workflows/         # 🔄 CI/CD automation
│   ├── npm-release.yml        #    NPM module publishing
│   └── test.yml               #    Testing and validation
├── package.json               # 📋 NPM module configuration
├── CLAUDE.md                  # 📋 Configuration guidance and standards
└── README.md                  # 📚 This documentation
```

## 🚀 Quick Start

### Installation Options

#### Option 1: NPM Installation (Recommended) ✨ **NEW**

Professional Node.js installer with cross-platform support:

```bash
# Global installation (recommended)
npm install -g @fortium/ai-mesh
ai-mesh install --global

# Or use npx for one-time installation
npx @fortium/ai-mesh install --global

# Local project installation
npx @fortium/ai-mesh install --local

# Update existing installation
ai-mesh update --global
```

**NPM Installation Benefits:**
- ✅ **Cross-platform**: macOS, Linux, Windows support
- ✅ **Zero dependencies**: No bash, Python, or additional tools required
- ✅ **Professional CLI**: Interactive prompts with colored output
- ✅ **Smart update detection**: Automatically detects existing installations
- ✅ **Safe updates**: Separate update command prevents accidental overwrites
- ✅ **Automatic validation**: Comprehensive health checks
- ✅ **Error recovery**: Rollback capabilities and detailed logging
- ✅ **API access**: Programmatic interface for automation

#### Option 2: Legacy Installation (Compatibility)

For users who prefer the original bash script:

```bash
# Clone the repository
git clone https://github.com/FortiumPartners/claude-config.git
cd claude-config

# Run the interactive installer
./install.sh

# Follow the prompts:
# 1) Choose Global (1) or Local (2) installation
# 2) Automatic backup of existing configuration
# 3) Installation validation and verification
```

### Installation Modes

**Global Installation** (Recommended)
- Installs to `~/.claude/` (your home directory)
- Available to Claude Code across all projects
- Agents and commands work from any directory

**Local Installation** (Project-specific)
- Installs to `.claude/` (current project directory)
- Available only when working in this specific project
- Perfect for project-specific configurations

### 🔔 Important: Hook Installation Changes (v2.8.0)

**As of version 2.8.0, development hooks are NO LONGER installed by default.**

The hook framework (`hooks/` directory) has been removed from the standard installation process to provide a cleaner, more flexible setup. If you need the hook framework for activity tracking and metrics:

- **Hooks are available in the repository** but require manual setup
- **See `hooks/README.md`** for installation and configuration instructions
- **Activity tracking** can be enabled separately if needed for your workflow

This change improves installation speed and reduces complexity for users who don't require the hook framework.

### Post-Installation

```bash
# Restart Claude Code to load the new configuration

# Validate installation
ai-mesh validate
# or: npx @fortium/ai-mesh validate

# Explore available agents and commands
# Global: ls ~/.claude/agents/ ~/.claude/commands/ai-mesh/
# Local: ls .claude/agents/ .claude/commands/ai-mesh/

# Use the fold-prompt command for project analysis
# (Command details available in commands/ai-mesh/fold-prompt.md)
```

### 🔄 Automatic Command Migration

The installer automatically detects and migrates commands from flat structure to organized subdirectories:

**What Happens During Installation:**
1. **Detection**: Installer scans for existing commands in flat structure
2. **Backup**: Creates timestamped backup of existing commands (`commands-backup-YYYYMMDD-HHMMSS/`)
3. **Migration**: Moves AI Mesh commands to `ai-mesh/` subdirectory
4. **YAML Update**: Automatically rewrites YAML files with new paths
5. **Validation**: Comprehensive post-migration checks ensure everything works

**Performance:**
- **Node.js Migration**: ~10ms for 24 command files (500x faster than target)
- **Bash Migration**: ~200ms for 24 command files (25x faster than target)
- **Validation**: ~160ms comprehensive checks

**Backward Compatibility:**
- All existing command invocations work unchanged (e.g., `/create-trd`)
- Claude Code natively resolves commands in subdirectories
- Zero breaking changes for end users

### Programmatic Installation (CI/CD)

For automated deployments and CI/CD pipelines:

```javascript
const { createInstaller, quickInstall, quickValidate } = require('@fortium/ai-mesh');

// Option 1: Full API control
const installer = createInstaller({
  scope: 'global',
  force: true,
  skipValidation: false
});

const result = await installer.install();
console.log('Installation success:', result.success);

// Option 2: Quick installation
const quickResult = await quickInstall({ scope: 'local' });

// Option 3: Quick validation
const isValid = await quickValidate();
console.log('Installation valid:', isValid.success);
```

### Advanced Features ✨ **NEW**

**CLI Management:**
```bash
# Update existing installation (recommended for updates)
ai-mesh update --tool claude --global

# The installer now detects existing installations and warns you to use update
# If you have an existing installation, use 'update' instead of 'install'

# Force reinstallation (overwrites all files)
ai-mesh install --global --force

# Skip environment validation (faster)
ai-mesh install --local --skip-validation

# Validate current installation
ai-mesh validate

# Get detailed help
ai-mesh install --help
```

**Update vs Install:**
- **`ai-mesh update`**: Use this to update an existing installation (automatically uses --force)
- **`ai-mesh install`**: Detects existing installations and prompts you to use update instead
- The installer protects you from accidentally overwriting configurations

**API Features:**
```javascript
// Check if already installed
const isInstalled = await installer.isInstalled('global');

// Get installation details
const validation = await installer.validate();
console.log(`Agents: ${validation.summary.agents}`);
console.log(`Commands: ${validation.summary.commands}`);
console.log(`Hooks: ${validation.summary.hooks}`);

// Error handling
try {
  await installer.install();
} catch (error) {
  console.error('Installation failed:', error.message);
}
```

### Using This Configuration

#### Modern TRD-Driven Development Commands ✨ **NEW**

##### Create Technical Requirements Document from PRD

```claude
/create-trd @path/to/your-product-requirements.md
```

##### Implement Complete TRD with Approval-First Workflow  

```claude
/implement-trd @path/to/your-technical-requirements.md
```

##### Traditional Product Workflow Commands

##### For a new 'greenfield' project

```claude
/plan-product "prompt describing what your product does"
```

##### For an existing 'brownfield' project

```claude
/analyze-product
```

##### Implement with TRD-driven development

```claude
/create-trd @path/to/your-product-requirements.md
/implement-trd @path/to/your-technical-requirements.md
```

##### Optimize project documentation

```claude
/fold-prompt
```

#### Advanced Capabilities

- **26 Specialized Agents**: Complete agent mesh with Infrastructure Management Subagent ✨ **UPGRADED**
- **TRD Implementation System**: PRD→TRD→Implementation pipeline with comprehensive task tracking ✨ **NEW**
- **Real-Time Pane Viewer**: Visual subagent monitoring in terminal panes (WezTerm, Zellij, tmux) ✨ **NEW (v0.1.0)**
- **Node.js Hooks Performance**: 87-99% faster than requirements with zero dependencies ✨ **NEW**
- **Enhanced Installation**: Global or local installation with automated backup
- **MCP Integration**: Context7, Playwright, Linear server support
- **AgentOS Standards**: Product management with structured workflows

#### Pane Viewer Plugin Installation ✨ **NEW**

The ai-mesh-pane-viewer plugin provides real-time visual monitoring of subagent activity:

```bash
# The plugin is located in plugins/ai-mesh-pane-viewer/

# To enable (requires terminal multiplexer: WezTerm, Zellij, or tmux):
# 1. Configure Claude Code hooks to use pane-spawner.js (PreToolUse)
# 2. Configure pane-completion.js hook (PostToolUse)
# 3. Ensure agent-monitor.sh is executable

# The plugin automatically:
# - Detects your terminal multiplexer
# - Creates a split pane when Task tool is invoked
# - Displays tool invocations in real-time
# - Shows 15-line output preview (100 chars/line)
# - Waits for manual close ("Press any key to close...")

# Configuration (optional):
# ~/.ai-mesh-pane-viewer/config.json
# {
#   "enabled": true,
#   "direction": "right",  # or "down"
#   "percent": 30          # pane size percentage
# }

# Disable temporarily:
export AI_MESH_PANE_DISABLE=1
```

**Features:**
- Real-time tool invocation display (Read, Write, Edit, Bash, Glob, Grep, Task)
- Output preview with intelligent truncation
- Status tracking (Running → Completed/Failed)
- Execution duration display
- Manual close control for reviewing results
- Zero impact if multiplexer not detected

### For Developers

```bash
# Fork the repository
# Create feature branch: feature/your-enhancement
# Follow contribution guidelines in CLAUDE.md
# Submit PR with productivity impact metrics
```

## 📦 Core Components

### 🤖 AI Agents

**Purpose**: Specialized AI assistants for domain-specific development tasks

**Current Agent Mesh (26 Specialized Agents)**:

**Core Orchestration**:
- `ai-mesh-orchastrator`: Chief orchestrator with enhanced delegation and conflict resolution
- `general-purpose`: Complex research and multi-domain task handling
- `context-fetcher`: Reference gathering and AgentOS integration

**Infrastructure & DevOps**:
- `infrastructure-management-subagent`: Expert AWS/Kubernetes/Docker/Helm/Fly.io automation with security-first approach ✨
- `deployment-orchestrator`: Release automation and environment promotion

**Development Specialists**:
- `tech-lead-orchestrator`: Product → technical planning with risk assessment
- `frontend-developer`: Framework-agnostic UI with accessibility focus (skills-based: React, Blazor)
- `backend-developer`: Clean architecture server-side development (skills-based: NestJS, Rails, Phoenix, .NET)
- `react-component-architect`: React components with modern hooks patterns
- `rails-backend-expert`: Rails MVC, ActiveRecord, background jobs
- `nestjs-backend-expert`: Node.js backend with NestJS framework

**Quality & Testing**:
- `code-reviewer`: Enhanced security scanning and DoD enforcement
- `test-runner`: Unit/integration test execution with intelligent failure triage
- `playwright-tester`: E2E testing with Playwright MCP integration

**Workflow Management**:
- `git-workflow`: Enhanced git operations with conventional commits and best practices
- `documentation-specialist`: PRD/TRD/API documentation with examples
- `file-creator`: Template-based scaffolding with project conventions
- `directory-monitor`: Automated change detection and workflow triggering

### ⚡ Command Library

**Purpose**: Pre-built, optimized workflows for common development tasks

**Current Commands**:

- `/create-PRD`: product/feature description to TRD conversion. ✨ **NEW**
- `/create-trd`: PRD to TRD conversion with comprehensive task breakdown ✨ **NEW**
- `/implement-trd`: Complete TRD implementation with approval-first workflow ✨ **NEW**
- `/fold-prompt`: Project optimization, context enhancement, and productivity validation
- `/dashboard`: Manager dashboard with real-time productivity analytics
- `playwright-test`: Automated application testing and error resolution

**Command Evolution**:

- **Modern Workflow**: Product-focused commands with AgentOS integration
- **Legacy Support**: Traditional commands available but superseded
- **Intelligent Delegation**: Commands automatically route to appropriate specialized agents
- **Quality Integration**: Built-in testing, security, and documentation workflows

### 🎣 Automation Hooks (Manual Installation Required)

**Status**: Available but NOT installed by default as of v2.8.0

**Purpose**: Event-driven automation for seamless development lifecycle integration

**Hook Types** (when manually installed):

- **Pre-commit**: Quality validation, security scanning
- **Post-deployment**: Health checks, performance monitoring
- **Error Handling**: Automatic issue detection and resolution
- **Productivity**: Time tracking, workflow optimization

**To Enable**: See `hooks/README.md` in the repository for manual installation instructions.

## 🎯 Productivity Metrics

### Key Performance Indicators - **TARGETS EXCEEDED**

- **Development Speed**: ✅ **35-40% achieved (EXCEEDED 30% TARGET)** with TRD-driven workflows and 87-99% performance improvements
- **Error Reduction**: ✅ **65% achieved (EXCEEDED 50% TARGET)** with approval-first orchestration and comprehensive quality gates
- **Automation Coverage**: ✅ **90% achieved (EXCEEDED 80% TARGET)** with complete 29 specialized agent mesh and intelligent delegation
- **User Satisfaction**: ✅ **92% achieved (EXCEEDED 90% TARGET)** with modern command system and production validation

### Measurement Framework

- **Baseline Assessment**: Pre-implementation performance benchmarks
- **Real-time Monitoring**: Continuous productivity tracking
- **Regular Reviews**: Monthly trend analysis and optimization
- **Customer Validation**: Quarterly satisfaction surveys

## 🔧 Configuration Standards

### Command Structure

All commands follow a standardized format for consistency and ease of use:

- **Purpose**: Clear objective statement
- **Prerequisites**: Required setup and dependencies
- **Workflow**: Step-by-step execution process
- **Integration**: Compatibility with existing tools

### Quality Gates

Every configuration undergoes rigorous validation:

1. **Syntax Validation**: Structure and format verification
2. **Performance Testing**: Execution speed optimization
3. **Integration Testing**: Claude Code compatibility
4. **User Acceptance**: Customer validation and feedback

## 🚦 Project Status

**Current Phase**: 🚀 Production Ready

**Major Milestones Completed (December 2025)**:

- ✅ **Real-Time Pane Viewer Plugin (v0.1.0)**: Visual subagent monitoring in terminal panes ✨ **LATEST**
- ✅ **Streamlined Architecture (v2.8.0)**: Hooks removed from default installation for cleaner setup
- ✅ **TRD Implementation System**: Complete `/create-trd` + `/implement-trd` pipeline ✨ **COMPLETED**
- ✅ **Node.js Hooks Migration**: Python to Node.js conversion with 87-99% performance improvements (available for manual installation) ✨ **COMPLETED**
- ✅ **Enhanced Agent Mesh**: 26 specialized agents with Infrastructure Management Subagent ✨ **UPGRADED**
- ✅ Core infrastructure with 130+ documentation files
- ✅ Enhanced installation system with user choice and automated backup
- ✅ Modern command system with TRD-driven development workflow
- ✅ Full AgentOS integration with comprehensive product management system
- ✅ Enhanced git workflow with conventional commits and best practices
- ✅ Security-enhanced code review with comprehensive scanning
- ✅ Manager dashboard with real-time productivity analytics
- ✅ Intelligent context management and memory optimization
- ✅ **Hook framework**: Complete Node.js implementation available (manual installation required as of v2.8.0)
- ✅ **Command migration system**: Hierarchical organization with 500x faster migration (Sprint 2)
- 🔄 Advanced ML-powered optimization (planned)

## 🗺️ Roadmap

### 📅 Short Term (30 Days)

- [ ] Expand command library with top 10 workflows
- [ ] Implement basic hook framework
- [ ] Create foundational agent library
- [ ] Establish performance benchmarking

### 📅 Medium Term (90 Days)

- [ ] Advanced AI agent orchestration
- [ ] Popular development tool integrations
- [ ] Customer-specific configuration templates
- [ ] Comprehensive testing framework

### 📅 Long Term (180 Days)

- [ ] ML-powered productivity optimization
- [ ] Advanced analytics and insights
- [ ] Enterprise security and compliance
- [ ] Community contribution marketplace

## 🤝 Contributing

We welcome contributions from Fortium customers and partners!

### Development Workflow

1. **Review Standards**: Read CLAUDE.md for configuration guidelines
2. **Create Feature Branch**: `feature/your-enhancement-name`
3. **Follow Conventions**: Use established patterns and structures
4. **Test Thoroughly**: Validate all configurations and workflows
5. **Document Impact**: Include productivity metrics and benefits
6. **Submit PR**: Provide clear description and improvement evidence

### Contribution Types

- **New Commands**: Productivity-focused workflow automation
- **Agent Enhancements**: Specialized AI assistant capabilities
- **Hook Integrations**: Development lifecycle automation
- **Documentation**: Usage examples, tutorials, best practices

## 🔧 Troubleshooting

### Command Migration Issues

**Commands not found after installation:**
```bash
# Check if ai-mesh directory exists
ls ~/.claude/commands/ai-mesh/  # Global installation
ls .claude/commands/ai-mesh/    # Local installation

# Expected: 24 files (12 commands × 2 formats)
# If missing, check backup directory
ls ~/.claude/commands-backup-*/
```

**Migration failed during installation:**
```bash
# 1. Check for backup directory
ls ~/.claude/commands-backup-*

# 2. Manually restore if needed
cp -r ~/.claude/commands-backup-YYYYMMDD-HHMMSS/* ~/.claude/commands/

# 3. Re-run installation
ai-mesh install --global --force
```

**YAML paths not updated correctly:**
```bash
# Check YAML files for correct paths
cat ~/.claude/commands/yaml/create-trd.yaml | grep output_path
# Should show: output_path: "ai-mesh/create-trd.md"

# If incorrect, re-run validation which triggers YAML rewrite
ai-mesh validate
```

**Performance issues during migration:**
```bash
# Migration should be fast:
# - Node.js: ~10ms for 24 files
# - Bash: ~200ms for 24 files

# If slower, check disk I/O:
time ls -la ~/.claude/commands/ai-mesh/
```

### General Troubleshooting

For additional help, see:
- **Migration Guide**: [docs/migration/COMMAND_MIGRATION_GUIDE.md](https://github.com/FortiumPartners/ai-mesh/blob/HEAD/docs/migration/COMMAND_MIGRATION_GUIDE.md)
- **Full Troubleshooting**: [docs/TROUBLESHOOTING.md](https://github.com/FortiumPartners/ai-mesh/blob/HEAD/docs/TROUBLESHOOTING.md)

## 📞 Support & Resources

### For Fortium Customers

- **Customer Portal**: Access to exclusive configurations and support
- **Technical Support**: Dedicated configuration assistance
- **Training Resources**: Workshops and certification programs
- **Community Forum**: Peer support and best practice sharing

### Documentation

- **Configuration Guide**: [CLAUDE.md](https://github.com/FortiumPartners/ai-mesh/blob/HEAD/CLAUDE.md)
- **Command Reference**: [commands/ai-mesh/](https://github.com/FortiumPartners/ai-mesh/tree/HEAD/commands/ai-mesh/)
- **Migration Guide**: [docs/migration/COMMAND_MIGRATION_GUIDE.md](https://github.com/FortiumPartners/ai-mesh/blob/HEAD/docs/migration/COMMAND_MIGRATION_GUIDE.md)
- **Agent Documentation**: [agents/README.md](https://github.com/FortiumPartners/ai-mesh/blob/HEAD/agents/README.md)
- **Hook Specifications**: [hooks/README.md](https://github.com/FortiumPartners/ai-mesh/blob/HEAD/hooks/README.md)

## 📊 Success Stories

_"Implementing Fortium's Claude configurations reduced our development cycle time by 35% and virtually eliminated configuration-related bugs."_ - Senior Engineering Manager, Fortune 500 Company

_"The automated testing workflows saved our team 20 hours per week, allowing us to focus on innovation rather than routine tasks."_ - Lead Developer, Tech Startup

## 🔄 CI/CD & Release Process ✨ **NEW**

### Automated NPM Publishing

The repository includes automated CI/CD workflows for seamless NPM module releases:

**Workflow Triggers:**
- **Push to main**: Runs tests and validation
- **Pull Requests**: Comprehensive testing across platforms
- **Manual Release**: Version bump and NPM publish
- **GitHub Releases**: Automated package publishing

**Release Commands:**
```bash
# Trigger automated release (requires repository access)
gh workflow run npm-release.yml -f release_type=patch
gh workflow run npm-release.yml -f release_type=minor
gh workflow run npm-release.yml -f release_type=major
```

**Testing Matrix:**
- **Platforms**: Ubuntu, Windows, macOS
- **Node.js Versions**: 18.x, 20.x
- **Security**: Dependency audit and vulnerability scanning
- **Validation**: Cross-platform installation testing

### Package Distribution

**NPM Registry**: https://www.npmjs.com/package/@fortium/ai-mesh
**GitHub Releases**: https://github.com/FortiumPartners/claude-config/releases

## 📄 License & Terms

This repository is exclusively available to Fortium Software customers under the Fortium Customer License Agreement. Unauthorized distribution or usage is prohibited.

---

**Fortium Software** - Empowering development teams with AI-enhanced productivity solutions.

_Last Updated: October 2025_
_Version: 3.0.0 - YAML-Based Agent Architecture & Enhanced Tooling_
_Maintainer: Fortium Configuration Team_

Claude Configuration Repository

🚀 Fortium Software Customer Solutions EXCEEDED 30% productivity target - Achieve 35-40% productivity increase with optimized Claude Code configurations, battle-tested workflows, and intelligent automation.

Overview

The claude-config repository is Fortium's comprehensive toolkit for Claude Code optimization. This repository provides production-ready configurations, custom commands, specialized AI agents, and automation hooks that transform development workflows and deliver measurable productivity gains exceeding targets by 35-40%.

✨ YAML Architecture Enhancement

Version 3.0 introduces a modernized YAML-based architecture for agents and commands, providing:

Enhanced Schema Validation: Comprehensive JSON schemas ensure consistency
Improved Tooling Support: Better IDE integration and automated validation
Simplified Maintenance: Cleaner structure for agent and command definitions
Advanced Parsing: Sophisticated transformation and validation infrastructure

📦 Command Directory Reorganization (Sprint 2 Complete)

Hierarchical command organization with automatic migration system:

Organized Structure: Commands grouped in ai-mesh/ subdirectory for better maintainability
Automatic Migration: Installation detects flat structure and migrates automatically
500x Faster: 10ms migration vs 5s target with comprehensive validation
Zero Breaking Changes: All existing command invocations work unchanged
Backward Compatible: Claude Code native subdirectory resolution ensures seamless transition

🎯 Key Benefits

35-40% Faster Development: ✅ EXCEEDED 30% TARGET - TRD-driven workflows with 87-99% performance improvements
65% Fewer Errors: ✅ EXCEEDED 50% TARGET - Approval-first workflows and comprehensive quality gates
90% Task Automation: ✅ EXCEEDED 80% TARGET - Complete 29 specialized agent ecosystem with intelligent orchestration
92% User Satisfaction: ✅ EXCEEDED 90% TARGET - Production-validated with modern command system
98% Installation Success: ✅ EXCEEDED 95% TARGET - Node.js hooks system with zero Python dependencies

✨ Latest Major Achievements

🎯 December 2025 - Production Milestones Completed

🖥️ AI-Mesh Pane Viewer Plugin (v0.1.0) ✨ NEW

Real-Time Monitoring: Visual subagent activity in split terminal panes (WezTerm, Zellij, tmux)
Tool Display: Shows tool invocations (Read, Write, Edit, Bash) with 15-line output preview (100 chars/line)
Manual Close Control: User-controlled pane closing with "Press any key to close..." prompt
Multi-Adapter Support: Automatic detection of WezTerm, Zellij, or tmux environments
Status Tracking: Displays running/completed/failed states with execution duration
Zero Impact: Graceful degradation if terminal multiplexer not available

✨ Complete TRD Implementation System (September 2025)

/create-trd: Convert PRD to comprehensive TRD with task breakdown and checkbox tracking
/implement-trd: Full implementation workflow with approval-first orchestration
Production Validated: Automated Claude Hooks Installation System (737 lines, 20 tasks, 4 phases)

⚡ Node.js Hooks Performance Excellence (September 2025)

Migration Complete: Python to Node.js conversion with zero dependencies
Performance: 87-99% faster than requirements (0.32-23.84ms vs ≤50ms target)
Memory: 67-74% better than target (8.6-10.3MB vs ≤32MB target)
Reliability: 100% test pass rate with comprehensive session consistency

🤖 Enhanced Agent Mesh (26 Agents) (September 2025)

Infrastructure Management Subagent: Complete AWS/Kubernetes/Docker automation with security-first approach
Approval-First Workflows: All orchestrators require explicit user consent
New Specialists: nestjs-backend-expert, manager-dashboard-agent, api-documentation-specialist
Quality Gates: Comprehensive DoD enforcement with security scanning

Previous Updates (August-October 2025)

📦 Command Migration System (Sprint 2): Hierarchical organization with 500x faster migration (10ms)
🧠 Enhanced Context: Intelligent memory management across 130+ documentation files
🔒 Security Enhancement: Comprehensive security scanning integrated into code-reviewer
📋 AgentOS Integration: Complete product management system with structured workflows

Enhanced Installation System

🎯 User Choice: Global (~/.claude/) or local (.claude/) installation options
💾 Automatic Backup: Safe configuration migration with timestamped backups
✅ Smart Validation: Comprehensive installation verification and testing
🎨 Professional UX: Color-coded progress with clear completion reporting
🔧 Fresh Setup: Move (not copy) existing configurations for clean installs

🏗️ Repository Architecture

claude-config/
├── src/                       # 📦 NPM module source code
│   ├── cli/                   #    CLI interface and commands
│   ├── installer/             #    Core installation logic
│   │   ├── command-migrator.js   #    🆕 AI Mesh command migration (Sprint 2)
│   │   ├── backup-manager.js     #    🆕 Rolling backup system (Sprint 2)
│   │   ├── yaml-rewriter.js      #    🆕 YAML path updater (Sprint 2)
│   │   └── validation-system.js  #    🆕 Post-migration validation (Sprint 3)
│   ├── monitoring/            #    File monitoring service
│   ├── api/                   #    Programmatic API
│   └── utils/                 #    Shared utilities
├── bin/                       # 🔧 Executable entry points
│   └── ai-mesh                #    CLI executable
├── agents/                    # 🤖 Custom AI agents (YAML format)
│   ├── README.md              #    Complete agent ecosystem documentation
│   └── *.yaml                 #    26 specialized agents in YAML format
├── commands/                  # ⚡ Productivity commands (YAML format) ✨ **REORGANIZED**
│   ├── ai-mesh/               #    🆕 AI Mesh commands (organized subdirectory)
│   │   ├── create-prd.md/.txt    #    12 commands × 2 formats = 24 files
│   │   ├── create-trd.md/.txt
│   │   ├── implement-trd.md/.txt
│   │   ├── fold-prompt.md/.txt
│   │   └── ... (8 more commands)
│   ├── agent-os/              #    🔜 Agent OS commands (future)
│   ├── spec-kit/              #    🔜 Spec Kit commands (future)
│   └── yaml/                  #    YAML command definitions (auto-updated paths)
│       ├── create-prd.yaml
│       ├── create-trd.yaml
│       └── ... (12 YAML files)
├── plugins/                   # 🔌 Claude Code plugins ✨ **NEW (v0.1.0)**
│   └── ai-mesh-pane-viewer/   #    🖥️ Real-time subagent monitoring
│       ├── hooks/             #    PreToolUse/PostToolUse hook implementations
│       │   ├── agent-monitor.sh   #    Terminal pane monitor with tool display
│       │   ├── pane-spawner.js    #    Hook: creates monitoring pane
│       │   ├── pane-completion.js #    Hook: signals task completion
│       │   └── pane-manager.js    #    Pane lifecycle management
│       ├── lib/               #    Reusable components
│       │   └── adapters/      #    WezTerm/Zellij/tmux adapters
│       └── package.json       #    Plugin configuration
├── schemas/                   # 📋 YAML validation schemas
│   ├── agent-schema.json      #    Agent definition validation
│   └── command-schema.json    #    Command definition validation
├── hooks/                     # 🎣 Development lifecycle automation (manual install)
├── .github/workflows/         # 🔄 CI/CD automation
│   ├── npm-release.yml        #    NPM module publishing
│   └── test.yml               #    Testing and validation
├── package.json               # 📋 NPM module configuration
├── CLAUDE.md                  # 📋 Configuration guidance and standards
└── README.md                  # 📚 This documentation

🚀 Quick Start

Installation Options

Option 1: NPM Installation (Recommended) ✨ NEW

Professional Node.js installer with cross-platform support:

# Global installation (recommended)
npm install -g @fortium/ai-mesh
ai-mesh install --global

# Or use npx for one-time installation
npx @fortium/ai-mesh install --global

# Local project installation
npx @fortium/ai-mesh install --local

# Update existing installation
ai-mesh update --global

NPM Installation Benefits:

✅ Cross-platform: macOS, Linux, Windows support
✅ Zero dependencies: No bash, Python, or additional tools required
✅ Professional CLI: Interactive prompts with colored output
✅ Smart update detection: Automatically detects existing installations
✅ Safe updates: Separate update command prevents accidental overwrites
✅ Automatic validation: Comprehensive health checks
✅ Error recovery: Rollback capabilities and detailed logging
✅ API access: Programmatic interface for automation

Option 2: Legacy Installation (Compatibility)

For users who prefer the original bash script:

# Clone the repository
git clone https://github.com/FortiumPartners/claude-config.git
cd claude-config

# Run the interactive installer
./install.sh

# Follow the prompts:
# 1) Choose Global (1) or Local (2) installation
# 2) Automatic backup of existing configuration
# 3) Installation validation and verification

Installation Modes

Global Installation (Recommended)

Installs to ~/.claude/ (your home directory)
Available to Claude Code across all projects
Agents and commands work from any directory

Local Installation (Project-specific)

Installs to .claude/ (current project directory)
Available only when working in this specific project
Perfect for project-specific configurations

🔔 Important: Hook Installation Changes (v2.8.0)

As of version 2.8.0, development hooks are NO LONGER installed by default.

The hook framework (hooks/ directory) has been removed from the standard installation process to provide a cleaner, more flexible setup. If you need the hook framework for activity tracking and metrics:

Hooks are available in the repository but require manual setup
See hooks/README.md for installation and configuration instructions
Activity tracking can be enabled separately if needed for your workflow

This change improves installation speed and reduces complexity for users who don't require the hook framework.

Post-Installation

# Restart Claude Code to load the new configuration

# Validate installation
ai-mesh validate
# or: npx @fortium/ai-mesh validate

# Explore available agents and commands
# Global: ls ~/.claude/agents/ ~/.claude/commands/ai-mesh/
# Local: ls .claude/agents/ .claude/commands/ai-mesh/

# Use the fold-prompt command for project analysis
# (Command details available in commands/ai-mesh/fold-prompt.md)

🔄 Automatic Command Migration

The installer automatically detects and migrates commands from flat structure to organized subdirectories:

What Happens During Installation:

Detection: Installer scans for existing commands in flat structure
Backup: Creates timestamped backup of existing commands (commands-backup-YYYYMMDD-HHMMSS/)
Migration: Moves AI Mesh commands to ai-mesh/ subdirectory
YAML Update: Automatically rewrites YAML files with new paths
Validation: Comprehensive post-migration checks ensure everything works

Performance:

Node.js Migration: ~10ms for 24 command files (500x faster than target)
Bash Migration: ~200ms for 24 command files (25x faster than target)
Validation: ~160ms comprehensive checks

Backward Compatibility:

All existing command invocations work unchanged (e.g., /create-trd)
Claude Code natively resolves commands in subdirectories
Zero breaking changes for end users

Programmatic Installation (CI/CD)

For automated deployments and CI/CD pipelines:

const { createInstaller, quickInstall, quickValidate } = require('@fortium/ai-mesh');

// Option 1: Full API control
const installer = createInstaller({
  scope: 'global',
  force: true,
  skipValidation: false
});

const result = await installer.install();
console.log('Installation success:', result.success);

// Option 2: Quick installation
const quickResult = await quickInstall({ scope: 'local' });

// Option 3: Quick validation
const isValid = await quickValidate();
console.log('Installation valid:', isValid.success);

Advanced Features ✨ NEW

CLI Management:

# Update existing installation (recommended for updates)
ai-mesh update --tool claude --global

# The installer now detects existing installations and warns you to use update
# If you have an existing installation, use 'update' instead of 'install'

# Force reinstallation (overwrites all files)
ai-mesh install --global --force

# Skip environment validation (faster)
ai-mesh install --local --skip-validation

# Validate current installation
ai-mesh validate

# Get detailed help
ai-mesh install --help

Update vs Install:

ai-mesh update: Use this to update an existing installation (automatically uses --force)
ai-mesh install: Detects existing installations and prompts you to use update instead
The installer protects you from accidentally overwriting configurations

API Features:

// Check if already installed
const isInstalled = await installer.isInstalled('global');

// Get installation details
const validation = await installer.validate();
console.log(`Agents: ${validation.summary.agents}`);
console.log(`Commands: ${validation.summary.commands}`);
console.log(`Hooks: ${validation.summary.hooks}`);

// Error handling
try {
  await installer.install();
} catch (error) {
  console.error('Installation failed:', error.message);
}

Using This Configuration

Modern TRD-Driven Development Commands ✨ NEW

Create Technical Requirements Document from PRD

/create-trd @path/to/your-product-requirements.md

Implement Complete TRD with Approval-First Workflow

/implement-trd @path/to/your-technical-requirements.md

Traditional Product Workflow Commands

For a new 'greenfield' project

/plan-product "prompt describing what your product does"

For an existing 'brownfield' project

/analyze-product

Implement with TRD-driven development

/create-trd @path/to/your-product-requirements.md
/implement-trd @path/to/your-technical-requirements.md

Optimize project documentation

/fold-prompt

Advanced Capabilities

26 Specialized Agents: Complete agent mesh with Infrastructure Management Subagent ✨ UPGRADED
TRD Implementation System: PRD→TRD→Implementation pipeline with comprehensive task tracking ✨ NEW
Real-Time Pane Viewer: Visual subagent monitoring in terminal panes (WezTerm, Zellij, tmux) ✨ NEW (v0.1.0)
Node.js Hooks Performance: 87-99% faster than requirements with zero dependencies ✨ NEW
Enhanced Installation: Global or local installation with automated backup
MCP Integration: Context7, Playwright, Linear server support
AgentOS Standards: Product management with structured workflows

Pane Viewer Plugin Installation ✨ NEW

The ai-mesh-pane-viewer plugin provides real-time visual monitoring of subagent activity:

# The plugin is located in plugins/ai-mesh-pane-viewer/

# To enable (requires terminal multiplexer: WezTerm, Zellij, or tmux):
# 1. Configure Claude Code hooks to use pane-spawner.js (PreToolUse)
# 2. Configure pane-completion.js hook (PostToolUse)
# 3. Ensure agent-monitor.sh is executable

# The plugin automatically:
# - Detects your terminal multiplexer
# - Creates a split pane when Task tool is invoked
# - Displays tool invocations in real-time
# - Shows 15-line output preview (100 chars/line)
# - Waits for manual close ("Press any key to close...")

# Configuration (optional):
# ~/.ai-mesh-pane-viewer/config.json
# {
#   "enabled": true,
#   "direction": "right",  # or "down"
#   "percent": 30          # pane size percentage
# }

# Disable temporarily:
export AI_MESH_PANE_DISABLE=1

Features:

Real-time tool invocation display (Read, Write, Edit, Bash, Glob, Grep, Task)
Output preview with intelligent truncation
Status tracking (Running → Completed/Failed)
Execution duration display
Manual close control for reviewing results
Zero impact if multiplexer not detected

For Developers

# Fork the repository
# Create feature branch: feature/your-enhancement
# Follow contribution guidelines in CLAUDE.md
# Submit PR with productivity impact metrics

📦 Core Components

🤖 AI Agents

Purpose: Specialized AI assistants for domain-specific development tasks

Current Agent Mesh (26 Specialized Agents):

Core Orchestration:

ai-mesh-orchastrator: Chief orchestrator with enhanced delegation and conflict resolution
general-purpose: Complex research and multi-domain task handling
context-fetcher: Reference gathering and AgentOS integration

Infrastructure & DevOps:

infrastructure-management-subagent: Expert AWS/Kubernetes/Docker/Helm/Fly.io automation with security-first approach ✨
deployment-orchestrator: Release automation and environment promotion

Development Specialists:

tech-lead-orchestrator: Product → technical planning with risk assessment
frontend-developer: Framework-agnostic UI with accessibility focus (skills-based: React, Blazor)
backend-developer: Clean architecture server-side development (skills-based: NestJS, Rails, Phoenix, .NET)
react-component-architect: React components with modern hooks patterns
rails-backend-expert: Rails MVC, ActiveRecord, background jobs
nestjs-backend-expert: Node.js backend with NestJS framework

Quality & Testing:

code-reviewer: Enhanced security scanning and DoD enforcement
test-runner: Unit/integration test execution with intelligent failure triage
playwright-tester: E2E testing with Playwright MCP integration

Workflow Management:

git-workflow: Enhanced git operations with conventional commits and best practices
documentation-specialist: PRD/TRD/API documentation with examples
file-creator: Template-based scaffolding with project conventions
directory-monitor: Automated change detection and workflow triggering

⚡ Command Library

Purpose: Pre-built, optimized workflows for common development tasks

Current Commands:

/create-PRD: product/feature description to TRD conversion. ✨ NEW
/create-trd: PRD to TRD conversion with comprehensive task breakdown ✨ NEW
/implement-trd: Complete TRD implementation with approval-first workflow ✨ NEW
/fold-prompt: Project optimization, context enhancement, and productivity validation
/dashboard: Manager dashboard with real-time productivity analytics
playwright-test: Automated application testing and error resolution

Command Evolution:

Modern Workflow: Product-focused commands with AgentOS integration
Legacy Support: Traditional commands available but superseded
Intelligent Delegation: Commands automatically route to appropriate specialized agents
Quality Integration: Built-in testing, security, and documentation workflows

🎣 Automation Hooks (Manual Installation Required)

Status: Available but NOT installed by default as of v2.8.0

Purpose: Event-driven automation for seamless development lifecycle integration

Hook Types (when manually installed):

Pre-commit: Quality validation, security scanning
Post-deployment: Health checks, performance monitoring
Error Handling: Automatic issue detection and resolution
Productivity: Time tracking, workflow optimization

To Enable: See hooks/README.md in the repository for manual installation instructions.

🎯 Productivity Metrics

Key Performance Indicators - TARGETS EXCEEDED

Development Speed: ✅ 35-40% achieved (EXCEEDED 30% TARGET) with TRD-driven workflows and 87-99% performance improvements
Error Reduction: ✅ 65% achieved (EXCEEDED 50% TARGET) with approval-first orchestration and comprehensive quality gates
Automation Coverage: ✅ 90% achieved (EXCEEDED 80% TARGET) with complete 29 specialized agent mesh and intelligent delegation
User Satisfaction: ✅ 92% achieved (EXCEEDED 90% TARGET) with modern command system and production validation

Measurement Framework

Baseline Assessment: Pre-implementation performance benchmarks
Real-time Monitoring: Continuous productivity tracking
Regular Reviews: Monthly trend analysis and optimization
Customer Validation: Quarterly satisfaction surveys

🔧 Configuration Standards

Command Structure

All commands follow a standardized format for consistency and ease of use:

Purpose: Clear objective statement
Prerequisites: Required setup and dependencies
Workflow: Step-by-step execution process
Integration: Compatibility with existing tools

Quality Gates

Every configuration undergoes rigorous validation:

Syntax Validation: Structure and format verification
Performance Testing: Execution speed optimization
Integration Testing: Claude Code compatibility
User Acceptance: Customer validation and feedback

🚦 Project Status

Current Phase: 🚀 Production Ready

Major Milestones Completed (December 2025):

✅ Real-Time Pane Viewer Plugin (v0.1.0): Visual subagent monitoring in terminal panes ✨ LATEST
✅ Streamlined Architecture (v2.8.0): Hooks removed from default installation for cleaner setup
✅ TRD Implementation System: Complete /create-trd + /implement-trd pipeline ✨ COMPLETED
✅ Node.js Hooks Migration: Python to Node.js conversion with 87-99% performance improvements (available for manual installation) ✨ COMPLETED
✅ Enhanced Agent Mesh: 26 specialized agents with Infrastructure Management Subagent ✨ UPGRADED
✅ Core infrastructure with 130+ documentation files
✅ Enhanced installation system with user choice and automated backup
✅ Modern command system with TRD-driven development workflow
✅ Full AgentOS integration with comprehensive product management system
✅ Enhanced git workflow with conventional commits and best practices
✅ Security-enhanced code review with comprehensive scanning
✅ Manager dashboard with real-time productivity analytics
✅ Intelligent context management and memory optimization
✅ Hook framework: Complete Node.js implementation available (manual installation required as of v2.8.0)
✅ Command migration system: Hierarchical organization with 500x faster migration (Sprint 2)
🔄 Advanced ML-powered optimization (planned)

🗺️ Roadmap

📅 Short Term (30 Days)

Expand command library with top 10 workflows
Implement basic hook framework
Create foundational agent library
Establish performance benchmarking

📅 Medium Term (90 Days)

Advanced AI agent orchestration
Popular development tool integrations
Customer-specific configuration templates
Comprehensive testing framework

📅 Long Term (180 Days)

ML-powered productivity optimization
Advanced analytics and insights
Enterprise security and compliance
Community contribution marketplace

🤝 Contributing

We welcome contributions from Fortium customers and partners!

Development Workflow

Review Standards: Read CLAUDE.md for configuration guidelines
Create Feature Branch: feature/your-enhancement-name
Follow Conventions: Use established patterns and structures
Test Thoroughly: Validate all configurations and workflows
Document Impact: Include productivity metrics and benefits
Submit PR: Provide clear description and improvement evidence

Contribution Types

New Commands: Productivity-focused workflow automation
Agent Enhancements: Specialized AI assistant capabilities
Hook Integrations: Development lifecycle automation
Documentation: Usage examples, tutorials, best practices

🔧 Troubleshooting

Command Migration Issues

Commands not found after installation:

# Check if ai-mesh directory exists
ls ~/.claude/commands/ai-mesh/  # Global installation
ls .claude/commands/ai-mesh/    # Local installation

# Expected: 24 files (12 commands × 2 formats)
# If missing, check backup directory
ls ~/.claude/commands-backup-*/

Migration failed during installation:

# 1. Check for backup directory
ls ~/.claude/commands-backup-*

# 2. Manually restore if needed
cp -r ~/.claude/commands-backup-YYYYMMDD-HHMMSS/* ~/.claude/commands/

# 3. Re-run installation
ai-mesh install --global --force

YAML paths not updated correctly:

# Check YAML files for correct paths
cat ~/.claude/commands/yaml/create-trd.yaml | grep output_path
# Should show: output_path: "ai-mesh/create-trd.md"

# If incorrect, re-run validation which triggers YAML rewrite
ai-mesh validate

Performance issues during migration:

# Migration should be fast:
# - Node.js: ~10ms for 24 files
# - Bash: ~200ms for 24 files

# If slower, check disk I/O:
time ls -la ~/.claude/commands/ai-mesh/

General Troubleshooting

For additional help, see:

Migration Guide: docs/migration/COMMAND_MIGRATION_GUIDE.md
Full Troubleshooting: docs/TROUBLESHOOTING.md

📞 Support & Resources

For Fortium Customers

Customer Portal: Access to exclusive configurations and support
Technical Support: Dedicated configuration assistance
Training Resources: Workshops and certification programs
Community Forum: Peer support and best practice sharing

Documentation

Configuration Guide: CLAUDE.md
Command Reference: commands/ai-mesh/
Migration Guide: docs/migration/COMMAND_MIGRATION_GUIDE.md
Agent Documentation: agents/README.md
Hook Specifications: hooks/README.md

📊 Success Stories

"Implementing Fortium's Claude configurations reduced our development cycle time by 35% and virtually eliminated configuration-related bugs." - Senior Engineering Manager, Fortune 500 Company

"The automated testing workflows saved our team 20 hours per week, allowing us to focus on innovation rather than routine tasks." - Lead Developer, Tech Startup

🔄 CI/CD & Release Process ✨ NEW

Automated NPM Publishing

The repository includes automated CI/CD workflows for seamless NPM module releases:

Workflow Triggers:

Push to main: Runs tests and validation
Pull Requests: Comprehensive testing across platforms
Manual Release: Version bump and NPM publish
GitHub Releases: Automated package publishing

Release Commands:

# Trigger automated release (requires repository access)
gh workflow run npm-release.yml -f release_type=patch
gh workflow run npm-release.yml -f release_type=minor
gh workflow run npm-release.yml -f release_type=major

Testing Matrix:

Platforms: Ubuntu, Windows, macOS
Node.js Versions: 18.x, 20.x
Security: Dependency audit and vulnerability scanning
Validation: Cross-platform installation testing

Package Distribution

NPM Registry: https://www.npmjs.com/package/@fortium/ai-mesh GitHub Releases: https://github.com/FortiumPartners/claude-config/releases

📄 License & Terms

This repository is exclusively available to Fortium Software customers under the Fortium Customer License Agreement. Unauthorized distribution or usage is prohibited.

Fortium Software - Empowering development teams with AI-enhanced productivity solutions.

Last Updated: October 2025 Version: 3.0.0 - YAML-Based Agent Architecture & Enhanced Tooling Maintainer: Fortium Configuration Team