Claude Repository Setup System

Core Philosophy

1. CLI-First: Always prefer CLI tools over MCP (more token-efficient)
2. Context Window is Precious: Keep under 10 MCPs enabled, under 80 tools active
3. Modular Configuration: Rules in .claude/rules/, not one mega CLAUDE.md
4. Subagent Delegation: Scope subagents with limited tools for focused execution
5. Progressive Automation: Hooks for formatting, linting, reminders

Mode Detection

1. Explicit mode: If the user specifies

   init

   or

   audit

   , use that mode
2. Auto-detect mode: Otherwise, analyze the current directory:
   • If

     .claude/

     directory exists OR

     CLAUDE.md

     exists → audit mode
   • If directory is empty or has minimal files (< 5 files) → init mode
   • If directory has code but no Claude config → audit mode (treat as existing project needing setup)

Mode Routing

Init Mode (New Repositories)

workflows/init-new-repo.md

1. Environment & Global Tools Check
2. Project Scaffolding
3. Tech Stack Interview
4. CLI Discovery & Authentication ⭐
5. MCP Configuration (Context Window Aware) ⭐
6. Plugin Setup
7. Skills Installation
8. Subagent Configuration
9. Rules Configuration
10. Hooks Configuration
11. CLAUDE.md Generation
12. Ralph TUI Setup
13. Verification & Summary

Audit Mode (Existing Repositories)

workflows/audit-existing-repo.md

1. Environment Analysis
2. CLI Audit ⭐
3. Context Window Analysis ⭐
4. Gap Analysis
5. Recommendations Report
6. Interactive Fixes
7. Context Window Optimization
8. Summary & Verification

Complete Ecosystem

~/.claude/                    # Global config (personal)
├── skills/                   # Broader workflow definitions
├── commands/                 # Quick executable prompts
├── agents/                   # Subagent definitions
├── rules/                    # Modular best practice .md files
├── settings.json             # Global hooks & permissions
└── CLAUDE.md                 # Global context

.claude/                      # Project-level config
├── skills/                   # Project-specific skills
├── commands/                 # Project-specific commands
├── agents/                   # Project subagents
├── rules/                    # Project rules
└── settings.json             # Project hooks

CLAUDE.md                     # Project context file (10 sections)
.mcp.json                     # MCP configuration
.ralph-tui/                   # Ralph TUI config

Component Reference

components/cli-discovery.md

components/mcp-management.md

components/plugin-setup.md

components/subagent-setup.md

components/rules-configuration.md

components/documentation-setup.md

components/tools-installation.md

components/skills-discovery.md

components/hooks-configuration.md

components/claudemd-writing.md

components/folder-structure.md

Reference Data

reference/tech-stack-clis.md

reference/mcp-servers.md

reference/essential-plugins.md

reference/subagent-templates.md

reference/hook-patterns.md

reference/mandatory-skills.md

reference/tech-stack-skills.md

reference/hook-templates.md

Templates

templates/ralph-tui/config.toml

templates/ralph-tui/prompt.hbs

templates/subagents/*.md

templates/rules/*.md

templates/claude-md/complete-template.md

Quick Start Examples

User: /setup-claude init
Claude: [Runs 13-phase init workflow]

User: /setup-claude audit
Claude: [Runs 8-phase audit workflow]

User: /setup-claude
Claude: [Detects mode based on directory contents]

Important Notes

• Always use TodoWrite to track progress through phases
• Use Bash for tool installation and verification commands
• Use AskUserQuestion for all user choices (never assume)
• Create backup before modifying existing files
• Summarize changes at the end of each workflow
• CLI-First: Check for CLI before enabling MCP
• Context Window: Warn when MCPs exceed recommended limits