sugarai 1.7.2__tar.gz → 3.1.1.dev4__tar.gz

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 (89) hide show
  1. sugarai-3.1.1.dev4/LICENSE +30 -0
  2. sugarai-3.1.1.dev4/PKG-INFO +535 -0
  3. sugarai-3.1.1.dev4/README.md +481 -0
  4. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/pyproject.toml +8 -6
  5. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/__version__.py +26 -6
  6. sugarai-3.1.1.dev4/sugar/agent/__init__.py +26 -0
  7. sugarai-3.1.1.dev4/sugar/agent/base.py +535 -0
  8. sugarai-3.1.1.dev4/sugar/agent/hooks.py +383 -0
  9. sugarai-3.1.1.dev4/sugar/agent/subagent_manager.py +329 -0
  10. sugarai-3.1.1.dev4/sugar/agent/tools.py +238 -0
  11. sugarai-3.1.1.dev4/sugar/billing/__init__.py +24 -0
  12. sugarai-3.1.1.dev4/sugar/billing/api_keys.py +369 -0
  13. sugarai-3.1.1.dev4/sugar/billing/tiers.py +318 -0
  14. sugarai-3.1.1.dev4/sugar/billing/usage.py +295 -0
  15. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/core/loop.py +44 -15
  16. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/code_quality.py +2 -2
  17. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/error_monitor.py +4 -4
  18. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/github_watcher.py +6 -6
  19. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/test_coverage.py +2 -2
  20. sugarai-3.1.1.dev4/sugar/executor/__init__.py +19 -0
  21. sugarai-3.1.1.dev4/sugar/executor/agent_sdk_executor.py +223 -0
  22. sugarai-3.1.1.dev4/sugar/executor/base.py +139 -0
  23. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/executor/claude_wrapper.py +39 -22
  24. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/executor/structured_request.py +3 -3
  25. sugarai-3.1.1.dev4/sugar/integrations/__init__.py +14 -0
  26. sugarai-3.1.1.dev4/sugar/integrations/github.py +423 -0
  27. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/learning/feedback_processor.py +2 -2
  28. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/main.py +1279 -156
  29. sugarai-3.1.1.dev4/sugar/mcp/__init__.py +11 -0
  30. sugarai-3.1.1.dev4/sugar/mcp/server.py +476 -0
  31. sugarai-3.1.1.dev4/sugar/orchestration/__init__.py +25 -0
  32. sugarai-3.1.1.dev4/sugar/orchestration/agent_router.py +238 -0
  33. sugarai-3.1.1.dev4/sugar/orchestration/task_orchestrator.py +953 -0
  34. sugarai-3.1.1.dev4/sugar/profiles/__init__.py +19 -0
  35. sugarai-3.1.1.dev4/sugar/profiles/base.py +119 -0
  36. sugarai-3.1.1.dev4/sugar/profiles/default.py +129 -0
  37. sugarai-3.1.1.dev4/sugar/profiles/issue_responder.py +416 -0
  38. sugarai-3.1.1.dev4/sugar/quality_gates/__init__.py +59 -0
  39. sugarai-3.1.1.dev4/sugar/quality_gates/coordinator.py +289 -0
  40. sugarai-3.1.1.dev4/sugar/quality_gates/diff_validator.py +298 -0
  41. sugarai-3.1.1.dev4/sugar/quality_gates/evidence.py +294 -0
  42. sugarai-3.1.1.dev4/sugar/quality_gates/failure_handler.py +345 -0
  43. sugarai-3.1.1.dev4/sugar/quality_gates/functional_verifier.py +413 -0
  44. sugarai-3.1.1.dev4/sugar/quality_gates/preflight_checks.py +394 -0
  45. sugarai-3.1.1.dev4/sugar/quality_gates/success_criteria.py +388 -0
  46. sugarai-3.1.1.dev4/sugar/quality_gates/test_validator.py +349 -0
  47. sugarai-3.1.1.dev4/sugar/quality_gates/truth_enforcer.py +329 -0
  48. sugarai-3.1.1.dev4/sugar/storage/task_type_manager.py +517 -0
  49. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/storage/work_queue.py +343 -15
  50. sugarai-3.1.1.dev4/sugar/utils/toon_encoder.py +159 -0
  51. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/workflow/orchestrator.py +104 -2
  52. sugarai-3.1.1.dev4/sugarai.egg-info/PKG-INFO +535 -0
  53. sugarai-3.1.1.dev4/sugarai.egg-info/SOURCES.txt +81 -0
  54. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugarai.egg-info/requires.txt +1 -0
  55. sugarai-3.1.1.dev4/tests/test_agent.py +800 -0
  56. sugarai-3.1.1.dev4/tests/test_billing.py +407 -0
  57. sugarai-3.1.1.dev4/tests/test_cli.py +650 -0
  58. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/tests/test_core_loop.py +131 -54
  59. sugarai-3.1.1.dev4/tests/test_goose_integration.py +650 -0
  60. sugarai-3.1.1.dev4/tests/test_hold_functionality.py +276 -0
  61. sugarai-3.1.1.dev4/tests/test_hooks.py +613 -0
  62. sugarai-3.1.1.dev4/tests/test_issue_responder_cli.py +739 -0
  63. sugarai-3.1.1.dev4/tests/test_orchestration.py +1141 -0
  64. sugarai-3.1.1.dev4/tests/test_profiles.py +456 -0
  65. sugarai-3.1.1.dev4/tests/test_quality_gates.py +494 -0
  66. sugarai-3.1.1.dev4/tests/test_subagent_manager.py +713 -0
  67. sugarai-3.1.1.dev4/tests/test_task_types.py +747 -0
  68. sugarai-3.1.1.dev4/tests/test_toon_encoder.py +155 -0
  69. sugarai-3.1.1.dev4/tests/test_v3_benchmarks.py +406 -0
  70. sugarai-1.7.2/PKG-INFO +0 -702
  71. sugarai-1.7.2/README.md +0 -652
  72. sugarai-1.7.2/sugar/utils/__init__.py +0 -0
  73. sugarai-1.7.2/sugarai.egg-info/PKG-INFO +0 -702
  74. sugarai-1.7.2/sugarai.egg-info/SOURCES.txt +0 -33
  75. sugarai-1.7.2/tests/test_cli.py +0 -266
  76. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/setup.cfg +0 -0
  77. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/__init__.py +0 -0
  78. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/core/__init__.py +0 -0
  79. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/__init__.py +0 -0
  80. {sugarai-1.7.2/sugar/executor → sugarai-3.1.1.dev4/sugar/learning}/__init__.py +0 -0
  81. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/learning/adaptive_scheduler.py +0 -0
  82. {sugarai-1.7.2/sugar/learning → sugarai-3.1.1.dev4/sugar/storage}/__init__.py +0 -0
  83. {sugarai-1.7.2/sugar/storage → sugarai-3.1.1.dev4/sugar/utils}/__init__.py +0 -0
  84. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/utils/git_operations.py +0 -0
  85. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/workflow/__init__.py +0 -0
  86. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugarai.egg-info/dependency_links.txt +0 -0
  87. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugarai.egg-info/entry_points.txt +0 -0
  88. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugarai.egg-info/top_level.txt +0 -0
  89. {sugarai-1.7.2 → sugarai-3.1.1.dev4}/tests/test_storage.py +0 -0
@@ -0,0 +1,30 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Sugar - AI-Powered Autonomous Development System
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ ## Additional Terms
24
+
25
+ This software is subject to additional terms and disclaimers as outlined in
26
+ the TERMS.md file, which includes important limitations of liability and
27
+ user responsibilities when using AI-powered autonomous development tools.
28
+
29
+ By using this software, you acknowledge that you have read and agree to both
30
+ this MIT License and the additional terms in TERMS.md.
@@ -0,0 +1,535 @@
1
+ Metadata-Version: 2.4
2
+ Name: sugarai
3
+ Version: 3.1.1.dev4
4
+ Summary: Sugar 🍰 - A dev team that never stops. Delegate full tasks to AI in the background.
5
+ Author-email: Steven Leggett <contact@roboticforce.io>
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/roboticforce/sugar
8
+ Project-URL: Documentation, https://docs.roboticforce.io/sugar
9
+ Project-URL: Repository, https://github.com/roboticforce/sugar
10
+ Project-URL: Bug Tracker, https://github.com/roboticforce/sugar/issues
11
+ Keywords: claude,autonomous,development,ai,automation
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Topic :: Software Development :: Quality Assurance
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: click>=8.1.0
25
+ Requires-Dist: pyyaml>=6.0
26
+ Requires-Dist: aiosqlite>=0.19.0
27
+ Requires-Dist: sqlalchemy>=2.0.0
28
+ Requires-Dist: python-dotenv>=1.0.0
29
+ Requires-Dist: asyncio-throttle>=1.0.0
30
+ Requires-Dist: setuptools>=45
31
+ Requires-Dist: claude-agent-sdk>=0.1.0
32
+ Provides-Extra: github
33
+ Requires-Dist: PyGithub>=1.59.0; extra == "github"
34
+ Provides-Extra: dev
35
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
36
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
37
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
38
+ Requires-Dist: black>=23.0.0; extra == "dev"
39
+ Requires-Dist: flake8>=6.0.0; extra == "dev"
40
+ Requires-Dist: flake8-docstrings>=1.7.0; extra == "dev"
41
+ Requires-Dist: isort>=5.12.0; extra == "dev"
42
+ Requires-Dist: mypy>=1.0.0; extra == "dev"
43
+ Requires-Dist: bandit>=1.7.5; extra == "dev"
44
+ Requires-Dist: safety>=2.3.0; extra == "dev"
45
+ Requires-Dist: pre-commit>=3.0.0; extra == "dev"
46
+ Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
47
+ Requires-Dist: types-requests>=2.28.0; extra == "dev"
48
+ Requires-Dist: types-setuptools>=69.0.0; extra == "dev"
49
+ Provides-Extra: test
50
+ Requires-Dist: pytest>=7.0.0; extra == "test"
51
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
52
+ Requires-Dist: pytest-cov>=4.0.0; extra == "test"
53
+ Dynamic: license-file
54
+
55
+ # Sugar 🍰
56
+
57
+ A dev team that never stops.
58
+
59
+ Delegate full tasks to AI in the background. Sugar builds features, fixes bugs, and ships code while you focus on what matters.
60
+
61
+ ## What It Does
62
+
63
+ Think of Sugar as **Claude Code with persistence**. Instead of one-off interactions:
64
+
65
+ - **Continuous execution** - Runs 24/7, working through your task queue
66
+ - **Delegate from Claude** - Hand off tasks during interactive sessions
67
+ - **Builds features** - Takes specs, implements, tests, commits working code
68
+ - **Fixes bugs** - Reads error logs, investigates, implements fixes
69
+ - **GitHub integration** - Creates PRs, updates issues, tracks progress
70
+ - **Smart discovery** - Finds work from errors, issues, and code analysis
71
+
72
+ You plan the work. Sugar executes it.
73
+
74
+ **Works with:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [Goose](https://block.github.io/goose/docs/mcp/sugar-mcp) | [Claude Desktop](https://claude.ai/download)
75
+
76
+ ## Install
77
+
78
+ ```bash
79
+ pip install sugarai
80
+ ```
81
+
82
+ Or use uv (much faster):
83
+ ```bash
84
+ uv pip install sugarai
85
+ ```
86
+
87
+ ## Quick Start
88
+
89
+ ```bash
90
+ # Initialize in your project
91
+ cd your-project
92
+ sugar init
93
+
94
+ # Add tasks to the queue
95
+ sugar add "Fix authentication timeout" --type bug_fix --urgent
96
+ sugar add "Add user profile settings" --type feature
97
+
98
+ # Start the loop
99
+ sugar run
100
+ ```
101
+
102
+ Sugar will:
103
+ 1. Pick up tasks from the queue
104
+ 2. Execute them using Claude Code
105
+ 3. Run tests and verify changes
106
+ 4. Commit working code
107
+ 5. Move to the next task
108
+
109
+ It keeps going until the queue is empty (or you stop it).
110
+
111
+ **Or delegate from Claude Code:**
112
+ ```
113
+ /sugar-task "Fix login timeout" --type bug_fix --urgent
114
+ ```
115
+ Sugar picks it up and works on it while you keep coding.
116
+
117
+ ## Real Example
118
+
119
+ **Simple tasks:**
120
+ ```bash
121
+ # Quick task creation
122
+ sugar add "Fix authentication timeout" --type bug_fix --urgent
123
+ sugar add "Add user profile settings" --type feature --priority 4
124
+ ```
125
+
126
+ **Complex tasks with rich context** (recommended for best results):
127
+ ```bash
128
+ sugar add "User Dashboard Redesign" --json --description '{
129
+ "priority": 5,
130
+ "type": "feature",
131
+ "context": "Complete overhaul of user dashboard with modern UI/UX patterns",
132
+ "business_context": "User feedback shows dashboard is confusing. Goal: reduce support tickets by 40%",
133
+ "technical_requirements": [
134
+ "React 18 with TypeScript",
135
+ "Responsive design (mobile-first)",
136
+ "Real-time data updates via WebSocket",
137
+ "Accessibility compliance (WCAG 2.1 AA)"
138
+ ],
139
+ "agent_assignments": {
140
+ "ux_design_specialist": "Design system and user flows",
141
+ "frontend_developer": "Implementation and optimization",
142
+ "qa_test_engineer": "Testing and validation"
143
+ },
144
+ "success_criteria": [
145
+ "Dashboard loads in < 2 seconds",
146
+ "Mobile responsive on all breakpoints",
147
+ "Passes accessibility audit",
148
+ "User testing shows 90%+ satisfaction"
149
+ ],
150
+ "requirements": [
151
+ "Dark mode support",
152
+ "Customizable widget layout",
153
+ "Export dashboard data to PDF"
154
+ ]
155
+ }'
156
+ ```
157
+
158
+ **Why JSON format?** Rich context gives Claude Code everything it needs to build production-quality features autonomously. The more detail you provide, the better the results.
159
+
160
+ ```bash
161
+ # Start autonomous mode
162
+ sugar run
163
+
164
+ # Check progress anytime
165
+ sugar status
166
+ sugar list --status completed
167
+
168
+ # Sugar handles:
169
+ # - Writing the code
170
+ # - Running tests
171
+ # - Making commits
172
+ # - Creating PRs (if configured)
173
+ # - Updating GitHub issues
174
+ ```
175
+
176
+ ## Features
177
+
178
+ **Task Management**
179
+ - Rich task context with priorities and metadata
180
+ - Custom task types for your workflow
181
+ - Queue management and filtering
182
+
183
+ **Task Orchestration** *(New in v3.0)*
184
+ - Auto-decomposes complex features into subtasks
185
+ - 4-stage workflow: Research → Planning → Implementation → Review
186
+ - Specialist agent routing (frontend, backend, QA, security, DevOps)
187
+ - Parallel execution with dependency management
188
+
189
+ **Autonomous Execution**
190
+ - Specialized Claude agents (UX, backend, QA)
191
+ - Automatic retries on failures
192
+ - Quality checks and testing
193
+
194
+ **GitHub Integration**
195
+ - Reads issues, creates PRs
196
+ - Updates issue status automatically
197
+ - Commits with proper messages
198
+
199
+ **Smart Discovery**
200
+ - Monitors error logs
201
+ - Analyzes code quality
202
+ - Identifies missing tests
203
+ - Auto-creates tasks from findings
204
+
205
+ **Issue Responder**
206
+ - AI-powered GitHub issue analysis
207
+ - Generates contextual responses
208
+ - Confidence-based auto-posting
209
+ - Searchable issue history
210
+
211
+ ## Issue Responder
212
+
213
+ Automatically analyze and respond to GitHub issues with AI-powered insights. Sugar understands issue context, codebase structure, and project patterns to generate helpful responses.
214
+
215
+ ```bash
216
+ # List open issues
217
+ sugar issue list
218
+
219
+ # Analyze an issue
220
+ sugar issue analyze 42
221
+
222
+ # Generate AI response (preview)
223
+ sugar issue respond 42
224
+
225
+ # Generate and post if confident
226
+ sugar issue respond 42 --post
227
+ ```
228
+
229
+ The Issue Responder evaluates confidence before posting. Use `--force-post` to override the confidence check, or adjust the threshold with `--confidence-threshold`.
230
+
231
+ **Full documentation:** [docs/issue-responder.md](docs/issue-responder.md)
232
+
233
+ ## How It Works
234
+
235
+ ```
236
+ ┌─────────────────────────────────────────────────────────┐
237
+ │ The Sugar Loop │
238
+ └─────────────────────────────────────────────────────────┘
239
+
240
+ You Priority Queue Sugar
241
+ │ │ │
242
+ │ sugar add "task" │ │
243
+ ├─────────────────────────>│ │
244
+ │ │ │
245
+ │ │ Picks highest priority │
246
+ │ │<────────────────────────┤
247
+ │ │ │
248
+ │ │ │
249
+ │ Claude Code │
250
+ │ │ │
251
+ │ │ Executes in background │
252
+ │ │ (uses agents, tests) │
253
+ │ │ │
254
+ │ ▼ │
255
+ │ Completes Work │
256
+ │ │ │
257
+ │ │ Commits, updates │
258
+ │ │ │
259
+ │ │ Back to queue ────────>│
260
+ │ │ │
261
+ └──────────────────────────┴─────────────────────────┘
262
+ ↻ Repeat
263
+ ```
264
+
265
+ **The continuous execution loop:**
266
+
267
+ 1. **You assign** - Add tasks with priorities and context
268
+ 2. **Sugar picks up** - Grabs highest priority work from the queue
269
+ 3. **Claude Code executes** - Runs in background, uses specialized agents as needed
270
+ 4. **Completes work** - Tests, commits, moves to next task
271
+ 5. **Repeat** - Continuous execution until queue is empty
272
+
273
+ ## Configuration
274
+
275
+ `.sugar/config.yaml` is auto-generated on `sugar init`. Key settings:
276
+
277
+ ```yaml
278
+ sugar:
279
+ dry_run: false # Set to true for testing
280
+ loop_interval: 300 # 5 minutes between cycles
281
+ max_concurrent_work: 3 # Parallel task execution
282
+
283
+ claude:
284
+ enable_agents: true # Use specialized Claude agents
285
+
286
+ discovery:
287
+ github:
288
+ enabled: true
289
+ repo: "user/repository"
290
+ error_logs:
291
+ enabled: true
292
+ paths: ["logs/errors/"]
293
+ code_quality:
294
+ enabled: true
295
+ ```
296
+
297
+ ## Use Sugar from Claude Code
298
+
299
+ **Sugar has native Claude Code integration!** Delegate work to Sugar directly from your Claude sessions.
300
+
301
+ ### Install the Plugin
302
+
303
+ ```
304
+ /plugin install roboticforce/sugar
305
+ ```
306
+
307
+ > **Note**: If you see "Plugin not found in any marketplace", make sure you're using `roboticforce/sugar` (the GitHub repository path).
308
+
309
+ ### Delegate Work from Claude
310
+
311
+ **Inside a Claude Code session:**
312
+
313
+ ```
314
+ You: "I'm working on authentication but need to fix these test failures.
315
+ Can you handle the test fixes while I finish the auth flow?"
316
+
317
+ Claude: "I'll create a Sugar task for the test fixes so you can keep coding."
318
+
319
+ /sugar-task "Fix authentication test failures" --type test --urgent
320
+ ```
321
+
322
+ **Why this is powerful:** Claude Code handles your interactive work while Sugar autonomously fixes the tests in the background. No context switching.
323
+
324
+ ### Example Workflow
325
+
326
+ ```
327
+ You: "Found a memory leak in the cache module. Add it to the queue."
328
+
329
+ Claude:
330
+ /sugar-task "Fix memory leak in cache module" --json --description '{
331
+ "priority": 5,
332
+ "type": "bug_fix",
333
+ "context": "Memory usage grows unbounded in production",
334
+ "technical_requirements": ["Profile memory usage", "Add cleanup cycle"],
335
+ "agent_assignments": {
336
+ "tech_lead": "Investigate root cause and fix"
337
+ }
338
+ }'
339
+
340
+ Task created! You can check progress with /sugar-status
341
+ ```
342
+
343
+ ### Available Slash Commands
344
+
345
+ - `/sugar-task` - Create tasks with rich context
346
+ - `/sugar-status` - Check queue and progress
347
+ - `/sugar-run` - Start autonomous mode
348
+ - `/sugar-review` - Review pending tasks
349
+ - `/sugar-analyze` - Analyze code for potential work
350
+
351
+ ### MCP Server Integration
352
+
353
+ Sugar provides an MCP server for integration with Goose, Claude Desktop, and other MCP clients.
354
+
355
+ **Using with Goose:**
356
+
357
+ Sugar is an official extension in the [Goose extensions library](https://block.github.io/goose/docs/mcp/sugar-mcp).
358
+
359
+ ```bash
360
+ # Via Goose CLI
361
+ goose configure
362
+ # Select "Add Extension" → "Command-line Extension"
363
+ # Name: sugar
364
+ # Command: npx -y sugarai-mcp
365
+ ```
366
+
367
+ **Using with Claude Desktop:**
368
+ ```json
369
+ {
370
+ "mcpServers": {
371
+ "sugar": {
372
+ "command": "npx",
373
+ "args": ["-y", "sugarai-mcp"],
374
+ "env": {
375
+ "SUGAR_PROJECT_ROOT": "/path/to/your/project"
376
+ }
377
+ }
378
+ }
379
+ }
380
+ ```
381
+
382
+ **Available MCP Tools:**
383
+ - `createTask` - Create development tasks
384
+ - `listTasks` - List/filter tasks
385
+ - `viewTask` / `updateTask` / `removeTask` - Manage tasks
386
+ - `getStatus` - Get system metrics
387
+ - `runOnce` - Execute one autonomous cycle
388
+
389
+ ## Architecture (v3.0)
390
+
391
+ Sugar 3.0 is built natively on the **Claude Agent SDK**, providing:
392
+
393
+ **Agent Foundation**
394
+ - `SugarAgent` - Native SDK integration with streaming and tool use
395
+ - Quality gate hooks - PreToolUse/PostToolUse security checks
396
+ - Workflow profiles - Specialized behaviors for different tasks
397
+
398
+ **Distribution Options**
399
+ - **GitHub Action** - Event-driven, BYOK (Bring Your Own Key)
400
+ - **MCP Server** - Native Python or Node.js for Claude Desktop/Goose
401
+ - **Python Package** - Direct library usage
402
+ - **CLI** - Local development
403
+
404
+ **SaaS Features** (Enterprise)
405
+ - Usage tracking per customer
406
+ - API key management with rate limiting
407
+ - Tiered pricing (Free → Enterprise)
408
+
409
+ ## Requirements
410
+
411
+ - Python 3.11+
412
+ - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (for CLI mode)
413
+
414
+ ## Documentation
415
+
416
+ - **[Quick Start](docs/user/quick-start.md)** - Get running in 5 minutes
417
+ - **[CLI Reference](docs/user/cli-reference.md)** - All commands
418
+ - **[Task Orchestration](docs/task_orchestration.md)** - Complex feature decomposition
419
+ - **[GitHub Integration](docs/user/github-integration.md)** - Connect to GitHub
420
+ - **[Configuration Guide](docs/user/configuration-best-practices.md)** - Best practices
421
+ - **[Claude Code Plugin](.claude-plugin/README.md)** - Native integration
422
+
423
+ ## Advanced Usage
424
+
425
+ **Task Orchestration**
426
+
427
+ For complex features, Sugar can automatically decompose work and route to specialist agents:
428
+
429
+ ```bash
430
+ # Add a feature that will be orchestrated
431
+ sugar add "Add user authentication with OAuth" --type feature --orchestrate
432
+
433
+ # Sugar will:
434
+ # 1. RESEARCH - Search best practices, analyze codebase
435
+ # 2. PLAN - Create implementation plan with subtasks
436
+ # 3. IMPLEMENT - Route subtasks to specialists in parallel
437
+ # 4. REVIEW - Code review and test verification
438
+
439
+ # Check orchestration status
440
+ sugar orchestrate <task_id> --stages
441
+
442
+ # View accumulated context
443
+ sugar context <task_id>
444
+ ```
445
+
446
+ Specialist agents are automatically assigned based on task content:
447
+ - `frontend-designer` - UI, components, styling
448
+ - `backend-developer` - APIs, databases, services
449
+ - `qa-engineer` - Testing, test strategies
450
+ - `security-engineer` - Auth, vulnerabilities
451
+ - `devops-engineer` - CI/CD, infrastructure
452
+
453
+ **Custom Task Types**
454
+ ```bash
455
+ sugar task-type add deployment --name "Deployment" --emoji "🚀"
456
+ sugar add "Deploy to staging" --type deployment
457
+ ```
458
+
459
+ **Complex Tasks with Context**
460
+ ```bash
461
+ sugar add "User Dashboard" --json --description '{
462
+ "priority": 5,
463
+ "context": "Complete dashboard redesign",
464
+ "agent_assignments": {
465
+ "ux_design_specialist": "UI/UX design",
466
+ "frontend_developer": "Implementation",
467
+ "qa_test_engineer": "Testing"
468
+ }
469
+ }'
470
+ ```
471
+
472
+ **Multiple Projects**
473
+ ```bash
474
+ # Run Sugar on multiple projects simultaneously
475
+ cd /path/to/project-a && sugar run &
476
+ cd /path/to/project-b && sugar run &
477
+ cd /path/to/project-c && sugar run &
478
+ ```
479
+
480
+ ## Troubleshooting
481
+
482
+ **Sugar not finding Claude CLI?**
483
+ ```bash
484
+ # Specify Claude path in .sugar/config.yaml
485
+ claude:
486
+ command: "/full/path/to/claude"
487
+ ```
488
+
489
+ **Tasks not executing?**
490
+ ```bash
491
+ # Check dry_run is disabled
492
+ cat .sugar/config.yaml | grep dry_run
493
+
494
+ # Monitor logs
495
+ tail -f .sugar/sugar.log
496
+
497
+ # Test single cycle
498
+ sugar run --once
499
+ ```
500
+
501
+ **Need help?**
502
+ - [Troubleshooting Guide](docs/user/troubleshooting.md)
503
+ - [GitHub Issues](https://github.com/roboticforce/sugar/issues)
504
+
505
+ ## Contributing
506
+
507
+ Contributions welcome! See [CONTRIBUTING.md](docs/dev/contributing.md) for guidelines.
508
+
509
+ ```bash
510
+ # Development setup
511
+ git clone https://github.com/roboticforce/sugar.git
512
+ cd sugar
513
+
514
+ # Install with uv (recommended)
515
+ uv pip install -e ".[dev,test,github]"
516
+
517
+ # Or with pip
518
+ pip install -e ".[dev,test,github]"
519
+
520
+ # Run tests
521
+ pytest tests/ -v
522
+
523
+ # Format code
524
+ black .
525
+ ```
526
+
527
+ ## License
528
+
529
+ MIT - see [LICENSE](LICENSE) and [TERMS.md](TERMS.md)
530
+
531
+ ---
532
+
533
+ **Sugar v3.0.0** - Autonomous development powered by Claude Agent SDK
534
+
535
+ > ⚠️ Sugar is provided "AS IS" without warranty. Review all AI-generated code before use. See [TERMS.md](TERMS.md) for details.