Skip to content
Shell

Update README with comprehensive documentation

eddiebe147901f2f95ebc8
diff --git a/README.md b/README.md
index 8f13612..195a5f4 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,374 @@
-# Claude Code Settings
+# Claude Code Settings - ID8Labs
-This repository contains my personal Claude Code configuration, including:
+Personal Claude Code configuration for cross-machine sync and team sharing.
-- Custom agents
-- Slash commands
-- Hooks (automation)
-- MCP server configurations
-- Global project instructions (CLAUDE.md)
-- Skills
+## Quick Start
-## Syncing Across Machines
-
-### Initial Setup (New Machine)
+### New Machine Setup
```bash
cd ~
-git clone https://github.com/eddiebelaval/claude-code-settings .claude
+git clone https://github.com/eddiebe147/claude-settings.git .claude
```
-### Daily Workflow
-
-**When starting work:**
+### Sync Between Machines
```bash
-cd ~/.claude
-git pull
+# Pull latest
+cd ~/.claude && git pull
+
+# Push changes
+cd ~/.claude && git add . && git commit -m "update" && git push
+```
+
+---
+
+## What's Inside
+
+| Folder | Purpose | Count |
+|--------|---------|-------|
+| [`agents/`](#agents) | Specialized AI agents for specific domains | 38+ |
+| [`skills/`](#skills) | Reusable skill modules (slash commands) | 21 |
+| [`hooks/`](#hooks) | Automation scripts (pre/post actions) | 26 |
+| [`commands/`](#commands) | Quick slash commands | 21 |
+| [`plugins/`](#plugins) | Claude Code plugin configs | - |
+
+### Core Files
+
+| File | Purpose |
+|------|---------|
+| `CLAUDE.md` | Global instructions for ALL projects |
+| `settings.json` | Claude Code preferences |
+| `hooks.json` | Hook configurations |
+| `mcpServers.json` | MCP server connections |
+
+---
+
+## Agents
+
+Specialized AI agents in `agents/` folder. Each handles a specific domain.
+
+### Development Agents
+
+| Agent | Description |
+|-------|-------------|
+| `nextjs-senior-dev.md` | Next.js 14+ App Router expert |
+| `backend-architect.md` | Backend system architecture |
+| `database-migration-specialist.md` | Database schema migrations |
+
+### MCP Ecosystem Agents
+
+| Agent | Description |
+|-------|-------------|
+| `mcp-server-architect.md` | Design MCP servers |
+| `mcp-protocol-specialist.md` | Protocol compliance |
+| `mcp-integration-engineer.md` | Multi-server orchestration |
+| `mcp-deployment-orchestrator.md` | Production deployments |
+| `mcp-security-auditor.md` | Security reviews |
+| `mcp-testing-engineer.md` | Testing & QA |
+| `mcp-registry-navigator.md` | Registry discovery |
+
+### Business & Strategy Agents
+
+| Agent | Description |
+|-------|-------------|
+| `market-intelligence-analyst.md` | Market research & trends |
+| `steve-jobs-advisor.md` | Visionary product guidance |
+| `strategic-think-tank.md` | Major business decisions |
+| `operations-manager.md` | Project coordination |
+| `relationship-builder.md` | Client relationships |
+
+### Content & Marketing Agents
+
+| Agent | Description |
+|-------|-------------|
+| `social-media-manager.md` | Social content creation |
+| `x-viral-optimizer.md` | X/Twitter optimization |
+| `nana-image-generator.md` | AI image generation |
+| `notebooklm-producer.md` | Audio/video from docs |
+| `reality-tv-beat-writer.md` | Documentary production |
+
+### TMNT Dev Team (Fun Names!)
+
+| Agent | Role |
+|-------|------|
+| `leonardo-strategist-agent.md` | Strategy & planning |
+| `donatello-architect-agent.md` | Technical architecture |
+| `michelangelo-builder-agent.md` | Implementation |
+| `raphael-guardian-agent.md` | Security & protection |
+| `splinter-mentor-agent.md` | Mentorship |
+| `krang-brain-agent.md` | AI/ML expertise |
+| `bebop-devops-agent.md` | DevOps |
+| `rocksteady-database-agent.md` | Database |
+| `casey-tester-agent.md` | Testing |
+
+### Full Projects
+
+| Project | Description |
+|---------|-------------|
+| `reddit-research/` | Market research agent using Reddit's JSON API |
+
+---
+
+## Skills
+
+Reusable modules in `skills/` that extend Claude's capabilities.
+
+### Development Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `nextjs-project-manager` | Next.js 14+ project guidance |
+| `api-design` | RESTful API design |
+| `database-design` | Schema & Supabase |
+| `supabase-expert` | Supabase integration |
+| `testing-qa` | Test automation |
+| `performance-optimization` | Speed & Core Web Vitals |
+| `state-management` | React state (Zustand, Context) |
+| `ui-builder` | React + Tailwind + Shadcn |
+
+### Infrastructure Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `deployment-automation` | Vercel & CI/CD |
+| `file-uploads` | File handling & cloud storage |
+| `error-monitoring` | Logging & Sentry |
+| `real-time-features` | WebSockets & Supabase Realtime |
+| `mcp-builder` | Build MCP servers |
+
+### Business Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `llc-ops` | LLC operations for ID8Labs |
+| `analytics-tracking` | User analytics & A/B testing |
+| `email-notifications` | Transactional emails |
+
+---
+
+## Hooks
+
+Automation scripts in `hooks/` that run before/after actions.
+
+### Quality Gates
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `code-review-gate.sh` | Before PR | Code quality check |
+| `quality-gate-check.sh` | Before commit | Standards enforcement |
+| `pre-commit.sh` | Before commit | Pre-commit checks |
+| `post-commit.sh` | After commit | Post-commit actions |
+
+### Workflow Automation
+
+| Hook | Purpose |
+|------|---------|
+| `auto-commit.sh` | Automatic commits |
+| `auto-git-workflow.sh` | Git flow automation |
+| `auto-documentation.sh` | Doc generation |
+| `enforce-feature-branch.sh` | Branch protection |
+| `suggest-feature-branch.sh` | Branch suggestions |
+
+### Verification
+
+| Hook | Purpose |
+|------|---------|
+| `verify-after-edit.sh` | Verify edits worked |
+| `verify-after-write.sh` | Verify writes worked |
+| `verify-deployment.sh` | Check deployments |
+| `deployment-check.sh` | Pre-deploy validation |
+
+### Session Management
+
+| Hook | Purpose |
+|------|---------|
+| `session-persist.sh` | Save session state |
+| `session-recovery-check.sh` | Recover sessions |
+| `progress-report.sh` | Progress tracking |
+| `milestone-tracker.sh` | Milestone tracking |
+
+### Specialized
+
+| Hook | Purpose |
+|------|---------|
+| `browser-automation-check.sh` | Playwright/Comet checks |
+| `accessibility-check.sh` | A11y validation |
+| `performance-alert.sh` | Performance monitoring |
+
+---
+
+## Commands
+
+Quick slash commands in `commands/` for common actions.
+
+### Feature Development
+
+| Command | Purpose |
+|---------|---------|
+| `/start` | Begin new feature |
+| `/feature-dev` | Complete feature workshop |
+| `/ship` | Complete & create PR |
+| `/idea` | Brainstorm & plan |
+
+### Code Management
+
+| Command | Purpose |
+|---------|---------|
+| `/fix` | Debug & fix issues |
+| `/test` | Run Playwright tests |
+| `/cleanup` | Clean up project |
+| `/compare` | Compare changes |
+| `/preview` | Preview before commit |
+| `/rollback` | Undo changes |
+
+### Documentation
+
+| Command | Purpose |
+|---------|---------|
+| `/docs` | Generate documentation |
+| `/explain` | Explain in plain English |
+| `/status` | Project status report |
+
+### Session
+
+| Command | Purpose |
+|---------|---------|
+| `/save-state` | Save session checkpoint |
+| `/resume` | Resume from checkpoint |
+
+### Help
+
+| Command | Purpose |
+|---------|---------|
+| `/CHEATSHEET` | Quick reference |
+| `/COMMAND-MAP` | Visual command map |
+| `/GETTING-STARTED` | Getting started guide |
+| `/WHICH-COMMAND` | Find right command |
+
+---
+
+## Configuration Files
+
+### CLAUDE.md (Global Instructions)
+
+The `CLAUDE.md` file contains global instructions that apply to ALL projects:
+
+- **Agentic Patterns**: Reflection, PEV (Plan-Execute-Verify), Metacognitive
+- **ID8Pipeline**: 12-stage build process for all projects
+- **Auto-Approve Commands**: Commands that don't need confirmation
+- **Comet Browser Automation**: Playwright MCP integration
+
+### hooks.json
+
+Configures which hooks run and when:
+```json
+{
+ "hooks": [
+ { "event": "pre-commit", "script": "hooks/pre-commit.sh" },
+ { "event": "post-edit", "script": "hooks/verify-after-edit.sh" }
+ ]
+}
```
-**When switching machines:**
+### settings.json
+
+Claude Code preferences (theme, model defaults, etc.)
+
+---
+
+## Project: Reddit Research Agent
+
+Full market research agent at `agents/reddit-research/`:
+
```bash
-cd ~/.claude
-git add .
-git commit -m "update settings"
-git push
+cd ~/.claude/agents/reddit-research
+npm install
+npx tsx src/agent/index.ts help
+```
+
+**Features:**
+- Extracts pain points, opportunities, competitor mentions
+- Uses Reddit's hidden JSON API (add `/.json` to any URL)
+- Web dashboard at localhost:3456
+- Slack/Email alerts
+- Notion sync
+- Multi-agent parallel scanning
+
+---
+
+## File Structure
+
+```
+~/.claude/
+├── CLAUDE.md # Global instructions
+├── README.md # This file
+├── settings.json # Preferences
+├── hooks.json # Hook configs
+├── mcpServers.json # MCP servers
+│
+├── agents/ # 38+ specialized agents
+│ ├── *.md # Agent definitions
+│ └── reddit-research/ # Full project
+│
+├── skills/ # 21 skill modules
+│ ├── nextjs-project-manager/
+│ ├── supabase-expert/
+│ └── ...
+│
+├── hooks/ # 26 automation scripts
+│ ├── code-review-gate.sh
+│ ├── auto-commit.sh
+│ └── ...
+│
+├── commands/ # 21 slash commands
+│ ├── start.md
+│ ├── ship.md
+│ └── ...
+│
+└── plugins/ # Plugin configs
+ └── marketplaces/
```
-## What's Included
+---
+
+## Tips
-- `/agents/` - Custom AI agents
-- `/commands/` - Slash commands for quick actions
-- `/hooks/` - Automation scripts (pre/post actions)
-- `/skills/` - Reusable skill modules
-- `CLAUDE.md` - Global instructions for all projects
-- `settings.json` - Claude Code preferences
-- `.mcp.json` - MCP server configurations
+### Adding a New Agent
+1. Create `agents/my-agent.md`
+2. Define role, capabilities, and when to use
+3. Commit and push
-## Backup
+### Adding a New Skill
+1. Create `skills/my-skill/` directory
+2. Add skill definition files
+3. Register in manifest if needed
-A backup script is available at `~/Development/id8/backup-claude-settings.sh`
+### Adding a New Hook
+1. Create `hooks/my-hook.sh`
+2. Make executable: `chmod +x hooks/my-hook.sh`
+3. Register in `hooks.json`
-To create a backup:
+---
+
+## Sync Troubleshooting
+
+**Merge conflicts:**
```bash
-bash ~/Development/id8/backup-claude-settings.sh
+cd ~/.claude
+git stash
+git pull
+git stash pop
+# Resolve conflicts manually
```
+
+**Reset to remote:**
+```bash
+cd ~/.claude
+git fetch origin
+git reset --hard origin/main
+```
+
+---
+
+## License
+
+MIT - ID8Labs