diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 000000000..38e5e5edc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,60 @@ +name: Bug report +description: Something OpenRig does is wrong, or a command fails +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks. Include a small reproduction and the relevant versions. + This report will be public. Remove API keys, tokens, private prompts, personal details and private paths from commands, logs and configuration. + For a suspected vulnerability, follow our [security policy](https://github.com/mvschwarz/openrig/security/policy) instead of posting details here. + - type: input + id: version + attributes: + label: OpenRig version + description: Output of `rig --version` + placeholder: 0.5.14 (2edc1b7a) + validations: + required: true + - type: input + id: platform + attributes: + label: OS, Node and tmux versions + placeholder: macOS 15.6, Node 22.22.1, tmux 3.5a + validations: + required: true + - type: dropdown + id: harness + attributes: + label: Harnesses involved + multiple: true + options: + - None / not sure + - Claude Code + - Codex + - Pi / Oh My Pi + - Other (say which below) + validations: + required: true + - type: textarea + id: repro + attributes: + label: What you ran and what happened + description: The command(s), relevant redacted output, and what you expected instead. Paste text where you can; screenshots are useful for visual issues. + render: shell + validations: + required: true + - type: textarea + id: state + attributes: + label: Instance state that might matter + description: Fresh install or upgrade? Include only relevant redacted lines from status output or your rig spec; do not upload full transcripts, credentials or your instance directory. + - type: checkboxes + id: checks + attributes: + label: Checks + options: + - label: I searched existing issues and Discussions for this. + required: true + - label: I am on the latest published version, or I said which version above. + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..dbba60733 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,14 @@ +blank_issues_enabled: true +contact_links: + - name: Ask a question + url: https://github.com/mvschwarz/openrig/discussions/categories/q-a + about: Setup, usage and "is this expected" questions go to Discussions Q&A. + - name: Share an idea or a setup + url: https://github.com/mvschwarz/openrig/discussions + about: Ideas and Show and tell live in Discussions. + - name: Documentation + url: https://openrig.dev/docs + about: Getting started, CLI reference, configuration and troubleshooting. + - name: Security report + url: https://github.com/mvschwarz/openrig/security/policy + about: Read how to arrange a private report. Do not include vulnerability details in public issues. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 000000000..62edcba31 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,32 @@ +name: Feature request +description: Something you want OpenRig to do that it does not +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + For open-ended ideas or "how should this work" questions, [Discussions › Ideas](https://github.com/mvschwarz/openrig/discussions/categories/ideas) is the better place. Use this form when you can name the outcome you want. + This request will be public; use examples without credentials, private prompts or personal details. + - type: textarea + id: outcome + attributes: + label: What are you trying to do, and what stops you today? + description: Describe the situation, not the solution. One real example beats a general case. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: What would you like OpenRig to do? + description: A command, a setting, a behaviour. Rough is fine. + validations: + required: true + - type: textarea + id: workaround + attributes: + label: How do you handle it now? + - type: input + id: version + attributes: + label: OpenRig version + placeholder: 0.5.14 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..0f0bc06ac --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ + + +## What a user gets + + + +## How you verified it + + + +## Anything you were unsure about + + + +- [ ] One concern per PR; no version bump; no `CHANGELOG.md` edit +- [ ] Tests added or updated where the change is testable +- [ ] I listed the checks I ran, their results, and any checks I could not run diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md new file mode 100644 index 000000000..ddb52eefe --- /dev/null +++ b/.github/SUPPORT.md @@ -0,0 +1,16 @@ +# Getting help with OpenRig + +- **Docs:** https://openrig.dev/docs — getting started, CLI reference, configuration, + troubleshooting. An index linking to agent-friendly documentation is at + https://openrig.dev/llms.txt. +- **Questions:** [Discussions › Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a). +- **Bugs:** [open an issue](https://github.com/mvschwarz/openrig/issues/new/choose) with the bug + template. Include `rig --version`, your OS and Node versions, and relevant redacted command output. + Reports are public: remove credentials, private prompts and personal information. +- **Ideas and setups:** [Ideas](https://github.com/mvschwarz/openrig/discussions/categories/ideas) + and [Show and tell](https://github.com/mvschwarz/openrig/discussions/categories/show-and-tell). +- **Videos:** https://www.youtube.com/@openrig +- **Security:** see [SECURITY.md](../SECURITY.md); please report privately. + +We aim to acknowledge issues and pull requests within one day. A substantive PR review decision +within seven days is a target, not a guaranteed deadline. Details in [CONTRIBUTING.md](../CONTRIBUTING.md). diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..fc9209641 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,75 @@ +# Code of Conduct + +## Our pledge + +We as members, contributors, and maintainers pledge to make participation in OpenRig a +harassment-free experience for everyone, regardless of age, body size, visible or invisible +disability, ethnicity, sex characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, +and healthy community. + +## Our standards + +Examples of behaviour that contributes to a positive environment: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from + the experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behaviour: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email address, without their + explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of acceptable +behaviour and will take appropriate and fair corrective action in response to any behaviour that +they deem inappropriate, threatening, offensive, or harmful. Maintainers have the right and +responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions +that are not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all project spaces (the repository, Discussions, issues and +pull requests) and when an individual is officially representing the project in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported to the +maintainers at **conduct@openrig.dev**. All complaints will be reviewed and investigated +promptly and fairly. +All maintainers are obligated to respect the privacy and security of the reporter of any incident. + +## Enforcement guidelines + +Maintainers will follow these community impact guidelines in determining the consequences for any +action they deem in violation of this Code of Conduct: + +1. **Correction.** A private, written warning, with clarity around the nature of the violation and + an explanation of why the behaviour was inappropriate. A public apology may be requested. +2. **Warning.** A warning with consequences for continued behaviour, including no interaction with + the people involved for a specified period. +3. **Temporary ban.** A temporary ban from any sort of interaction or public communication with + the community for a specified period. +4. **Permanent ban.** A permanent ban from any sort of public interaction within the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.1 by Coraline Ada Ehmke, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html and licensed under +[Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/). +This adaptation names OpenRig and its maintainers and summarizes the enforcement guidelines. Community impact guidelines +were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..6fa43a004 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# Contributing to OpenRig + +Thanks for being here. OpenRig is built in the open and by the thing it is: a rig of coding +agents and a small group of people. External pull requests and issues have started arriving +faster than we planned for, which is the best problem to have. This page says how to get a +change in with the least friction on both sides. + +## Before you start + +- **Bugs:** open an issue with the bug template. Include your OpenRig version (`rig --version`), + OS, Node version, which harnesses are involved (or none), and the relevant command and output. + Reports are public: remove credentials, private prompts, personal details and private paths + before posting. Share a small reproduction rather than a full transcript or instance dump. +- **Features and behaviour changes:** open an issue or a Discussion in *Ideas* first. A short + "what I am trying to do and what stops me" saves both of us a rewrite. Small, obvious fixes do + not need an issue. +- **Questions:** use [Discussions › Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a), + not an issue. + +## Setting up + +Node `^20 || ^22 || ^24` and a working `tmux` are required. Then: + +```bash +git clone https://github.com/mvschwarz/openrig.git +cd openrig +npm install +npm run build # all workspaces +npm test # repo checks + daemon, cli, tui test suites +npm run lint # typecheck every package +``` + +`npm test` builds the daemon and runs repository checks before the package suites. Read the +specific failure: `npm run mirror-skills` updates skill mirrors, and +`npm run generate-context-packs` updates generated packs. Use them when their source changed and +review the generated diff; neither command fixes every documentation failure. The UI unit-test +suite is advisory and separate: `npm run test:ui`. + +For hands-on development, read the [check requirements](docs/reference/developing.md), +[worktree setup](docs/reference/worktree-builds.md), and +[machine changes](README.md#what-openrig-changes-on-your-machine). Use an isolated environment +for changes that start daemons or agents; `OPENRIG_HOME` alone does not isolate provider settings. +Permission configuration is an [explicit choice](docs/reference/getting-started.md#have-your-agent-configure-permissions). +A checked-out tree is not the installed daemon; restarting an installed daemon does not adopt +your working copy. + +## Making the change + +- One concern per pull request. Keep unrelated refactors separate; explain any refactor needed + for the fix. +- Keep the diff small enough to review in one sitting. If it is not, say why in the description. +- Add or update a test where the change is testable. Use focused deterministic tests where + possible. For terminal or provider behaviour, state what was exercised with the actual runtime + and what was simulated; a stub alone does not prove the native interaction works. +- Do not edit `CHANGELOG.md`. Maintainers write release notes at the tag. +- Do not bump versions. +- Match the surrounding style. `npm run lint` typechecks; it does not format code. +- Write commit messages in the form the log already uses: `fix(cli): …`, `feat(daemon): …`, + `docs(reference): …`, `harness: …`. + +## The pull request + +Fill in the template. The three things a reviewer needs are: what a user gets, how you verified +it, and anything you were unsure about. State the revision and relevant local changes you tested, +what you actually ran, and any checks you could not run. Redact private information from evidence. + +Contributions follow the repository's [Apache-2.0 license](LICENSE). Preserve attribution and any +applicable license notices when adapting third-party material. + +## What to expect from us + +- We aim to acknowledge issues and pull requests within **one day**. An acknowledgement is not + a completed review or a merge decision. +- Our target for a first substantive review decision on an external PR is **seven days**. If it + takes longer, we explain what is pending on the PR. This is a target, not a guaranteed deadline. +- Labels you will see: `needs-repro` (we could not reproduce it yet; waiting on versions or steps), + `fixed-on-main` (merged, not yet on npm), `good first issue`, `help wanted`, `discussion` + (direction question; continues in Discussions). + +Reviews here are done by people and by the project's own agents. An agent may ask the first +clarifying question or run the reproduction; a maintainer makes the merge decision. + +## Where things live + +- Repository reference: `docs/reference/`; user documentation: [openrig.dev/docs](https://openrig.dev/docs). +- Skills: `packages/daemon/specs/agents/shared/skills/` and plugin skills under + `packages/daemon/assets/plugins/`; static context-pack sources: `packages/daemon/context-packs-src/`. + Generated packs live in `packages/daemon/context-packs/` and are not hand-edited or committed. +- Releases: [GitHub Releases](https://github.com/mvschwarz/openrig/releases) and npm `@openrig/cli`. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..f2d6a95d0 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,47 @@ +# Security policy + +## Supported versions + +Only the latest published version on npm (`@openrig/cli`) is supported. Fixes are developed on +`main` and released after verification; a merged fix is not necessarily in the published package. +Include the affected version even when reporting a problem in an older installation. + +## What OpenRig touches + +OpenRig runs a local daemon, drives coding agents in tmux sessions on your machine, and writes +configuration for those harnesses (for example under `~/.claude` and `~/.codex`). The README +section [What OpenRig changes on your machine](README.md#what-openrig-changes-on-your-machine) +describes these effects and the trust/permission choices. Unexpected access, disclosure or +permission changes are useful reports; include what you expected and what you observed. + +## Reporting a vulnerability + +Please do not open a public issue for a vulnerability. + +Open the repository's [Security page](https://github.com/mvschwarz/openrig/security). If +**Report a vulnerability** is available, use it to send a private report to the maintainers. +The reporter and authorized advisory collaborators can also see that report; it is not public. +Availability depends on the repository setting, not on this file being present. + +If that option is unavailable, ask in [Discussions Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a) +for a private security contact. Post only the request for a channel: do not include the +vulnerability details, reproduction, logs, credentials or affected private systems in public. +Wait for the private channel before sharing the report. + +Include: the OpenRig version, the harnesses involved, the steps to reproduce, and what an attacker +could do. A proof of concept is welcome; a working exploit against a third party's machine is not. + +## What to expect + +- We will acknowledge the report and coordinate assessment and next steps privately. +- Assessment and fix timing depend on impact and reproduction; no fixed deadline is promised. +- We will agree on disclosure and credit with you. You can ask to remain anonymous. + +## Scope notes + +- OpenRig assumes the machine and the accounts it runs under are trusted by their owner. Reports + that require a hostile local user with the same account are still welcome but are unlikely to be + treated as high severity. +- A harness carrying out an intentionally authorized operation is not by itself evidence of an + OpenRig vulnerability. Reports of OpenRig bypassing a chosen permission, changing trust + unexpectedly, or routing data or actions to the wrong destination are in scope.