Skip to content

Commit dba90bb

Browse files
mfittkoclaude
mfittko
and
claude
committed
Initial open source repository setup (Phase 0 Complete)
✅ Phase 0: Repository & Documentation Foundation This commit establishes the complete foundation for the Agents CLI project, a multi-agent workflow engine optimized for agentic IDE integration using the OpenAI Agents SDK. ## 📋 Key Components Added: ### Open Source Foundation - MIT License with proper copyright attribution - Comprehensive SECURITY.md for vulnerability reporting - CONTRIBUTING.md with development guidelines and phase structure - Professional README.md with badges, examples, and roadmap ### GitHub Repository Setup - Issue templates: bug reports, feature requests, IDE integration - Pull request template with security and phase alignment checks - Basic CI workflow for repository validation - .gitignore configured for Node.js/TypeScript development ### Documentation Site (Jekyll/GitHub Pages) - Complete Jekyll configuration for GitHub Pages - Documentation structure: getting-started, guides, api, examples - Homepage with project overview and navigation - Installation and IDE integration guide placeholders ### Project Architecture - Comprehensive Product Requirements Document (PRD.md) - OpenAI Agents SDK knowledge base (AGENTS.md) with detailed documentation - Phase 0 and Phase 1 task breakdowns with 70+ detailed implementation tasks - Source code structure: src/{cli,config,agents,mcp,tools,security,workflows} ### Development Structure - TypeScript project foundation with organized src/ directory - Testing structure: tests/{unit,integration,fixtures} - Examples directory for workflow configurations - Comprehensive .gitignore for security and development ## 🚀 Next Steps: Phase 1 Development Phase 0 provides the complete foundation for Phase 1 core development: - CLI interface with Commander.js - MCP server for IDE integration - Configuration system with Zod validation - OpenAI Agents SDK integration - Security framework with tool sandboxing ## 📚 Documentation References - Project Requirements: docs/PRD.md - OpenAI SDK Knowledge: AGENTS.md - Phase 0 Tasks: docs/tasks/phase0.md - Phase 1 Tasks: docs/tasks/phase1.md - Contributing Guide: CONTRIBUTING.md This foundation enables collaborative open source development with comprehensive documentation, security practices, and clear implementation phases. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
0 parents  commit dba90bb

30 files changed

+8673
-0
lines changed

‎.cursor/commands/multi_agent_workflow.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Multi-Agent Decision Session Blueprint
2+
3+
Use this template when kicking off a structured collaboration between multiple personas inside Cursor. It pairs well with the shared rules in `.cursor/rules/multi_agent_guidelines.mdc`.
4+
5+
## Purpose
6+
Provide a repeatable command that guides two or more expert personas through iterative review/refinement of a target artifact (e.g., spec, PRD, architecture doc) until it is stakeholder-ready.
7+
8+
## How to Use
9+
1. Update the **Context** section before running (repository, files of interest, problem statement).
10+
2. List the personas you want to involve; each persona should have a clear responsibility.
11+
3. Copy the final prompt block into Cursor’s command runner (or invoke via saved command) to start the session. The command automatically inherits any rules placed in `.cursor/rules/`, so enable `multi_agent_guidelines.mdc` when you want the Observe→Reason→Adjust→Verify→Hand Off workflow enforced.
12+
4. To run the same session via the OpenAI CLI, wrap the command with `zsh -ic` so your shell aliases/environment load correctly:
13+
14+
```bash
15+
zsh -ic "openai api chat.completions.create \\ \\
16+
-m gpt-5 \\ \\
17+
-g system \"<system-guidance>\" \\ \\
18+
-g user \"<multi-agent prompt copied from this file>\" \\ \\
19+
--format json"
20+
```
21+
22+
Notes:
23+
- Replace `<system-guidance>` with the high-level instructions (e.g., "Enforce Observe→Reason→Adjust→Verify→Hand Off and alternate personas").
24+
- If your prompt contains quotes or newlines, pipe it through `sed -e 's/"/\\"/g'` (or similar) before interpolation to keep the JSON payload valid.
25+
- Escape backticks (`\``) by appending the sed expression -e 's/`/\\`/g' so zsh does not treat them as command substitution.
26+
- The `--format json` flag ensures the response is emitted as valid JSON; parse the `choices[0].message.content` field.
27+
- For multi-turn loops, capture the JSON, append follow-up messages with `-g assistant` / `-g user`, and rerun the command. Persist the conversation history in a `.jsonl` file if you need reproducibility.
28+
29+
5. For ad-hoc edits to the working prompt, use `sed` inline filters (chain multiple -e expressions like `sed -e 's/<placeholder>/<value>/g' -e 's/`/\\`/g'`) so the command stays copy/paste friendly and safe for shells.
30+
31+
## Context (edit as needed)
32+
- Artifact to refine: `<path/to/document>`
33+
- Goal: `<clear objective>`
34+
- Personas: `<Persona A>`, `<Persona B>`, `[optional Persona C]`
35+
36+
## Session Framework
37+
Each persona must follow a consistent loop during the session:
38+
- **Observe**: skim the next relevant portion of the artifact.
39+
- **Reason**: call out findings, risks, or gaps from their perspective.
40+
- **Adjust**: propose or make focused edits (append to the doc, insert TODOs, or note follow-ups).
41+
- **Verify**: restate the change and confirm it improves alignment with the goal.
42+
- **Hand Off**: direct the next persona toward the remaining open items.
43+
44+
Continue cycling personas until they jointly agree the artifact is ready for review. Document unresolved questions explicitly.
45+
46+
## Command Prompt
47+
Paste the following prompt when starting a session (replace placeholders first):
48+
49+
```
50+
You are coordinating a multi-persona working session. The personas are: <Persona A role>, <Persona B role>[, <Persona C role>]. Alternate between personas. On each turn, the active persona must Observe a small portion of <artifact>, Reason about issues or improvements, Adjust the document or add TODOs, Verify the outcome, then Hand Off to the next persona with explicit guidance. If automation scripts replay this prompt, assume inputs may be escaped/templated with `sed` (including backtick sanitization) and respond with well-formed JSON when requested. Repeat until the artifact meets the stated goal, then provide a joint summary and list outstanding questions.
51+
```
52+
53+
## Tips
54+
- Keep each turn scoped; do not rewrite the whole document at once.
55+
- Use callouts like `> TODO (Owner)` for follow-ups.
56+
- Encourage personas to reference relevant sections rather than general opinions.
57+
- Conclude only when all personas agree the objective is met.

‎.cursor/rules/multi_agent_guidelines.mdc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Multi-Agent Collaboration Guidelines
2+
3+
- Alternate personas every turn in the order defined by the active command.
4+
- Each persona’s turn must follow the **Observe → Reason → Adjust → Verify → Hand Off** pattern.
5+
- Keep edits focused on the referenced artifact; avoid unrelated commentary.
6+
- Mark follow-up work with `> TODO (Role)` and describe the needed action.
7+
- Ensure accessibility, performance, and security considerations are explicitly called out when relevant.
8+
- End the session only after every persona confirms the goal is met and outstanding questions are documented.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
name: Bug Report
2+
description: Report a bug or issue with Agents CLI
3+
title: "[Bug]: "
4+
labels: ["bug", "triage"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for taking the time to report a bug! Please fill out the information below to help us diagnose and fix the issue.
10+
11+
**⚠️ Security Note**: If this is a security vulnerability, please don't file a public issue. Instead, follow our [Security Policy](../../SECURITY.md).
12+
13+
- type: textarea
14+
id: description
15+
attributes:
16+
label: Bug Description
17+
description: A clear and concise description of what the bug is
18+
placeholder: Describe what happened and what you expected to happen
19+
validations:
20+
required: true
21+
22+
- type: textarea
23+
id: reproduction
24+
attributes:
25+
label: Steps to Reproduce
26+
description: Detailed steps to reproduce the issue
27+
placeholder: |
28+
1. Run `agents-cli run --config example.json`
29+
2. Enter input "Review this code"
30+
3. See error message...
31+
validations:
32+
required: true
33+
34+
- type: textarea
35+
id: expected
36+
attributes:
37+
label: Expected Behavior
38+
description: What you expected to happen
39+
validations:
40+
required: true
41+
42+
- type: textarea
43+
id: actual
44+
attributes:
45+
label: Actual Behavior
46+
description: What actually happened instead
47+
validations:
48+
required: true
49+
50+
- type: dropdown
51+
id: component
52+
attributes:
53+
label: Component
54+
description: Which component is affected?
55+
options:
56+
- CLI Interface
57+
- MCP Server
58+
- Configuration System
59+
- Security Framework
60+
- Tool Integration
61+
- Workflow Engine
62+
- OpenAI SDK Integration
63+
- Documentation
64+
- Other
65+
validations:
66+
required: true
67+
68+
- type: textarea
69+
id: environment
70+
attributes:
71+
label: Environment
72+
description: Information about your environment
73+
value: |
74+
- OS:
75+
- Node.js version:
76+
- Agents CLI version:
77+
- IDE:
78+
- OpenAI SDK version:
79+
validations:
80+
required: true
81+
82+
- type: textarea
83+
id: config
84+
attributes:
85+
label: Configuration
86+
description: Your workflow configuration (remove any sensitive data like API keys)
87+
render: json
88+
placeholder: |
89+
{
90+
"agents": {
91+
"code_reviewer": {
92+
"name": "Code Reviewer",
93+
"instructions": "Review code for issues",
94+
"model": "gpt-4o"
95+
}
96+
}
97+
}
98+
99+
- type: textarea
100+
id: logs
101+
attributes:
102+
label: Logs
103+
description: Relevant logs or error messages (make sure to redact any API keys or sensitive information)
104+
render: text
105+
placeholder: Paste error logs here
106+
107+
- type: checkboxes
108+
id: checklist
109+
attributes:
110+
label: Pre-submission Checklist
111+
options:
112+
- label: I have checked that this issue hasn't already been reported
113+
required: true
114+
- label: I have redacted any sensitive information (API keys, credentials, etc.)
115+
required: true
116+
- label: I have provided enough information to reproduce the issue
117+
required: true
118+
- label: I have tested with the latest version
119+
required: false

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
name: Feature Request
2+
description: Suggest a new feature or enhancement for Agents CLI
3+
title: "[Feature]: "
4+
labels: ["enhancement", "triage"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thanks for suggesting a new feature! Please provide as much detail as possible to help us understand and evaluate your request.
10+
11+
**📋 Note**: Check our [Phase Documentation](../../docs/tasks/) to see if your feature is already planned for future phases.
12+
13+
- type: textarea
14+
id: problem
15+
attributes:
16+
label: Problem Statement
17+
description: What problem does this feature solve? What's the current limitation?
18+
placeholder: I'm frustrated when...
19+
validations:
20+
required: true
21+
22+
- type: textarea
23+
id: solution
24+
attributes:
25+
label: Proposed Solution
26+
description: Describe the feature you'd like to see implemented
27+
placeholder: I'd like to be able to...
28+
validations:
29+
required: true
30+
31+
- type: dropdown
32+
id: component
33+
attributes:
34+
label: Component
35+
description: Which component would this feature affect?
36+
options:
37+
- CLI Interface
38+
- MCP Server
39+
- Configuration System
40+
- Security Framework
41+
- Tool Integration
42+
- Workflow Engine
43+
- OpenAI SDK Integration
44+
- Documentation
45+
- IDE Integration
46+
- Other
47+
validations:
48+
required: true
49+
50+
- type: dropdown
51+
id: priority
52+
attributes:
53+
label: Priority
54+
description: How important is this feature to you?
55+
options:
56+
- Nice to have
57+
- Would be helpful
58+
- Important for my use case
59+
- Critical for adoption
60+
validations:
61+
required: true
62+
63+
- type: textarea
64+
id: use_case
65+
attributes:
66+
label: Use Case
67+
description: Describe a specific scenario where this feature would be useful
68+
placeholder: |
69+
When I'm working on a large codebase, I need to...
70+
validations:
71+
required: true
72+
73+
- type: textarea
74+
id: alternatives
75+
attributes:
76+
label: Alternatives Considered
77+
description: What workarounds or alternative solutions have you considered?
78+
placeholder: I could work around this by...
79+
80+
- type: textarea
81+
id: example
82+
attributes:
83+
label: Example Implementation
84+
description: If you have ideas about how this might work, share them here
85+
placeholder: |
86+
# CLI Usage
87+
agents-cli run --config my-workflow.json --new-feature
88+
89+
# Configuration
90+
{
91+
"new_feature": {
92+
"option": "value"
93+
}
94+
}
95+
96+
- type: dropdown
97+
id: breaking
98+
attributes:
99+
label: Breaking Change
100+
description: Would this require breaking changes to existing APIs?
101+
options:
102+
- No breaking changes needed
103+
- Minor breaking changes acceptable
104+
- Major breaking changes required
105+
- Not sure
106+
107+
- type: checkboxes
108+
id: checklist
109+
attributes:
110+
label: Pre-submission Checklist
111+
options:
112+
- label: I have searched existing issues and feature requests
113+
required: true
114+
- label: I have checked the phase documentation for planned features
115+
required: true
116+
- label: I have provided a clear use case and problem statement
117+
required: true

0 commit comments

Comments
 (0)