Contributing to AI Dev¶

Contributions of all kinds are welcome — agent configurations, MCP integration examples, documentation improvements, and troubleshooting guides.

New to open source contributing? See GitHub's Contributing to Projects Guide.

Quick Start¶

Fork the repository and clone your fork
Create a descriptive branch (add-postgres-mcp-config, fix-opencode-docs)
Make your changes following the guidelines below
Run the validation commands below
Open a Pull Request with a clear description

What to Contribute¶

Type	Where to Put It
MCP server configs	`harness/opencode-samples/mcp/`
Agent definitions	`agents/`
Skill instructions	`skills/<skill-name>/`
Harness documentation	`docs/harness/<harness-name>/`
General docs	`docs/`

Guidelines¶

Configuration Files¶

Configurations should be self-documenting. Include inline comments explaining non-obvious settings, and never hardcode secrets — always reference environment variables with {env:NAME}. Use the OpenCode V2 format, with servers under mcp.servers:

{
  "mcp": {
    "servers": {
      "postgres": {
        "type": "local",
        "command": ["docker", "run", "--rm", "-i", "postgres-mcp"],
        "environment": {
          "DB_PASSWORD": "{env:DB_PASSWORD}"
        }
      }
    }
  }
}

Note

OpenCode accepts comments in both .json and .jsonc files, but strict JSON parsers and some editors do not. Name a standalone sample that carries comments with the .jsonc extension. A file OpenCode loads by name, such as opencode.json, keeps that name. Put setup instructions on the MCP Servers page rather than beside the file.

Each configuration should be accompanied by:

Prerequisites (tools, accounts, environment variables needed)
Setup instructions
At least one usage example
Common troubleshooting tips

Documentation¶

All docs use GitHub Flavored Markdown.

Keeping Docs in Sync¶

When you change a configuration or behavior, update the related documentation in the same PR. Common places to check:

Companion README.md files
docs/ pages that reference the changed content
mkdocs.yml nav (required when adding or removing pages)
AGENTS.md if agent behavior changes

Topology inventory, roster, and GitHub Copilot install blocks, and the domain specialist roster on the agents overview page, are generated from agent frontmatter. After changing an agent roster, model, description, client mirror, or harness mapping, refresh those blocks:

python scripts/validate_artifact_sync.py --write

The validator also requires every skills/*/SKILL.md definition to appear in docs/skills/index.md, skills/README.md, and cerebro-catalog.yaml. It checks topology mirror rosters and bodies, harness defaults, and the generated documentation blocks, including that every root agents/*.agent.md file appears in the specialist roster.

Run the same checks used by pull requests before submitting:

python agents/lane-topology/validate.py
bash agents/matrix-topology/verify-deployment.sh
python scripts/validate_artifact_sync.py
mkdocs build --clean --strict

Pre-Submission Checklist¶

Before opening a PR:

Configurations tested and working in a real environment
All links resolve correctly
Code blocks have language specifiers
No hardcoded secrets or tokens
Artifact synchronization validators pass
mkdocs build --clean --strict passes
mkdocs.yml updated if pages were added or removed
Related documentation updated in the same PR

Review and Merge¶

Agent reviewers use the repository's repository-review maintenance skill. It lives under .agents/skills/ and is loaded through the repository instruction entrypoints; it is separate from the installable skills in the public catalog.

PRs are reviewed for accuracy, formatting, and completeness. At least one maintainer approval is required. Expect a response within a week — if you haven't heard back, feel free to ping on the issue.

Questions and Feedback¶

Found a bug or gap? File an issue
Have an idea? Start a discussion before building something large
Not sure it's ready? Open a draft PR for early feedback

Code of Conduct¶

Be respectful and constructive. Focus on the content, not the person. Assume good intentions and help keep this a welcoming space.

License¶

By contributing, you agree that your work will be licensed under the same terms as this project, the MIT License.

Thank you for contributing! Your improvements help the entire AI development community.