Skip to content

Commit 7cbec8f

Browse files
drewdrewthisdrewdrewthis
authored
feat: add release please (#26)
* fix: update husky hooks for v9 compatibility and install missing commitlint * fix: convert commitlint config to ES module syntax for type: module compatibility * fix: remove prettier from CI and lint-staged, use eslint only for formatting * fix: remove duplicate @types/node dependency * docs: reorganize documentation into docs/ directory with CAPITAL file naming * chore: add image * chore: update rule * chore: move changelog back * feat: add release-please configuration with prerelease support - Configure release-please for Node.js prerelease management - Add release-please manifest and repo metadata files - Update CI workflow to handle prerelease branches (main/develop) - Create release workflow for automatic publishing - Remove semantic-release dependencies and scripts - Set up beta releases from develop branch
1 parent f31da71 commit 7cbec8f

22 files changed

+4890
-147
lines changed

‎.cursor/rules/coding-guidelines.mdc‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,5 @@ DIRECTIVES:
1717
- Classes should be small
1818
- functions, classes, methods should have TSDoc with example usage
1919
- top-level directories represent core features, and should each have a README.md that describes the feature and its purpose.
20-
- Never use .js extensions in import statements
20+
- Never use .js extensions in import statements
21+
- Always use package init commands rather than writing configs manually (e.g., use `npx eslint --init` or `pnpm exec husky init` instead of creating config files directly)

‎.cursor/rules/docs-directory.mdc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: When writing documentation for the repository
3+
alwaysApply: false
4+
---
5+
DIRECTIVES:
6+
- Documentation directories should be named "docs" (lowercase)
7+
- Documentation files should use CAPITAL LETTERS with hyphens (e.g., GETTING-STARTED.md, CONTRIBUTING.md)
8+
- This follows the convention of treating documentation as a special top-level concern
9+
- Apply this to any new documentation directories created in the project

‎.github/workflows/ci.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main, develop]
6+
pull_request:
7+
branches: [main, develop]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
node-version: [18, 20, 22]
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- name: Setup pnpm
19+
uses: pnpm/action-setup@v4
20+
with:
21+
version: 10.15.0
22+
23+
- name: Setup Node.js ${{ matrix.node-version }}
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: ${{ matrix.node-version }}
27+
cache: "pnpm"
28+
29+
- name: Install dependencies
30+
run: pnpm install --frozen-lockfile
31+
32+
- name: Type check
33+
run: pnpm typecheck
34+
35+
- name: Lint
36+
run: pnpm lint
37+
38+
- name: Build
39+
run: pnpm build
40+
41+
- name: Run unit tests
42+
run: pnpm test:ci
43+
44+
- name: Run E2E tests
45+
run: pnpm test:e2e
46+
47+
release-please:
48+
runs-on: ubuntu-latest
49+
if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop'
50+
steps:
51+
- uses: actions/checkout@v4
52+
with:
53+
fetch-depth: 0
54+
55+
- name: Run release-please
56+
uses: googleapis/release-please-action@v4
57+
with:
58+
token: ${{ secrets.GITHUB_TOKEN }}
59+
prerelease: ${{ github.ref == 'refs/heads/develop' }}

‎.github/workflows/release.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
release:
10+
runs-on: ubuntu-latest
11+
# Only run if this is a release commit created by release-please
12+
if: contains(github.event.head_commit.message, 'chore: release')
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Setup pnpm
17+
uses: pnpm/action-setup@v4
18+
with:
19+
version: 10.15.0
20+
21+
- name: Setup Node.js
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: "22"
25+
cache: "pnpm"
26+
registry-url: "https://registry.npmjs.org"
27+
28+
- name: Install dependencies
29+
run: pnpm install --frozen-lockfile
30+
31+
- name: Build
32+
run: pnpm build
33+
34+
- name: Release
35+
run: |
36+
if [[ "${{ github.event.head_commit.message }}" == *"beta"* ]]; then
37+
npm publish --tag beta
38+
else
39+
npm publish
40+
fi
41+
env:
42+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,5 @@
11
# Dependencies
22
node_modules/
3-
pnpm-lock.yaml
4-
package-lock.json
5-
yarn.lock
63

74
# Build output
85
dist/

‎.husky/commit-msg‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pnpm commitlint --edit $1

‎.husky/pre-commit‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pnpm test:ci

‎.release-please-manifest.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
".": "0.1.0-beta.0"
3+
}

‎.repo-metadata.json‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"release_type": "node",
3+
"separate_pull_requests": false,
4+
"prerelease": true,
5+
"changelog_sections": [
6+
{ "type": "feat", "section": "Features" },
7+
{ "type": "fix", "section": "Bug Fixes" },
8+
{ "type": "chore", "section": "Chores" },
9+
{ "type": "docs", "section": "Documentation" },
10+
{ "type": "style", "section": "Styles" },
11+
{ "type": "refactor", "section": "Code Refactoring" },
12+
{ "type": "perf", "section": "Performance Improvements" },
13+
{ "type": "test", "section": "Tests" }
14+
]
15+
}

‎README.md‎

Lines changed: 12 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,12 @@
1+
![](/images/cover-image.png)
2+
13
# Superagents
24

35
Superagents is a CLI tool and a set of standards for agent building.
46

5-
It supercharges your coding assistant (Claude Code, Cursor, etc), making it an expert in any agent framework you choose (Agno, Mastra, etc) and all their best practices, being able to autodiscover MCP tools to augment your agent.
6-
7-
The Superagent Structure and AGENTS.md ensures industry best practices, making your agent ready for production:
8-
- [Scenario](https://github.com/langwatch/scenario) agent tests written for every feature to ensure agent behaviour
9-
- Versioning of the prompts for collaboration
10-
- Evaluation notebooks for measuring specific prompts performance
11-
- Already instrumented for full observability
12-
- Standardization of structure for better project maintainability
13-
14-
15-
### The Superagent Structure
16-
17-
```
18-
my-agent-project/
19-
├── app/ (or src/) # The actual agent code, structured according to the chosen framework
20-
├── tests/
21-
│ ├── evaluations/ # Jupyter notebooks for evaluations
22-
│ │ └── example_eval.ipynb
23-
│ └── scenarios/ # End-to-end scenario tests
24-
│ └── example_scenario.test.{py,ts}
25-
├── prompts/ # Versioned prompt files for team collaboration
26-
│ └── sample_prompt.yaml
27-
├── prompts.json # Prompt registry
28-
├── .mcp.json # MCP server configuration
29-
├── AGENTS.md # Development guidelines
30-
├── .env # Environment variables
31-
└── .gitignore
32-
```
33-
34-
The structure and guidelines on `AGENTS.md` ensure every new feature required for the coding assistant is properly tested, evaluated, and that the prompts are versioned.
35-
36-
The `.mcp.json` comes with all the right MCPs set up so you coding assistant becomes an expert in your framework of choice and know where to find new tools.
7+
It supercharges your coding assistant (Claude Code, Cursor, Kilocode, etc), making it an expert in any agent framework you choose (Agno, Mastra, etc) and all their best practices, being able to autodiscover MCP tools to augment your agent.
378

38-
[`scenarios/`](https://github.com/langwatch/scenario) tests guarantee the agent behaves as expected, which simulates a conversation with the agent making sure it does what expected.
39-
40-
`evaluations/` notebooks holds dataset and notebooks for evaluating pieces of your agent pipeline such as a RAG or classification tasks it must do
41-
42-
Finally, `prompts/` hold all your versioned prompts in yaml format, synced and controlled by `prompts.json`, to allow for playground and team collaboration.
9+
The Superagent Structure ensures industry best practices, making your agent ready for production with proper testing, observability, and prompt management.
4310

4411
## Installation
4512

@@ -55,9 +22,13 @@ npx @langwatch/superagents init my-agent-project
5522

5623
## Documentation
5724

58-
- **[Quick Start](QUICKSTART.md)** - Get started in 2 minutes
59-
- **[Walkthrough](examples/WALKTHROUGH.md)** - Detailed step-by-step guide
60-
- **[Contributing](CONTRIBUTING.md)** - How to contribute to Superagents
25+
- **[Getting Started](docs/GETTING-STARTED.md)** - Quick start guide (2 minutes)
26+
- **[Walkthrough](docs/WALKTHROUGH.md)** - Detailed step-by-step guide
27+
- **[Project Structure](docs/STRUCTURE.md)** - Understanding the Superagent structure
28+
- **[Features](docs/FEATURES.md)** - Key features and capabilities
29+
- **[Usage](docs/USAGE.md)** - CLI usage and examples
30+
- **[Philosophy](docs/PHILOSOPHY.md)** - Agent Testing Pyramid approach
31+
- **[Contributing](docs/CONTRIBUTING.md)** - How to contribute to Superagents
6132
- **[Changelog](CHANGELOG.md)** - Version history
6233

6334
## Usage
@@ -72,54 +43,7 @@ superagents init .
7243
superagents init my-awesome-agent
7344
```
7445

75-
The CLI will guide you through:
76-
77-
1. **Programming Language**: Python or TypeScript
78-
2. **Agent Framework**: Agno (Python) or Mastra (TypeScript)
79-
3. **Coding Assistant**: Claude Code, Cursor, Kilocode CLI, or None (manual prompt)
80-
4. **LLM Provider**: OpenAI, Anthropic, Gemini, Bedrock, OpenRouter, or Grok
81-
5. **API Keys**: LLM Provider and LangWatch (required), Smithery (optional)
82-
6. **Project Goal**: What you want to build
83-
84-
## Philosophy
85-
86-
Superagents promotes the **Agent Testing Pyramid** approach:
87-
88-
1. **Unit Tests** - Test deterministic components
89-
2. **Evals & Optimization** - Measure and optimize probabilistic components
90-
3. **Simulations** - End-to-end validation with Scenario
91-
92-
Learn more: https://scenario.langwatch.ai/best-practices/the-agent-testing-pyramid
93-
94-
## Key Features
95-
96-
### 🎯 Framework Integration
97-
98-
- **Agno**: Automatically downloads `.cursorrules` and `llms.txt`
99-
- **Mastra**: Configures Mastra MCP for real-time documentation
100-
101-
### 🧪 LangWatch Integration
102-
103-
- **Prompt CLI**: Manage versioned prompts
104-
- **Scenario Testing**: End-to-end agent testing
105-
- **Evaluations**: Measure component performance
106-
- **MCP Server**: Expert guidance built into your coding assistant
107-
108-
### 🔧 MCP Tool Integration
109-
110-
- **Smithery Toolbox** (optional): When you provide a Smithery API key during setup, your coding agent gets automatic access to MCP tools for enhanced capabilities
111-
- Auto-configured in `.mcp.json` for seamless integration
112-
- Your coding assistant can discover and use tools to help build your agent
113-
114-
### 🤖 Coding Assistant Setup
115-
116-
Your coding assistant (e.g., Claude Code, Cursor, Kilocode CLI) is:
117-
- **Automatically launched** after project setup with initial prompt
118-
- Pre-configured with framework-specific knowledge (via MCP or docs)
119-
- Loaded with LangWatch best practices
120-
- Equipped with prompt management expertise
121-
- Set up with testing methodologies
122-
- Auto-detected - the CLI shows which assistants are installed on your system
46+
The CLI will guide you through selecting your programming language, agent framework, coding assistant, LLM provider, and API keys.
12347

12448
## Requirements
12549

@@ -134,53 +58,6 @@ Your coding assistant (e.g., Claude Code, Cursor, Kilocode CLI) is:
13458
- LangWatch API key (get one at https://app.langwatch.ai/authorize)
13559
- Smithery API key (optional - for MCP tool auto-discovery, get one at https://smithery.ai/account/api-keys)
13660

137-
## Development
138-
139-
```bash
140-
# Clone the repo
141-
git clone https://github.com/langwatch/superagents
142-
cd superagents
143-
144-
# Install dependencies
145-
pnpm install
146-
147-
# Run in development
148-
pnpm dev init test-project
149-
150-
# Build
151-
pnpm build
152-
```
153-
154-
## Examples
155-
156-
### Python + Agno
157-
158-
```bash
159-
superagents init trading-agent
160-
# Select: Python, Agno, your preferred coding assistant, OpenAI
161-
# Goal: "Build an agent that can analyze stock prices and provide trading recommendations"
162-
```
163-
164-
### TypeScript + Mastra
165-
166-
```bash
167-
superagents init customer-support
168-
# Select: TypeScript, Mastra, your preferred coding assistant, OpenAI
169-
# Goal: "Build a customer support agent that can handle common queries and escalate complex issues"
170-
```
171-
172-
### Coding Assistant Auto-Launch
173-
174-
After project setup completes, Superagents **automatically launches** your chosen coding assistant with a customized initial prompt that includes:
175-
- Your project goal
176-
- Framework-specific context
177-
- Best practices guidance
178-
- Next steps to get started
179-
180-
The CLI detects which coding assistants are installed on your system and shows installed options first in the selection menu. Not installed assistants appear in gray with "(not installed)" but can still be selected.
181-
182-
You can also select **"None - I will prompt it myself"** if you prefer to manually launch your coding assistant later with the provided initial prompt.
183-
18461
## Resources
18562

18663
- [LangWatch](https://langwatch.ai)
@@ -193,11 +70,6 @@ You can also select **"None - I will prompt it myself"** if you prefer to manual
19370

19471
MIT
19572

196-
## Contributing
197-
198-
Contributions are welcome! Please open an issue or submit a pull request.
199-
20073
---
20174

20275
Built with ❤️ by the LangWatch team
203-

0 commit comments

Comments
 (0)