Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
125 lines (88 loc) · 4.78 KB

CONTRIBUTING.md

File metadata and controls

125 lines (88 loc) · 4.78 KB
Raw

Contributing to StatsClaw for Codex

Thank you for your interest in StatsClaw for Codex! We welcome contributions of all kinds — from bug reports and feature ideas to code and documentation.

Ways to Contribute

1. Submit Ideas and Requests

No coding required! You can help by:

  • Feature requests — Open an issue describing what you'd like
  • Bug reports — Report a bug with steps to reproduce
  • Use case reports — Share how you used StatsClaw and what could be improved

2. Contribute Code

Getting Started

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/<your-username>/statsclaw-for-codex.git
cd statsclaw-for-codex
  3. Make your changes
  4. Verify your changes work by running a workflow against a test repository via Codex
  5. Push and open a Pull Request

What Can You Work On?

  • Skills (skills/) — Improve or add workflow skill protocols
  • Language profiles (profiles/) — Add or improve language-specific rules
  • Templates (templates/) — Improve runtime artifact templates
  • Helpers (helpers/) — Improve Python authoritative executors
  • Documentation (docs/) — Improve README, docs, add usage examples and workflow guides

Code Guidelines

  • Keep changes focused — one PR per feature or fix
  • Follow existing patterns in the codebase
  • Skill and profile files use Markdown — keep them clear and structured
  • Python helpers should include type hints and docstrings
  • Python helpers should be executable from the project root

3. Add a Language Profile

StatsClaw supports multiple languages through profiles. To add a new one:

  1. Create profiles/<language>.md following the pattern in existing profiles (e.g., profiles/r-package.md)
  2. Include at minimum:
    • File patterns — How to identify this language in a repo
    • Build commands — How to build/install
    • Test commands — How to run tests
    • Packaging conventions — Package manager, distribution format
    • Simulation support level — Whether Monte Carlo workflows are available
    • Known limitations — What StatsClaw cannot yet do for this language
  3. Update the support matrix in AGENTS.md and README.md
  4. Open a PR with example usage

4. Add a Workflow Skill

Skills define execution protocols for roles. To add or modify one:

  1. Follow the standard section order defined in docs/skill-format.md: 
    Role / Allowed Inputs / Prohibited Inputs / Outputs / HOLD Policy / Execution Protocol
  2. Optional sections (Isolation Constraints, Reroute Policy, Known Limitations) may appear after the standard block
  3. Register the skill in AGENTS.md if it is a new entry point
  4. Verify the skill works end-to-end with a test workflow

5. Add or Improve Templates

Templates in templates/ define the structure of runtime artifacts. When modifying:

  1. Preserve the unified frontmatter contract (at minimum: runId, artifactType, schemaVersion, ownerRole)
  2. Update the corresponding JSON schema in schemas/ if one exists
  3. Verify that helpers consuming the template still parse correctly
  4. Verify that existing workflows still work

6. Contribute Knowledge to the Brain

StatsClaw has a local knowledge system where techniques, methods, and patterns discovered during workflows are extracted and stored. When brain mode is enabled:

  1. The distiller role extracts reusable knowledge from your workflow
  2. You review the extracted entries and approve or decline — nothing is stored without your explicit consent
  3. Approved entries are written to the local .brain/ directory
  4. The privacy scrub pipeline removes all identifying information before storage

What gets stored: Mathematical methods, coding patterns, validation strategies, simulation designs — all genericized.

What never gets stored: Repo names, file paths, usernames, proprietary code, data column names, or any identifying information.

Development Setup

StatsClaw for Codex is a framework for OpenAI Codex. To develop:

  1. Install OpenAI Codex
  2. Clone this repository
  3. Ensure Python 3.10+ is available
  4. Test changes by running workflows against a target repository via Codex

Pull Request Process

  1. Describe what your PR does and why
  2. Reference any related issues
  3. Keep the diff minimal — don't include unrelated changes
  4. Include or update tests for changed behavior
  5. Be responsive to review feedback

Community Guidelines

  • Be respectful and constructive
  • Focus on the idea, not the person
  • Help newcomers get oriented
  • Write in English or Chinese — both are welcome

Questions?

  • Open an issue for bugs or specific feature requests
  • Check the Roadmap for planned work

Thank you for helping StatsClaw for Codex grow!