# How to Contribute to the JuliusBrussee/caveman Project: Complete Guide

> Contribute to the JuliusBrussee/caveman project easily. Learn how to edit source files, run tests locally, and adhere to Conventional Commits for a smooth contribution process.

- Repository: [Julius Brussee/caveman](https://github.com/JuliusBrussee/caveman)
- Tags: how-to-guide
- Published: 2026-07-03

---

**Yes, you can contribute to the JuliusBrussee/caveman project by editing source-of-truth files in the `skills/` and `bin/` directories, running the local test suite, and following the Conventional Commits specification enforced by the repository.**

Caveman is a multi-agent skill plugin that compresses AI coding agent outputs into terse "caveman" style, reducing token usage by up to 65%. The JuliusBrussee/caveman repository welcomes contributions ranging from skill prose edits to new agent support and installer improvements. Understanding the project's unique architecture—where source files live in specific directories and mirrors are CI-generated—is essential before submitting your first pull request.

## Understanding the Caveman Architecture

The repository maintains a strict separation between **source-of-truth files** and **CI-generated mirrors**. All contributions must target the source files; automated workflows handle distribution.

- **Source-of-truth directories**: `skills/` and `bin/` contain the master copies of all skill definitions and installation logic.
- **Mirror directories**: `plugins/` folders are automatically populated by the CI pipeline and will be overwritten on every push.
- **CI sync**: The workflow defined in [`.github/workflows/sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/.github/workflows/sync-skill.yml) handles propagation from source to mirrors.

Never edit files in `plugins/caveman/` directly. Instead, modify the corresponding files in `skills/caveman/` or [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js), and allow the automation to distribute your changes.

## Ways to Contribute to the Caveman Project

The project accepts three main categories of contributions according to the source code:

- **Editing skill prose**: Modify [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) to change compression wording, add intensity levels, or refine the caveman persona.
- **Adding a new agent**: Extend support to additional AI coding agents by updating the installer configuration in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js).
- **Fixing hooks or the installer**: Improve reliability in [`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js) or the activation hooks in `src/hooks/`.

## Step-by-Step Contribution Workflow

Follow this process to ensure your contribution to the JuliusBrussee/caveman project meets quality standards:

1. **Fork and clone** the repository to your local machine.

2. **Create a feature branch** using a descriptive name:
   
   ```bash
   git checkout -b my-new-feature
   ```

3. **Make edits** in the source-of-truth location (e.g., [`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md) or [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)).

4. **Run the test suite** locally to verify your changes:
   
   ```bash
   npm test                     # Node installer & e2e tests

   python -m unittest tests/test_compress_safety.py   # Python safety tests

   ```

5. **Update documentation** in [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) and [`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md) if you modified the installer or added agent support.

6. **Commit using Conventional Commits**. The repository enforces this format via [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md).

7. **Push and open a PR**. The CI will run the full test matrix and automatically sync the mirrors.

## Adding Support for a New AI Agent

To contribute a new agent integration, modify the `PROVIDERS` array in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js). Below is a minimal example adding a hypothetical "example-agent":

```javascript
// bin/install.js – add a new provider entry
const PROVIDERS = [
  // ... existing entries ...
  {
    id: "example-agent",
    label: "Example Agent",
    mech: "plugin",               // distribution mechanism
    detect: "command:example || dir:$HOME/.example", // detection rule
    profile: "example-agent",     // vercel-labs/skills slug (if any)
    soft: false,                  // hard detection – fail if not present
  },
];

```

After adding the entry, verify detection by running:

```bash
node bin/install.js --list

```

Update the installation tables in [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) and [`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md) to document the new agent support.

## Critical Source Files and Test Locations

When contributing to the JuliusBrussee/caveman project, these files handle core functionality:

- **[`skills/caveman/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman/SKILL.md)**: Core skill prose that defines the compression behavior.
- **[`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md)**: Enforces the Conventional Commits format for the repository.
- **[`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js)**: The unified Node installer containing the `PROVIDERS` array for agent detection.
- **[`src/tools/caveman-init.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/tools/caveman-init.js)**: Repo-level initialization script that writes rule files.
- **[`src/hooks/caveman-activate.js`](https://github.com/JuliusBrussee/caveman/blob/main/src/hooks/caveman-activate.js)**: Activation hook for Claude Code sessions.
- **[`.github/workflows/sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/.github/workflows/sync-skill.yml)**: CI configuration that mirrors source files into `plugins/`.
- **`tests/`**: Directory containing unit tests for installer logic, flag-file safety, and compression algorithms.
- **`benchmarks/`** and **`evals/`**: Directories for performance testing and token savings validation.

## Summary

- **Edit source-of-truth only**: Modify files in `skills/` and `bin/`; never touch `plugins/` directly.
- **Test locally**: Run `npm test` and Python unit tests before submitting.
- **Follow Conventional Commits**: The repository enforces commit message standards via [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md).
- **Update documentation**: Keep [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) and [`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md) current when adding features or agents.
- **CI handles distribution**: The sync workflow automatically propagates your changes to all mirrored agent plugins.

## Frequently Asked Questions

### Can I edit files directly in the plugins/ directory?

No. The `plugins/` directories contain CI-generated mirrors that are overwritten on every push by [`.github/workflows/sync-skill.yml`](https://github.com/JuliusBrussee/caveman/blob/main/.github/workflows/sync-skill.yml). Always edit the source-of-truth files in `skills/` or `bin/`, and let the automation handle the mirroring.

### What tests must pass before submitting a pull request?

You must run the Node.js test suite with `npm test` to validate installer and end-to-end functionality, plus Python safety tests with `python -m unittest tests/test_compress_safety.py`. These ensure that flag-file operations and compression logic remain safe across platforms.

### How do I add support for a new AI coding agent?

Add a new entry to the `PROVIDERS` array in [`bin/install.js`](https://github.com/JuliusBrussee/caveman/blob/main/bin/install.js) with the appropriate `id`, `label`, `mech`, and `detect` properties. Verify your configuration runs correctly with `node bin/install.js --list`, then update the agent compatibility tables in [`README.md`](https://github.com/JuliusBrussee/caveman/blob/main/README.md) and [`INSTALL.md`](https://github.com/JuliusBrussee/caveman/blob/main/INSTALL.md).

### What commit message format does the project require?

The JuliusBrussee/caveman project enforces Conventional Commits. Follow the specification defined in [`skills/caveman-commit/SKILL.md`](https://github.com/JuliusBrussee/caveman/blob/main/skills/caveman-commit/SKILL.md) to ensure your commits pass automated checks and maintain consistency with the project's commit history.