# Contributing

## Contributing to Assemble

Assemble is an open-source project, and contributions are welcome. Here’s how to get involved.

## Ways to contribute

| Type                    | Description                                             | Difficulty |
|-------------------------|---------------------------------------------------------|------------|
| Bug reports             | Report issues with agents, workflows, or generation     | Easy       |
| Agent improvements      | Improve an existing agent’s prompt or behavior          | Medium     |
| New agents              | Create a new specialized agent                           | Medium     |
| Platform adapters       | Add support for a new AI coding tool                     | Medium-Hard|
| Workflow improvements    | Improve or add workflows                                  | Medium     |
| Documentation          | Fix or improve docs                                     | Easy       |
| Core engine            | Work on the generation engine                             | Hard       |

## Development setup

### Prerequisites

- Node.js >= 18
- Git
- An AI coding tool (Cursor, Claude Code, etc.) for testing

### Getting started

```
# Clone the repository

git clone https://github.com/CohesiumAI/assemble.git

cd assemble

# Install dependencies

npm install

# Run the test suite

npm test

# Run the development server (for the landing page)

npm run dev
```

### Project structure

```
assemble/

├── src/
│   ├── agents/          # Agent definitions (Markdown)
│   ├── workflows/       # Workflow definitions (YAML)
│   ├── adapters/        # Platform adapters
│   ├── engine/          # Core generation engine
│   └── cli/             # CLI tool
├── tests/               # Test suites
├── docs/                # Documentation (this site)
└── landing/             # Landing page (Astro)
```

## Contributing agents

### Improving an existing agent

1. Find the agent file in `src/agents/`
2. Identify the improvement (better instructions, new anti-patterns, updated stack)
3. Make your changes
4. Test with real requests in your AI coding tool
5. Submit a PR with before/after examples

### Creating a new agent

1. Copy an existing agent as a template
2. Follow the [Custom Agents guide](/content/docs/guides/custom-agents/index.html) for the structure
3. Add routing keywords in `src/routing/domain-map.ts`
4. Add the agent to the team registry
5. Test thoroughly with real requests
6. Submit a PR with usage examples

## Contributing workflows

1. Create a YAML file following the [workflow structure](/content/docs/concepts/workflows/index.html)
2. Verify all referenced agents exist
3. Test the complete workflow end-to-end
4. Submit a PR with a description of when to use this workflow

## Contributing platform adapters

1. Research the platform’s configuration format
2. Create an adapter in `src/adapters/`
3. Implement the `generate()` method that produces the platform-native file
4. Add tests
5. Submit a PR with a sample generated file

## Code guidelines

### Commit messages

Follow [Conventional Commits](https://www.conventionalcommits.org/):

```
feat(agent): improve spider-man's accessibility guidelines

fix(adapter): handle special characters in cursor rules

docs: add YOLO mode examples
```

### Pull request process

1. Create a branch: `feat/my-feature` or `fix/my-bug`
2. Make your changes with clear commits
3. Ensure tests pass: `npm test`
4. Submit a PR with:
   - Description of the change
   - Motivation (why this change)
   - Testing done
   - Before/after examples (for agent changes)

### Code style

- TypeScript strict mode
- ESLint + Prettier (auto-formatted on save)
- Agent Markdown files follow the standard structure

## Testing

### Agent testing

Test agents by giving them real prompts and evaluating the output quality:

```
# Run agent evaluation suite

npm run test:agents

# Test a specific agent

npm run test:agent -- --name spider-man
```

### Adapter testing

```
# Generate files and compare with snapshots

npm run test:adapters
```

### E2E testing

```
# Full generation pipeline test

npm run test:e2e
```

## Community

- **GitHub Issues**: Bug reports and feature requests
- **GitHub Discussions**: Questions, ideas, and show-and-tell
- **Discord**: Real-time chat with the community

## Code of Conduct

We follow the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) Code of Conduct. Be respectful, inclusive, and constructive.

## License

Assemble is licensed under the [MIT License](https://github.com/CohesiumAI/assemble/blob/main/LICENSE). By contributing, you agree that your contributions will be licensed under the same terms.