claudetools/README.md

# ClaudeTools

**Custom Claude Code behaviors and workflows for multi-mode operation.**

---

## Overview

ClaudeTools is a sophisticated system that extends Claude Code with specialized agents, workflows, and modes for different types of work:

- **MSP Mode** - Managed Service Provider client work tracking
- **Development Mode** - Software development project management
- **Normal Mode** - General research and experimentation

## Key Features

### Specialized Agents
- **Coding Agent** - Perfectionist programmer (no shortcuts, production-ready code)
- **Code Review Agent** - Quality gatekeeper (mandatory code review)
- **Database Agent** - Data custodian (all database operations)
- **Gitea Agent** - Version control custodian (commits, session logs)
- **Backup Agent** - Data protection (automated backups, disaster recovery)

### Workflows
- **Code Generation Workflow** - Coding Agent → Code Review Agent → User (mandatory review)
- **Task Management** - All work tracked in checklist with database persistence
- **File Organization** - Hybrid storage (database + filesystem + Git)
- **Backup Strategy** - Daily/weekly/monthly database backups with retention

### Storage Architecture
- **Database** - MariaDB on Jupiter (metadata, context, relationships)
- **Filesystem** - Organized by mode (clients/, projects/, normal/)
- **Gitea** - Version control for all file-based work
- **Backups** - Local database dumps with rotation

## Quick Start

### Prerequisites
- Claude Code CLI installed
- Git installed and configured
- Access to Jupiter server (172.16.3.20) for database
- SSH access to Gitea (git.azcomputerguru.com)

### Sync Settings from Gitea
```bash
# In D:\ClaudeTools directory
claude /sync
```

This pulls latest configuration, agents, and workflows from Gitea.

### Modes

**Enter MSP Mode:**
```
Claude, switch to MSP mode for [client-name]
```

**Enter Development Mode:**
```
Claude, switch to Development mode for [project-name]
```

**Return to Normal Mode:**
```
Claude, switch to Normal mode
```

## Directory Structure

```
D:\ClaudeTools\
├── .claude/                    # System configuration
│   ├── agents/                 # Agent definitions
│   │   ├── coding.md
│   │   ├── code-review.md
│   │   ├── database.md
│   │   ├── gitea.md
│   │   └── backup.md
│   ├── commands/               # Custom commands/skills
│   │   └── sync.md
│   ├── plans/                  # Plan mode outputs
│   ├── CODE_WORKFLOW.md        # Mandatory review workflow
│   ├── TASK_MANAGEMENT.md      # Task tracking system
│   ├── FILE_ORGANIZATION.md    # File organization strategy
│   └── MSP-MODE-SPEC.md        # Complete architecture spec
│
├── clients/                    # MSP Mode - Client work
│   └── [client-name]/
│       ├── configs/
│       ├── docs/
│       ├── scripts/
│       └── session-logs/
│
├── projects/                   # Development Mode - Projects
│   └── [project-name]/
│       ├── src/
│       ├── docs/
│       ├── tests/
│       └── session-logs/
│
├── normal/                     # Normal Mode - General work
│   ├── research/
│   ├── experiments/
│   └── notes/
│
└── backups/                    # Local backups (not in Git)
    ├── database/
    └── files/
```

## Database Schema

**36 tables total** - See `MSP-MODE-SPEC.md` for complete schema

**Core tables:**
- `machines` - User's machines and capabilities
- `clients` - MSP client information
- `projects` - Development projects
- `sessions` - Conversation sessions
- `tasks` - Checklist items with context
- `work_items` - Individual pieces of work
- `infrastructure` - Servers, devices, equipment
- `environmental_insights` - Learned constraints
- `failure_patterns` - Known failure patterns
- `backup_log` - Backup history

**Database:** MariaDB on Jupiter (172.16.3.20)

## Agent Workflows

### Code Implementation
```
User Request
    ↓
Coding Agent (generates production-ready code)
    ↓
Code Review Agent (mandatory review - minor fixes or rejection)
    ↓
┌─────────────┬──────────────┐
│ APPROVED ✅ │ REJECTED ❌  │
│ → User      │ → Coding Agent│
└─────────────┴──────────────┘
```

### Task Management
```
User Request → Tasks Created (Database Agent)
    ↓
Agents Execute → Progress Updates (Database Agent)
    ↓
Work Complete → Tasks Marked Done (Database Agent)
    ↓
Gitea Agent → Commits with context
    ↓
Backup Agent → Daily backup if needed
```

## Key Documents

- **MSP-MODE-SPEC.md** - Complete architecture specification
- **CODE_WORKFLOW.md** - Mandatory code review process
- **TASK_MANAGEMENT.md** - Task tracking and checklist system
- **FILE_ORGANIZATION.md** - Hybrid storage strategy

## Commands

### /sync
Pull latest configuration from Gitea repository
```bash
claude /sync
```

## Backup Strategy

- **Daily backups** - 7 days retention
- **Weekly backups** - 4 weeks retention
- **Monthly backups** - 12 months retention
- **Manual/pre-migration** - Keep indefinitely

**Backup location:** `D:\ClaudeTools\backups\database/`

## Git Repositories

**System repo:** `azcomputerguru/claudetools`
- Configuration, agents, workflows

**Client repos:** `azcomputerguru/claudetools-client-[name]`
- Per-client MSP work

**Project repos:** `azcomputerguru/[project-name]`
- Development projects

## Development Status

**Phase:** Architecture Complete, Implementation Pending
**Created:** 2026-01-15
**Status:** Foundation laid, ready for implementation

### Next Steps
1. Implement ClaudeTools API (Python FastAPI)
2. Create database on Jupiter
3. Build mode switching mechanism
4. Implement agent orchestration
5. Test workflows end-to-end

## Architecture Highlights

### Context Preservation
- Agents handle heavy processing (90-99% context saved)
- Main Claude orchestrates and communicates
- Database stores persistent context

### Quality Assurance
- No code bypasses review (zero exceptions)
- Production-ready code only
- Comprehensive error handling
- Security-first approach

### Data Safety
- Multiple backup layers
- Version control for all files
- Database backups with retention
- Disaster recovery procedures

## Contact

**System:** ClaudeTools
**Author:** Mike Swanson with Claude Sonnet 4.5
**Organization:** AZ Computer Guru
**Gitea:** https://git.azcomputerguru.com/azcomputerguru/claudetools

## License

Internal use only - AZ Computer Guru

---

**Built with Claude Sonnet 4.5 - January 2026**