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.