Skip to content

Commit 686c942

Browse files
GSMLG-BOTGSMLG-BOT
committed
feat: implement comprehensive Open Code Agents CLI tool with multi-agent workflow orchestration
- Add complete Go application structure with CLI interface - Implement 8 specialized agents (Architect, Implementer, Tester, Debugger, Reviewer, Refactorer, Documenter, Researcher) - Create workflow orchestration system for automated development tasks - Add agent management and installation system - Include embedded agent definitions and resource management - Provide comprehensive documentation and usage examples - Support both user-wide and project-specific installation scopes - Add interactive CLI menus and command structure
1 parent 8658c5a commit 686c942

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+9493
-1
lines changed

‎README.md‎

Lines changed: 188 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,192 @@
11
# Open Code Agents
22

3-
This project is for common opensource code agent use case.
3+
A CLI tool for managing specialized AI agents that automate software development workflows. This project provides a structured way to orchestrate different AI personas (Architect, Implementer, Tester, etc.) for various development tasks.
44

5+
## Features
56

7+
- **Agent Management**: Install and manage specialized AI agents
8+
- **Workflow Orchestration**: Execute multi-agent workflows for common development tasks
9+
- **Interactive CLI**: User-friendly command-line interface
10+
- **Scope-based Installation**: User-wide or project-specific agent installations
11+
- **Configuration Management**: Persistent settings and preferences
12+
13+
## Quick Start
14+
15+
### Installation
16+
17+
```bash
18+
# Build from source
19+
go build ./cmd/opencode-setup
20+
21+
# Or use the provided binary
22+
./opencode-setup
23+
```
24+
25+
### Basic Usage
26+
27+
```bash
28+
# List available agents and workflows
29+
./opencode-setup commands list
30+
31+
# Execute a specific agent
32+
./opencode-setup commands execute implementer
33+
34+
# Run a predefined workflow
35+
./opencode-setup commands workflow
36+
37+
# Interactive agent management
38+
./opencode-setup agents
39+
```
40+
41+
## Available Agents
42+
43+
| Agent | Role | Description |
44+
|-------|------|-------------|
45+
| **Architect** | System Design | High-level architectural planning and design decisions |
46+
| **Implementer** | Code Development | Writes production-quality code based on specifications |
47+
| **Tester** | Quality Assurance | Creates comprehensive test suites |
48+
| **Debugger** | Issue Resolution | Analyzes and fixes bugs in code |
49+
| **Reviewer** | Code Review | Evaluates code quality and adherence to standards |
50+
| **Refactorer** | Code Improvement | Improves code structure and maintainability |
51+
| **Documenter** | Documentation | Creates comprehensive documentation |
52+
| **Researcher** | Investigation | Researches technologies and solutions |
53+
54+
## Predefined Workflows
55+
56+
### New Feature Development
57+
```bash
58+
./opencode-setup commands workflow
59+
# Select "new-feature"
60+
# Provide context: feature_description="Add user authentication"
61+
```
62+
**Sequence**: Researcher → Architect → Implementer → Tester → Reviewer → Documenter
63+
64+
### Bug Fix
65+
```bash
66+
./opencode-setup commands workflow
67+
# Select "bug-fix"
68+
# Provide context: bug_description="Login fails with valid credentials"
69+
```
70+
**Sequence**: Debugger → Implementer → Tester → Reviewer
71+
72+
### Code Improvement
73+
```bash
74+
./opencode-setup commands workflow
75+
# Select "code-improvement"
76+
# Provide context: code_location="src/auth/"
77+
```
78+
**Sequence**: Refactorer → Tester → Reviewer
79+
80+
## Installation Scopes
81+
82+
### User Scope
83+
- Location: `~/.config/opencode/`
84+
- Available to all projects
85+
- Ideal for commonly used agents
86+
87+
### Project Scope
88+
- Location: `.opencode/` in project root
89+
- Project-specific agents and configurations
90+
- Version controlled with project
91+
92+
## Configuration
93+
94+
Configuration is stored in JSON format at:
95+
- User: `~/.config/opencode/config.json`
96+
- Project: `.opencode/config.json`
97+
98+
Example configuration:
99+
```json
100+
{
101+
"default_agent": "implementer",
102+
"workflows": {
103+
"my-feature": "new-feature"
104+
},
105+
"settings": {
106+
"log_level": "info",
107+
"auto_save": true,
108+
"show_hints": true,
109+
"max_history": 100
110+
}
111+
}
112+
```
113+
114+
## Development
115+
116+
### Project Structure
117+
```
118+
├── cmd/opencode-setup/ # Main CLI application
119+
├── pkg/
120+
│ ├── agent/ # Agent execution engine
121+
│ ├── cli/ # CLI commands and menus
122+
│ ├── config/ # Configuration management
123+
│ ├── installer/ # Agent installation system
124+
│ ├── interactive/ # Interactive UI components
125+
│ ├── orchestrator/ # Workflow orchestration
126+
│ └── resources/ # Embedded agent definitions
127+
├── agents/ # Agent definition files
128+
└── embed/ # Embedded resources
129+
```
130+
131+
### Building and Testing
132+
133+
```bash
134+
# Build the application
135+
go build ./cmd/opencode-setup
136+
137+
# Run tests
138+
go test ./...
139+
140+
# Run specific package tests
141+
go test ./pkg/agent
142+
go test ./pkg/orchestrator
143+
```
144+
145+
### Adding New Agents
146+
147+
1. Create agent definition in `agents/` directory
148+
2. Follow the established template format
149+
3. Include role, responsibilities, workflow sections
150+
4. Update agent resource parsing if needed
151+
5. Add tests for the new agent
152+
153+
### Creating Custom Workflows
154+
155+
```go
156+
// Define workflow in pkg/orchestrator/workflow.go
157+
customWorkflow := orchestrator.Workflow{
158+
Name: "custom-workflow",
159+
Description: "Custom workflow for specific needs",
160+
Steps: []orchestrator.WorkflowStep{
161+
{
162+
AgentName: "researcher",
163+
Input: "Research {{topic}}",
164+
Required: true,
165+
},
166+
{
167+
AgentName: "implementer",
168+
Input: "Implement based on research: {{last_output}}",
169+
Required: true,
170+
},
171+
},
172+
}
173+
```
174+
175+
## Contributing
176+
177+
1. Fork the repository
178+
2. Create a feature branch
179+
3. Add tests for new functionality
180+
4. Ensure all tests pass
181+
5. Submit a pull request
182+
183+
## License
184+
185+
This project is open source. See LICENSE file for details.
186+
187+
## Support
188+
189+
For issues and questions:
190+
- Check the documentation
191+
- Review existing issues
192+
- Create new issue with detailed description

‎cmd/opencode-setup/main.go‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
package main
2+
3+
import (
4+
"os"
5+
6+
"github.com/gsmlg-dev/open-code-agents/pkg/cli"
7+
)
8+
9+
func main() {
10+
rootCmd := cli.NewRootCommand()
11+
12+
if err := rootCmd.Execute(); err != nil {
13+
os.Exit(1)
14+
}
15+
}

‎embed/agents/README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Agents
2+
3+
## Overview
4+
5+
Agents are specialized AI personas designed to handle specific aspects of software development. Each agent has a well-defined role, set of responsibilities, and workflow that makes it expert in its domain.
6+
7+
## What Are Agents?
8+
9+
Agents represent different "hats" that developers wear during software development. They embody:
10+
11+
- **Expertise**: Deep knowledge in a specific domain (architecture, testing, debugging, etc.)
12+
- **Focus**: Single responsibility principle - each agent does one thing well
13+
- **Workflow**: Structured approach to completing their specialized tasks
14+
- **Collaboration**: Ability to hand off work to other agents and provide context
15+
16+
## Available Agents
17+
18+
| Agent | Role | Primary Use Case |
19+
|-------|------|------------------|
20+
| [Architect](./architect.md) | System design and architecture | Designing new features, system structure, technical decisions |
21+
| [Implementer](./implementer.md) | Code writing and feature implementation | Writing new code, implementing designs, building features |
22+
| [Tester](./tester.md) | Test creation and validation | Writing unit/integration tests, test strategies |
23+
| [Debugger](./debugger.md) | Bug investigation and resolution | Finding root causes, fixing bugs, troubleshooting |
24+
| [Refactorer](./refactorer.md) | Code improvement and optimization | Improving code quality, refactoring, performance tuning |
25+
| [Documenter](./documenter.md) | Documentation and knowledge sharing | Writing docs, API documentation, code comments |
26+
| [Reviewer](./reviewer.md) | Code review and quality assurance | Reviewing code, ensuring quality, catching issues |
27+
| [Researcher](./researcher.md) | Investigation and exploration | Researching libraries, patterns, technologies |
28+
29+
## When to Use Which Agent
30+
31+
### Starting a New Project or Feature
32+
1. **Unclear requirements or technology?** → Start with **Researcher**
33+
2. **Clear requirements, need design?** → Start with **Architect**
34+
3. **Small, well-defined task?** → Start with **Implementer**
35+
36+
### Working with Existing Code
37+
1. **Bug or error?** → Start with **Debugger**
38+
2. **Code quality issues?** → Start with **Refactorer**
39+
3. **Missing tests?** → Start with **Tester**
40+
4. **Missing docs?** → Start with **Documenter**
41+
42+
### Quality Assurance
43+
1. **Need code review?** → Use **Reviewer**
44+
2. **Pre-commit check?** → Use **Reviewer** + **Tester**
45+
46+
## How Agents Work Together
47+
48+
Agents collaborate through **handoffs** - passing work and context from one agent to another. See [orchestration.md](../orchestration.md) for detailed workflow patterns.
49+
50+
### Common Workflows
51+
52+
**New Feature (Full Cycle)**
53+
```
54+
Researcher → Architect → Implementer → Tester → Reviewer → Documenter
55+
```
56+
57+
**Bug Fix**
58+
```
59+
Debugger → Implementer → Tester → Reviewer
60+
```
61+
62+
**Code Improvement**
63+
```
64+
Refactorer → Tester → Reviewer
65+
```
66+
67+
**Research & Prototype**
68+
```
69+
Researcher → Architect → Implementer → Reviewer
70+
```
71+
72+
## Agents and Skills
73+
74+
Agents leverage [skills](../skills/README.md) to perform their work. Skills represent reusable capabilities and knowledge domains that agents apply during their workflows.
75+
76+
For example:
77+
- **Implementer** uses language skills (JavaScript, Python) and framework skills (React, Django)
78+
- **Reviewer** uses code analysis skills and security skills
79+
- **Tester** uses test generation skills and framework testing skills
80+
81+
## Agents and Commands
82+
83+
[Commands](../commands/README.md) orchestrate multiple agents in pre-defined workflows. Commands are useful for:
84+
- Automating common multi-agent sequences
85+
- Ensuring consistent workflows
86+
- Reducing cognitive overhead
87+
88+
For example:
89+
- `/quick-implement` uses Implementer → Tester sequence
90+
- `/research-and-design` uses Researcher → Architect sequence
91+
92+
## Creating Custom Agents
93+
94+
To create a new specialized agent:
95+
96+
1. Use the [agent template](../templates/agents/agent-template.md)
97+
2. Define the agent's role, responsibilities, and workflow
98+
3. Identify required skills the agent needs
99+
4. Create example interactions
100+
5. Document handoff patterns with other agents
101+
6. Add the agent to this README's table
102+
103+
## Best Practices
104+
105+
### When Using Agents
106+
107+
1. **Start with the right agent**: Choose the agent that matches your current task
108+
2. **Provide context**: Give agents sufficient information to work effectively
109+
3. **Follow handoffs**: When an agent completes its work, follow its handoff recommendations
110+
4. **Trust specialization**: Let each agent focus on its domain of expertise
111+
5. **Iterate when needed**: Some workflows require multiple passes (e.g., Implementer ↔ Reviewer)
112+
113+
### When Creating Agents
114+
115+
1. **Single responsibility**: Each agent should have one clear purpose
116+
2. **Clear boundaries**: Define what the agent does and doesn't do
117+
3. **Structured workflow**: Provide step-by-step process
118+
4. **Integration points**: Document how the agent works with others
119+
5. **Skill references**: List skills the agent leverages
120+
121+
## Examples
122+
123+
See the [examples directory](../examples/README.md) for complete examples of agents in action:
124+
- [New Feature Development](../examples/workflows/new-feature-full.md)
125+
- [Bug Fix Workflow](../examples/workflows/bug-fix-workflow.md)
126+
- [Multi-Agent Collaboration](../examples/integrations/multi-agent-collab.md)
127+
128+
## Additional Resources
129+
130+
- [Orchestration Patterns](../orchestration.md) - Detailed agent coordination strategies
131+
- [Skills](../skills/README.md) - Capabilities agents leverage
132+
- [Commands](../commands/README.md) - Pre-built agent workflows
133+
- [Getting Started](../docs/getting-started.md) - Introduction to the system

0 commit comments

Comments
 (0)