enhance_swarm 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. checksums.yaml +7 -0
  2. data/.enhance_swarm/agent_scripts/frontend_agent.md +39 -0
  3. data/.enhance_swarm/user_patterns.json +37 -0
  4. data/CHANGELOG.md +184 -0
  5. data/LICENSE +21 -0
  6. data/PRODUCTION_TEST_LOG.md +502 -0
  7. data/README.md +905 -0
  8. data/Rakefile +28 -0
  9. data/USAGE_EXAMPLES.md +477 -0
  10. data/examples/enhance_workflow.md +346 -0
  11. data/examples/rails_project.md +253 -0
  12. data/exe/enhance-swarm +30 -0
  13. data/lib/enhance_swarm/additional_commands.rb +299 -0
  14. data/lib/enhance_swarm/agent_communicator.rb +460 -0
  15. data/lib/enhance_swarm/agent_reviewer.rb +283 -0
  16. data/lib/enhance_swarm/agent_spawner.rb +462 -0
  17. data/lib/enhance_swarm/cleanup_manager.rb +245 -0
  18. data/lib/enhance_swarm/cli.rb +1592 -0
  19. data/lib/enhance_swarm/command_executor.rb +78 -0
  20. data/lib/enhance_swarm/configuration.rb +324 -0
  21. data/lib/enhance_swarm/control_agent.rb +307 -0
  22. data/lib/enhance_swarm/dependency_validator.rb +195 -0
  23. data/lib/enhance_swarm/error_recovery.rb +785 -0
  24. data/lib/enhance_swarm/generator.rb +194 -0
  25. data/lib/enhance_swarm/interrupt_handler.rb +512 -0
  26. data/lib/enhance_swarm/logger.rb +106 -0
  27. data/lib/enhance_swarm/mcp_integration.rb +85 -0
  28. data/lib/enhance_swarm/monitor.rb +28 -0
  29. data/lib/enhance_swarm/notification_manager.rb +444 -0
  30. data/lib/enhance_swarm/orchestrator.rb +313 -0
  31. data/lib/enhance_swarm/output_streamer.rb +281 -0
  32. data/lib/enhance_swarm/process_monitor.rb +266 -0
  33. data/lib/enhance_swarm/progress_tracker.rb +215 -0
  34. data/lib/enhance_swarm/project_analyzer.rb +612 -0
  35. data/lib/enhance_swarm/resource_manager.rb +177 -0
  36. data/lib/enhance_swarm/retry_handler.rb +40 -0
  37. data/lib/enhance_swarm/session_manager.rb +247 -0
  38. data/lib/enhance_swarm/signal_handler.rb +95 -0
  39. data/lib/enhance_swarm/smart_defaults.rb +708 -0
  40. data/lib/enhance_swarm/task_integration.rb +150 -0
  41. data/lib/enhance_swarm/task_manager.rb +174 -0
  42. data/lib/enhance_swarm/version.rb +5 -0
  43. data/lib/enhance_swarm/visual_dashboard.rb +555 -0
  44. data/lib/enhance_swarm/web_ui.rb +211 -0
  45. data/lib/enhance_swarm.rb +69 -0
  46. data/setup.sh +86 -0
  47. data/sig/enhance_swarm.rbs +4 -0
  48. data/templates/claude/CLAUDE.md +160 -0
  49. data/templates/claude/MCP.md +117 -0
  50. data/templates/claude/PERSONAS.md +114 -0
  51. data/templates/claude/RULES.md +221 -0
  52. data/test_builtin_functionality.rb +121 -0
  53. data/test_core_components.rb +156 -0
  54. data/test_real_claude_integration.rb +285 -0
  55. data/test_security.rb +150 -0
  56. data/test_smart_defaults.rb +155 -0
  57. data/test_task_integration.rb +173 -0
  58. data/test_web_ui.rb +245 -0
  59. data/web/assets/css/main.css +645 -0
  60. data/web/assets/js/kanban.js +499 -0
  61. data/web/assets/js/main.js +525 -0
  62. data/web/templates/dashboard.html.erb +226 -0
  63. data/web/templates/kanban.html.erb +193 -0
  64. metadata +293 -0
@@ -0,0 +1,211 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'webrick'
4
+ require 'json'
5
+ require 'erb'
6
+ require_relative 'logger'
7
+ require_relative 'orchestrator'
8
+ require_relative 'process_monitor'
9
+
10
+ module EnhanceSwarm
11
+ class WebUI
12
+ attr_reader :server, :port
13
+
14
+ def initialize(port: 4567, host: 'localhost')
15
+ @port = port
16
+ @host = host
17
+ @orchestrator = Orchestrator.new
18
+ @process_monitor = ProcessMonitor.new
19
+ setup_server
20
+ end
21
+
22
+ def start
23
+ Logger.info("Starting EnhanceSwarm Web UI on http://#{@host}:#{@port}")
24
+ puts "🌐 EnhanceSwarm Web UI starting on http://#{@host}:#{@port}".colorize(:blue)
25
+ puts " 📋 Features: Task Management, Kanban Board, Agent Monitoring"
26
+ puts " 🚀 Open your browser to access the interface"
27
+ puts " ⏹️ Press Ctrl+C to stop the server"
28
+
29
+ trap 'INT' do
30
+ puts "\n👋 Shutting down EnhanceSwarm Web UI..."
31
+ @server.shutdown
32
+ end
33
+
34
+ @server.start
35
+ end
36
+
37
+ def stop
38
+ @server&.shutdown
39
+ end
40
+
41
+ private
42
+
43
+ def setup_server
44
+ @server = WEBrick::HTTPServer.new(
45
+ Port: @port,
46
+ Host: @host,
47
+ Logger: WEBrick::Log.new('/dev/null'),
48
+ AccessLog: []
49
+ )
50
+
51
+ # Static assets
52
+ @server.mount('/assets', WEBrick::HTTPServlet::FileHandler, assets_dir)
53
+
54
+ # API endpoints
55
+ setup_api_routes
56
+
57
+ # Main UI routes
58
+ setup_ui_routes
59
+ end
60
+
61
+ def setup_api_routes
62
+ # Status API
63
+ @server.mount_proc('/api/status') do |req, res|
64
+ res['Content-Type'] = 'application/json'
65
+ status_data = @process_monitor.status
66
+ res.body = JSON.pretty_generate(status_data)
67
+ end
68
+
69
+ # Task management API
70
+ @server.mount_proc('/api/tasks') do |req, res|
71
+ res['Content-Type'] = 'application/json'
72
+ task_data = @orchestrator.get_task_management_data
73
+ res.body = JSON.pretty_generate(task_data)
74
+ end
75
+
76
+ # Agent spawn API
77
+ @server.mount_proc('/api/agents/spawn') do |req, res|
78
+ res['Content-Type'] = 'application/json'
79
+
80
+ if req.request_method == 'POST'
81
+ begin
82
+ body = JSON.parse(req.body)
83
+ role = body['role'] || 'general'
84
+ task = body['task'] || 'General task'
85
+ worktree = body['worktree'] || true
86
+
87
+ result = @orchestrator.spawn_single(task: task, role: role, worktree: worktree)
88
+
89
+ if result
90
+ res.body = JSON.generate({ success: true, pid: result, message: "#{role.capitalize} agent spawned successfully" })
91
+ else
92
+ res.status = 400
93
+ res.body = JSON.generate({ success: false, message: "Failed to spawn #{role} agent" })
94
+ end
95
+ rescue JSON::ParserError
96
+ res.status = 400
97
+ res.body = JSON.generate({ success: false, message: 'Invalid JSON in request body' })
98
+ rescue StandardError => e
99
+ res.status = 500
100
+ res.body = JSON.generate({ success: false, message: e.message })
101
+ end
102
+ else
103
+ res.status = 405
104
+ res.body = JSON.generate({ success: false, message: 'Method not allowed' })
105
+ end
106
+ end
107
+
108
+ # Configuration API
109
+ @server.mount_proc('/api/config') do |req, res|
110
+ res['Content-Type'] = 'application/json'
111
+ config_data = EnhanceSwarm.configuration.to_h
112
+ res.body = JSON.pretty_generate(config_data)
113
+ end
114
+
115
+ # Project analysis API
116
+ @server.mount_proc('/api/project/analyze') do |req, res|
117
+ res['Content-Type'] = 'application/json'
118
+
119
+ begin
120
+ analyzer = ProjectAnalyzer.new
121
+ analysis = analyzer.analyze
122
+ smart_defaults = analyzer.generate_smart_defaults
123
+
124
+ res.body = JSON.pretty_generate({
125
+ analysis: analysis,
126
+ smart_defaults: smart_defaults
127
+ })
128
+ rescue StandardError => e
129
+ res.status = 500
130
+ res.body = JSON.generate({ error: e.message })
131
+ end
132
+ end
133
+ end
134
+
135
+ def setup_ui_routes
136
+ # Main dashboard
137
+ @server.mount_proc('/') do |req, res|
138
+ res['Content-Type'] = 'text/html'
139
+ res.body = render_template('dashboard')
140
+ end
141
+
142
+ # Kanban board
143
+ @server.mount_proc('/kanban') do |req, res|
144
+ res['Content-Type'] = 'text/html'
145
+ res.body = render_template('kanban')
146
+ end
147
+
148
+ # Agent monitoring
149
+ @server.mount_proc('/agents') do |req, res|
150
+ res['Content-Type'] = 'text/html'
151
+ res.body = render_template('agents')
152
+ end
153
+
154
+ # Project overview
155
+ @server.mount_proc('/project') do |req, res|
156
+ res['Content-Type'] = 'text/html'
157
+ res.body = render_template('project')
158
+ end
159
+
160
+ # Configuration
161
+ @server.mount_proc('/config') do |req, res|
162
+ res['Content-Type'] = 'text/html'
163
+ res.body = render_template('config')
164
+ end
165
+ end
166
+
167
+ def render_template(template_name)
168
+ template_path = File.join(templates_dir, "#{template_name}.html.erb")
169
+
170
+ unless File.exist?(template_path)
171
+ return error_template("Template not found: #{template_name}")
172
+ end
173
+
174
+ begin
175
+ template = ERB.new(File.read(template_path))
176
+ template.result(binding)
177
+ rescue StandardError => e
178
+ Logger.error("Template rendering error: #{e.message}")
179
+ error_template("Template error: #{e.message}")
180
+ end
181
+ end
182
+
183
+ def error_template(message)
184
+ <<~HTML
185
+ <!DOCTYPE html>
186
+ <html>
187
+ <head>
188
+ <title>EnhanceSwarm - Error</title>
189
+ <meta charset="utf-8">
190
+ <meta name="viewport" content="width=device-width, initial-scale=1">
191
+ </head>
192
+ <body style="font-family: -apple-system, sans-serif; padding: 2rem; background: #f5f5f5;">
193
+ <div style="max-width: 600px; margin: 0 auto; background: white; padding: 2rem; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1);">
194
+ <h1 style="color: #e74c3c; margin-top: 0;">⚠️ EnhanceSwarm Error</h1>
195
+ <p style="color: #666; font-size: 1.1rem;">#{message}</p>
196
+ <a href="/" style="display: inline-block; margin-top: 1rem; padding: 0.5rem 1rem; background: #3498db; color: white; text-decoration: none; border-radius: 4px;">← Back to Dashboard</a>
197
+ </div>
198
+ </body>
199
+ </html>
200
+ HTML
201
+ end
202
+
203
+ def templates_dir
204
+ File.join(File.dirname(__FILE__), '..', '..', 'web', 'templates')
205
+ end
206
+
207
+ def assets_dir
208
+ File.join(File.dirname(__FILE__), '..', '..', 'web', 'assets')
209
+ end
210
+ end
211
+ end
@@ -0,0 +1,69 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative 'enhance_swarm/version'
4
+ require_relative 'enhance_swarm/configuration'
5
+ require_relative 'enhance_swarm/command_executor'
6
+ require_relative 'enhance_swarm/retry_handler'
7
+ require_relative 'enhance_swarm/logger'
8
+ require_relative 'enhance_swarm/dependency_validator'
9
+ require_relative 'enhance_swarm/cleanup_manager'
10
+ require_relative 'enhance_swarm/signal_handler'
11
+ require_relative 'enhance_swarm/agent_reviewer'
12
+ require_relative 'enhance_swarm/progress_tracker'
13
+ require_relative 'enhance_swarm/output_streamer'
14
+ require_relative 'enhance_swarm/control_agent'
15
+ require_relative 'enhance_swarm/notification_manager'
16
+ require_relative 'enhance_swarm/interrupt_handler'
17
+ require_relative 'enhance_swarm/agent_communicator'
18
+ require_relative 'enhance_swarm/visual_dashboard'
19
+ require_relative 'enhance_swarm/smart_defaults'
20
+ require_relative 'enhance_swarm/error_recovery'
21
+ require_relative 'enhance_swarm/cli'
22
+ require_relative 'enhance_swarm/orchestrator'
23
+ require_relative 'enhance_swarm/monitor'
24
+ require_relative 'enhance_swarm/task_manager'
25
+ require_relative 'enhance_swarm/generator'
26
+ require_relative 'enhance_swarm/mcp_integration'
27
+
28
+ module EnhanceSwarm
29
+ class Error < StandardError; end
30
+ class ConfigurationError < Error; end
31
+ class CommandError < Error; end
32
+
33
+ class << self
34
+ def configure
35
+ yield(configuration)
36
+ rescue StandardError => e
37
+ raise ConfigurationError, "Configuration failed: #{e.message}"
38
+ end
39
+
40
+ def configuration
41
+ @configuration ||= Configuration.new
42
+ rescue StandardError => e
43
+ raise ConfigurationError, "Failed to initialize configuration: #{e.message}"
44
+ end
45
+
46
+ def root
47
+ @root ||= find_project_root
48
+ rescue StandardError => e
49
+ puts "Warning: Could not determine project root: #{e.message}"
50
+ Dir.pwd
51
+ end
52
+
53
+ def enhance!
54
+ Orchestrator.new.enhance
55
+ rescue StandardError => e
56
+ puts "Enhancement failed: #{e.message}".colorize(:red)
57
+ false
58
+ end
59
+
60
+ private
61
+
62
+ def find_project_root
63
+ current = Dir.pwd
64
+ current = File.dirname(current) while current != '/' && !File.exist?(File.join(current, '.enhance_swarm.yml'))
65
+
66
+ File.exist?(File.join(current, '.enhance_swarm.yml')) ? current : Dir.pwd
67
+ end
68
+ end
69
+ end
data/setup.sh ADDED
@@ -0,0 +1,86 @@
1
+ #!/bin/bash
2
+ set -e
3
+
4
+ # EnhanceSwarm Auto-Setup Script
5
+ # This script can be run directly from GitHub to set up EnhanceSwarm in any project
6
+
7
+ echo "🚀 EnhanceSwarm Auto-Setup"
8
+ echo "========================="
9
+
10
+ # Colors
11
+ GREEN='\033[0;32m'
12
+ YELLOW='\033[1;33m'
13
+ RED='\033[0;31m'
14
+ NC='\033[0m' # No Color
15
+
16
+ # Check dependencies
17
+ echo -e "\n${YELLOW}Checking dependencies...${NC}"
18
+
19
+ check_dependency() {
20
+ if command -v $1 &> /dev/null; then
21
+ echo -e " ✅ $1 found"
22
+ return 0
23
+ else
24
+ echo -e " ❌ $1 not found"
25
+ return 1
26
+ fi
27
+ }
28
+
29
+ MISSING_DEPS=0
30
+ check_dependency "ruby" || MISSING_DEPS=1
31
+ check_dependency "git" || MISSING_DEPS=1
32
+ check_dependency "bundle" || MISSING_DEPS=1
33
+
34
+ if [ $MISSING_DEPS -eq 1 ]; then
35
+ echo -e "\n${RED}Missing required dependencies. Please install them first.${NC}"
36
+ exit 1
37
+ fi
38
+
39
+ # Clone or update enhance_swarm
40
+ ENHANCE_DIR="$HOME/.enhance_swarm"
41
+
42
+ if [ -d "$ENHANCE_DIR" ]; then
43
+ echo -e "\n${YELLOW}Updating EnhanceSwarm...${NC}"
44
+ cd "$ENHANCE_DIR"
45
+ git pull origin main
46
+ else
47
+ echo -e "\n${YELLOW}Installing EnhanceSwarm...${NC}"
48
+ git clone https://github.com/todddickerson/enhance_swarm.git "$ENHANCE_DIR"
49
+ cd "$ENHANCE_DIR"
50
+ fi
51
+
52
+ # Install gem dependencies
53
+ echo -e "\n${YELLOW}Installing dependencies...${NC}"
54
+ bundle install
55
+
56
+ # Build and install the gem
57
+ echo -e "\n${YELLOW}Building and installing gem...${NC}"
58
+ rake build
59
+ gem install pkg/enhance_swarm-*.gem
60
+
61
+ # Check optional dependencies
62
+ echo -e "\n${YELLOW}Checking optional dependencies...${NC}"
63
+ check_dependency "claude" || echo " ⚠️ Install Claude CLI for enhanced agent spawning"
64
+ check_dependency "gemini" || echo " ⚠️ Install Gemini CLI for large context analysis"
65
+
66
+ # Initialize in current project if we're in a project directory
67
+ if [ -f "Gemfile" ] || [ -f "package.json" ] || [ -f ".git/config" ]; then
68
+ echo -e "\n${YELLOW}Detected project directory. Initialize EnhanceSwarm here?${NC}"
69
+ read -p "Initialize EnhanceSwarm in current directory? (y/n) " -n 1 -r
70
+ echo
71
+ if [[ $REPLY =~ ^[Yy]$ ]]; then
72
+ enhance-swarm init
73
+ fi
74
+ else
75
+ echo -e "\n${GREEN}✅ EnhanceSwarm installed successfully!${NC}"
76
+ echo -e "\nTo initialize in a project, run:"
77
+ echo -e " ${YELLOW}cd your-project${NC}"
78
+ echo -e " ${YELLOW}enhance-swarm init${NC}"
79
+ fi
80
+
81
+ echo -e "\n${GREEN}🎉 Setup complete!${NC}"
82
+ echo -e "\nAvailable commands:"
83
+ echo " enhance-swarm init - Initialize in a project"
84
+ echo " enhance-swarm enhance - Run ENHANCE protocol"
85
+ echo " enhance-swarm doctor - Check system setup"
86
+ echo " enhance-swarm --help - See all commands"
@@ -0,0 +1,4 @@
1
+ module EnhanceSwarm
2
+ VERSION: String
3
+ # See the writing guide of rbs: https://github.com/ruby/rbs#guides
4
+ end
@@ -0,0 +1,160 @@
1
+ # CLAUDE.md - <%= project_name %> Project Instructions
2
+
3
+ ## Project Overview
4
+ <%= project_description %>
5
+
6
+ ## Key Technologies
7
+ <%= technology_stack %>
8
+
9
+ ## Development Guidelines
10
+
11
+ ### For Swarm Agents
12
+ When working on tasks:
13
+ 1. **You have FULL AUTONOMY** - Do not wait for permission to make changes
14
+ 2. **Always run tests** - Use `<%= test_command %>` to verify your work
15
+ 3. **Commit and push** - Always commit your changes and push to a feature branch
16
+ 4. **Fix issues completely** - Don't leave work half-done
17
+
18
+ ### CRITICAL: Multi-Agent Orchestration for Complex Tasks
19
+
20
+ **"ENHANCE" KEYWORD = FULL ORCHESTRATION PROTOCOL**
21
+
22
+ When user says "enhance", ALWAYS:
23
+ 1. Identify next priority task(s) from backlog
24
+ 2. Orchestrate multi-agent parallel implementation
25
+ 3. Monitor all work to completion
26
+ 4. Review, merge, and integrate
27
+ 5. Clean up all worktrees and branches
28
+ 6. Commit and push everything
29
+ 7. Update task statuses
30
+ 8. Provide completion summary
31
+
32
+ **ALWAYS use Claude Swarm orchestration for features requiring multiple components** (e.g., models + UI + tests):
33
+
34
+ 1. **Break down the task** into parallel work for specialists:
35
+ - UX Designer: UI/email templates
36
+ - Backend Developer: Models, services, APIs
37
+ - Frontend Developer: Controllers, views, JavaScript
38
+ - QA Lead: Comprehensive test coverage
39
+
40
+ 2. **Spawn parallel agents** (DO NOT implement directly):
41
+ ```bash
42
+ # First move task to active
43
+ <%= task_move_command %> <task-id> active
44
+
45
+ # Then spawn specialists in parallel
46
+ claude-swarm start -p "UX_TASK: [specific design work from task]" --worktree &
47
+ claude-swarm start -p "BACKEND_TASK: [specific backend work from task]" --worktree &
48
+ claude-swarm start -p "FRONTEND_TASK: [specific frontend work from task]" --worktree &
49
+ claude-swarm start -p "QA_TASK: [specific testing work from task]" --worktree &
50
+
51
+ sleep 5 # Wait for initialization
52
+ ```
53
+
54
+ 3. **Monitor progress** every 30 seconds:
55
+ ```bash
56
+ while claude-swarm ps | grep -q "running"; do
57
+ echo "Checking status..."
58
+ claude-swarm ps
59
+ sleep 30
60
+ done
61
+ ```
62
+
63
+ 4. **Review and iterate** on completed work
64
+ 5. **Only mark task complete** after all agents finish and work is merged
65
+
66
+ **Single-agent tasks** (simple fixes, documentation, configuration):
67
+ - Implement directly without orchestration
68
+ - Examples: Fix typo, update config, add single method
69
+
70
+ ### Code Standards
71
+ <%= code_standards %>
72
+
73
+ ### Git Workflow
74
+ ```bash
75
+ # Stage all changes
76
+ git add -A
77
+
78
+ # Commit with descriptive message
79
+ git commit -m "Add feature: description
80
+
81
+ - Detail 1
82
+ - Detail 2"
83
+
84
+ # Push to feature branch
85
+ git checkout -b feature/description
86
+ git push origin HEAD
87
+ ```
88
+
89
+ ### Common Tasks
90
+
91
+ #### Fix Failing Tests
92
+ 1. Run tests to see failures: `<%= test_command %>`
93
+ 2. Read error messages carefully
94
+ 3. Check for missing database columns
95
+ 4. Ensure test data is valid
96
+ 5. Mock external services properly
97
+ 6. Run tests again to verify
98
+
99
+ #### Add New Feature
100
+ 1. Create necessary models/migrations
101
+ 2. Add services for business logic
102
+ 3. Create controllers and routes
103
+ 4. Build UI components
104
+ 5. Write comprehensive tests
105
+ 6. Document in commit message
106
+
107
+ ## Task Management Process
108
+
109
+ ### Working with Tasks - Use the `<%= task_command %>` Command
110
+ ```bash
111
+ # List tasks
112
+ <%= task_command %> list # Show all tasks
113
+ <%= task_command %> list active # Show active tasks
114
+ <%= task_command %> list backlog # Show backlog
115
+
116
+ # Move tasks between states
117
+ <%= task_command %> move <task-id> active # Start working on a task
118
+ <%= task_command %> move <task-id> completed # Mark task as done
119
+
120
+ # View task details
121
+ <%= task_command %> show <task-id>
122
+
123
+ # Get statistics
124
+ <%= task_command %> stats
125
+
126
+ # Create new tasks
127
+ <%= task_command %> create "Task Title" --effort 4 --tags backend,api
128
+
129
+ # For AI agents - use JSON output
130
+ <%= task_command %> list active --json
131
+ ```
132
+
133
+ ### For Swarm Agents
134
+ 1. **Check for tasks**: `<%= task_command %> list active --json`
135
+ 2. **Start a task**: `<%= task_command %> move <task-id> active`
136
+ 3. **Complete a task**: `<%= task_command %> move <task-id> completed`
137
+ 4. **Commit and push changes**:
138
+ ```bash
139
+ git add -A
140
+ git commit -m "Complete task: <task-id> - <description>"
141
+ git push origin main # or feature branch
142
+ ```
143
+ 5. **Never use manual mv commands** - always use the <%= task_command %> gem
144
+
145
+ ### Task File Format
146
+ Each task file should contain:
147
+ - **Status**: (implicit by directory location)
148
+ - **Description**: What needs to be done
149
+ - **Acceptance Criteria**: How we know it's complete
150
+ - **Time Estimate**: Hours expected
151
+ - **Actual Time**: Hours spent (update when complete)
152
+
153
+ ## Important Notes
154
+ <%= important_notes %>
155
+
156
+ # important-instruction-reminders
157
+ Do what has been asked; nothing more, nothing less.
158
+ NEVER create files unless they're absolutely necessary for achieving your goal.
159
+ ALWAYS prefer editing an existing file to creating a new one.
160
+ NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
@@ -0,0 +1,117 @@
1
+ # MCP.md - Model Context Protocol Ops
2
+
3
+ ## Legend
4
+ | Symbol | Meaning | | Abbrev | Meaning |
5
+ |--------|---------|---|--------|---------|
6
+ | → | leads to | | ops | operations |
7
+ | & | and/with | | UI | user interface |
8
+ | w/ | with | | impl | implementation |
9
+
10
+ ## Decision Matrix
11
+
12
+ ```yaml
13
+ Flag Control:
14
+ --c7: Force Context7→docs | --seq: Force Sequential→analysis | --magic: Force Magic→UI
15
+ --pup: Force Puppeteer→browser | --all-mcp: Enable all | --no-mcp: Disable all
16
+
17
+ User Triggers (no flags):
18
+ "docs for X" → C7(resolve-library-id: X) → get-docs
19
+ "how to use Y in Z" → C7(resolve-library-id: Z) → get-docs(topic: Y)
20
+ "need button/form/component" → Magic(builder) → integrate
21
+ "why slow/broken" → Sequential(analysis) → impl fix
22
+ "design architecture" → Sequential(system design) → C7(patterns)
23
+
24
+ Context Triggers (flags override):
25
+ Import errors → C7(resolve-library-id) → verify docs
26
+ Complex debugging → Sequential(root cause) → native impl
27
+ UI requests → Magic(builder/refiner) → Puppeteer(test)
28
+ Perf issues → Sequential(analysis) → optimize impl
29
+
30
+ Research-First (shared/research-first.yml):
31
+ External lib detected → C7 lookup REQUIRED (blocks w/o docs)
32
+ New component → Magic search REQUIRED or existing pattern
33
+ API integration → WebSearch REQUIRED for official docs
34
+ Unknown pattern → Sequential thinking + research REQUIRED
35
+ Confidence < 90% → Impl BLOCKED until research complete
36
+
37
+ Task Complexity:
38
+ Simple queries → Native tools only (unless flagged)
39
+ Lib questions → C7 progressive loading (or --c7)
40
+ Multi-step problems → Sequential adaptive thinking (or --seq)
41
+ UI generation → Magic + integration (or --magic)
42
+ Full workflows → Multi-MCP orchestration (or --all-mcp)
43
+ ```
44
+
45
+ ## Execution Playbooks
46
+
47
+ ```yaml
48
+ Lib Research: C7 resolve-library-id w/ user term → options if multiple → C7 get-docs w/ topic → Sequential if insufficient → impl
49
+ Ex: "React forms?" → C7 resolve("react") → C7 get-docs(topic:"forms") → impl form code
50
+
51
+ Complex Analysis: Sequential problem decomposition → guide C7 docs lookup → combine analysis+docs→impl plan → execute w/ native
52
+ Ex: "App slow debug" → Sequential(analyze perf bottlenecks) → C7 get-docs optimization patterns → impl fixes
53
+
54
+ UI Generation: Magic builder w/ user requirements+project context → Magic refiner if needed → integrate component → Puppeteer validation
55
+ Ex: "Dashboard w/ charts" → Magic builder("dashboard","charts") → edit files integrate → Puppeteer screenshot
56
+ ```
57
+
58
+ ## Token Economics
59
+
60
+ ```yaml
61
+ Budget: Native:0 | Light MCP:100-500 | Medium MCP:500-2K | Heavy MCP:2K-10K
62
+ Escalation: 1.Native first simple tasks 2.C7 lib questions 3.Sequential complex analysis 4.Combine MCPs synergy
63
+ Abort: >50% context→native | MCP timeout/error→fallback | Diminishing returns→stop MCP
64
+ Cost: Quick→C7 only | Architecture→Sequential | UI→Magic | Else→Native
65
+ UltraCompressed: --uc flag|High context|Token budget | ~70% reduction | Clarity→conciseness | Legend auto-gen
66
+ ```
67
+
68
+ ## Quality Control
69
+
70
+ ```yaml
71
+ C7: ✓Relevant docs→Proceed | ⚠Partial→Try different terms | ✗No match→Sequential alternatives
72
+ Sequential: ✓Clear analysis+steps→Impl | ⚠Partial→Continue thoughts | ✗Unclear/timeout→Native+user questions
73
+ Magic: ✓Component matches→Integrate | ⚠Close needs changes→Refiner | ✗Poor→Try different terms
74
+ Multi-MCP: Results enhance each other | Conflict→Most authoritative | Redundant→Stop calls
75
+ ```
76
+
77
+ ## Persona Integration
78
+
79
+ ```yaml
80
+ Persona Preferences:
81
+ architect: Sequential(design)+C7(patterns)+avoid Magic | frontend: Magic(UI)+Puppeteer(test)+C7(React/Vue docs)
82
+ backend: C7(API docs)+Sequential(scale analysis)+avoid Magic | analyzer: Sequential(root cause) primary+C7(solutions) secondary
83
+ security: Sequential(threats)+C7(security patterns)+Puppeteer(test) | mentor: C7(learning)+Sequential(explanations)+avoid Magic
84
+ refactorer: Sequential(analysis)+C7(patterns)+avoid Magic/Puppeteer | perf: Sequential(bottlenecks)+Puppeteer(metrics)+C7(optimization)
85
+ qa: Puppeteer(testing)+Sequential(edge cases)+C7(testing frameworks)
86
+
87
+ Behaviors: architect→Long Sequential system design | frontend→Quick Magic components | analyzer→Deep Sequential before solutions
88
+ ```
89
+
90
+ ## Command Integration
91
+
92
+ ```yaml
93
+ Planning: Default execute immediately | --plan flag→Forces planning mode | --skip-plan→Skip (redundant w/ default)
94
+ MCP Flags: --c7/--no-c7 | --seq/--no-seq | --magic/--no-magic | --pup/--no-pup | --all-mcp | --no-mcp
95
+ Auto-Activation (no flags): /user:build→Magic(UI) if frontend | /user:analyze→Sequential complex | /user:design→Sequential+C7
96
+ /user:explain→C7 if lib mentioned else native | /user:improve→Sequential→C7 | /user:scan→Native only (security)
97
+ Priority: Explicit flags>Auto-activation>Context triggers | --no-mcp overrides all | --no-[server] overrides specific
98
+ Context Share: Sequential→feeds C7 topic selection | C7 docs→inform Magic generation | Magic→tested w/ Puppeteer | All cached
99
+ Execution: Default→Execute immediately | --plan flag→Show plan before changes | User controls→Full control
100
+ ```
101
+
102
+ ## Failure Recovery & Best Practices
103
+
104
+ ```yaml
105
+ Failures: C7: Lib not found→broader terms | Docs incomplete→Sequential | API timeout→cache partial+native
106
+ Sequential: Timeout→use partial+note limit | Token limit→summarize+native | Unclear→ask questions+avoid retry
107
+ Magic: No components→try different terms once | Poor quality→refiner w/ context | Integration issues→document+native
108
+ Multi-MCP: Conflict→most reliable source | Resource exhaustion→single best MCP | Partial failures→continue successful only
109
+
110
+ DO: Match MCP→user need | Set token budgets | Validate before impl | Cache patterns | Graceful fallback
111
+ Use C7 ALL external lib docs (research-first.yml enforced) | Cite MCP sources in impl
112
+ DON'T: MCPs for simple tasks native handles | Chain w/o validation | Exceed 50% context | Retry failed w/o change | MCPs when immediate needed
113
+ OPTIMIZE: Batch similar calls | Reuse session results | Start least expensive | Prefer native file ops | Document successful patterns
114
+ ```
115
+
116
+ ---
117
+ *SuperClaude v4.0.0 | Ops MCP instructions for Claude Code intelligence*