How to Contribute Code or Documentation to Different-AI/OpenWork: A Complete Guide

Contributing to the different-ai/openwork repository requires forking the repo, creating a descriptive branch, and opening a pull request against the dev branch after following the project's Code of Conduct and documentation standards.

The OpenWork project actively welcomes contributions from developers and technical writers. Whether you're fixing a bug, adding a feature, or improving documentation, the repository follows a standardized open-source workflow defined in its governance files. This guide covers both code and documentation contributions with exact commands and file paths from the source code.

Prerequisites: Understanding the Repository Structure

Before contributing, familiarize yourself with the key entry points and policies that govern the project.

• Main entry point: The [README.md](https://github.com/different-ai/openwork/blob/dev/README.md) contains project overview, installation instructions, and architecture basics.
• Community standards: The [CODE_OF_CONDUCT.md](https://github.com/different-ai/openwork/blob/dev/CODE_OF_CONDUCT.md) defines expected behavior; you must acknowledge this in any pull request.
• Support guidelines: The [SUPPORT.md](https://github.com/different-ai/openwork/blob/dev/SUPPORT.md) explains how to report issues and request help.

OpenWork uses pnpm for package management and targets the dev branch for all contributions.

How to Contribute Documentation

Documentation contributions follow a lightweight markdown-based workflow. All user-facing docs live in the docs/ directory and deploy automatically to openworklabs.com/docs after merge.

Step 1: Fork and Clone the Repository

Create your personal copy of the repository and set up local development:

# Click Fork on GitHub first, then:

git clone https://github.com/<your-username>/openwork.git
cd openwork

# Verify you're on the default branch

git checkout dev

Step 2: Create a Descriptive Branch

Use the docs/ prefix for documentation changes to make the purpose immediately clear:

git checkout -b docs/<topic-description>

Example branch names:

• docs/add-cli-quickstart
• docs/fix-desktop-app-typo
• docs/update-marketplace-architecture

Step 3: Add or Edit Markdown Files

All documentation uses GitHub-flavored markdown (*.md files). Existing examples include:

• docs/desktop-app-policies.md
• docs/extensions-manifest-foundation.md
• docs/marketplace-capabilities-architecture.md

To add a new document:

cat <<EOF > docs/cli-quickstart.md

# OpenWork CLI Quick-Start

This guide shows how to install and run OpenWork from the command line.

[Install instructions](https://github.com/different-ai/openwork/blob/dev/README.md#install-with-your-ai-agent)
EOF

Style requirements:

• Use logical heading hierarchy (# for title, ## for sections)
• Include optional front-matter for descriptions
• Use markdown links, never raw URLs
• Link to source files using exact paths: [OpenWorkProvider.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/openwork-provider.ts)

Step 4: Validate and Commit

Optional but recommended: run the test suite to catch syntax errors:

pnpm dev    # Start local dev server

pnpm test   # Run full test suite

Write a conventional commit message:

git add docs/cli-quickstart.md
git commit -m "docs: add CLI quick-start guide"

Step 5: Open a Pull Request

Push your branch and create a PR against the dev branch:

git push origin docs/cli-quickstart

Required PR description elements:

• Brief summary of changes
• Issue references (e.g., Closes #123)
• Confirmation of Code of Conduct compliance

Respond promptly to reviewer feedback with additional commits.

How to Contribute Code

Code contributions follow the identical branch-and-PR workflow with additional quality gates.

Branch Naming Conventions

Prefix	Use Case
feat/	New features or capabilities
fix/	Bug fixes
refactor/	Code restructuring without behavior change
test/	Test additions or improvements

Key Source File Locations

When contributing code, you may need to reference or modify these canonical paths:

• packages/types/src/openwork-provider.ts — Core provider interface definitions
• CODE_OF_CONDUCT.md — Must acknowledge in PRs
• SUPPORT.md — Reference for issue reporting standards

Development Commands

# Install dependencies

pnpm install

# Start development environment

pnpm dev

# Run test suite before submitting

pnpm test

Contribution Checklist for All PRs

Before submitting any contribution to different-ai/openwork, verify:

• Branch targets dev, not main
• Branch name follows docs/, feat/, fix/, or refactor/ convention
• Commit messages use conventional format (type: description)
• Code of Conduct acknowledgment included in PR description
• Related issues linked with Closes #XXX syntax
• Tests pass (pnpm test)
• Documentation updated for behavioral changes

Summary

• Fork and clone the repository, then create prefixed branches targeting dev
• Documentation lives in docs/ as markdown files with internal links to source code
• Code changes follow identical PR workflow with pnpm test validation required
• Commit format uses conventional prefixes: docs:, feat:, fix:, refactor:
• Governance compliance requires acknowledging the Code of Conduct in every PR

Frequently Asked Questions

What branch should I target for contributions to openwork?

Target the dev branch exclusively. The main branch represents stable releases; all active development and contribution review happens on dev. Your PR will fail automated checks if opened against the wrong branch.

Do I need to run tests for documentation-only changes?

Running pnpm test is optional for pure documentation edits, but recommended. Documentation still renders through the build system, and the test suite catches markdown syntax errors and broken internal links that would fail in CI.

How do I link to source files from documentation?

Use absolute GitHub URLs pointing to the dev branch with this pattern:

[ComponentName.ts](https://github.com/different-ai/openwork/blob/dev/path/to/file.ts)

For example: [OpenWorkProvider.ts](https://github.com/different-ai/openwork/blob/dev/packages/types/src/openwork-provider.ts).

Where do I find examples of existing documentation?

Browse the docs/ directory. Key reference files include desktop-app-policies.md for policy-style docs and extensions-manifest-foundation.md for technical specification documents.

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