Contributors Guide

How to contribute to SAM, CLIO, and ALICE.

Thinking about contributing to the Synthetic Autonomic Mind ecosystem? Whether you're fixing a bug, adding a feature, improving documentation, or sharing ideas, this is how. This guide covers everything you need to know to contribute effectively.

Ways to contribute: - Bug fixes: Find and fix issues - Features: Build new capabilities - Documentation: Improve guides and examples - Testing: Add tests and improve coverage - Ideas: Share feature requests and suggestions - UI/UX: Improve the interface - Tools: Create new MCP tools

What's covered: - Getting started with the codebase - Development workflow and best practices - Code style and conventions - Pull request process - Testing requirements - How to get help

Fixing typos, improving comments, or asking questions all help make the ecosystem better.

Table of Contents

  1. Code of Conduct
  2. Getting Started
  3. Development Workflow
  4. Code Style Guidelines
  5. Pull Request Process
  6. Issue Guidelines
  7. Testing Requirements
  8. Documentation

Code of Conduct

Our Pledge

We pledge to make participation in the Synthetic Autonomic Mind ecosystem a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Positive behavior includes: - Using welcoming and inclusive language - Being respectful of differing viewpoints - Gracefully accepting constructive criticism - Focusing on what is best for the community - Showing empathy towards other community members

Unacceptable behavior includes: - Trolling, insulting comments, and personal attacks - Public or private harassment - Publishing others' private information - Other conduct which could reasonably be considered inappropriate

Enforcement

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions that do not align with this Code of Conduct.

Getting Started

Prerequisites

Before contributing, ensure you have:

  • For SAM: macOS 14.0+ with Xcode 15.0+, familiarity with Swift and SwiftUI
  • For CLIO: Perl 5.32+, Git, any modern terminal (macOS/Linux/Windows)
  • For ALICE: Python 3.10+, PyTorch, FastAPI knowledge
  • Git configured with your GitHub account
  • Read the relevant SAM Developer's Guide, CLIO Documentation, or ALICE Documentation

Recommended Tool: - CLIO - Terminal AI assistant for efficient development workflow - Particularly helpful for code reviews, git operations, and quick iterations - Install: git clone https://github.com/SyntheticAutonomicMind/CLIO.git && cd CLIO && sudo ./install.sh

Fork and Clone

Choose the repository you want to contribute to:

# For SAM:
git clone https://github.com/YOUR_USERNAME/SAM.git
cd SAM

# For CLIO:
git clone https://github.com/YOUR_USERNAME/CLIO.git
cd CLIO

# For ALICE:
git clone https://github.com/YOUR_USERNAME/ALICE.git
cd ALICE

# Add upstream remote (example for SAM)
git remote add upstream https://github.com/SyntheticAutonomicMind/SAM.git

# Initialize submodules (if applicable)
git submodule update --init --recursive

Build and Test

Each project has its own build process:

# SAM
make build-debug
make test
open .build/Build/Products/Debug/SAM.app

# CLIO
./check-deps
./clio --new

# ALICE
pip install -r requirements.txt
python -m alice

If everything builds and tests pass, you're ready to contribute!

Development Workflow

1. Create a Branch

Always create a feature branch for your work:

# Update main
git checkout main
git pull upstream main

# Create feature branch
git checkout -b feature/my-new-feature

# Or for bug fixes:
git checkout -b fix/issue-123

Branch naming: - feature/ - New features - fix/ - Bug fixes - docs/ - Documentation changes - refactor/ - Code refactoring - test/ - Test additions

2. Make Changes

  • Write clean, readable code
  • Follow the project's style guidelines (below)
  • Add tests for new functionality
  • Update documentation if needed
  • Follow the Unbroken Method - investigate first, complete ownership, structured handoffs

3. Commit Changes

Use conventional commit format:

git add .
git commit -m "type(scope): description

- Detail 1
- Detail 2

Fixes #123"

Commit types: - feat: New feature - fix: Bug fix - docs: Documentation - test: Tests - refactor: Code refactoring - perf: Performance improvement - chore: Maintenance

Examples:

git commit -m "feat(tools): Add new web scraping tool"
git commit -m "fix(ui): Fix conversation list crash on delete"
git commit -m "docs: Update API reference for streaming"

4. Push and Create PR

# Push to your fork
git push origin feature/my-new-feature

# Create pull request on GitHub
# Visit the appropriate repo's compare page

Code Style Guidelines

Swift Style (SAM)

SAM follows Swift standard conventions with some additions:

1. Naming

// [OK] Good: Clear, descriptive names
class ConversationManager { }
func sendMessage(_ text: String) { }

// [AVOID] Vague names
class Manager { }
func doIt() { }

2. Async/Await

// [OK] Structured concurrency
func fetchConversations() async throws -> [Conversation] {
    try await service.getConversations()
}

// [OK] Task groups for parallel work
func loadAllData() async throws {
    try await withThrowingTaskGroup(of: Void.self) { group in
        group.addTask { try await loadConversations() }
        group.addTask { try await loadModels() }
        group.addTask { try await loadProviders() }
    }
}

Perl Style (CLIO)

CLIO follows modern Perl 5 best practices:

  • Use use v5.32; with strict, warnings, utf8
  • Subroutine signatures: sub foo ($self, $arg) { ... }
  • Functional style: prefer map, grep, reduce over loops
  • Error handling: use Try::Tiny or eval with proper checks
  • Documentation: POD for all public subroutines
  • See Perl Best Practices for details

Python Style (ALICE)

  • Follow PEP 8 with black formatting
  • Type hints required for all public functions
  • Use async/await for I/O operations
  • Pydantic models for API schemas
  • Docstrings for all public APIs

Pull Request Process

Before Submitting

  • Run all tests: make test (SAM), prove -lr t/ (CLIO), pytest (ALICE)
  • Run linter: swiftlint (SAM), perlcritic (CLIO), ruff (ALICE)
  • Update documentation if behavior changed
  • Add tests for new functionality
  • No TODOs or FIXMEs in committed code

PR Description

Include in your PR description:

  • What: Brief summary of changes
  • Why: Problem being solved or feature added
  • How: Key implementation decisions
  • Testing: How you verified it works
  • Screenshots: For UI changes
  • Related issues: Link to GitHub issues

Review Process

  1. Automated checks must pass
  2. Maintainer reviews code and design
  3. Address feedback (commit to same branch)
  4. Squash and merge by maintainer

Review criteria: Correctness, simplicity, test coverage, documentation, consistency with existing patterns, adherence to Unbroken Method principles.

Issue Guidelines

Bug Reports

Include:

  • Steps to reproduce (minimal, complete)
  • Expected vs actual behavior
  • Environment (OS, version, hardware)
  • Logs or error messages
  • Configuration if relevant

Feature Requests

Include:

  • Problem statement (what you're trying to achieve)
  • Proposed solution (if you have one)
  • Alternatives considered
  • Impact assessment (who benefits, complexity)

Questions

Use GitHub Discussions for questions, ideas, and general discussion. Issues are for actionable work.

Testing Requirements

SAM Testing

  • Unit tests for business logic (Tests/)
  • UI tests for critical flows
  • Integration tests for provider communication
  • Run: make test

CLIO Testing

  • Unit tests for tools and subsystems (tests/)
  • Integration tests for tool chains
  • Session replay tests for regression
  • Run: prove -lr t/

ALICE Testing

  • API endpoint tests
  • Model loading/generation tests
  • GPU backend tests (CUDA, ROCm, MPS)
  • Run: pytest

Cross-project: Changes affecting integration points (SAM↔ALICE API, CLIO→SAM development) should be tested in both systems.

Documentation

Where to Document

  • Code comments: Brief, explain what not why (git history handles why)
  • Doc comments: All public APIs (Swift: ///, Perl: POD, Python: docstrings)
  • Website docs: User-facing features, guides, API references in docs/
  • Architecture docs: System design decisions in docs/SAM/developer/

Documentation Standards

  • Keep current with full rewrites, not changelog-style patches
  • Verify against source code before claiming facts
  • Use semantic HTML in website docs (already handled by templates)
  • No marketing language: "seamlessly," "powerful," "revolutionary," etc.
  • Active voice: "CLIO reads your code" not "Your code will be read by CLIO"
  • Follow the Website Antipatterns guide to avoid common mistakes

Updating Documentation

Documentation changes follow the same PR process as code. Update docs/ in the same commit as the feature/fix when possible.

Getting Help

We welcome contributions of all sizes. Thank you for helping make the Synthetic Autonomic Mind ecosystem better!

See Also