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.
- sugarai-3.1.1.dev4/LICENSE +30 -0
- sugarai-3.1.1.dev4/PKG-INFO +535 -0
- sugarai-3.1.1.dev4/README.md +481 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/pyproject.toml +8 -6
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/__version__.py +26 -6
- sugarai-3.1.1.dev4/sugar/agent/__init__.py +26 -0
- sugarai-3.1.1.dev4/sugar/agent/base.py +535 -0
- sugarai-3.1.1.dev4/sugar/agent/hooks.py +383 -0
- sugarai-3.1.1.dev4/sugar/agent/subagent_manager.py +329 -0
- sugarai-3.1.1.dev4/sugar/agent/tools.py +238 -0
- sugarai-3.1.1.dev4/sugar/billing/__init__.py +24 -0
- sugarai-3.1.1.dev4/sugar/billing/api_keys.py +369 -0
- sugarai-3.1.1.dev4/sugar/billing/tiers.py +318 -0
- sugarai-3.1.1.dev4/sugar/billing/usage.py +295 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/core/loop.py +44 -15
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/code_quality.py +2 -2
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/error_monitor.py +4 -4
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/github_watcher.py +6 -6
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/test_coverage.py +2 -2
- sugarai-3.1.1.dev4/sugar/executor/__init__.py +19 -0
- sugarai-3.1.1.dev4/sugar/executor/agent_sdk_executor.py +223 -0
- sugarai-3.1.1.dev4/sugar/executor/base.py +139 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/executor/claude_wrapper.py +39 -22
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/executor/structured_request.py +3 -3
- sugarai-3.1.1.dev4/sugar/integrations/__init__.py +14 -0
- sugarai-3.1.1.dev4/sugar/integrations/github.py +423 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/learning/feedback_processor.py +2 -2
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/main.py +1279 -156
- sugarai-3.1.1.dev4/sugar/mcp/__init__.py +11 -0
- sugarai-3.1.1.dev4/sugar/mcp/server.py +476 -0
- sugarai-3.1.1.dev4/sugar/orchestration/__init__.py +25 -0
- sugarai-3.1.1.dev4/sugar/orchestration/agent_router.py +238 -0
- sugarai-3.1.1.dev4/sugar/orchestration/task_orchestrator.py +953 -0
- sugarai-3.1.1.dev4/sugar/profiles/__init__.py +19 -0
- sugarai-3.1.1.dev4/sugar/profiles/base.py +119 -0
- sugarai-3.1.1.dev4/sugar/profiles/default.py +129 -0
- sugarai-3.1.1.dev4/sugar/profiles/issue_responder.py +416 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/__init__.py +59 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/coordinator.py +289 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/diff_validator.py +298 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/evidence.py +294 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/failure_handler.py +345 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/functional_verifier.py +413 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/preflight_checks.py +394 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/success_criteria.py +388 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/test_validator.py +349 -0
- sugarai-3.1.1.dev4/sugar/quality_gates/truth_enforcer.py +329 -0
- sugarai-3.1.1.dev4/sugar/storage/task_type_manager.py +517 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/storage/work_queue.py +343 -15
- sugarai-3.1.1.dev4/sugar/utils/toon_encoder.py +159 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/workflow/orchestrator.py +104 -2
- sugarai-3.1.1.dev4/sugarai.egg-info/PKG-INFO +535 -0
- sugarai-3.1.1.dev4/sugarai.egg-info/SOURCES.txt +81 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugarai.egg-info/requires.txt +1 -0
- sugarai-3.1.1.dev4/tests/test_agent.py +800 -0
- sugarai-3.1.1.dev4/tests/test_billing.py +407 -0
- sugarai-3.1.1.dev4/tests/test_cli.py +650 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/tests/test_core_loop.py +131 -54
- sugarai-3.1.1.dev4/tests/test_goose_integration.py +650 -0
- sugarai-3.1.1.dev4/tests/test_hold_functionality.py +276 -0
- sugarai-3.1.1.dev4/tests/test_hooks.py +613 -0
- sugarai-3.1.1.dev4/tests/test_issue_responder_cli.py +739 -0
- sugarai-3.1.1.dev4/tests/test_orchestration.py +1141 -0
- sugarai-3.1.1.dev4/tests/test_profiles.py +456 -0
- sugarai-3.1.1.dev4/tests/test_quality_gates.py +494 -0
- sugarai-3.1.1.dev4/tests/test_subagent_manager.py +713 -0
- sugarai-3.1.1.dev4/tests/test_task_types.py +747 -0
- sugarai-3.1.1.dev4/tests/test_toon_encoder.py +155 -0
- sugarai-3.1.1.dev4/tests/test_v3_benchmarks.py +406 -0
- sugarai-1.7.2/PKG-INFO +0 -702
- sugarai-1.7.2/README.md +0 -652
- sugarai-1.7.2/sugar/utils/__init__.py +0 -0
- sugarai-1.7.2/sugarai.egg-info/PKG-INFO +0 -702
- sugarai-1.7.2/sugarai.egg-info/SOURCES.txt +0 -33
- sugarai-1.7.2/tests/test_cli.py +0 -266
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/setup.cfg +0 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/__init__.py +0 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/core/__init__.py +0 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/discovery/__init__.py +0 -0
- {sugarai-1.7.2/sugar/executor → sugarai-3.1.1.dev4/sugar/learning}/__init__.py +0 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/learning/adaptive_scheduler.py +0 -0
- {sugarai-1.7.2/sugar/learning → sugarai-3.1.1.dev4/sugar/storage}/__init__.py +0 -0
- {sugarai-1.7.2/sugar/storage → sugarai-3.1.1.dev4/sugar/utils}/__init__.py +0 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/utils/git_operations.py +0 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugar/workflow/__init__.py +0 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugarai.egg-info/dependency_links.txt +0 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugarai.egg-info/entry_points.txt +0 -0
- {sugarai-1.7.2 → sugarai-3.1.1.dev4}/sugarai.egg-info/top_level.txt +0 -0
- {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.
|