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 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
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:

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 Code of Conduct. Be respectful, inclusive, and constructive.

License

Assemble is licensed under the MIT License. By contributing, you agree that your contributions will be licensed under the same terms.