OpenShell/CONTRIBUTING.md

Contributing to OpenShell

OpenShell is built agent-first. We design systems and use agents to implement them. Your agent is your first collaborator — point it at this repo before opening issues, asking questions, or submitting code.

The Critical Rule

You must understand your code. Using AI agents to write code is not just acceptable, it's how this project works. But you must be able to explain what your changes do and how they interact with the rest of the system. If you can't, don't submit it.

Submitting agent-generated code without understanding it — regardless of how clean it looks — wastes maintainer time and will result in your PR being closed. Repeat offenders will be blocked from the project.

AI Usage

OpenShell is agent-first, not agent-only. The distinction matters:

• Do use agents to explore the codebase, run diagnostics, generate code, and iterate on implementations.
• Do use the skills in .agents/skills/ — they exist to make your agent effective.
• Do interrogate your agent until you understand every edge case and interaction in your changes.
• Don't submit code you can't explain without your agent open.
• Don't use agents as a substitute for understanding the system. Read the architecture docs.

First-Time Contributors

We use a vouch system. This exists because AI makes it trivial to generate plausible-looking but low-quality contributions, and we can no longer trust by default.

1. Open a Vouch Request discussion.
2. Describe what you want to change and why.
3. Write in your own words. AI-generated vouch requests will be denied.
4. A maintainer will comment /vouch if approved.
5. Once vouched, you can submit pull requests.

If you are not vouched, any pull request you open will be automatically closed. Org members and collaborators with push access bypass this check.

Finding Work

Issues labeled good-first-issue are scoped, well-documented, and friendly to new contributors. Start there. If you need guidance, comment on the issue.

Open issues are not all the same: bugs and implementation issues may be ready to work, while feature proposal issues are product discussions until maintainers accept the feature request.

Before You Open an Issue

This project ships with agent skills that can diagnose problems, explore the codebase, generate policies, and walk you through common workflows. Before filing an issue:

1. Clone the repo and point your coding agent at it.
2. Load the relevant skill - debug-openshell-cluster for gateway or deployment problems, debug-inference for inference setup problems, openshell-cli for usage questions, generate-sandbox-policy for policy help.
3. Have your agent investigate. Let it run diagnostics, read the architecture docs, and attempt a fix.
4. If the agent cannot resolve it, open an issue. For bug and troubleshooting reports, attach the agent's diagnostic output; those issue templates require it.

When to Open an Issue

• A real bug that your agent confirmed and could not fix.
• A completed feature request document that needs product discussion. For substantial product changes, use create-feature-request to start a feature request draft, complete the draft, make it visible through a GitHub URL, and then create a GitHub issue that links to the doc or PR for discussion.
• An infrastructure problem that the gateway deployment troubleshooting skill could not resolve.
• An inference setup problem that the debug-inference skill could not resolve.
• Security vulnerabilities must follow SECURITY.md — not GitHub issues.

When NOT to Open an Issue

• Questions about how things work — your agent can answer these from the codebase and architecture docs.
• Configuration problems - your agent can diagnose these with openshell-cli, debug-openshell-cluster, and debug-inference.
• "How do I..." requests — the skills cover CLI usage, policy generation, TUI development, and more.

Agent Skills for Contributors

Skills live in .agents/skills/. Your agent's harness can discover and load them natively. Here is the full inventory:

Category	Skill	Purpose
Getting Started	openshell-cli	CLI usage, sandbox lifecycle, provider management, BYOC workflows
Getting Started	debug-openshell-cluster	Diagnose gateway deployment and health issues
Getting Started	debug-inference	Diagnose inference.local, host-backed local inference, and direct external inference setup issues
Contributing	create-spike	Investigate a problem, produce a structured GitHub issue
Contributing	build-from-issue	Plan and implement work from a GitHub issue (maintainer workflow)
Contributing	create-feature-request	Start and iteratively fill a numbered feature request draft
Contributing	create-github-issue	Create well-structured GitHub issues
Contributing	create-github-pr	Create pull requests with proper conventions
Reviewing	review-github-pr	Summarize PR diffs and key design decisions
Reviewing	review-security-issue	Assess security issues for severity and remediation
Reviewing	watch-github-actions	Monitor CI pipeline status and logs
Triage	triage-issue	Assess, classify, and route community-filed issues
Platform	generate-sandbox-policy	Generate YAML sandbox policies from requirements or API docs
Platform	tui-development	Development guide for the ratatui-based terminal UI
Documentation	update-docs	Scan recent commits and draft doc updates for user-facing changes
Maintenance	sync-agent-infra	Detect and fix drift across agent-first infrastructure files
Reference	sbom	Generate SBOMs and resolve dependency licenses

Workflow Chains

Skills connect into pipelines. Individual skill files don't describe these relationships.

• Community inflow: triage-issue → create-spike → build-from-issue
• Internal development: create-spike → build-from-issue
• Feature proposals: create-feature-request → user completes proposal → feature request PR/doc link → linked GitHub issue → product review
• Security: review-security-issue → fix-security-issue
• Policy iteration: openshell-cli → generate-sandbox-policy

Workflow state labels use the state:* prefix, and security work uses topic:security. GitHub issue templates assign built-in issue types where applicable, and agent-created issues should use issue types or manual follow-up rather than type labels. New issues opened by users without write, maintain, or admin repository permission are automatically labeled state:triage-needed by the issue triage workflow.

Prerequisites

Install mise. This is used to set up the development environment.

# Install mise (macOS/Linux)
curl https://mise.run | sh

After installing mise, activate it with mise activate or add it to your shell.

Shell setup examples:

# Bash
echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc

# Fish
echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish

# Zsh
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc

Project requirements:

• Rust 1.88+
• Python 3.12+
• Docker (running)
• Z3 solver library (for the policy prover crate)

Z3 installation

The openshell-prover crate links against the system Z3 library via pkg-config.

# macOS
brew install z3

# Ubuntu / Debian
sudo apt install libz3-dev

# Fedora
sudo dnf install z3-devel

If you prefer not to install Z3 system-wide, you can compile it from source as a one-time step:

cargo build -p openshell-prover --features bundled-z3

Getting Started

# One-time trust
mise trust

# Run a standalone gateway for local development
mise run gateway

Building the openshell CLI

Inside this repository, openshell is a local shortcut script at scripts/bin/openshell. The script will

1. Build openshell-cli if needed.
2. Run the local debug CLI binary under target/debug/openshell.

Because mise adds scripts/bin to PATH for this project, you can run openshell directly from the repo.

openshell --help
openshell sandbox create -- codex

Main Tasks

These are the primary mise tasks for day-to-day development:

Task	Purpose
mise run gateway	Run a standalone gateway for local development
mise run sandbox	Create or reconnect to the dev sandbox
mise run test	Default test suite
mise run e2e	Default end-to-end test lane
mise run ci	Full local CI checks (lint, compile/type checks, tests)
mise run docs	Validate Fern docs locally
mise run clean	Clean build artifacts

Project Structure

Path	Purpose
crates/	Rust crates
python/	Python SDK and bindings
proto/	Protocol buffer definitions
tasks/	mise task definitions and build scripts
deploy/	Dockerfiles, Helm chart, Kubernetes manifests
docs/	Published Fern docs source, navigation, and content assets
fern/	Fern site config, components, and theme assets
architecture/	Architecture docs and plans
feature-requests/	Product requirements and feature proposal templates
rfc/	Request for Comments proposals
.agents/	Agent skills and persona definitions

Feature Requests and RFCs

Feature requests are product proposals. Use them when you want maintainers to decide whether a capability belongs in OpenShell, who it serves, what user outcome it should provide, and where users should expect it to be available. For substantial proposals, use the create-feature-request skill to start a draft under feature-requests/, complete the draft, make it visible through a GitHub URL, and then create a GitHub issue that links to the completed feature request doc or PR.

RFCs are technical design proposals. Use them after a feature request has been discussed and approved by core maintainers, or for non-feature technical decisions such as architecture, API contracts, process changes, or test design. RFCs live in rfc/; copy the template, fill it in, and link the approved feature request when applicable.

Typical flow for new product capabilities:

1. Use create-feature-request to start a numbered draft.
2. Complete the feature request draft.
3. Open a PR or push the doc so it has a GitHub URL.
4. Create a GitHub issue that links to the completed feature request doc or PR.
5. Review the feature request in the PR and linked issue, then get core maintainer approval on the product direction.
6. Create an RFC only if detailed technical design is needed.

See feature-requests/README.md and rfc/README.md for the full processes.

Documentation

If your change affects user-facing behavior (new flags, changed defaults, new features, bug fixes that contradict existing docs), update the relevant pages under docs/ in the same PR and adjust docs/index.yml if navigation changes. For explicit navigation entries, keep page: aligned with sidebar-title when present and put relative slug: values in docs/index.yml. Reserve frontmatter slug for folder-discovered pages or absolute URL overrides.

To ensure your doc changes follow NVIDIA documentation style, use the update-docs skill. It scans commits, identifies doc pages that need updates, and drafts content that follows the style guide in docs/CONTRIBUTING.mdx.

To preview Fern docs locally:

mise run docs:serve

To run non-interactive validation:

mise run docs

PRs that touch docs/** or fern/** are validated by .github/workflows/branch-docs.yml, and they get a preview when FERN_TOKEN is available to the workflow.

Fern docs publishing is handled by the publish-fern-docs job in .github/workflows/release-tag.yml when a release tag is created.

docs/ is the source-of-truth docs tree. fern/ contains the site config, components, and theme assets that publish those pages.

See docs/CONTRIBUTING.mdx for the current docs authoring guide.

Pull Requests

1. Create a feature branch from main.
2. Make your changes with tests.
3. Run mise run ci to verify.
4. Open a PR using the create-github-pr skill or manually following the PR template.

Commit Messages

This project uses Conventional Commits. All commit messages must follow the format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation only
• chore - Maintenance tasks (dependencies, build config)
• refactor - Code change that neither fixes a bug nor adds a feature
• test - Adding or updating tests
• ci - CI/CD changes
• perf - Performance improvements

Examples:

feat(cli): add --verbose flag to openshell run
fix(sandbox): handle timeout errors gracefully
docs: update installation instructions
chore(deps): bump tokio to 1.40

DCO

All contributions must include a Signed-off-by line in each commit message. This certifies you have the right to submit the work under the project license. See the Developer Certificate of Origin.

git commit -s -m "feat(sandbox): add new capability"

DCO sign-off is separate from cryptographic commit signing. CI requires signing for org members so that copy-pr-bot can mirror your PR automatically; see CI.md for setup.

CI

How E2E runs in CI, the test:e2e / test:e2e-gpu labels, copy-pr-bot, and commit-signing setup are documented in CI.md.