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

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 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, 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 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.
• Fixing hooks or the installer: Improve reliability in 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:

   git checkout -b my-new-feature

3. Make edits in the source-of-truth location (e.g., skills/caveman/SKILL.md or bin/install.js).

4. Run the test suite locally to verify your changes:

   npm test                     # Node installer & e2e tests
   
   python -m unittest tests/test_compress_safety.py   # Python safety tests
   

5. Update documentation in README.md and 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.

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. Below is a minimal example adding a hypothetical "example-agent":

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

node bin/install.js --list

Update the installation tables in README.md and 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: Core skill prose that defines the compression behavior.
• skills/caveman-commit/SKILL.md: Enforces the Conventional Commits format for the repository.
• bin/install.js: The unified Node installer containing the PROVIDERS array for agent detection.
• src/tools/caveman-init.js: Repo-level initialization script that writes rule files.
• src/hooks/caveman-activate.js: Activation hook for Claude Code sessions.
• .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.
• Update documentation: Keep README.md and 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. 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 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 and 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 to ensure your commits pass automated checks and maintain consistency with the project's commit history.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}