Contributing

Help improve the Agentic Cognitive Governance Protocol!

Ways to Contribute

Report Bugs

Found an issue? Open a bug report

Suggest Features

Have an idea? Open a feature request

Improve Documentation

Documentation can always be better. Submit PRs for: - Typo fixes - Clarifications - New examples - Tutorial improvements

Contribute Code

Submit pull requests for: - Bug fixes - New features - Performance improvements - Test coverage

Write Examples

Share your ACGP implementations and use cases

Help Others

Answer questions on Discord and GitHub Discussions

Getting Started

1. Fork the Repository

git clone https://github.com/YOUR_USERNAME/acgp.git
cd acgp

2. Create a Branch

git checkout -b feature/your-feature-name

3. Make Changes

Follow our coding standards and add tests.

4. Submit PR

Push your branch and open a pull request.

Development Setup

# Install dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run linter
flake8

# Build docs
mkdocs build

Code Style

  • Follow PEP 8 for Python
  • Use meaningful variable names
  • Add docstrings
  • Write tests for new features

Pull Request Process

  1. Update documentation if needed
  2. Add tests for new features
  3. Ensure all tests pass
  4. Update CHANGELOG.md
  5. Request review from maintainers

Community Guidelines

Please read our Code of Conduct before contributing.

Diagram Conventions

Use these conventions for all Mermaid diagrams in the documentation.

Element Convention
Stage 1 (Local/SDK) subgraph labeled STAGE 1 — Local (SDK)
Stage 2 (Remote/Steward) subgraph labeled STAGE 2 — Remote (Steward)
Deny outcomes Terminal marker (⛔ or explicit terminal label)
Allow outcomes Terminal marker (✅)
Audit / storage Cylinder shape [(...)]
Human involvement 👤 prefix or distinct node label
Fallback / error paths Dashed edges (-..-> or -.->)
Flag (orthogonal) Dashed edge (-.-)

Color is optional reinforcement. Meaning MUST be readable from labels, shapes, and edge styles alone.

Diagram Hierarchy Levels

  • L1 — Hook: landing-page diagram (5-7 nodes)
  • L2 — Mental Model: concept-level learner diagram (12-16 nodes)
  • L3 — Implementation: spec sequence/detail diagrams
  • L4 — Reference: normative pseudocode/complete reference flow

Each diagram SHOULD link to the next level of detail.

Diagram Definition of Done (DoD)

Before merging, every diagram update MUST satisfy:

  • Spec-aligned: Every box maps to a named spec primitive.
  • No orphan nodes: All non-terminal nodes have outgoing edges.
  • Canonical naming: Uses Operating Agent, Governance Steward, SDK, Governance Store, Cognitive Trace.
  • Fallback correctness: Failure/disconnect paths say per contract/profile; no hardwired single behavior.
  • Theme-safe: Meaning does not depend on color alone.
  • Renders and links: Mermaid renders and links/anchors resolve.
  • Level-appropriate: Diagram indicates L1-L4 level and links onward.
  • Branch coverage: Major branches map to quickstart examples or conformance scenarios.

Questions?

Contributors

Thank you to all contributors!

Contributors

Want to see your name here? Start with a small contribution:

  1. Fix a typo in the docs
  2. Add a code example
  3. Improve an error message
  4. Write a test case

Every contribution counts!

Code of Conduct Project Updates