> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to contribute to WednesdayAI: setup, checks, PR workflow, and maintainer guidelines.

# Contributing

WednesdayAI welcomes contributions — bug fixes, new plugins, channel adapters, hook packs, and documentation.

## Before you start

Read [CONTRIBUTING.md](https://github.com/ExpansionX/WednesdayAI-core/blob/main/CONTRIBUTING.md) for the full guide. Key points:

* **Fork philosophy:** lean core, highly extensible. If it can be a plugin, it should be.
* **Stability over features:** we prefer a stable, well-tested core over feature parity with upstream openclaw.
* **Extension scope:** new extensions use `@wednesdayai/*`, not `@openclaw/*`.
* **Plugin version pinning:** plugins pin `openclaw` to exactly `2026.3.2` (the fork base) — never a range. Plugins built against a newer openclaw may import APIs that do not exist in this fork.

## Setup

```bash theme={"dark"}
git clone https://github.com/ExpansionX/WednesdayAI-core.git
cd WednesdayAI-core
pnpm install
pnpm build
pnpm test:fast    # verify baseline passes
```

## Development workflow

<Steps>
  <Step title="Create a branch from main">
    Branch first — do not work directly on `main`.
  </Step>

  <Step title="Write tests first">
    TDD is preferred. Colocate `*.test.ts` next to the source.
  </Step>

  <Step title="Implement the change">
    Keep changes scoped; do not bundle unrelated refactors.
  </Step>

  <Step title="Run checks before committing">
    ```bash theme={"dark"}
    pnpm tsgo          # native TypeScript checker — must exit 0
    pnpm check         # format check + tsgo + lint
    pnpm test:fast     # unit tests
    pnpm build         # full build
    ```
  </Step>

  <Step title="Commit with the committer script">
    ```bash theme={"dark"}
    scripts/committer "feat(plugin-sdk): add ToolContext type" src/plugin-sdk/types.ts
    ```

    Use Conventional Commit format: `type(scope): description`.
  </Step>

  <Step title="Open a PR">
    Use the template in `.github/pull_request_template.md`.
  </Step>
</Steps>

<Warning>
  `pnpm tsgo` **must exit 0** before you commit. The native checker is the source of truth
  for type correctness; a green editor is not sufficient.
</Warning>

## Documentation requirements

WednesdayAI tracks completed work in two places. Both are required **for new features** and committed with the PR branch:

* **Dev log** — create `docs/logs/YYYY-MM-DD-<feature-slug>.md` (Summary / Goal / Changes / Impact / Benefits / References).
* **CHANGELOG entry** — add a record to `CHANGELOG.md` linking to the dev log.

Bugfix-only PRs need only a CHANGELOG entry (no dev log required unless the fix is complex).

## PR checklist

Before opening a PR, verify:

* [ ] `pnpm tsgo` exits 0
* [ ] `pnpm build && pnpm check && pnpm test` pass
* [ ] Fork philosophy: lean core, stable contracts, correct naming
* [ ] If new extension: `@wednesdayai/*` scope, plugin-sdk contract, `openclaw` pinned to `2026.3.2`, no `workspace:*` in `dependencies`
* [ ] If touching plugin-sdk exports: no `any`, no breaking changes without a migration path
* [ ] `CHANGELOG.md` updated for user-facing changes
* [ ] Dev log created for new features at `docs/logs/YYYY-MM-DD-<slug>.md`
* [ ] AI-assisted PRs marked as such in the title or description

## Review criteria

PRs are evaluated against the **fork philosophy**:

1. **Lean core** — does this add to core, or could it be a plugin/hook/SDK extension?
2. **Stable contracts** — does this change public plugin-sdk, hook, or gateway API? If so, is there a migration path?
3. **Naming** — user-facing text uses `WednesdayAI`; code/config/imports use `openclaw`.
4. **Extension scope** — new WednesdayAI-native extensions use `@wednesdayai/*`.

## Cherry-picks from upstream openclaw

We selectively adopt changes from upstream openclaw. The bar:

1. Does it improve **stability** or **extensibility**?
2. Does it touch core contracts (plugin-sdk, hooks, gateway, routing)? If so, a detailed stability rationale is required.
3. Does it add platform-specific dependencies that belong in a transport integration?

Propose a cherry-pick in an issue before opening a PR. We decline wholesale upstream rewrites.

## Reporting security issues

Report security vulnerabilities via [GitHub Security Advisories](https://github.com/ExpansionX/WednesdayAI-core/security/advisories) or email `security@expansionx.com.au`. Do not post publicly before a fix is ready. See [SECURITY.md](https://github.com/ExpansionX/WednesdayAI-core/blob/main/SECURITY.md) for the trust model and what qualifies as a vulnerability.

## Getting help

* **Issues:** [github.com/ExpansionX/WednesdayAI-core/issues](https://github.com/ExpansionX/WednesdayAI-core/issues)
* **Discussions:** GitHub Discussions on the repo
* **Contact:** [hello@expansionx.com.au](mailto:hello@expansionx.com.au) for maintainer discussions